@smonn/ids 0.15.0 → 1.0.0-rc.1

package/dist/prisma.d.mts

@@ -1,9 +1,29 @@
 import { t as Id } from "./types-hGBnCpJj.mjs";
 import { n as IdColumnCodec } from "./adapter-types-Bia_w9sg.mjs";
 import { n as IdsErrorCode, r as isIdsError, t as IdsError } from "./error-CifcKKOG.mjs";
+import { ModelQueryOptionsCb } from "@prisma/client/runtime/library";
 
 //#region src/adapters/prisma.d.ts
 /**
+* Extension of {@link IdColumnCodec} that also exposes synchronous `generate()`.
+* Required by {@link idField} so that {@link IdTransform.defaultQuery} can produce
+* IDs at write time. Every full codec variant (Timestamp, Reverse Timestamp) satisfies
+* this; async-generate codecs (Opaque, Signed, Wrapped, Digest) do not and are
+* therefore unsupported by `defaultQuery`.
+*/
+type IdGeneratingCodec<Brand extends string> = IdColumnCodec<Brand> & {
+  generate(): Id<Brand>;
+};
+/**
+* The per-model object returned by {@link IdTransform.defaultQuery}, suitable for
+* the model-level value inside a Prisma `$extends({ query: { modelName: … } })` block.
+* Structurally identical to `{ [operation: string]: ModelQueryOptionsCb }` from
+* `@prisma/client/runtime/library`.
+*/
+type IdQueryField = {
+  [operation: string]: ModelQueryOptionsCb;
+};
+/**
 * Typed `$extends` result-component field definition produced by
 * {@link IdTransform.computeField} — a `{ needs, compute }` pair whose `compute`
 * return type is statically `Id<Brand>`, so the extended-client model field is
@@ -14,6 +34,15 @@ type IdComputeField<Brand extends string> = {
   compute: (model: Record<string, unknown>) => Id<Brand>;
 };
 /**
+* Typed `$extends` result-component field definition produced by
+* {@link IdTransform.computeNullableField} — like {@link IdComputeField} but
+* `compute` returns `Id<Brand> | null` for nullable columns.
+*/
+type NullableIdComputeField<Brand extends string> = {
+  needs: Record<string, boolean>;
+  compute: (model: Record<string, unknown>) => Id<Brand> | null;
+};
+/**
 * Read/write transform pair and `$extends` result-component factory for
 * integrating `Id<Brand>` with Prisma extensions.
 */
@@ -25,6 +54,11 @@ type IdTransform<Brand extends string> = {
   */
   read(value: unknown): Id<Brand>;
   /**
+  * Nullable read transform: returns `null` when `value` is `null` or `undefined`;
+  * otherwise delegates to {@link read}. Use for optional foreign keys.
+  */
+  readNullable(value: unknown): Id<Brand> | null;
+  /**
   * Write transform: passes `Id<Brand>` through as its canonical string form.
   * `Id<Brand>` is already the canonical string, so this is an identity function
   * at runtime.
@@ -51,16 +85,61 @@ type IdTransform<Brand extends string> = {
   * ```
   */
   computeField(fieldName: string): IdComputeField<Brand>;
+  /**
+  * Creates a `$extends` query-component model slice that auto-generates
+  * `Id<Brand>` values for `create`, `createMany`, and `upsert` operations
+  * when the field is absent, `undefined`, or `null` in `args.data` (or
+  * `args.create` for upsert). Explicitly supplied values are always passed
+  * through unchanged.
+  *
+  * @param fieldName - The model field to auto-generate (e.g. `"id"`).
+  * @returns An {@link IdQueryField} suitable for the model-level value inside
+  * a Prisma `$extends({ query: { modelName: … } })` block.
+  *
+  * @example
+  * ```ts
+  * const xprisma = prisma.$extends({
+  *   query: { user: userIdField.defaultQuery("id") },
+  *   result: { user: { id: userIdField.computeField("id") } },
+  * });
+  * // id is auto-filled on create, and typed as Id<"usr"> on read
+  * await xprisma.user.create({ data: { name: "Alice" } });
+  * ```
+  */
+  defaultQuery(fieldName: string): IdQueryField;
+  /**
+  * Like {@link computeField} but for nullable columns — `compute` returns
+  * `Id<Brand> | null` instead of `Id<Brand>`.
+  *
+  * @param fieldName - The nullable model field to read from.
+  * @returns A {@link NullableIdComputeField} whose `compute` returns `Id<Brand> | null`.
+  */
+  computeNullableField(fieldName: string): NullableIdComputeField<Brand>;
+};
+/**
+* The read/nullable-read/write surface returned by {@link nullableIdField} —
+* mirrors the nullable methods of {@link IdTransform} but omits `defaultQuery`,
+* `read`, and `computeField` since nullable FK columns neither auto-generate IDs
+* nor require a non-null read path at the top level.
+*/
+type NullableIdTransform<Brand extends string> = {
+  readNullable(value: unknown): Id<Brand> | null;
+  write(value: Id<Brand>): string;
+  computeNullableField(fieldName: string): NullableIdComputeField<Brand>;
 };
 /**
 * Creates a read/write transform pair for use with Prisma's `$extends` extension model.
 *
-* Works with any codec variant exposing `safeParse`.
+* Requires a codec variant that exposes a synchronous `generate()` in addition to `safeParse` — see {@link IdGeneratingCodec}. Only the **Timestamp codec** and **Reverse Timestamp codec** qualify; Opaque, Signed, Wrapped, and Digest codecs cannot be passed to `idField()`.
 *
 * Use `computeField(fieldName)` to produce a typed `$extends` result-component
 * field definition — the brand is carried through Prisma's type machinery
 * automatically and no per-call-site cast is required.
 *
+* For codecs that do not expose a synchronous `generate()` (Opaque Timestamp,
+* Signed Timestamp, Wrapped key, Digest), use {@link idFieldReadOnly} instead —
+* it accepts any {@link IdColumnCodec} and omits `defaultQuery`.
+*
 * @example
 * ```ts
 * import { idField } from "@smonn/ids/prisma";
@@ -77,7 +156,60 @@ type IdTransform<Brand extends string> = {
 * // xprisma.user.findUnique(…).id is typed as Id<"usr"> — no cast required
 * ```
 */
-declare function idField<Brand extends string>(codec: IdColumnCodec<Brand>): IdTransform<Brand>;
+declare function idField<Brand extends string>(codec: IdGeneratingCodec<Brand>): IdTransform<Brand>;
+/**
+* Standalone nullable counterpart of {@link idField} for Prisma adapter symmetry
+* with the other ORM adapters ({@link nullableIdColumn} in Drizzle/Kysely,
+* `nullableIdType` in MikroORM, `nullableIdTransformer` in TypeORM).
+*
+* Accepts any {@link IdColumnCodec} — no synchronous `generate()` required,
+* because nullable FK columns do not auto-generate IDs.
+*
+* @example
+* ```ts
+* import { nullableIdField } from "@smonn/ids/prisma";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+* const authorIdField = nullableIdField(usr);
+*
+* const xprisma = prisma.$extends({
+*   result: {
+*     post: { authorId: authorIdField.computeNullableField("authorId") },
+*   },
+* });
+* // xprisma.post.findUnique(…).authorId is typed as Id<"usr"> | null
+* ```
+*/
+declare function nullableIdField<Brand extends string>(codec: IdColumnCodec<Brand>): NullableIdTransform<Brand>;
+/**
+* Read-only sibling of {@link idField} for codec variants that do not expose a
+* synchronous `generate()` — Opaque Timestamp, Signed Timestamp, Wrapped key,
+* and Digest codecs all qualify.
+*
+* Accepts any {@link IdColumnCodec} (the wider constraint that only requires
+* `safeParse`) and returns the full read/transform surface of {@link IdTransform}
+* **minus `defaultQuery`**. Because `defaultQuery` is the only method that calls
+* `generate()`, callers who only need the read path are not forced to provide a
+* synchronous generator.
+*
+* @example
+* ```ts
+* import { idFieldReadOnly } from "@smonn/ids/prisma";
+* import { createOpaqueTimestampId } from "@smonn/ids/opaque";
+*
+* const inv = createOpaqueTimestampId("inv", { key });
+* const invoiceIdField = idFieldReadOnly(inv);
+*
+* const xprisma = prisma.$extends({
+*   result: {
+*     invoice: { id: invoiceIdField.computeField("id") },
+*   },
+* });
+* // xprisma.invoice.findUnique(…).id is typed as Id<"inv"> — no cast required
+* ```
+*/
+declare function idFieldReadOnly<Brand extends string>(codec: IdColumnCodec<Brand>): Omit<IdTransform<Brand>, "defaultQuery">;
 //#endregion
