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
tonioriol · Dec 6, 2024 · b8ca220 · b8ca220
1 parent 428e0e5
commit b8ca220
Show file tree

Hide file tree

Showing 5 changed files with 52 additions and 52 deletions.
diff --git 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
@@ -74,9 +74,9 @@ type. Each rule specifies:
 - Either a source property key for direct mapping or a transmuter function (`from`)
 
 ```typescript
-type Schema<Source, Target, Extra> = {
+type Schema<Source, Target, Context> = {
   to: keyof Target,
-  from: keyof Source | Transmuter<Source, Target, Extra>
+  from: keyof Source | Transmuter<Source, Target, Context>
 }
 ```
 
@@ -123,7 +123,7 @@ const schema: Schema<Source, Target>[] = [
 
 #### 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<Source, Target, ExtraData>[] = [
+const schema: Schema<Source, Target, ContextData>[] = [
   {
     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, Extra> = { source: Source, extra?: Extra }
+type TransmuterArgs<Source, Context> = { source: Source, context?: Context }
 
 // Function that performs a custom transmutation
-type Transmuter<Source, Target, Extra> = (args: TransmuterArgs<Source, Extra>) => Target[keyof Target]
+type Transmuter<Source, Target, Context> = (args: TransmuterArgs<Source, Context>) => Target[keyof Target]
 
 // Defines how a property should be transmuted
-type Schema<Source, Target, Extra> = {
+type Schema<Source, Target, Context> = {
   to: keyof Target,
-  from: keyof Source | Transmuter<Source, Target, Extra>
+  from: keyof Source | Transmuter<Source, Target, Context>
 }
 ```
 
@@ -177,20 +177,20 @@ type Schema<Source, Target, Extra> = {
 Main function for performing object transmutations.
 
 ```typescript
-function transmute<Source, Target, Extra>(
-  schema: Schema<Source, Target, Extra>[],
+function transmute<Source, Target, Context>(
+  schema: Schema<Source, Target, Context>[],
   source: Source,
-  extra?: Extra
+  context?: Context
 ): Target;
 ```
 
 #### Parameters
 
-| Parameter | Type                              | Description                        |
-|-----------|-----------------------------------|------------------------------------|
-| schema    | `Schema<Source, Target, Extra>[]` | Array of transmutation rules       |
-| source    | `Source`                          | Source object to transmute         |
-| extra     | `Extra` (optional)                | Additional data for transmutations |
+| Parameter | Type                                | Description                        |
+|-----------|-------------------------------------|------------------------------------|
+| schema    | `Schema<Source, Target, Context>[]` | 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
@@ -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<SourceUser, TargetUser, Extra>[] = [
+    const schema: Schema<SourceUser, TargetUser, Context>[] = [
       {
         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<SourceUser, TargetUser, Extra>[] = [
+    const schema: Schema<SourceUser, TargetUser, Context>[] = [
       {
         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
@@ -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 = <Source, Target, Extra = undefined>(
-  schema: Schema<Source, Target, Extra>[],
+export const transmute = <Source, Target, Context = undefined>(
+  schema: Schema<Source, Target, Context>[],
   source: Source,
-  extra?: Extra
+  context?: Context
 ): Target => {
   return schema.reduce<Target>(
     (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
@@ -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<Source, Extra> = Extra extends undefined
+export type TransmuterArgs<Source, Context> = 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<Source, Target, TargetKey extends keyof Target, Extra = undefined> =
-  (args: TransmuterArgs<Source, Extra>) => Target[TargetKey]
+export type Transmuter<Source, Target, TargetKey extends keyof Target, Context = undefined> =
+  (args: TransmuterArgs<Source, Context>) => Target[TargetKey]
 
 /**
  * Get keys of Source that have values assignable to Target[TargetKey]
@@ -28,11 +28,11 @@ type AssignableKeys<Source, Target, TargetKey extends keyof Target> = {
  * 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<Source, Target, Extra = undefined> = {
+export type Schema<Source, Target, Context = undefined> = {
   [TargetKey in keyof Target]: {
     to: TargetKey
-    from: AssignableKeys<Source, Target, TargetKey> | Transmuter<Source, Target, TargetKey, Extra>
+    from: AssignableKeys<Source, Target, TargetKey> | Transmuter<Source, Target, TargetKey, Context>
   }
 }[keyof Target]