@prisma-next/mongo-codec 0.5.0-dev.7 → 0.5.0-dev.9

package/README.md

@@ -4,10 +4,36 @@ Codec interface and registry for MongoDB value serialization.
 
 ## Responsibilities
 
-- **Codec interface**: `MongoCodec<Id, TTraits, TWire, TJs>` — defines encode/decode between wire (BSON) and JS representations, with trait annotations (`equality`, `order`, `boolean`, `numeric`, `textual`, `vector`)
-- **Codec factory**: `mongoCodec()` — creates frozen codec instances from a config object
+- **Codec interface**: `MongoCodec<Id, TTraits, TWire, TInput>` — declares how a JS value translates to and from the BSON-shaped wire format the Mongo driver exchanges, plus the JSON-safe form stored in contract artifacts. Carries trait annotations (`equality`, `order`, `boolean`, `numeric`, `textual`, `vector`) for operator gating. Same four generics as the framework `Codec` base.
+- **Codec factory**: `mongoCodec()` — creates frozen codec instances from a config object. `encode` is optional (identity default when omitted); `encode`/`decode` may be authored as sync or async functions and are lifted to Promise-returning query-time methods automatically. Build-time methods (`encodeJson`, `decodeJson`) are synchronous and default to identity when omitted.
 - **Codec registry**: `MongoCodecRegistry` and `createMongoCodecRegistry()` — a map-based container that stores and retrieves codecs by ID, with duplicate-ID protection
-- **Type-level helpers**: `MongoCodecJsType<T>` and `MongoCodecTraits<T>` for extracting JS types and traits from codec types
+- **Type-level helpers**: `MongoCodecInput<T>` and `MongoCodecTraits<T>` for extracting the input JS type and traits from codec types
+
+## Examples
+
+```ts
+// Sync authoring:
+const intCodec = mongoCodec({
+  typeId: 'mongo/int@1',
+  targetTypes: ['int'],
+  encode: (v: number) => v,
+  decode: (w: number) => w,
+  encodeJson: (v: number) => v,
+  decodeJson: (j: number) => j,
+});
+
+// Async authoring (e.g. KMS-backed encryption): same factory, same shape.
+const secretCodec = mongoCodec({
+  typeId: 'mongo/secret@1',
+  targetTypes: ['string'],
+  encode: async (v: string) => encrypt(v, await getKey()),
+  decode: async (w: string) => decrypt(w, await getKey()),
+  encodeJson: (v: string) => v,
+  decodeJson: (j: string) => j,
+});
+```
+
+See [ADR 204 — Single-Path Async Codec Runtime](../../../../docs/architecture%20docs/adrs/ADR%20204%20-%20Single-Path%20Async%20Codec%20Runtime.md) for the codec runtime's async boundary contract.
 
 ## Dependencies
 

package/dist/index.d.mts

@@ -3,20 +3,55 @@ import { Codec, CodecTrait } from "@prisma-next/framework-components/codec";
 
 //#region src/codecs.d.ts
 type MongoCodecTrait = CodecTrait;