-export { type IdColumnCodec, IdComputeField, IdTransform, IdsError, type IdsErrorCode, idField, isIdsError };
+export { type IdColumnCodec, IdComputeField, IdGeneratingCodec, IdQueryField, IdTransform, IdsError, type IdsErrorCode, NullableIdComputeField, NullableIdTransform, idField, idFieldReadOnly, isIdsError, nullableIdField };
 //# sourceMappingURL=prisma.d.mts.map

package/dist/prisma.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"prisma.d.mts","names":[],"sources":["../src/adapters/prisma.ts"],"mappings":";;;;;AAcA;;;;;;AAAA,KAAY,cAAA;EACV,KAAA,EAAO,MAAA;EACP,OAAA,GAAU,KAAA,EAAO,MAAA,sBAA4B,EAAA,CAAG,KAAA;AAAA;;;;;KAOtC,WAAA;;;;AAPsC;AAOlD;EAME,IAAA,CAAK,KAAA,YAAiB,EAAA,CAAG,KAAA;;;;;;;;EAQzB,KAAA,CAAM,KAAA,EAAO,EAAA,CAAG,KAAA;EAmBiB;;;;;;;;;;;;;;;AAAe;AA4BlD;;EA5BE,YAAA,CAAa,SAAA,WAAoB,cAAA,CAAe,KAAA;AAAA;;;;;;;;;;;;;AA4BsC;;;;;;;;;;;;;iBAAxE,OAAA,uBAA8B,KAAA,EAAO,aAAA,CAAc,KAAA,IAAS,WAAA,CAAY,KAAA"}
+{"version":3,"file":"prisma.d.mts","names":[],"sources":["../src/adapters/prisma.ts"],"mappings":";;;;;;AAgBA;;;;;;;AAAA,KAAY,iBAAA,yBAA0C,aAAA,CAAc,KAAA;EAClE,QAAA,IAAY,EAAA,CAAG,KAAA;AAAA;;;;;;;KASL,YAAA;EAAA,CAAsC,SAAA,WAAA,mBAAA;AAAA;;;AAAA;AAQlD;;;KAAY,cAAA;EACV,KAAA,EAAO,MAAA;EACP,OAAA,GAAU,KAAA,EAAO,MAAA,sBAA4B,EAAA,CAAG,KAAA;AAAA;;;;;;KAQtC,sBAAA;EACV,KAAA,EAAO,MAAA;EACP,OAAA,GAAU,KAAA,EAAO,MAAA,sBAA4B,EAAA,CAAG,KAAA;AAAA;;;AAVA;AAQlD;KASY,WAAA;;;;;;EAMV,IAAA,CAAK,KAAA,YAAiB,EAAA,CAAG,KAAA;EAboB;;;;EAkB7C,YAAA,CAAa,KAAA,YAAiB,EAAA,CAAG,KAAA;;;;;;AAlBe;AAOlD;EAmBE,KAAA,CAAM,KAAA,EAAO,EAAA,CAAG,KAAA;;;;;;;;;;;;;;;;;;;EAmBhB,YAAA,CAAa,SAAA,WAAoB,cAAA,CAAe,KAAA;;;;;;;;;;;;;;;;;;;;;AA8BgB;EARhE,YAAA,CAAa,SAAA,WAAoB,YAAA;EAiBvB;;;;;;;EATV,oBAAA,CAAqB,SAAA,WAAoB,sBAAA,CAAuB,KAAA;AAAA;;;;;;;KAStD,mBAAA;EACV,YAAA,CAAa,KAAA,YAAiB,EAAA,CAAG,KAAA;EACjC,KAAA,CAAM,KAAA,EAAO,EAAA,CAAG,KAAA;EAChB,oBAAA,CAAqB,SAAA,WAAoB,sBAAA,CAAuB,KAAA;AAAA;;;;;AAAA;AAgClE;;;;;;;;;;;;;;;;AAA4F;AA4F5F;;;;;;;iBA5FgB,OAAA,uBAA8B,KAAA,EAAO,iBAAA,CAAkB,KAAA,IAAS,WAAA,CAAY,KAAA;;;;;;;;;AA8FrE;AA6CvB;;;;;;;;;;;;;;;iBA/CgB,eAAA,uBACd,KAAA,EAAO,aAAA,CAAc,KAAA,IACpB,mBAAA,CAAoB,KAAA;;;AA+CH;;;;;;;;;;;;;;;;;;;;;;;;;iBAFJ,eAAA,uBACd,KAAA,EAAO,aAAA,CAAc,KAAA,IACpB,IAAA,CAAK,WAAA,CAAY,KAAA"}

package/dist/prisma.mjs

@@ -1,15 +1,19 @@
 import { n as isIdsError, t as IdsError } from "./error-Cp5qYZcv.mjs";
