refactor: codec as generic type

Author: jasonkuhrt

src/types/Codec.ts

@@ -0,0 +1,54 @@
+/**
+ * Bidirectional transformation codec.
+ *
+ * Generic pattern for encoding and decoding between two type representations.
+ * Useful for serialization, API transformations, or any A ↔ B conversion.
+ *
+ * @example
+ * ```typescript
+ * const dateCodec = createCodec({
+ *   encode: (date: Date) => date.toISOString(),
+ *   decode: (str: string) => new Date(str)
+ * })
+ *
+ * const encoded = dateCodec.encode(new Date())  // "2024-01-01T00:00:00.000Z"
+ * const decoded = dateCodec.decode(encoded)     // Date object
+ * ```
+ */
+export interface Codec<$Decoded = any, $Encoded = any> {
+  /**
+   * Transform from decoded (application) type to encoded (wire) type.
+   */
+  encode: (value: $Decoded) => $Encoded
+
+  /**
+   * Transform from encoded (wire) type to decoded (application) type.
+   */
+  decode: (value: $Encoded) => $Decoded
+
+  /**
+   * Type witness for encoded type (compile-time only).
+   */
+  _typeEncoded: $Encoded
+
+  /**
+   * Type witness for decoded type (compile-time only).
+   */
+  _typeDecoded: $Decoded
+}
+
+/**
+ * Create a codec from encode and decode functions.
+ *
+ * @param codec - Object with encode and decode functions
+ * @returns Typed Codec instance
+ */
+export const createCodec = <$Decoded, $Encoded>(codec: {
+  encode: (value: $Decoded) => $Encoded
+  decode: (value: $Encoded) => $Decoded
+}): Codec<$Decoded, $Encoded> => codec as any
+
+/**
+ * Generic mapper function type for codec operations.
+ */
+export type Mapper = (value: any) => any

src/types/Schema/_.test.ts

@@ -1,5 +1,6 @@
 import { Ts } from '@wollybeard/kit'
 import { describe, expect, test } from 'vitest'