-interface MongoCodec<Id extends string = string, TTraits$1 extends readonly MongoCodecTrait[] = readonly MongoCodecTrait[], TWire = unknown, TJs = unknown> extends Codec<Id, TTraits$1, TWire, TJs> {
-  readonly traits: TTraits$1;
-}
-declare function mongoCodec<Id extends string, const TTraits$1 extends readonly MongoCodecTrait[] = readonly [], TWire = unknown, TJs = unknown>(config: {
+/**
+ * A codec for the Mongo target. Translates between an application value
+ * and the BSON-shaped wire form the Mongo driver exchanges, and between
+ * an application value and the JSON form stored in contract artifacts.
+ *
+ * Same shape as the framework codec base — see `Codec` in
+ * `@prisma-next/framework-components/codec` for the contract. The alias
+ * exists so Mongo-specific metadata can be added here in future without
+ * touching the framework base.
+ */
+type MongoCodec<Id extends string = string, TTraits$1 extends readonly MongoCodecTrait[] = readonly MongoCodecTrait[], TWire = unknown, TInput = unknown> = Codec<Id, TTraits$1, TWire, TInput>;
+/**
+ * Conditional bundle for `encodeJson`/`decodeJson`: when `TInput` is
+ * structurally assignable to `JsonValue` the identity defaults are
+ * sound and both fields are optional; otherwise both fields are
+ * required so an author cannot silently produce a non-JSON-safe
+ * contract artifact.
+ */
+type JsonRoundTripConfig<TInput> = [TInput] extends [JsonValue] ? {
+  encodeJson?: (value: TInput) => JsonValue;
+  decodeJson?: (json: JsonValue) => TInput;
+} : {
+  encodeJson: (value: TInput) => JsonValue;
+  decodeJson: (json: JsonValue) => TInput;
+};
+/**
+ * Construct a Mongo codec from author functions.
+ *
+ * Author `encode` and `decode` as sync or async functions; the factory
+ * produces a {@link MongoCodec} whose query-time methods follow the
+ * boundary contract documented on the framework {@link BaseCodec}.
+ *
+ * `encode` is optional — when omitted, an identity default is installed
+ * (declaring "the input value already is the wire value", so `TInput` and
+ * `TWire` are interchangeable for that codec). `decode` is always
+ * required. `encodeJson` and `decodeJson` default to identity **only when
+ * `TInput` is assignable to `JsonValue`**; otherwise both are required so
+ * the contract artifact stays JSON-safe.
+ */
+declare function mongoCodec<Id extends string, const TTraits$1 extends readonly MongoCodecTrait[] = readonly [], TWire = unknown, TInput = unknown>(config: {
   typeId: Id;
   targetTypes: readonly string[];
   traits?: TTraits$1;
-  encode: (value: TJs) => TWire;
-  decode: (wire: TWire) => TJs;
-  encodeJson?: (value: TJs) => JsonValue;
-  decodeJson?: (json: JsonValue) => TJs;
+  encode?: (value: TInput) => TWire | Promise<TWire>;
+  decode: (wire: TWire) => TInput | Promise<TInput>;
   renderOutputType?: (typeParams: Record<string, unknown>) => string | undefined;
-}): MongoCodec<Id, TTraits$1, TWire, TJs>;
-type MongoCodecJsType<T> = T extends MongoCodec<string, readonly MongoCodecTrait[], unknown, infer TJs> ? TJs : never;
+} & JsonRoundTripConfig<TInput>): MongoCodec<Id, TTraits$1, TWire, TInput>;
+/** Extract the JS application type carried by a Mongo codec — used both as `encode` input and as `decode` output. */
+type MongoCodecInput<T> = T extends MongoCodec<string, readonly MongoCodecTrait[], unknown, infer TInput> ? TInput : never;
 type MongoCodecTraits<T> = T extends MongoCodec<string, infer TTraits> ? TTraits[number] & MongoCodecTrait : never;
 //#endregion
 //#region src/codec-registry.d.ts
@@ -29,5 +64,5 @@ interface MongoCodecRegistry {
 }
 declare function createMongoCodecRegistry(): MongoCodecRegistry;
 //#endregion