-import { t as readIdColumn } from "./adapter-types-7wWdELSh.mjs";
+import { n as readIdColumnNullable, t as readIdColumn } from "./adapter-types-CjzFNDcJ.mjs";
 //#region src/adapters/prisma.ts
 /**
 * Creates a read/write transform pair for use with Prisma's `$extends` extension model.
 *
-* Works with any codec variant exposing `safeParse`.
+* Requires a codec variant that exposes a synchronous `generate()` in addition to `safeParse` — see {@link IdGeneratingCodec}. Only the **Timestamp codec** and **Reverse Timestamp codec** qualify; Opaque, Signed, Wrapped, and Digest codecs cannot be passed to `idField()`.
 *
 * Use `computeField(fieldName)` to produce a typed `$extends` result-component
 * field definition — the brand is carried through Prisma's type machinery
 * automatically and no per-call-site cast is required.
 *
+* For codecs that do not expose a synchronous `generate()` (Opaque Timestamp,
+* Signed Timestamp, Wrapped key, Digest), use {@link idFieldReadOnly} instead —
+* it accepts any {@link IdColumnCodec} and omits `defaultQuery`.
+*
 * @example
 * ```ts
 * import { idField } from "@smonn/ids/prisma";
@@ -27,10 +31,138 @@ import { t as readIdColumn } from "./adapter-types-7wWdELSh.mjs";
 * ```
 */
 function idField(codec) {
+	const { generate } = codec;
+	return {
+		read(value) {
+			return readIdColumn(codec, value);
+		},
+		readNullable(value) {
+			return readIdColumnNullable(codec, value);
+		},
+		write(value) {
+			return value;
+		},
+		computeField(fieldName) {
+			return {
+				needs: { [fieldName]: true },
+				compute: (model) => readIdColumn(codec, model[fieldName])
+			};
+		},
+		defaultQuery(fieldName) {
+			function injectIfAbsent(data) {
+				if (data[fieldName] == null) return {
+					...data,
+					[fieldName]: generate()
+				};
+				return data;
+			}
+			return {
+				async create({ args, query }) {
+					const data = args.data;
+					return query(data != null ? {
+						...args,
+						data: injectIfAbsent(data)
+					} : args);
+				},
+				async createMany({ args, query }) {
+					const data = args.data;
+					return query(Array.isArray(data) ? {
+						...args,
+						data: data.map((item) => injectIfAbsent(item))
+					} : args);
+				},
+				async upsert({ args, query }) {
+					const createData = args.create;
+					return query(createData != null ? {
+						...args,
+						create: injectIfAbsent(createData)
+					} : args);
+				}
+			};
+		},
+		computeNullableField(fieldName) {
+			return {
+				needs: { [fieldName]: true },
+				compute: (model) => readIdColumnNullable(codec, model[fieldName])
+			};
+		}
+	};
+}
+/**
+* Standalone nullable counterpart of {@link idField} for Prisma adapter symmetry
+* with the other ORM adapters ({@link nullableIdColumn} in Drizzle/Kysely,
+* `nullableIdType` in MikroORM, `nullableIdTransformer` in TypeORM).
+*
+* Accepts any {@link IdColumnCodec} — no synchronous `generate()` required,
+* because nullable FK columns do not auto-generate IDs.
+*
+* @example
+* ```ts
+* import { nullableIdField } from "@smonn/ids/prisma";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+* const authorIdField = nullableIdField(usr);
+*
+* const xprisma = prisma.$extends({
+*   result: {
+*     post: { authorId: authorIdField.computeNullableField("authorId") },
+*   },
+* });
+* // xprisma.post.findUnique(…).authorId is typed as Id<"usr"> | null
+* ```
+*/
+function nullableIdField(codec) {
+	return {
+		readNullable(value) {
+			return readIdColumnNullable(codec, value);
+		},
+		write(value) {
+			return value;
+		},
+		computeNullableField(fieldName) {
+			return {
+				needs: { [fieldName]: true },
+				compute: (model) => readIdColumnNullable(codec, model[fieldName])
+			};
+		}
+	};
+}
+/**
+* Read-only sibling of {@link idField} for codec variants that do not expose a
+* synchronous `generate()` — Opaque Timestamp, Signed Timestamp, Wrapped key,
+* and Digest codecs all qualify.
+*
+* Accepts any {@link IdColumnCodec} (the wider constraint that only requires
+* `safeParse`) and returns the full read/transform surface of {@link IdTransform}
+* **minus `defaultQuery`**. Because `defaultQuery` is the only method that calls
+* `generate()`, callers who only need the read path are not forced to provide a
+* synchronous generator.
+*
+* @example
+* ```ts
+* import { idFieldReadOnly } from "@smonn/ids/prisma";
+* import { createOpaqueTimestampId } from "@smonn/ids/opaque";
+*
+* const inv = createOpaqueTimestampId("inv", { key });
+* const invoiceIdField = idFieldReadOnly(inv);
+*
+* const xprisma = prisma.$extends({
+*   result: {
+*     invoice: { id: invoiceIdField.computeField("id") },
+*   },
+* });
+* // xprisma.invoice.findUnique(…).id is typed as Id<"inv"> — no cast required
+* ```
+*/
+function idFieldReadOnly(codec) {
 	return {
 		read(value) {
 			return readIdColumn(codec, value);
 		},
+		readNullable(value) {
+			return readIdColumnNullable(codec, value);
+		},
 		write(value) {
 			return value;
 		},
@@ -39,10 +171,16 @@ function idField(codec) {
 				needs: { [fieldName]: true },
 				compute: (model) => readIdColumn(codec, model[fieldName])
 			};
+		},
+		computeNullableField(fieldName) {
+			return {
+				needs: { [fieldName]: true },
+				compute: (model) => readIdColumnNullable(codec, model[fieldName])
+			};
 		}
 	};
 }
 //#endregion
-export { IdsError, idField, isIdsError };
+export { IdsError, idField, idFieldReadOnly, isIdsError, nullableIdField };
 
 //# sourceMappingURL=prisma.mjs.map