+import { createCodec } from '../Codec.js'
 import { Schema } from './_.js'
 
 describe('LookupCustomScalarOrFallbackToUnknown', () => {
@@ -24,7 +25,7 @@ describe('LookupCustomScalarOrFallbackToUnknown', () => {
     const DateScalar: DateScalar = {
       kind: 'Scalar',
       name: 'Date',
-      codec: Schema.Scalar.createCodec({ encode: () => '', decode: () => new Date() }),
+      codec: createCodec({ encode: () => '', decode: () => new Date() }),
     }
 
     // Custom scalar in registry should resolve
@@ -53,7 +54,7 @@ describe('lookupCustomScalarOrFallbackToUnknown (runtime)', () => {
     const DateScalar = {
       kind: 'Scalar' as const,
       name: 'Date',
-      codec: Schema.Scalar.createCodec({ encode: () => '', decode: () => new Date() }),
+      codec: createCodec({ encode: () => '', decode: () => new Date() }),
     }
     const scalars = { Date: DateScalar }
 

src/types/Schema/helpers.ts

@@ -1,17 +1,15 @@
 import type { Schema } from './_.js'
-import * as Nodes from './nodes/__.js'
-import type { List } from './nodes/List.js'
-import type { Nullable } from './nodes/Nullable.js'
-import * as Standard from './standard/scalars/scalars.js'
+import { Nodes } from './nodes/_.js'
+import { Standard } from './standard/_.js'
 
 /**
  * Unwrap a type to get its named type, ditching inline types like List and Nullable.
  */
 // todo extends any because of infinite depth issue in generated schema types
 // dprint-ignore
 export type GetNamedType<$Type> =
-      $Type extends List<infer $innerType>      ? GetNamedType<$innerType> :
-      $Type extends Nullable<infer $innerType>  ? GetNamedType<$innerType> :
+      $Type extends Nodes.List<infer $innerType>      ? GetNamedType<$innerType> :
+      $Type extends Nodes.Nullable<infer $innerType>  ? GetNamedType<$innerType> :
       $Type extends Nodes.__typename                  ? $Type :
       $Type
 
@@ -33,11 +31,11 @@ export type Define<$Type extends Partial<Schema>> = $Type & Schema
 // dprint-ignore
 export type LookupCustomScalarOrFallbackToUnknown<$Name extends string, $Scalars extends Nodes.Scalar.Registry> =
   $Name extends keyof $Scalars['map']  ? $Scalars['map'][$Name]
-  : $Name extends 'String'              ? typeof Standard.String
-  : $Name extends 'Int'                 ? typeof Standard.Int
-  : $Name extends 'Float'               ? typeof Standard.Float
-  : $Name extends 'Boolean'             ? typeof Standard.Boolean
-  : $Name extends 'ID'                  ? typeof Standard.ID
+  : $Name extends 'String'              ? typeof Standard.Scalars.String
+  : $Name extends 'Int'                 ? typeof Standard.Scalars.Int
+  : $Name extends 'Float'               ? typeof Standard.Scalars.Float
+  : $Name extends 'Boolean'             ? typeof Standard.Scalars.Boolean
+  : $Name extends 'ID'                  ? typeof Standard.Scalars.ID
   :                                       typeof Nodes.Scalar.UnknownScalar
 
 /**
@@ -61,15 +59,15 @@ export const lookupCustomScalarOrFallbackToUnknown = (scalars: Nodes.Scalar.Scal
   // Handle standard GraphQL scalars
   switch (name) {
     case 'String':
-      return Standard.String
+      return Standard.Scalars.String
     case 'Int':
-      return Standard.Int
+      return Standard.Scalars.Int
     case 'Float':
-      return Standard.Float
+      return Standard.Scalars.Float
     case 'Boolean':
-      return Standard.Boolean
+      return Standard.Scalars.Boolean
     case 'ID':
-      return Standard.ID
+      return Standard.Scalars.ID
     default:
       return Nodes.Scalar.UnknownScalar
   }

src/types/Schema/nodes/Scalar/_.ts

@@ -1,5 +1,4 @@
-import type { GraphqlKit } from '#src/lib/graphql-kit/_.js'
-import type { Codec } from './codec.js'
+import type { Codec } from '../../../Codec.js'
 
 export * as Scalar from './__.js'
 

src/types/Schema/nodes/Scalar/__.ts

@@ -1,4 +1,3 @@
 export * from '../ScalarCodecless.js'
-export * from './codec.js'
 export * from './create.js'
 export * from './helpers.js'

src/types/Schema/nodes/Scalar/codec.ts

@@ -1,6 +1,6 @@
 import { Obj, Ts } from '@wollybeard/kit'
+import { createCodec, type Mapper } from '../../../Codec.js'
 import type { Scalar } from './_.js'
-import { createCodec, type Mapper } from './codec.js'
 
 /**
  * Scalar representing an unknown custom scalar type without a codec definition.
@@ -11,9 +11,6 @@ import { createCodec, type Mapper } from './codec.js'
  * The decoded type is `unknown`, forcing users to either:
  * 1. Define a proper codec for the custom scalar, or
  * 2. Explicitly handle the unknown type at runtime
- *
- * This aligns with gql-tada's behavior and provides better type safety than
- * the previous fallback to `string`.
  */
 export const UnknownScalar: Scalar<string, unknown, any> = {
   kind: 'Scalar',

src/types/Schema/nodes/Scalar/helpers.ts

@@ -0,0 +1 @@
+export * as Nodes from './__.js'

src/types/Schema/nodes/_.ts

@@ -1,4 +1,4 @@
-import { createCodec } from '../../nodes/Scalar/codec.js'
+import { createCodec } from '../../../Codec.js'
 import { create } from '../../nodes/Scalar/create.js'
 
 export const JavaScriptScalarCodecs = {