From b8ca22055c50d76dedc96e080acc8d377e4fab0c Mon Sep 17 00:00:00 2001 From: Toni Oriol Date: Fri, 6 Dec 2024 13:53:36 +0100 Subject: [PATCH] refactor!: rename extra parameter to context BREAKING CHANGE: The `extra` parameter in transmute() and related types has been renamed to `context` to better reflect its purpose in providing contextual data for transmutations. This change affects the public API including type definitions, function parameters, and documentation. This affects: - transmute() function's third parameter - Schema type parameter - TransmuterArgs type - Related documentation and examples --- CHANGELOG.md | 4 ++-- README.md | 38 ++++++++++++++++++------------------- src/__tests__/index.test.ts | 26 ++++++++++++------------- src/index.ts | 18 +++++++++--------- src/types.ts | 18 +++++++++--------- 5 files changed, 52 insertions(+), 52 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2d05fce..52e7e1d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,7 +16,7 @@ ### Features -* **transmute:** infer transmuter extra param based on transmute call ([c83b1c0](https://github.com/tonioriol/transmutant/commit/c83b1c0260d9d37e5b4e20b2417179379949795a)) +* **transmute:** infer transmuter context param based on transmute call ([c83b1c0](https://github.com/tonioriol/transmutant/commit/c83b1c0260d9d37e5b4e20b2417179379949795a)) ## [3.0.0](https://github.com/tonioriol/transmutant/compare/v2.1.0...v3.0.0) (2024-10-31) @@ -45,7 +45,7 @@ ### Features -* improved type safety for extra param ([f8247b1](https://github.com/tonioriol/transmutant/commit/f8247b1f9b098cc23efec30caec798be72d72d6a)) +* improved type safety for context param ([f8247b1](https://github.com/tonioriol/transmutant/commit/f8247b1f9b098cc23efec30caec798be72d72d6a)) ## [1.0.1](https://github.com/tonioriol/transmutant/compare/v1.0.0...v1.0.1) (2024-10-27) diff --git a/README.md b/README.md index c4e9278..4a4d650 100644 --- a/README.md +++ b/README.md @@ -74,9 +74,9 @@ type. Each rule specifies: - Either a source property key for direct mapping or a transmuter function (`from`) ```typescript -type Schema = { +type Schema = { to: keyof Target, - from: keyof Source | Transmuter + from: keyof Source | Transmuter } ``` @@ -123,7 +123,7 @@ const schema: Schema[] = [ #### 3. External Data Transmutations -Include additional context in transmutations through the `extra` parameter: +Include additional context in transmutations through the `context` parameter: ```typescript interface Source { @@ -135,15 +135,15 @@ interface Target { location: string; } -interface ExtraData { +interface ContextData { separator: string; } -const schema: Schema[] = [ +const schema: Schema[] = [ { to: 'location', - from: ({ source, extra }) => - `${source.city}${extra.separator}${source.country}` + from: ({ source, context }) => + `${source.city}${context.separator}${source.country}` } ]; @@ -160,15 +160,15 @@ const result = transmute(schema, ```typescript // Arguments passed to a mutation function -type TransmuterArgs = { source: Source, extra?: Extra } +type TransmuterArgs = { source: Source, context?: Context } // Function that performs a custom transmutation -type Transmuter = (args: TransmuterArgs) => Target[keyof Target] +type Transmuter = (args: TransmuterArgs) => Target[keyof Target] // Defines how a property should be transmuted -type Schema = { +type Schema = { to: keyof Target, - from: keyof Source | Transmuter + from: keyof Source | Transmuter } ``` @@ -177,20 +177,20 @@ type Schema = { Main function for performing object transmutations. ```typescript -function transmute( - schema: Schema[], +function transmute( + schema: Schema[], source: Source, - extra?: Extra + context?: Context ): Target; ``` #### Parameters -| Parameter | Type | Description | -|-----------|-----------------------------------|------------------------------------| -| schema | `Schema[]` | Array of transmutation rules | -| source | `Source` | Source object to transmute | -| extra | `Extra` (optional) | Additional data for transmutations | +| Parameter | Type | Description | +|-----------|-------------------------------------|------------------------------------| +| schema | `Schema[]` | Array of transmutation rules | +| source | `Source` | Source object to transmute | +| context | `Context` (optional) | Additional data for transmutations | #### Returns diff --git a/src/__tests__/index.test.ts b/src/__tests__/index.test.ts index 6cccf1d..8834a6d 100644 --- a/src/__tests__/index.test.ts +++ b/src/__tests__/index.test.ts @@ -63,16 +63,16 @@ describe('transmute', () => { }) }) - it('should handle transmutation with extra data when specified', () => { - interface Extra { + it('should handle transmutation with context data when specified', () => { + interface Context { separator: string } - const schema: Schema[] = [ + const schema: Schema[] = [ { to: 'location', - from: ({ source, extra }) => - `${source.address.city}${extra.separator}${source.address.country}` + from: ({ source, context }) => + `${source.address.city}${context.separator}${source.address.country}` } ] @@ -117,16 +117,16 @@ describe('transmute', () => { }) }) - it('should ensure type safety with extra data', () => { - interface Extra { + it('should ensure type safety with context data', () => { + interface Context { prefix: string } - const schema: Schema[] = [ + const schema: Schema[] = [ { to: 'fullName', - from: ({ source, extra }) => - `${extra.prefix} ${source.firstName} ${source.lastName}` + from: ({ source, context }) => + `${context.prefix} ${source.firstName} ${source.lastName}` } ] @@ -143,15 +143,15 @@ describe('transmute', () => { } ] - interface Extra { + interface Context { title: string } const schema2 = [ { to: 'fullName' as const, - from: ({ source, extra }: { source: SourceUser; extra: Extra }) => - `${extra.title} ${source.firstName} ${source.lastName}` + from: ({ source, context }: { source: SourceUser; context: Context }) => + `${context.title} ${source.firstName} ${source.lastName}` } ] diff --git a/src/index.ts b/src/index.ts index 7f59863..d282747 100644 --- a/src/index.ts +++ b/src/index.ts @@ -6,25 +6,25 @@ export * from './types' * Transmutes an object from the Source type into the Target type based on the provided schema * @template Source - The source type being transmuted from * @template Target - The target type being transmuted to - * @template Extra - Type of additional data passed to mutation functions + * @template Context - Type of additional data passed to mutation functions * @param schema - Array of mutation rules * @param source - Source object to transmute - * @param extra - Optional extra data to pass to mutation functions + * @param context - Optional context data to pass to mutation functions * @returns Transmuted object matching Target type */ -export const transmute = ( - schema: Schema[], +export const transmute = ( + schema: Schema[], source: Source, - extra?: Extra + context?: Context ): Target => { return schema.reduce( (acc, { from, to }) => { const isFunction = typeof from === 'function' - // Only include extra in args if it's defined - const args: Extra extends undefined ? { source: Source } : { source: Source; extra: Extra } = - extra === undefined + // Only include context in args if it's defined + const args: Context extends undefined ? { source: Source } : { source: Source; context: Context } = + context === undefined ? { source } - : { source, extra } as any // Type assertion needed due to conditional type + : { source, context } as any // Type assertion needed due to conditional type const value = isFunction ? (from as Function)(args) diff --git a/src/types.ts b/src/types.ts index 7e52aed..ba547e9 100644 --- a/src/types.ts +++ b/src/types.ts @@ -1,21 +1,21 @@ /** * Arguments passed to a mutation function * @template Source - The source type being transmuted from - * @template Extra - Type of additional data for transmutation + * @template Context - Type of additional data for transmutation */ -export type TransmuterArgs = Extra extends undefined +export type TransmuterArgs = Context extends undefined ? { source: Source } - : { source: Source; extra: Extra } + : { source: Source; context: Context } /** * Function that performs a custom transmutation on a source object * @template Source - The source type being transmuted from * @template Target - The target type being transmuted to * @template TargetKey - The specific key of the target property being set - * @template Extra - Type of additional data for transmutation + * @template Context - Type of additional data for transmutation */ -export type Transmuter = - (args: TransmuterArgs) => Target[TargetKey] +export type Transmuter = + (args: TransmuterArgs) => Target[TargetKey] /** * Get keys of Source that have values assignable to Target[TargetKey] @@ -28,11 +28,11 @@ type AssignableKeys = { * Defines how a property should be transmuted from source to target type * @template Source - The source type being transmuted from * @template Target - The target type being transmuted to - * @template Extra - Type of additional data for transmutation + * @template Context - Type of additional data for transmutation */ -export type Schema = { +export type Schema = { [TargetKey in keyof Target]: { to: TargetKey - from: AssignableKeys | Transmuter + from: AssignableKeys | Transmuter } }[keyof Target]