package/dist/prisma.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"prisma.mjs","names":[],"sources":["../src/adapters/prisma.ts"],"sourcesContent":["import { readIdColumn, type IdColumnCodec } from \"./adapter-types.js\";\nimport type { Id } from \"../types.js\";\n\n/** {@link IdsError} class, {@link isIdsError} type guard, and {@link IdsErrorCode} union — re-exported from `\"@smonn/ids\"` for convenience. */\nexport { IdsError, isIdsError, type IdsErrorCode } from \"../error.js\";\n\nexport type { IdColumnCodec };\n\n/**\n * Typed `$extends` result-component field definition produced by\n * {@link IdTransform.computeField} — a `{ needs, compute }` pair whose `compute`\n * return type is statically `Id<Brand>`, so the extended-client model field is\n * typed correctly without a per-call-site cast.\n */\nexport type IdComputeField<Brand extends string> = {\n  needs: Record<string, boolean>;\n  compute: (model: Record<string, unknown>) => Id<Brand>;\n};\n\n/**\n * Read/write transform pair and `$extends` result-component factory for\n * integrating `Id<Brand>` with Prisma extensions.\n */\nexport type IdTransform<Brand extends string> = {\n  /**\n   * Read transform: validates the raw database value via `safeParse` and returns\n   * `Id<Brand>`. Throws if the value is missing, malformed, or belongs to a\n   * different brand.\n   */\n  read(value: unknown): Id<Brand>;\n  /**\n   * Write transform: passes `Id<Brand>` through as its canonical string form.\n   * `Id<Brand>` is already the canonical string, so this is an identity function\n   * at runtime.\n   *\n   * Use in a Prisma `$extends` query component or explicit `data` mapping.\n   */\n  write(value: Id<Brand>): string;\n  /**\n   * Creates a typed `$extends` result-component field definition that carries\n   * `Id<Brand>` through Prisma's type machinery without a per-call-site cast.\n   *\n   * @param fieldName - The model field to read from (e.g. `\"id\"`).\n   * @returns An {@link IdComputeField} whose `compute` return type is statically\n   * `Id<Brand>`, so the extended-client model field is typed correctly.\n   *\n   * @example\n   * ```ts\n   * const xprisma = prisma.$extends({\n   *   result: {\n   *     user: { id: userIdField.computeField(\"id\") },\n   *   },\n   * });\n   * // xprisma.user.findUnique(…).id is typed as Id<\"usr\"> — no cast required\n   * ```\n   */\n  computeField(fieldName: string): IdComputeField<Brand>;\n};\n\n/**\n * Creates a read/write transform pair for use with Prisma's `$extends` extension model.\n *\n * Works with any codec variant exposing `safeParse`.\n *\n * Use `computeField(fieldName)` to produce a typed `$extends` result-component\n * field definition — the brand is carried through Prisma's type machinery\n * automatically and no per-call-site cast is required.\n *\n * @example\n * ```ts\n * import { idField } from \"@smonn/ids/prisma\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n * const userIdField = idField(usr);\n *\n * const xprisma = prisma.$extends({\n *   result: {\n *     user: { id: userIdField.computeField(\"id\") },\n *   },\n * });\n * // xprisma.user.findUnique(…).id is typed as Id<\"usr\"> — no cast required\n * ```\n */\nexport function idField<Brand extends string>(codec: IdColumnCodec<Brand>): IdTransform<Brand> {\n  return {\n    read(value: unknown): Id<Brand> {\n      return readIdColumn(codec, value);\n    },\n    write(value: Id<Brand>): string {\n      return value;\n    },\n    computeField(fieldName: string) {\n      return {\n        needs: { [fieldName]: true },\n        // Prisma's $extends types `compute` as returning `any` in its constraint\n        // type (DynamicResultExtensionArgs). Returning a pre-built object with an\n        // explicit Id<Brand> return type on `compute` causes TypeScript to infer\n        // the brand through the `& R` intersection in $extends — encapsulating\n        // the single necessary cast here rather than pushing it to every call site.\n        compute: (model: Record<string, unknown>): Id<Brand> =>\n          readIdColumn(codec, model[fieldName]),\n      };\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoFA,SAAgB,QAA8B,OAAiD;CAC7F,OAAO;EACL,KAAK,OAA2B;GAC9B,OAAO,aAAa,OAAO,KAAK;EAClC;EACA,MAAM,OAA0B;GAC9B,OAAO;EACT;EACA,aAAa,WAAmB;GAC9B,OAAO;IACL,OAAO,GAAG,YAAY,KAAK;IAM3B,UAAU,UACR,aAAa,OAAO,MAAM,UAAU;GACxC;EACF;CACF;AACF"}
+{"version":3,"file":"prisma.mjs","names":[],"sources":["../src/adapters/prisma.ts"],"sourcesContent":["import type { ModelQueryOptionsCb, ModelQueryOptionsCbArgs } from \"@prisma/client/runtime/library\";\nimport { readIdColumn, readIdColumnNullable, type IdColumnCodec } from \"./adapter-types.js\";\nimport type { Id } from \"../types.js\";\n\n/** {@link IdsError} class, {@link isIdsError} type guard, and {@link IdsErrorCode} union — re-exported from `\"@smonn/ids\"` for convenience. */\nexport { IdsError, isIdsError, type IdsErrorCode } from \"../error.js\";\n\nexport type { IdColumnCodec };\n\n/**\n * Extension of {@link IdColumnCodec} that also exposes synchronous `generate()`.\n * Required by {@link idField} so that {@link IdTransform.defaultQuery} can produce\n * IDs at write time. Every full codec variant (Timestamp, Reverse Timestamp) satisfies\n * this; async-generate codecs (Opaque, Signed, Wrapped, Digest) do not and are\n * therefore unsupported by `defaultQuery`.\n */\nexport type IdGeneratingCodec<Brand extends string> = IdColumnCodec<Brand> & {\n  generate(): Id<Brand>;\n};\n\n/**\n * The per-model object returned by {@link IdTransform.defaultQuery}, suitable for\n * the model-level value inside a Prisma `$extends({ query: { modelName: … } })` block.\n * Structurally identical to `{ [operation: string]: ModelQueryOptionsCb }` from\n * `@prisma/client/runtime/library`.\n */\nexport type IdQueryField = { [operation: string]: ModelQueryOptionsCb };\n\n/**\n * Typed `$extends` result-component field definition produced by\n * {@link IdTransform.computeField} — a `{ needs, compute }` pair whose `compute`\n * return type is statically `Id<Brand>`, so the extended-client model field is\n * typed correctly without a per-call-site cast.\n */\nexport type IdComputeField<Brand extends string> = {\n  needs: Record<string, boolean>;\n  compute: (model: Record<string, unknown>) => Id<Brand>;\n};\n\n/**\n * Typed `$extends` result-component field definition produced by\n * {@link IdTransform.computeNullableField} — like {@link IdComputeField} but\n * `compute` returns `Id<Brand> | null` for nullable columns.\n */\nexport type NullableIdComputeField<Brand extends string> = {\n  needs: Record<string, boolean>;\n  compute: (model: Record<string, unknown>) => Id<Brand> | null;\n};\n\n/**\n * Read/write transform pair and `$extends` result-component factory for\n * integrating `Id<Brand>` with Prisma extensions.\n */\nexport type IdTransform<Brand extends string> = {\n  /**\n   * Read transform: validates the raw database value via `safeParse` and returns\n   * `Id<Brand>`. Throws if the value is missing, malformed, or belongs to a\n   * different brand.\n   */\n  read(value: unknown): Id<Brand>;\n  /**\n   * Nullable read transform: returns `null` when `value` is `null` or `undefined`;\n   * otherwise delegates to {@link read}. Use for optional foreign keys.\n   */\n  readNullable(value: unknown): Id<Brand> | null;\n  /**\n   * Write transform: passes `Id<Brand>` through as its canonical string form.\n   * `Id<Brand>` is already the canonical string, so this is an identity function\n   * at runtime.\n   *\n   * Use in a Prisma `$extends` query component or explicit `data` mapping.\n   */\n  write(value: Id<Brand>): string;\n  /**\n   * Creates a typed `$extends` result-component field definition that carries\n   * `Id<Brand>` through Prisma's type machinery without a per-call-site cast.\n   *\n   * @param fieldName - The model field to read from (e.g. `\"id\"`).\n   * @returns An {@link IdComputeField} whose `compute` return type is statically\n   * `Id<Brand>`, so the extended-client model field is typed correctly.\n   *\n   * @example\n   * ```ts\n   * const xprisma = prisma.$extends({\n   *   result: {\n   *     user: { id: userIdField.computeField(\"id\") },\n   *   },\n   * });\n   * // xprisma.user.findUnique(…).id is typed as Id<\"usr\"> — no cast required\n   * ```\n   */\n  computeField(fieldName: string): IdComputeField<Brand>;\n  /**\n   * Creates a `$extends` query-component model slice that auto-generates\n   * `Id<Brand>` values for `create`, `createMany`, and `upsert` operations\n   * when the field is absent, `undefined`, or `null` in `args.data` (or\n   * `args.create` for upsert). Explicitly supplied values are always passed\n   * through unchanged.\n   *\n   * @param fieldName - The model field to auto-generate (e.g. `\"id\"`).\n   * @returns An {@link IdQueryField} suitable for the model-level value inside\n   * a Prisma `$extends({ query: { modelName: … } })` block.\n   *\n   * @example\n   * ```ts\n   * const xprisma = prisma.$extends({\n   *   query: { user: userIdField.defaultQuery(\"id\") },\n   *   result: { user: { id: userIdField.computeField(\"id\") } },\n   * });\n   * // id is auto-filled on create, and typed as Id<\"usr\"> on read\n   * await xprisma.user.create({ data: { name: \"Alice\" } });\n   * ```\n   */\n  defaultQuery(fieldName: string): IdQueryField;\n  /**\n   * Like {@link computeField} but for nullable columns — `compute` returns\n   * `Id<Brand> | null` instead of `Id<Brand>`.\n   *\n   * @param fieldName - The nullable model field to read from.\n   * @returns A {@link NullableIdComputeField} whose `compute` returns `Id<Brand> | null`.\n   */\n  computeNullableField(fieldName: string): NullableIdComputeField<Brand>;\n};\n\n/**\n * The read/nullable-read/write surface returned by {@link nullableIdField} —\n * mirrors the nullable methods of {@link IdTransform} but omits `defaultQuery`,\n * `read`, and `computeField` since nullable FK columns neither auto-generate IDs\n * nor require a non-null read path at the top level.\n */\nexport type NullableIdTransform<Brand extends string> = {\n  readNullable(value: unknown): Id<Brand> | null;\n  write(value: Id<Brand>): string;\n  computeNullableField(fieldName: string): NullableIdComputeField<Brand>;\n};\n\n/**\n * Creates a read/write transform pair for use with Prisma's `$extends` extension model.\n *\n * Requires a codec variant that exposes a synchronous `generate()` in addition to `safeParse` — see {@link IdGeneratingCodec}. Only the **Timestamp codec** and **Reverse Timestamp codec** qualify; Opaque, Signed, Wrapped, and Digest codecs cannot be passed to `idField()`.\n *\n * Use `computeField(fieldName)` to produce a typed `$extends` result-component\n * field definition — the brand is carried through Prisma's type machinery\n * automatically and no per-call-site cast is required.\n *\n * For codecs that do not expose a synchronous `generate()` (Opaque Timestamp,\n * Signed Timestamp, Wrapped key, Digest), use {@link idFieldReadOnly} instead —\n * it accepts any {@link IdColumnCodec} and omits `defaultQuery`.\n *\n * @example\n * ```ts\n * import { idField } from \"@smonn/ids/prisma\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n * const userIdField = idField(usr);\n *\n * const xprisma = prisma.$extends({\n *   result: {\n *     user: { id: userIdField.computeField(\"id\") },\n *   },\n * });\n * // xprisma.user.findUnique(…).id is typed as Id<\"usr\"> — no cast required\n * ```\n */\nexport function idField<Brand extends string>(codec: IdGeneratingCodec<Brand>): IdTransform<Brand> {\n  const { generate } = codec;\n  return {\n    read(value: unknown): Id<Brand> {\n      return readIdColumn(codec, value);\n    },\n    readNullable(value: unknown): Id<Brand> | null {\n      return readIdColumnNullable(codec, value);\n    },\n    write(value: Id<Brand>): string {\n      return value;\n    },\n    computeField(fieldName: string) {\n      return {\n        needs: { [fieldName]: true },\n        // Prisma's $extends types `compute` as returning `any` in its constraint\n        // type (DynamicResultExtensionArgs). Returning a pre-built object with an\n        // explicit Id<Brand> return type on `compute` causes TypeScript to infer\n        // the brand through the `& R` intersection in $extends — encapsulating\n        // the single necessary cast here rather than pushing it to every call site.\n        compute: (model: Record<string, unknown>): Id<Brand> =>\n          readIdColumn(codec, model[fieldName]),\n      };\n    },\n    defaultQuery(fieldName: string): IdQueryField {\n      function injectIfAbsent(data: Record<string, unknown>): Record<string, unknown> {\n        if (data[fieldName] == null) {\n          return { ...data, [fieldName]: generate() };\n        }\n        return data;\n      }\n\n      type QueryArg = Parameters<ModelQueryOptionsCbArgs[\"query\"]>[0];\n\n      return {\n        async create({ args, query }) {\n          const data = args.data as Record<string, unknown> | null | undefined;\n          const nextArgs =\n            data != null ? ({ ...args, data: injectIfAbsent(data) } as unknown as QueryArg) : args;\n          return query(nextArgs);\n        },\n        async createMany({ args, query }) {\n          const data = args.data as Array<Record<string, unknown>> | null | undefined;\n          const nextArgs = Array.isArray(data)\n            ? ({ ...args, data: data.map((item) => injectIfAbsent(item)) } as unknown as QueryArg)\n            : args;\n          return query(nextArgs);\n        },\n        async upsert({ args, query }) {\n          const createData = args.create as Record<string, unknown> | null | undefined;\n          const nextArgs =\n            createData != null\n              ? ({ ...args, create: injectIfAbsent(createData) } as unknown as QueryArg)\n              : args;\n          return query(nextArgs);\n        },\n      };\n    },\n    computeNullableField(fieldName: string) {\n      return {\n        needs: { [fieldName]: true },\n        compute: (model: Record<string, unknown>): Id<Brand> | null =>\n          readIdColumnNullable(codec, model[fieldName]),\n      };\n    },\n  };\n}\n\n/**\n * Standalone nullable counterpart of {@link idField} for Prisma adapter symmetry\n * with the other ORM adapters ({@link nullableIdColumn} in Drizzle/Kysely,\n * `nullableIdType` in MikroORM, `nullableIdTransformer` in TypeORM).\n *\n * Accepts any {@link IdColumnCodec} — no synchronous `generate()` required,\n * because nullable FK columns do not auto-generate IDs.\n *\n * @example\n * ```ts\n * import { nullableIdField } from \"@smonn/ids/prisma\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n * const authorIdField = nullableIdField(usr);\n *\n * const xprisma = prisma.$extends({\n *   result: {\n *     post: { authorId: authorIdField.computeNullableField(\"authorId\") },\n *   },\n * });\n * // xprisma.post.findUnique(…).authorId is typed as Id<\"usr\"> | null\n * ```\n */\nexport function nullableIdField<Brand extends string>(\n  codec: IdColumnCodec<Brand>,\n): NullableIdTransform<Brand> {\n  return {\n    readNullable(value: unknown): Id<Brand> | null {\n      return readIdColumnNullable(codec, value);\n    },\n    write(value: Id<Brand>): string {\n      return value;\n    },\n    computeNullableField(fieldName: string) {\n      return {\n        needs: { [fieldName]: true },\n        compute: (model: Record<string, unknown>): Id<Brand> | null =>\n          readIdColumnNullable(codec, model[fieldName]),\n      };\n    },\n  };\n}\n\n/**\n * Read-only sibling of {@link idField} for codec variants that do not expose a\n * synchronous `generate()` — Opaque Timestamp, Signed Timestamp, Wrapped key,\n * and Digest codecs all qualify.\n *\n * Accepts any {@link IdColumnCodec} (the wider constraint that only requires\n * `safeParse`) and returns the full read/transform surface of {@link IdTransform}\n * **minus `defaultQuery`**. Because `defaultQuery` is the only method that calls\n * `generate()`, callers who only need the read path are not forced to provide a\n * synchronous generator.\n *\n * @example\n * ```ts\n * import { idFieldReadOnly } from \"@smonn/ids/prisma\";\n * import { createOpaqueTimestampId } from \"@smonn/ids/opaque\";\n *\n * const inv = createOpaqueTimestampId(\"inv\", { key });\n * const invoiceIdField = idFieldReadOnly(inv);\n *\n * const xprisma = prisma.$extends({\n *   result: {\n *     invoice: { id: invoiceIdField.computeField(\"id\") },\n *   },\n * });\n * // xprisma.invoice.findUnique(…).id is typed as Id<\"inv\"> — no cast required\n * ```\n */\nexport function idFieldReadOnly<Brand extends string>(\n  codec: IdColumnCodec<Brand>,\n): Omit<IdTransform<Brand>, \"defaultQuery\"> {\n  return {\n    read(value: unknown): Id<Brand> {\n      return readIdColumn(codec, value);\n    },\n    readNullable(value: unknown): Id<Brand> | null {\n      return readIdColumnNullable(codec, value);\n    },\n    write(value: Id<Brand>): string {\n      return value;\n    },\n    computeField(fieldName: string) {\n      return {\n        needs: { [fieldName]: true },\n        compute: (model: Record<string, unknown>): Id<Brand> =>\n          readIdColumn(codec, model[fieldName]),\n      };\n    },\n    computeNullableField(fieldName: string) {\n      return {\n        needs: { [fieldName]: true },\n        compute: (model: Record<string, unknown>): Id<Brand> | null =>\n          readIdColumnNullable(codec, model[fieldName]),\n      };\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqKA,SAAgB,QAA8B,OAAqD;CACjG,MAAM,EAAE,aAAa;CACrB,OAAO;EACL,KAAK,OAA2B;GAC9B,OAAO,aAAa,OAAO,KAAK;EAClC;EACA,aAAa,OAAkC;GAC7C,OAAO,qBAAqB,OAAO,KAAK;EAC1C;EACA,MAAM,OAA0B;GAC9B,OAAO;EACT;EACA,aAAa,WAAmB;GAC9B,OAAO;IACL,OAAO,GAAG,YAAY,KAAK;IAM3B,UAAU,UACR,aAAa,OAAO,MAAM,UAAU;GACxC;EACF;EACA,aAAa,WAAiC;GAC5C,SAAS,eAAe,MAAwD;IAC9E,IAAI,KAAK,cAAc,MACrB,OAAO;KAAE,GAAG;MAAO,YAAY,SAAS;IAAE;IAE5C,OAAO;GACT;GAIA,OAAO;IACL,MAAM,OAAO,EAAE,MAAM,SAAS;KAC5B,MAAM,OAAO,KAAK;KAGlB,OAAO,MADL,QAAQ,OAAQ;MAAE,GAAG;MAAM,MAAM,eAAe,IAAI;KAAE,IAA4B,IAC/D;IACvB;IACA,MAAM,WAAW,EAAE,MAAM,SAAS;KAChC,MAAM,OAAO,KAAK;KAIlB,OAAO,MAHU,MAAM,QAAQ,IAAI,IAC9B;MAAE,GAAG;MAAM,MAAM,KAAK,KAAK,SAAS,eAAe,IAAI,CAAC;KAAE,IAC3D,IACiB;IACvB;IACA,MAAM,OAAO,EAAE,MAAM,SAAS;KAC5B,MAAM,aAAa,KAAK;KAKxB,OAAO,MAHL,cAAc,OACT;MAAE,GAAG;MAAM,QAAQ,eAAe,UAAU;KAAE,IAC/C,IACe;IACvB;GACF;EACF;EACA,qBAAqB,WAAmB;GACtC,OAAO;IACL,OAAO,GAAG,YAAY,KAAK;IAC3B,UAAU,UACR,qBAAqB,OAAO,MAAM,UAAU;GAChD;EACF;CACF;AACF;;;;;;;;;;;;;;;;;;;;;;;;;AA0BA,SAAgB,gBACd,OAC4B;CAC5B,OAAO;EACL,aAAa,OAAkC;GAC7C,OAAO,qBAAqB,OAAO,KAAK;EAC1C;EACA,MAAM,OAA0B;GAC9B,OAAO;EACT;EACA,qBAAqB,WAAmB;GACtC,OAAO;IACL,OAAO,GAAG,YAAY,KAAK;IAC3B,UAAU,UACR,qBAAqB,OAAO,MAAM,UAAU;GAChD;EACF;CACF;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,SAAgB,gBACd,OAC0C;CAC1C,OAAO;EACL,KAAK,OAA2B;GAC9B,OAAO,aAAa,OAAO,KAAK;EAClC;EACA,aAAa,OAAkC;GAC7C,OAAO,qBAAqB,OAAO,KAAK;EAC1C;EACA,MAAM,OAA0B;GAC9B,OAAO;EACT;EACA,aAAa,WAAmB;GAC9B,OAAO;IACL,OAAO,GAAG,YAAY,KAAK;IAC3B,UAAU,UACR,aAAa,OAAO,MAAM,UAAU;GACxC;EACF;EACA,qBAAqB,WAAmB;GACtC,OAAO;IACL,OAAO,GAAG,YAAY,KAAK;IAC3B,UAAU,UACR,qBAAqB,OAAO,MAAM,UAAU;GAChD;EACF;CACF;AACF"}

package/dist/typeorm.d.mts

@@ -1,9 +1,20 @@
+import { t as Id } from "./types-hGBnCpJj.mjs";
 import { n as IdColumnCodec } from "./adapter-types-Bia_w9sg.mjs";
 import { n as IdsErrorCode, r as isIdsError, t as IdsError } from "./error-CifcKKOG.mjs";
 import { ValueTransformer } from "typeorm";
 
 //#region src/adapters/typeorm.d.ts
 /**
+* Extension of {@link IdColumnCodec} that also exposes synchronous `generate()`.
+* Required by {@link beforeInsertHook} so that the hook can produce IDs at insert
+* time. Every full codec variant (Timestamp, Reverse Timestamp) satisfies this;
+* async-generate codecs (Opaque, Signed, Wrapped, Digest) do not and are therefore
+* unsupported by `beforeInsertHook`.
+*/
+type IdGeneratingCodec<Brand extends string> = IdColumnCodec<Brand> & {
+  generate(): Id<Brand>;
+};
+/**
 * TypeORM column transformer for `Id<Brand>`.
 *
 * Returns a `ValueTransformer` object suitable for use in a TypeORM `@Column`
@@ -36,6 +47,78 @@ import { ValueTransformer } from "typeorm";
 * ```
 */
 declare function idTransformer<Brand extends string>(codec: IdColumnCodec<Brand>): ValueTransformer;
+/**
+* Returns a function suitable for use inside a TypeORM `@BeforeInsert()` lifecycle
+* hook that auto-generates an `Id<Brand>` for `fieldName` when the field is absent
+* (`null` or `undefined`) on the entity at insert time. If the field already has a
+* value it is left unchanged.
+*
+* Requires a codec variant that exposes a synchronous `generate()` — see
+* {@link IdGeneratingCodec}. Only the **Timestamp codec** and **Reverse Timestamp
+* codec** qualify; passing an async-generate codec (Opaque, Signed, Wrapped, Digest)
+* is a **compile-time type error**.
+*
+* Pair with {@link idTransformer} on the same column: `idTransformer` handles the
+* read/write path; `beforeInsertHook` handles generation.
+*
+* @example
+* ```ts
+* import { idTransformer, beforeInsertHook } from "@smonn/ids/typeorm";
+* import { createTimestampId } from "@smonn/ids";
+* import type { Id } from "@smonn/ids";
+* import { BeforeInsert, Column, Entity } from "typeorm";
+*
+* const usr = createTimestampId("usr");
+* const fillUserId = beforeInsertHook("id", usr);
+*
+* @Entity()
+* class User {
+*   @Column({ type: "text", transformer: idTransformer(usr) })
+*   id!: Id<"usr">;
+*
+*   @BeforeInsert()
+*   generateId() {
+*     fillUserId(this);
+*   }
+* }
+* ```
+*
+* @remarks
+* **Gating rule:** `beforeInsertHook` requires a synchronous `generate()` codec
+* (`IdGeneratingCodec`). Async-generate codecs — Opaque Timestamp, Signed Timestamp,
+* Wrapped key, and Digest — do not satisfy `IdGeneratingCodec` and cannot be passed
+* here. TypeORM `@BeforeInsert` can be async, but synchronous generation keeps the
+* hook ergonomic and matches the full Prisma parity shape.
+*
+* **Read/write path:** Use {@link idTransformer} on the column for database
+* read/write transforms. `beforeInsertHook` only handles the generation step — it
+* does not replace the transformer.
+*/
+declare function beforeInsertHook<Brand extends string>(fieldName: string, codec: IdGeneratingCodec<Brand>): (entity: Record<string, unknown>) => void;
+/**
+* TypeORM column transformer for a **nullable** `Id<Brand>` column.
+*
+* Behaves like {@link idTransformer} but `from` returns `null` for `null` /
+* `undefined` database values and `to` passes `null` / `undefined` through
+* unchanged. Use for optional foreign keys.
+*
+* @example
+* ```ts
+* import { nullableIdTransformer } from "@smonn/ids/typeorm";
+* import { createTimestampId } from "@smonn/ids";
+* import type { Id } from "@smonn/ids";
+* import { Column, Entity } from "typeorm";
+*
+* const usr = createTimestampId("usr");
+*
+* @Entity()
+* class Post {
+*   @Column({ type: "text", nullable: true, transformer: nullableIdTransformer(usr) })
+*   authorId!: Id<"usr"> | null;
+* }
+* ```
+*/
+declare function nullableIdTransformer<Brand extends string>(codec: IdColumnCodec<Brand>): ValueTransformer;
 //#endregion
-export { type IdColumnCodec, IdsError, type IdsErrorCode, idTransformer, isIdsError };
+export { type IdColumnCodec, IdGeneratingCodec, IdsError, type IdsErrorCode, beforeInsertHook, idTransformer, isIdsError, nullableIdTransformer };
 //# sourceMappingURL=typeorm.d.mts.map

package/dist/typeorm.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"typeorm.d.mts","names":[],"sources":["../src/adapters/typeorm.ts"],"mappings":";;;;;AAyCA;;;;;;;;;;;;;;AAAkF;;;;;;;;;;;;;;;;;;AAAlF,iBAAgB,aAAA,uBAAoC,KAAA,EAAO,aAAA,CAAc,KAAA,IAAS,gBAAA"}
+{"version":3,"file":"typeorm.d.mts","names":[],"sources":["../src/adapters/typeorm.ts"],"mappings":";;;;;;AAgBA;;;;;;;AAAA,KAAY,iBAAA,yBAA0C,aAAA,CAAc,KAAA;EAClE,QAAA,IAAY,EAAA,CAAG,KAAA;AAAA;;;;;;;AAAA;AAmCjB;;;;;;;;;;;;;;AAAkF;AA0DlF;;;;;;;;;;iBA1DgB,aAAA,uBAAoC,KAAA,EAAO,aAAA,CAAc,KAAA,IAAS,gBAAA;;;;;;AA6DtE;AA+BZ;;;;;;;;;;;;;;AAEG;;;;;;;;;;;;;;;;;;;;;;;;;;;iBApCa,gBAAA,uBACd,SAAA,UACA,KAAA,EAAO,iBAAA,CAAkB,KAAA,KACvB,MAAA,EAAQ,MAAA;;;;;;;;;;;;;;;;;;;;;;;;iBA+BI,qBAAA,uBACd,KAAA,EAAO,aAAA,CAAc,KAAA,IACpB,gBAAA"}