-export { type MongoCodec, type MongoCodecJsType, type MongoCodecRegistry, type MongoCodecTrait, type MongoCodecTraits, createMongoCodecRegistry, mongoCodec };
+export { type MongoCodec, type MongoCodecInput, type MongoCodecRegistry, type MongoCodecTrait, type MongoCodecTraits, createMongoCodecRegistry, mongoCodec };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/codecs.ts","../src/codec-registry.ts"],"sourcesContent":[],"mappings":";;;;KAGY,eAAA,GAAkB;UAEb,kEAEU,6BAA6B,2DAG9C,MAAU,IAAI,WAAS,OAAO;EAP5B,SAAA,MAAA,EAQO,SARQ;AAE3B;AAE2B,iBAOX,UAPW,CAAA,WAAA,MAAA,EAAA,wBAAA,SASM,eATN,EAAA,GAAA,SAAA,EAAA,EAAA,QAAA,OAAA,EAAA,MAAA,OAAA,CAAA,CAAA,MAAA,EAAA;EAA6B,MAAA,EAa9C,EAb8C;EAGpC,WAAA,EAAA,SAAA,MAAA,EAAA;EAAI,MAAA,CAAA,EAYb,SAZa;EAAS,MAAA,EAAA,CAAA,KAAA,EAaf,GAbe,EAAA,GAaP,KAbO;EAAO,MAAA,EAAA,CAAA,IAAA,EAcvB,KAduB,EAAA,GAcb,GAda;EACrB,UAAA,CAAA,EAAA,CAAA,KAAA,EAcI,GAdJ,EAAA,GAcY,SAdZ;EADT,UAAA,CAAA,EAAA,CAAA,IAAA,EAgBY,SAhBZ,EAAA,GAgB0B,GAhB1B;EAAS,gBAAA,CAAA,EAAA,CAAA,UAAA,EAiBe,MAjBf,CAAA,MAAA,EAAA,OAAA,CAAA,EAAA,GAAA,MAAA,GAAA,SAAA;AAInB,CAAA,CAAA,EAcI,UAdY,CAcD,EAdW,EAcP,SAdO,EAcE,KAdF,EAcS,GAdT,CAAA;AAEO,KA6BrB,gBA7BqB,CAAA,CAAA,CAAA,GA8B/B,CA9B+B,SA8BrB,UA9BqB,CAAA,MAAA,EAAA,SA8BO,eA9BP,EAAA,EAAA,OAAA,EAAA,KAAA,IAAA,CAAA,GAAA,GAAA,GAAA,KAAA;AAIvB,KA4BE,gBA5BF,CAAA,CAAA,CAAA,GA6BR,CA7BQ,SA6BE,UA7BF,CAAA,MAAA,EAAA,KAAA,QAAA,CAAA,GA6BsC,OA7BtC,CAAA,MAAA,CAAA,GA6BwD,eA7BxD,GAAA,KAAA;;;UClBO,kBAAA;mBACE;;EDAP,QAAA,CAAA,KAAA,ECEM,UDFS,CAAA,MAAG,CAAA,CAAA,EAAA,IAAU;EAEvB,CAAA,MAAA,CAAA,QAAU,GAAA,ECCJ,QDDI,CCCK,UDDL,CAAA,MAAA,CAAA,CAAA;EAEA,MAAA,EAAA,ECAf,gBDAe,CCAE,UDAF,CAAA,MAAA,CAAA,CAAA;;AAGP,iBC2BJ,wBAAA,CAAA,CD3BI,EC2BwB,kBD3BxB"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/codecs.ts","../src/codec-registry.ts"],"sourcesContent":[],"mappings":";;;;KAIY,eAAA,GAAkB;;AAA9B;AAYA;;;;;;;;AAKa,KALD,UAKC,CAAA,WAAA,MAAA,GAAA,MAAA,EAAA,kBAAA,SAHc,eAGd,EAAA,GAAA,SAH2C,eAG3C,EAAA,EAAA,QAAA,OAAA,EAAA,SAAA,OAAA,CAAA,GAAT,KAAS,CAAC,EAAD,EAAK,SAAL,EAAc,KAAd,EAAqB,MAArB,CAAA;AAA6B;;;;;;;KASrC,mBAMqB,CAAA,MAAA,CAAA,GAAA,CANU,MAMV,CAAA,SAAA,CAN2B,SAM3B,CAAA,GAAA;EAAW,UAAA,CAAA,EAAA,CAAA,KAAA,EAJV,MAIU,EAAA,GAJC,SAID;EACZ,UAAA,CAAA,EAAA,CAAA,IAAA,EAJC,SAID,EAAA,GAJe,MAIf;CAAc,GAAA;EAAM,UAAA,EAAA,CAAA,KAAA,EADnB,MACmB,EAAA,GADR,SACQ;EAiB7B,UAAA,EAAA,CAAU,IAAA,EAjBD,SAiBC,EAAA,GAjBa,MAiBb;CAEO;;;;;;;;;;;;;;;AAYf,iBAdF,UAcE,CAAA,WAAA,MAAA,EAAA,wBAAA,SAZe,eAYf,EAAA,GAAA,SAAA,EAAA,EAAA,QAAA,OAAA,EAAA,SAAA,OAAA,CAAA,CAAA,MAAA,EAAA;EAAS,MAAA,EAPf,EAOe;EAAO,WAAA,EAAA,SAAA,MAAA,EAAA;EAA/B,MAAA,CAAA,EALU,SAKV;EAAU,MAAA,CAAA,EAAA,CAAA,KAAA,EAJQ,MAIR,EAAA,GAJmB,KAInB,GAJ2B,OAI3B,CAJmC,KAInC,CAAA;EAuCD,MAAA,EAAA,CAAA,IAAA,EA1CO,KA0CQ,EAAA,GA1CE,MA0CF,GA1CW,OA0CX,CA1CmB,MA0CnB,CAAA;EACzB,gBAAA,CAAA,EAAA,CAAA,UAAA,EA1CkC,MA0ClC,CAAA,MAAA,EAAA,OAAA,CAAA,EAAA,GAAA,MAAA,GAAA,SAAA;CAAsC,GAzClC,mBAyCkC,CAzCd,MAyCc,CAAA,CAAA,EAxCrC,UAwCqC,CAxC1B,EAwC0B,EAxCtB,SAwCsB,EAxCb,KAwCa,EAxCN,MAwCM,CAAA;;AAAlB,KADV,eACU,CAAA,CAAA,CAAA,GAApB,CAAoB,SAAV,UAAU,CAAA,MAAA,EAAA,SAAkB,eAAlB,EAAA,EAAA,OAAA,EAAA,KAAA,OAAA,CAAA,GAAA,MAAA,GAAA,KAAA;AAEV,KAAA,gBAAgB,CAAA,CAAA,CAAA,GAC1B,CAD0B,SAChB,UADgB,CAAA,MAAA,EAAA,KAAA,QAAA,CAAA,GACoB,OADpB,CAAA,MAAA,CAAA,GACsC,eADtC,GAAA,KAAA;;;UC5GX,kBAAA;mBACE;;EDCP,QAAA,CAAA,KAAA,ECCM,UDDS,CAAA,MAAG,CAAA,CAAA,EAAA,IAAU;EAY5B,CAAA,MAAA,CAAA,QAAU,GAAA,ECVC,QDUD,CCVU,UDUV,CAAA,MAAA,CAAA,CAAA;EAEK,MAAA,EAAA,ECXf,gBDWe,CCXE,UDWF,CAAA,MAAA,CAAA,CAAA;;AAGb,iBCgBE,wBAAA,CAAA,CDhBF,ECgB8B,kBDhB9B"}

