refactor: rename extra parameter to context

This renames the extra parameter to context throughout the codebase to better reflect its purpose in providing contextual data for transmutations. The change affects type definitions, tests, documentation, and the main transmute function.
tonioriol · Dec 6, 2024 · 3edd67d · 3edd67d
1 parent 428e0e5
commit 3edd67d
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]