package/dist/typeorm.mjs

@@ -1,5 +1,5 @@
 import { n as isIdsError, t as IdsError } from "./error-Cp5qYZcv.mjs";
-import { t as readIdColumn } from "./adapter-types-7wWdELSh.mjs";
+import { n as readIdColumnNullable, t as readIdColumn } from "./adapter-types-CjzFNDcJ.mjs";
 //#region src/adapters/typeorm.ts
 /**
 * TypeORM column transformer for `Id<Brand>`.
@@ -43,7 +43,92 @@ function idTransformer(codec) {
 		}
 	};
 }
+/**
+* Returns a function suitable for use inside a TypeORM `@BeforeInsert()` lifecycle
+* hook that auto-generates an `Id<Brand>` for `fieldName` when the field is absent
+* (`null` or `undefined`) on the entity at insert time. If the field already has a
+* value it is left unchanged.
+*
+* Requires a codec variant that exposes a synchronous `generate()` — see
+* {@link IdGeneratingCodec}. Only the **Timestamp codec** and **Reverse Timestamp
+* codec** qualify; passing an async-generate codec (Opaque, Signed, Wrapped, Digest)
+* is a **compile-time type error**.
+*
+* Pair with {@link idTransformer} on the same column: `idTransformer` handles the
+* read/write path; `beforeInsertHook` handles generation.
+*
+* @example
+* ```ts
+* import { idTransformer, beforeInsertHook } from "@smonn/ids/typeorm";
+* import { createTimestampId } from "@smonn/ids";
+* import type { Id } from "@smonn/ids";
+* import { BeforeInsert, Column, Entity } from "typeorm";
+*
+* const usr = createTimestampId("usr");
+* const fillUserId = beforeInsertHook("id", usr);
+*
+* @Entity()
+* class User {
+*   @Column({ type: "text", transformer: idTransformer(usr) })
+*   id!: Id<"usr">;
+*
+*   @BeforeInsert()
+*   generateId() {
+*     fillUserId(this);
+*   }
+* }
+* ```
+*
+* @remarks
+* **Gating rule:** `beforeInsertHook` requires a synchronous `generate()` codec
+* (`IdGeneratingCodec`). Async-generate codecs — Opaque Timestamp, Signed Timestamp,
+* Wrapped key, and Digest — do not satisfy `IdGeneratingCodec` and cannot be passed
+* here. TypeORM `@BeforeInsert` can be async, but synchronous generation keeps the
+* hook ergonomic and matches the full Prisma parity shape.
+*
+* **Read/write path:** Use {@link idTransformer} on the column for database
+* read/write transforms. `beforeInsertHook` only handles the generation step — it
+* does not replace the transformer.
+*/
+function beforeInsertHook(fieldName, codec) {
+	return function(entity) {
+		if (entity[fieldName] == null) entity[fieldName] = codec.generate();
+	};
+}
+/**
+* TypeORM column transformer for a **nullable** `Id<Brand>` column.
+*
+* Behaves like {@link idTransformer} but `from` returns `null` for `null` /
+* `undefined` database values and `to` passes `null` / `undefined` through
+* unchanged. Use for optional foreign keys.
+*
+* @example
+* ```ts
+* import { nullableIdTransformer } from "@smonn/ids/typeorm";
+* import { createTimestampId } from "@smonn/ids";
+* import type { Id } from "@smonn/ids";
+* import { Column, Entity } from "typeorm";
+*
+* const usr = createTimestampId("usr");
+*
+* @Entity()
+* class Post {
+*   @Column({ type: "text", nullable: true, transformer: nullableIdTransformer(usr) })
+*   authorId!: Id<"usr"> | null;
+* }
+* ```
+*/
+function nullableIdTransformer(codec) {
+	return {
+		to(value) {
+			return value;
+		},
+		from(value) {
+			return readIdColumnNullable(codec, value);
+		}
+	};
+}
 //#endregion