package/dist/index.mjs

@@ -1,3 +1,5 @@
+import { ifDefined } from "@prisma-next/utils/defined";
+
 //#region src/codec-registry.ts
 var MongoCodecRegistryImpl = class {
 	#byId = /* @__PURE__ */ new Map();
@@ -24,18 +26,46 @@ function createMongoCodecRegistry() {
 
 //#endregion
 //#region src/codecs.ts
+/**
+* Construct a Mongo codec from author functions.
+*
+* Author `encode` and `decode` as sync or async functions; the factory
+* produces a {@link MongoCodec} whose query-time methods follow the
+* boundary contract documented on the framework {@link BaseCodec}.
+*
+* `encode` is optional — when omitted, an identity default is installed
+* (declaring "the input value already is the wire value", so `TInput` and
+* `TWire` are interchangeable for that codec). `decode` is always
+* required. `encodeJson` and `decodeJson` default to identity **only when
+* `TInput` is assignable to `JsonValue`**; otherwise both are required so
+* the contract artifact stays JSON-safe.
+*/
 function mongoCodec(config) {
-	const traits = config.traits ? Object.freeze([...config.traits]) : Object.freeze([]);
 	const identity = (v) => v;
+	const userEncode = config.encode ?? ((value) => value);
+	const userDecode = config.decode;
+	const widenedConfig = config;
 	return {
 		id: config.typeId,
 		targetTypes: config.targetTypes,
-		traits,
-		decode: config.decode,
-		encode: config.encode,
-		encodeJson: config.encodeJson ?? identity,
-		decodeJson: config.decodeJson ?? identity,
-		...config.renderOutputType ? { renderOutputType: config.renderOutputType } : {}
+		...ifDefined("traits", config.traits ? Object.freeze([...config.traits]) : void 0),
+		...ifDefined("renderOutputType", config.renderOutputType),
+		encode: (value) => {
+			try {
+				return Promise.resolve(userEncode(value));
+			} catch (error) {
+				return Promise.reject(error);
+			}
+		},
+		decode: (wire) => {
+			try {
+				return Promise.resolve(userDecode(wire));
+			} catch (error) {
+				return Promise.reject(error);
+			}
+		},
+		encodeJson: widenedConfig.encodeJson ?? identity,
+		decodeJson: widenedConfig.decodeJson ?? identity
 	};
 }
 

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":["#byId"],"sources":["../src/codec-registry.ts","../src/codecs.ts"],"sourcesContent":["import type { MongoCodec } from './codecs';\n\nexport interface MongoCodecRegistry {\n  get(id: string): MongoCodec<string> | undefined;\n  has(id: string): boolean;\n  register(codec: MongoCodec<string>): void;\n  [Symbol.iterator](): Iterator<MongoCodec<string>>;\n  values(): IterableIterator<MongoCodec<string>>;\n}\n\nclass MongoCodecRegistryImpl implements MongoCodecRegistry {\n  readonly #byId = new Map<string, MongoCodec<string>>();\n\n  get(id: string): MongoCodec<string> | undefined {\n    return this.#byId.get(id);\n  }\n\n  has(id: string): boolean {\n    return this.#byId.has(id);\n  }\n\n  register(codec: MongoCodec<string>): void {\n    if (this.#byId.has(codec.id)) {\n      throw new Error(`Codec with ID '${codec.id}' is already registered`);\n    }\n    this.#byId.set(codec.id, codec);\n  }\n\n  *[Symbol.iterator](): Iterator<MongoCodec<string>> {\n    yield* this.#byId.values();\n  }\n\n  values(): IterableIterator<MongoCodec<string>> {\n    return this.#byId.values();\n  }\n}\n\nexport function createMongoCodecRegistry(): MongoCodecRegistry {\n  return new MongoCodecRegistryImpl();\n}\n","import type { JsonValue } from '@prisma-next/contract/types';\nimport type { Codec as BaseCodec, CodecTrait } from '@prisma-next/framework-components/codec';\n\nexport type MongoCodecTrait = CodecTrait;\n\nexport interface MongoCodec<\n  Id extends string = string,\n  TTraits extends readonly MongoCodecTrait[] = readonly MongoCodecTrait[],\n  TWire = unknown,\n  TJs = unknown,\n> extends BaseCodec<Id, TTraits, TWire, TJs> {\n  readonly traits: TTraits;\n}\n\nexport function mongoCodec<\n  Id extends string,\n  const TTraits extends readonly MongoCodecTrait[] = readonly [],\n  TWire = unknown,\n  TJs = unknown,\n>(config: {\n  typeId: Id;\n  targetTypes: readonly string[];\n  traits?: TTraits;\n  encode: (value: TJs) => TWire;\n  decode: (wire: TWire) => TJs;\n  encodeJson?: (value: TJs) => JsonValue;\n  decodeJson?: (json: JsonValue) => TJs;\n  renderOutputType?: (typeParams: Record<string, unknown>) => string | undefined;\n}): MongoCodec<Id, TTraits, TWire, TJs> {\n  const traits = config.traits\n    ? (Object.freeze([...config.traits]) as TTraits)\n    : (Object.freeze([] as const) as unknown as TTraits);\n  const identity = (v: unknown) => v;\n  return {\n    id: config.typeId,\n    targetTypes: config.targetTypes,\n    traits,\n    decode: config.decode,\n    encode: config.encode,\n    encodeJson: (config.encodeJson ?? identity) as (value: TJs) => JsonValue,\n    decodeJson: (config.decodeJson ?? identity) as (json: JsonValue) => TJs,\n    ...(config.renderOutputType ? { renderOutputType: config.renderOutputType } : {}),\n  };\n}\n\nexport type MongoCodecJsType<T> =\n  T extends MongoCodec<string, readonly MongoCodecTrait[], unknown, infer TJs> ? TJs : never;\n\nexport type MongoCodecTraits<T> =\n  T extends MongoCodec<string, infer TTraits> ? TTraits[number] & MongoCodecTrait : never;\n"],"mappings":";AAUA,IAAM,yBAAN,MAA2D;CACzD,CAASA,uBAAQ,IAAI,KAAiC;CAEtD,IAAI,IAA4C;AAC9C,SAAO,MAAKA,KAAM,IAAI,GAAG;;CAG3B,IAAI,IAAqB;AACvB,SAAO,MAAKA,KAAM,IAAI,GAAG;;CAG3B,SAAS,OAAiC;AACxC,MAAI,MAAKA,KAAM,IAAI,MAAM,GAAG,CAC1B,OAAM,IAAI,MAAM,kBAAkB,MAAM,GAAG,yBAAyB;AAEtE,QAAKA,KAAM,IAAI,MAAM,IAAI,MAAM;;CAGjC,EAAE,OAAO,YAA0C;AACjD,SAAO,MAAKA,KAAM,QAAQ;;CAG5B,SAA+C;AAC7C,SAAO,MAAKA,KAAM,QAAQ;;;AAI9B,SAAgB,2BAA+C;AAC7D,QAAO,IAAI,wBAAwB;;;;;ACxBrC,SAAgB,WAKd,QASsC;CACtC,MAAM,SAAS,OAAO,SACjB,OAAO,OAAO,CAAC,GAAG,OAAO,OAAO,CAAC,GACjC,OAAO,OAAO,EAAE,CAAU;CAC/B,MAAM,YAAY,MAAe;AACjC,QAAO;EACL,IAAI,OAAO;EACX,aAAa,OAAO;EACpB;EACA,QAAQ,OAAO;EACf,QAAQ,OAAO;EACf,YAAa,OAAO,cAAc;EAClC,YAAa,OAAO,cAAc;EAClC,GAAI,OAAO,mBAAmB,EAAE,kBAAkB,OAAO,kBAAkB,GAAG,EAAE;EACjF"}
+{"version":3,"file":"index.mjs","names":["#byId"],"sources":["../src/codec-registry.ts","../src/codecs.ts"],"sourcesContent":["import type { MongoCodec } from './codecs';\n\nexport interface MongoCodecRegistry {\n  get(id: string): MongoCodec<string> | undefined;\n  has(id: string): boolean;\n  register(codec: MongoCodec<string>): void;\n  [Symbol.iterator](): Iterator<MongoCodec<string>>;\n  values(): IterableIterator<MongoCodec<string>>;\n}\n\nclass MongoCodecRegistryImpl implements MongoCodecRegistry {\n  readonly #byId = new Map<string, MongoCodec<string>>();\n\n  get(id: string): MongoCodec<string> | undefined {\n    return this.#byId.get(id);\n  }\n\n  has(id: string): boolean {\n    return this.#byId.has(id);\n  }\n\n  register(codec: MongoCodec<string>): void {\n    if (this.#byId.has(codec.id)) {\n      throw new Error(`Codec with ID '${codec.id}' is already registered`);\n    }\n    this.#byId.set(codec.id, codec);\n  }\n\n  *[Symbol.iterator](): Iterator<MongoCodec<string>> {\n    yield* this.#byId.values();\n  }\n\n  values(): IterableIterator<MongoCodec<string>> {\n    return this.#byId.values();\n  }\n}\n\nexport function createMongoCodecRegistry(): MongoCodecRegistry {\n  return new MongoCodecRegistryImpl();\n}\n","import type { JsonValue } from '@prisma-next/contract/types';\nimport type { Codec as BaseCodec, CodecTrait } from '@prisma-next/framework-components/codec';\nimport { ifDefined } from '@prisma-next/utils/defined';\n\nexport type MongoCodecTrait = CodecTrait;\n\n/**\n * A codec for the Mongo target. Translates between an application value\n * and the BSON-shaped wire form the Mongo driver exchanges, and between\n * an application value and the JSON form stored in contract artifacts.\n *\n * Same shape as the framework codec base — see `Codec` in\n * `@prisma-next/framework-components/codec` for the contract. The alias\n * exists so Mongo-specific metadata can be added here in future without\n * touching the framework base.\n */\nexport type MongoCodec<\n  Id extends string = string,\n  TTraits extends readonly MongoCodecTrait[] = readonly MongoCodecTrait[],\n  TWire = unknown,\n  TInput = unknown,\n> = BaseCodec<Id, TTraits, TWire, TInput>;\n\n/**\n * Conditional bundle for `encodeJson`/`decodeJson`: when `TInput` is\n * structurally assignable to `JsonValue` the identity defaults are\n * sound and both fields are optional; otherwise both fields are\n * required so an author cannot silently produce a non-JSON-safe\n * contract artifact.\n */\ntype JsonRoundTripConfig<TInput> = [TInput] extends [JsonValue]\n  ? {\n      encodeJson?: (value: TInput) => JsonValue;\n      decodeJson?: (json: JsonValue) => TInput;\n    }\n  : {\n      encodeJson: (value: TInput) => JsonValue;\n      decodeJson: (json: JsonValue) => TInput;\n    };\n\n/**\n * Construct a Mongo codec from author functions.\n *\n * Author `encode` and `decode` as sync or async functions; the factory\n * produces a {@link MongoCodec} whose query-time methods follow the\n * boundary contract documented on the framework {@link BaseCodec}.\n *\n * `encode` is optional — when omitted, an identity default is installed\n * (declaring \"the input value already is the wire value\", so `TInput` and\n * `TWire` are interchangeable for that codec). `decode` is always\n * required. `encodeJson` and `decodeJson` default to identity **only when\n * `TInput` is assignable to `JsonValue`**; otherwise both are required so\n * the contract artifact stays JSON-safe.\n */\nexport function mongoCodec<\n  Id extends string,\n  const TTraits extends readonly MongoCodecTrait[] = readonly [],\n  TWire = unknown,\n  TInput = unknown,\n>(\n  config: {\n    typeId: Id;\n    targetTypes: readonly string[];\n    traits?: TTraits;\n    encode?: (value: TInput) => TWire | Promise<TWire>;\n    decode: (wire: TWire) => TInput | Promise<TInput>;\n    renderOutputType?: (typeParams: Record<string, unknown>) => string | undefined;\n  } & JsonRoundTripConfig<TInput>,\n): MongoCodec<Id, TTraits, TWire, TInput> {\n  const identity = (v: unknown) => v;\n  // The synchronous identity default is only safe when the author has\n  // declared \"the input is already the wire value\" (i.e. TInput == TWire);\n  // it returns the value directly, never a Promise.\n  const userEncode = config.encode ?? ((value: TInput) => value as unknown as TWire);\n  const userDecode = config.decode;\n  const widenedConfig = config as {\n    encodeJson?: (value: TInput) => JsonValue;\n    decodeJson?: (json: JsonValue) => TInput;\n  };\n  return {\n    id: config.typeId,\n    targetTypes: config.targetTypes,\n    ...ifDefined(\n      'traits',\n      config.traits ? (Object.freeze([...config.traits]) as TTraits) : undefined,\n    ),\n    ...ifDefined('renderOutputType', config.renderOutputType),\n    encode: (value) => {\n      try {\n        return Promise.resolve(userEncode(value));\n      } catch (error) {\n        return Promise.reject(error);\n      }\n    },\n    decode: (wire) => {\n      try {\n        return Promise.resolve(userDecode(wire));\n      } catch (error) {\n        return Promise.reject(error);\n      }\n    },\n    encodeJson: (widenedConfig.encodeJson ?? identity) as (value: TInput) => JsonValue,\n    decodeJson: (widenedConfig.decodeJson ?? identity) as (json: JsonValue) => TInput,\n  };\n}\n\n/** Extract the JS application type carried by a Mongo codec — used both as `encode` input and as `decode` output. */\nexport type MongoCodecInput<T> =\n  T extends MongoCodec<string, readonly MongoCodecTrait[], unknown, infer TInput> ? TInput : never;\n\nexport type MongoCodecTraits<T> =\n  T extends MongoCodec<string, infer TTraits> ? TTraits[number] & MongoCodecTrait : never;\n"],"mappings":";;;AAUA,IAAM,yBAAN,MAA2D;CACzD,CAASA,uBAAQ,IAAI,KAAiC;CAEtD,IAAI,IAA4C;AAC9C,SAAO,MAAKA,KAAM,IAAI,GAAG;;CAG3B,IAAI,IAAqB;AACvB,SAAO,MAAKA,KAAM,IAAI,GAAG;;CAG3B,SAAS,OAAiC;AACxC,MAAI,MAAKA,KAAM,IAAI,MAAM,GAAG,CAC1B,OAAM,IAAI,MAAM,kBAAkB,MAAM,GAAG,yBAAyB;AAEtE,QAAKA,KAAM,IAAI,MAAM,IAAI,MAAM;;CAGjC,EAAE,OAAO,YAA0C;AACjD,SAAO,MAAKA,KAAM,QAAQ;;CAG5B,SAA+C;AAC7C,SAAO,MAAKA,KAAM,QAAQ;;;AAI9B,SAAgB,2BAA+C;AAC7D,QAAO,IAAI,wBAAwB;;;;;;;;;;;;;;;;;;;ACgBrC,SAAgB,WAMd,QAQwC;CACxC,MAAM,YAAY,MAAe;CAIjC,MAAM,aAAa,OAAO,YAAY,UAAkB;CACxD,MAAM,aAAa,OAAO;CAC1B,MAAM,gBAAgB;AAItB,QAAO;EACL,IAAI,OAAO;EACX,aAAa,OAAO;EACpB,GAAG,UACD,UACA,OAAO,SAAU,OAAO,OAAO,CAAC,GAAG,OAAO,OAAO,CAAC,GAAe,OAClE;EACD,GAAG,UAAU,oBAAoB,OAAO,iBAAiB;EACzD,SAAS,UAAU;AACjB,OAAI;AACF,WAAO,QAAQ,QAAQ,WAAW,MAAM,CAAC;YAClC,OAAO;AACd,WAAO,QAAQ,OAAO,MAAM;;;EAGhC,SAAS,SAAS;AAChB,OAAI;AACF,WAAO,QAAQ,QAAQ,WAAW,KAAK,CAAC;YACjC,OAAO;AACd,WAAO,QAAQ,OAAO,MAAM;;;EAGhC,YAAa,cAAc,cAAc;EACzC,YAAa,cAAc,cAAc;EAC1C"}

package/package.json

@@ -1,20 +1,21 @@
 {
   "name": "@prisma-next/mongo-codec",
-  "version": "0.5.0-dev.7",
+  "version": "0.5.0-dev.9",
   "type": "module",
   "sideEffects": false,
   "description": "Codec interface and registry for Prisma Next MongoDB support",
   "dependencies": {
-    "@prisma-next/contract": "0.5.0-dev.7",
-    "@prisma-next/framework-components": "0.5.0-dev.7"
+    "@prisma-next/framework-components": "0.5.0-dev.9",
+    "@prisma-next/utils": "0.5.0-dev.9",
+    "@prisma-next/contract": "0.5.0-dev.9"
   },
   "devDependencies": {
     "tsdown": "0.18.4",
     "typescript": "5.9.3",
     "vitest": "4.0.17",
     "@prisma-next/test-utils": "0.0.1",
-    "@prisma-next/tsconfig": "0.0.0",
-    "@prisma-next/tsdown": "0.0.0"
+    "@prisma-next/tsdown": "0.0.0",
+    "@prisma-next/tsconfig": "0.0.0"
   },
   "files": [
     "dist",

package/src/codecs.ts

@@ -1,50 +1,112 @@
 import type { JsonValue } from '@prisma-next/contract/types';
 import type { Codec as BaseCodec, CodecTrait } from '@prisma-next/framework-components/codec';
+import { ifDefined } from '@prisma-next/utils/defined';
 
 export type MongoCodecTrait = CodecTrait;
 
-export interface MongoCodec<
+/**
+ * A codec for the Mongo target. Translates between an application value
+ * and the BSON-shaped wire form the Mongo driver exchanges, and between
+ * an application value and the JSON form stored in contract artifacts.
+ *
+ * Same shape as the framework codec base — see `Codec` in
+ * `@prisma-next/framework-components/codec` for the contract. The alias
+ * exists so Mongo-specific metadata can be added here in future without
+ * touching the framework base.
+ */
+export type MongoCodec<
   Id extends string = string,
   TTraits extends readonly MongoCodecTrait[] = readonly MongoCodecTrait[],
   TWire = unknown,
-  TJs = unknown,
-> extends BaseCodec<Id, TTraits, TWire, TJs> {
-  readonly traits: TTraits;
-}
+  TInput = unknown,
+> = BaseCodec<Id, TTraits, TWire, TInput>;
+
+/**
+ * Conditional bundle for `encodeJson`/`decodeJson`: when `TInput` is
+ * structurally assignable to `JsonValue` the identity defaults are
+ * sound and both fields are optional; otherwise both fields are
+ * required so an author cannot silently produce a non-JSON-safe
+ * contract artifact.
+ */
+type JsonRoundTripConfig<TInput> = [TInput] extends [JsonValue]
+  ? {
+      encodeJson?: (value: TInput) => JsonValue;
+      decodeJson?: (json: JsonValue) => TInput;
+    }
+  : {
+      encodeJson: (value: TInput) => JsonValue;
+      decodeJson: (json: JsonValue) => TInput;
+    };
 
+/**
+ * Construct a Mongo codec from author functions.
+ *
+ * Author `encode` and `decode` as sync or async functions; the factory
+ * produces a {@link MongoCodec} whose query-time methods follow the
+ * boundary contract documented on the framework {@link BaseCodec}.
+ *
+ * `encode` is optional — when omitted, an identity default is installed
+ * (declaring "the input value already is the wire value", so `TInput` and
+ * `TWire` are interchangeable for that codec). `decode` is always
+ * required. `encodeJson` and `decodeJson` default to identity **only when
+ * `TInput` is assignable to `JsonValue`**; otherwise both are required so
+ * the contract artifact stays JSON-safe.
+ */
 export function mongoCodec<
   Id extends string,
   const TTraits extends readonly MongoCodecTrait[] = readonly [],
   TWire = unknown,
-  TJs = unknown,
->(config: {
-  typeId: Id;
-  targetTypes: readonly string[];
-  traits?: TTraits;
-  encode: (value: TJs) => TWire;
-  decode: (wire: TWire) => TJs;
-  encodeJson?: (value: TJs) => JsonValue;
-  decodeJson?: (json: JsonValue) => TJs;
-  renderOutputType?: (typeParams: Record<string, unknown>) => string | undefined;
-}): MongoCodec<Id, TTraits, TWire, TJs> {
-  const traits = config.traits
-    ? (Object.freeze([...config.traits]) as TTraits)
-    : (Object.freeze([] as const) as unknown as TTraits);
+  TInput = unknown,
+>(
+  config: {
+    typeId: Id;
+    targetTypes: readonly string[];
+    traits?: TTraits;
+    encode?: (value: TInput) => TWire | Promise<TWire>;
+    decode: (wire: TWire) => TInput | Promise<TInput>;
+    renderOutputType?: (typeParams: Record<string, unknown>) => string | undefined;
+  } & JsonRoundTripConfig<TInput>,
+): MongoCodec<Id, TTraits, TWire, TInput> {
   const identity = (v: unknown) => v;
+  // The synchronous identity default is only safe when the author has
+  // declared "the input is already the wire value" (i.e. TInput == TWire);
+  // it returns the value directly, never a Promise.
+  const userEncode = config.encode ?? ((value: TInput) => value as unknown as TWire);
+  const userDecode = config.decode;
+  const widenedConfig = config as {
+    encodeJson?: (value: TInput) => JsonValue;
+    decodeJson?: (json: JsonValue) => TInput;
+  };
   return {
     id: config.typeId,
     targetTypes: config.targetTypes,
-    traits,
-    decode: config.decode,
-    encode: config.encode,
-    encodeJson: (config.encodeJson ?? identity) as (value: TJs) => JsonValue,
-    decodeJson: (config.decodeJson ?? identity) as (json: JsonValue) => TJs,
-    ...(config.renderOutputType ? { renderOutputType: config.renderOutputType } : {}),
+    ...ifDefined(
+      'traits',
+      config.traits ? (Object.freeze([...config.traits]) as TTraits) : undefined,
+    ),
+    ...ifDefined('renderOutputType', config.renderOutputType),
+    encode: (value) => {
+      try {
+        return Promise.resolve(userEncode(value));
+      } catch (error) {
+        return Promise.reject(error);
+      }
+    },
+    decode: (wire) => {
+      try {
+        return Promise.resolve(userDecode(wire));
+      } catch (error) {
+        return Promise.reject(error);
+      }
+    },
+    encodeJson: (widenedConfig.encodeJson ?? identity) as (value: TInput) => JsonValue,
+    decodeJson: (widenedConfig.decodeJson ?? identity) as (json: JsonValue) => TInput,
   };
 }
 
-export type MongoCodecJsType<T> =
-  T extends MongoCodec<string, readonly MongoCodecTrait[], unknown, infer TJs> ? TJs : never;
+/** Extract the JS application type carried by a Mongo codec — used both as `encode` input and as `decode` output. */
+export type MongoCodecInput<T> =
+  T extends MongoCodec<string, readonly MongoCodecTrait[], unknown, infer TInput> ? TInput : never;
 
 export type MongoCodecTraits<T> =
   T extends MongoCodec<string, infer TTraits> ? TTraits[number] & MongoCodecTrait : never;

package/src/exports/index.ts

@@ -1,4 +1,9 @@
 export type { MongoCodecRegistry } from '../codec-registry';
 export { createMongoCodecRegistry } from '../codec-registry';
-export type { MongoCodec, MongoCodecJsType, MongoCodecTrait, MongoCodecTraits } from '../codecs';
+export type {
+  MongoCodec,
+  MongoCodecInput,
+  MongoCodecTrait,
+  MongoCodecTraits,
+} from '../codecs';
 export { mongoCodec } from '../codecs';