-export { IdsError, idTransformer, isIdsError };
+export { IdsError, beforeInsertHook, idTransformer, isIdsError, nullableIdTransformer };
 
 //# sourceMappingURL=typeorm.mjs.map

package/dist/typeorm.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"typeorm.mjs","names":[],"sources":["../src/adapters/typeorm.ts"],"sourcesContent":["import type { ValueTransformer } from \"typeorm\";\nimport { readIdColumn, type IdColumnCodec } from \"./adapter-types.js\";\nimport type { Id } from \"../types.js\";\n\n/** {@link IdsError} class, {@link isIdsError} type guard, and {@link IdsErrorCode} union — re-exported from `\"@smonn/ids\"` for convenience. */\nexport { IdsError, isIdsError, type IdsErrorCode } from \"../error.js\";\n\nexport type { IdColumnCodec };\n\n/**\n * TypeORM column transformer for `Id<Brand>`.\n *\n * Returns a `ValueTransformer` object suitable for use in a TypeORM `@Column`\n * decorator's `transformer` option.\n *\n * **Write path (`to`):** passes the `Id<Brand>` directly to the database — it is\n * already the canonical string form.\n *\n * **Read path (`from`):** normalises the raw database value via `codec.safeParse()`.\n * Throws `IdsError` with code `\"invalid_id\"` if the value does not parse as a valid\n * `Id<Brand>`.\n *\n * **TypeORM branding caveat:** TypeORM cannot brand a generated entity field type at\n * the schema level. Annotate the entity field explicitly: `id!: Id<\"usr\">`.\n *\n * @example\n * ```ts\n * import { idTransformer } from \"@smonn/ids/typeorm\";\n * import { createTimestampId } from \"@smonn/ids\";\n * import type { Id } from \"@smonn/ids\";\n * import { Column, Entity } from \"typeorm\";\n *\n * const usr = createTimestampId(\"usr\");\n *\n * @Entity()\n * class User {\n *   @Column({ type: \"text\", transformer: idTransformer(usr) })\n *   id!: Id<\"usr\">;\n * }\n * ```\n */\nexport function idTransformer<Brand extends string>(codec: IdColumnCodec<Brand>): ValueTransformer {\n  return {\n    to(value: Id<Brand>): string {\n      return value;\n    },\n    from(value: unknown): Id<Brand> {\n      return readIdColumn(codec, value);\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,SAAgB,cAAoC,OAA+C;CACjG,OAAO;EACL,GAAG,OAA0B;GAC3B,OAAO;EACT;EACA,KAAK,OAA2B;GAC9B,OAAO,aAAa,OAAO,KAAK;EAClC;CACF;AACF"}
+{"version":3,"file":"typeorm.mjs","names":[],"sources":["../src/adapters/typeorm.ts"],"sourcesContent":["import type { ValueTransformer } from \"typeorm\";\nimport { readIdColumn, readIdColumnNullable, type IdColumnCodec } from \"./adapter-types.js\";\nimport type { Id } from \"../types.js\";\n\n/** {@link IdsError} class, {@link isIdsError} type guard, and {@link IdsErrorCode} union — re-exported from `\"@smonn/ids\"` for convenience. */\nexport { IdsError, isIdsError, type IdsErrorCode } from \"../error.js\";\n\nexport type { IdColumnCodec };\n\n/**\n * Extension of {@link IdColumnCodec} that also exposes synchronous `generate()`.\n * Required by {@link beforeInsertHook} so that the hook can produce IDs at insert\n * time. Every full codec variant (Timestamp, Reverse Timestamp) satisfies this;\n * async-generate codecs (Opaque, Signed, Wrapped, Digest) do not and are therefore\n * unsupported by `beforeInsertHook`.\n */\nexport type IdGeneratingCodec<Brand extends string> = IdColumnCodec<Brand> & {\n  generate(): Id<Brand>;\n};\n\n/**\n * TypeORM column transformer for `Id<Brand>`.\n *\n * Returns a `ValueTransformer` object suitable for use in a TypeORM `@Column`\n * decorator's `transformer` option.\n *\n * **Write path (`to`):** passes the `Id<Brand>` directly to the database — it is\n * already the canonical string form.\n *\n * **Read path (`from`):** normalises the raw database value via `codec.safeParse()`.\n * Throws `IdsError` with code `\"invalid_id\"` if the value does not parse as a valid\n * `Id<Brand>`.\n *\n * **TypeORM branding caveat:** TypeORM cannot brand a generated entity field type at\n * the schema level. Annotate the entity field explicitly: `id!: Id<\"usr\">`.\n *\n * @example\n * ```ts\n * import { idTransformer } from \"@smonn/ids/typeorm\";\n * import { createTimestampId } from \"@smonn/ids\";\n * import type { Id } from \"@smonn/ids\";\n * import { Column, Entity } from \"typeorm\";\n *\n * const usr = createTimestampId(\"usr\");\n *\n * @Entity()\n * class User {\n *   @Column({ type: \"text\", transformer: idTransformer(usr) })\n *   id!: Id<\"usr\">;\n * }\n * ```\n */\nexport function idTransformer<Brand extends string>(codec: IdColumnCodec<Brand>): ValueTransformer {\n  return {\n    to(value: Id<Brand>): string {\n      return value;\n    },\n    from(value: unknown): Id<Brand> {\n      return readIdColumn(codec, value);\n    },\n  };\n}\n\n/**\n * Returns a function suitable for use inside a TypeORM `@BeforeInsert()` lifecycle\n * hook that auto-generates an `Id<Brand>` for `fieldName` when the field is absent\n * (`null` or `undefined`) on the entity at insert time. If the field already has a\n * value it is left unchanged.\n *\n * Requires a codec variant that exposes a synchronous `generate()` — see\n * {@link IdGeneratingCodec}. Only the **Timestamp codec** and **Reverse Timestamp\n * codec** qualify; passing an async-generate codec (Opaque, Signed, Wrapped, Digest)\n * is a **compile-time type error**.\n *\n * Pair with {@link idTransformer} on the same column: `idTransformer` handles the\n * read/write path; `beforeInsertHook` handles generation.\n *\n * @example\n * ```ts\n * import { idTransformer, beforeInsertHook } from \"@smonn/ids/typeorm\";\n * import { createTimestampId } from \"@smonn/ids\";\n * import type { Id } from \"@smonn/ids\";\n * import { BeforeInsert, Column, Entity } from \"typeorm\";\n *\n * const usr = createTimestampId(\"usr\");\n * const fillUserId = beforeInsertHook(\"id\", usr);\n *\n * @Entity()\n * class User {\n *   @Column({ type: \"text\", transformer: idTransformer(usr) })\n *   id!: Id<\"usr\">;\n *\n *   @BeforeInsert()\n *   generateId() {\n *     fillUserId(this);\n *   }\n * }\n * ```\n *\n * @remarks\n * **Gating rule:** `beforeInsertHook` requires a synchronous `generate()` codec\n * (`IdGeneratingCodec`). Async-generate codecs — Opaque Timestamp, Signed Timestamp,\n * Wrapped key, and Digest — do not satisfy `IdGeneratingCodec` and cannot be passed\n * here. TypeORM `@BeforeInsert` can be async, but synchronous generation keeps the\n * hook ergonomic and matches the full Prisma parity shape.\n *\n * **Read/write path:** Use {@link idTransformer} on the column for database\n * read/write transforms. `beforeInsertHook` only handles the generation step — it\n * does not replace the transformer.\n */\nexport function beforeInsertHook<Brand extends string>(\n  fieldName: string,\n  codec: IdGeneratingCodec<Brand>,\n): (entity: Record<string, unknown>) => void {\n  return function (entity: Record<string, unknown>): void {\n    if (entity[fieldName] == null) {\n      entity[fieldName] = codec.generate();\n    }\n  };\n}\n\n/**\n * TypeORM column transformer for a **nullable** `Id<Brand>` column.\n *\n * Behaves like {@link idTransformer} but `from` returns `null` for `null` /\n * `undefined` database values and `to` passes `null` / `undefined` through\n * unchanged. Use for optional foreign keys.\n *\n * @example\n * ```ts\n * import { nullableIdTransformer } from \"@smonn/ids/typeorm\";\n * import { createTimestampId } from \"@smonn/ids\";\n * import type { Id } from \"@smonn/ids\";\n * import { Column, Entity } from \"typeorm\";\n *\n * const usr = createTimestampId(\"usr\");\n *\n * @Entity()\n * class Post {\n *   @Column({ type: \"text\", nullable: true, transformer: nullableIdTransformer(usr) })\n *   authorId!: Id<\"usr\"> | null;\n * }\n * ```\n */\nexport function nullableIdTransformer<Brand extends string>(\n  codec: IdColumnCodec<Brand>,\n): ValueTransformer {\n  return {\n    to(value: Id<Brand> | null | undefined): string | null | undefined {\n      return value;\n    },\n    from(value: unknown): Id<Brand> | null {\n      return readIdColumnNullable(codec, value);\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoDA,SAAgB,cAAoC,OAA+C;CACjG,OAAO;EACL,GAAG,OAA0B;GAC3B,OAAO;EACT;EACA,KAAK,OAA2B;GAC9B,OAAO,aAAa,OAAO,KAAK;EAClC;CACF;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiDA,SAAgB,iBACd,WACA,OAC2C;CAC3C,OAAO,SAAU,QAAuC;EACtD,IAAI,OAAO,cAAc,MACvB,OAAO,aAAa,MAAM,SAAS;CAEvC;AACF;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,SAAgB,sBACd,OACkB;CAClB,OAAO;EACL,GAAG,OAAgE;GACjE,OAAO;EACT;EACA,KAAK,OAAkC;GACrC,OAAO,qBAAqB,OAAO,KAAK;EAC1C;CACF;AACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smonn/ids",
-  "version": "0.15.0",
+  "version": "1.0.0-rc.1",
   "license": "MIT",
   "author": "Simon Ingeson (https://github.com/smonn)",
   "repository": {

package/dist/adapter-types-7wWdELSh.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"adapter-types-7wWdELSh.mjs","names":[],"sources":["../src/adapters/adapter-types.ts"],"sourcesContent":["import { IdsError } from \"../error.js\";\nimport type { Id, ParseError, ParseResult } from \"../types.js\";\n\n/** Discriminated failure value passed to `onError` and emitted to the framework's error handler. */\nexport type IdParamFailure =\n  | { readonly reason: \"brand_mismatch\"; readonly status: number }\n  | { readonly reason: \"malformed\"; readonly status: number };\n\n/** Minimum structural type required by web and ORM adapters. Any codec variant satisfies this — all expose `safeParse`. Adapters only ever call `safeParse` — never key-dependent methods like `extractTimestamp`, `wrap`, or `unwrap`. */\nexport type IdCodec<Brand extends string> = {\n  safeParse(value: unknown): ParseResult<Brand>;\n};\n\n/** Re-exported from ORM adapter subpaths (`@smonn/ids/drizzle`, `@smonn/ids/prisma`, `@smonn/ids/kysely`) under the public name; structurally identical to {@link IdCodec}. */\nexport type IdColumnCodec<Brand extends string> = IdCodec<Brand>;\n\n/** Parses `value` as `Id<Brand>` via `codec.safeParse`; throws `IdsError(\"invalid_id\")` on failure. Shared read helper for ORM adapters. */\nexport function readIdColumn<Brand extends string>(\n  codec: IdCodec<Brand>,\n  value: unknown,\n): Id<Brand> {\n  const result = codec.safeParse(value);\n  if (!result.ok) {\n    throw new IdsError(\"invalid_id\", `invalid ID from database: ${result.error}`, {\n      cause: result.error,\n    });\n  }\n  return result.id;\n}\n\n/**\n * Maps a `ParseError` to `{ reason, status }` for web adapter failure handling.\n *\n * - `invalid_prefix` → `brand_mismatch` / default 404\n * - anything else → `malformed` / default 400\n * - `options.status[reason]` overrides the default for that reason\n */\nexport function resolveIdParamFailure(\n  error: ParseError,\n  options?: { status?: { brand_mismatch?: number; malformed?: number } },\n): IdParamFailure {\n  const reason = error === \"invalid_prefix\" ? (\"brand_mismatch\" as const) : (\"malformed\" as const);\n  const defaultStatus = reason === \"brand_mismatch\" ? 404 : 400;\n  const status = options?.status?.[reason] ?? defaultStatus;\n  return { reason, status };\n}\n"],"mappings":";;;AAiBA,SAAgB,aACd,OACA,OACW;CACX,MAAM,SAAS,MAAM,UAAU,KAAK;CACpC,IAAI,CAAC,OAAO,IACV,MAAM,IAAI,SAAS,cAAc,6BAA6B,OAAO,SAAS,EAC5E,OAAO,OAAO,MAChB,CAAC;CAEH,OAAO,OAAO;AAChB;;;;;;;;AASA,SAAgB,sBACd,OACA,SACgB;CAChB,MAAM,SAAS,UAAU,mBAAoB,mBAA8B;CAC3E,MAAM,gBAAgB,WAAW,mBAAmB,MAAM;CAE1D,OAAO;EAAE;EAAQ,QADF,SAAS,SAAS,WAAW;CACpB;AAC1B"}