@smonn/ids 0.14.1 → 1.0.0-rc.0

package/dist/graphql.d.mts

@@ -1,5 +1,6 @@
 import { t as Id } from "./types-hGBnCpJj.mjs";
 import { t as IdCodec } from "./adapter-types-Bia_w9sg.mjs";
+import { n as IdsErrorCode, r as isIdsError, t as IdsError } from "./error-CifcKKOG.mjs";
 import { GraphQLScalarType } from "graphql";
 
 //#region src/adapters/graphql.d.ts
@@ -27,5 +28,5 @@ declare function idScalar<Brand extends string>(codec: IdCodec<Brand>, config: {
   description?: string;
 }): GraphQLScalarType<Id<Brand>, string>;
 //#endregion
-export { idScalar };
+export { IdsError, type IdsErrorCode, idScalar, isIdsError };
 //# sourceMappingURL=graphql.d.mts.map

package/dist/graphql.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"graphql.d.mts","names":[],"sources":["../src/adapters/graphql.ts"],"mappings":";;;;;;;AAwBA;;;;;;;;;;;;;;;;;iBAAgB,QAAA,uBACd,KAAA,EAAO,OAAA,CAAQ,KAAA,GACf,MAAA;EAAU,IAAA;EAAc,WAAA;AAAA,IACvB,iBAAA,CAAkB,EAAA,CAAG,KAAA"}
+{"version":3,"file":"graphql.d.mts","names":[],"sources":["../src/adapters/graphql.ts"],"mappings":";;;;;;;AA2BA;;;;;;;;;;;;;;;;;;iBAAgB,QAAA,uBACd,KAAA,EAAO,OAAA,CAAQ,KAAA,GACf,MAAA;EAAU,IAAA;EAAc,WAAA;AAAA,IACvB,iBAAA,CAAkB,EAAA,CAAG,KAAA"}

package/dist/graphql.mjs

@@ -1,3 +1,4 @@
+import { n as isIdsError, t as IdsError } from "./error-Cp5qYZcv.mjs";
 import { GraphQLError, GraphQLScalarType, Kind } from "graphql";
 //#region src/adapters/graphql.ts
 /**
@@ -37,6 +38,6 @@ function idScalar(codec, config) {
 	});
 }
 //#endregion
-export { idScalar };
+export { IdsError, idScalar, isIdsError };
 
 //# sourceMappingURL=graphql.mjs.map

package/dist/graphql.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"graphql.mjs","names":[],"sources":["../src/adapters/graphql.ts"],"sourcesContent":["import { GraphQLError, GraphQLScalarType, Kind } from \"graphql\";\nimport type { ValueNode } from \"graphql\";\nimport type { IdCodec } from \"./adapter-types.js\";\nimport type { Id } from \"../types.js\";\n\n/**\n * Builds a `GraphQLScalarType` for the given codec and brand.\n *\n * - `serialize` — validates via `codec.safeParse`; throws `GraphQLError` on a non-conforming value.\n * - `parseValue` — validates variables via `codec.safeParse`; throws `GraphQLError` on failure.\n * - `parseLiteral` — validates inline `Kind.STRING` literals; throws `GraphQLError` for any\n *   other AST kind or on a failed `safeParse`.\n *\n * `graphql` must be installed as a peer dependency.\n *\n * @example\n * ```ts\n * import { idScalar } from \"@smonn/ids/graphql\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n * const UserIdScalar = idScalar(usr, { name: \"UserId\", description: \"A branded user ID.\" });\n * ```\n */\nexport function idScalar<Brand extends string>(\n  codec: IdCodec<Brand>,\n  config: { name: string; description?: string },\n): GraphQLScalarType<Id<Brand>, string> {\n  const parse = (value: unknown): Id<Brand> => {\n    const result = codec.safeParse(value);\n    if (!result.ok) {\n      throw new GraphQLError(`invalid ${config.name}: ${result.error}`);\n    }\n    return result.id;\n  };\n  return new GraphQLScalarType<Id<Brand>, string>({\n    name: config.name,\n    description: config.description,\n    serialize: parse,\n    parseValue: parse,\n    parseLiteral: (ast: ValueNode) => {\n      if (ast.kind !== Kind.STRING) {\n        throw new GraphQLError(`${config.name} must be a string literal, got ${ast.kind}`);\n      }\n      return parse(ast.value);\n    },\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAwBA,SAAgB,SACd,OACA,QACsC;CACtC,MAAM,SAAS,UAA8B;EAC3C,MAAM,SAAS,MAAM,UAAU,KAAK;EACpC,IAAI,CAAC,OAAO,IACV,MAAM,IAAI,aAAa,WAAW,OAAO,KAAK,IAAI,OAAO,OAAO;EAElE,OAAO,OAAO;CAChB;CACA,OAAO,IAAI,kBAAqC;EAC9C,MAAM,OAAO;EACb,aAAa,OAAO;EACpB,WAAW;EACX,YAAY;EACZ,eAAe,QAAmB;GAChC,IAAI,IAAI,SAAS,KAAK,QACpB,MAAM,IAAI,aAAa,GAAG,OAAO,KAAK,iCAAiC,IAAI,MAAM;GAEnF,OAAO,MAAM,IAAI,KAAK;EACxB;CACF,CAAC;AACH"}
+{"version":3,"file":"graphql.mjs","names":[],"sources":["../src/adapters/graphql.ts"],"sourcesContent":["import { GraphQLError, GraphQLScalarType, Kind } from \"graphql\";\nimport type { ValueNode } from \"graphql\";\nimport type { IdCodec } 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\n/**\n * Builds a `GraphQLScalarType` for the given codec and brand.\n *\n * - `serialize` — validates via `codec.safeParse`; throws `GraphQLError` on a non-conforming value.\n * - `parseValue` — validates variables via `codec.safeParse`; throws `GraphQLError` on failure.\n * - `parseLiteral` — validates inline `Kind.STRING` literals; throws `GraphQLError` for any\n *   other AST kind or on a failed `safeParse`.\n *\n * `graphql` must be installed as a peer dependency.\n *\n * @example\n * ```ts\n * import { idScalar } from \"@smonn/ids/graphql\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n * const UserIdScalar = idScalar(usr, { name: \"UserId\", description: \"A branded user ID.\" });\n * ```\n */\nexport function idScalar<Brand extends string>(\n  codec: IdCodec<Brand>,\n  config: { name: string; description?: string },\n): GraphQLScalarType<Id<Brand>, string> {\n  const parse = (value: unknown): Id<Brand> => {\n    const result = codec.safeParse(value);\n    if (!result.ok) {\n      throw new GraphQLError(`invalid ${config.name}: ${result.error}`);\n    }\n    return result.id;\n  };\n  return new GraphQLScalarType<Id<Brand>, string>({\n    name: config.name,\n    description: config.description,\n    serialize: parse,\n    parseValue: parse,\n    parseLiteral: (ast: ValueNode) => {\n      if (ast.kind !== Kind.STRING) {\n        throw new GraphQLError(`${config.name} must be a string literal, got ${ast.kind}`);\n      }\n      return parse(ast.value);\n    },\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AA2BA,SAAgB,SACd,OACA,QACsC;CACtC,MAAM,SAAS,UAA8B;EAC3C,MAAM,SAAS,MAAM,UAAU,KAAK;EACpC,IAAI,CAAC,OAAO,IACV,MAAM,IAAI,aAAa,WAAW,OAAO,KAAK,IAAI,OAAO,OAAO;EAElE,OAAO,OAAO;CAChB;CACA,OAAO,IAAI,kBAAqC;EAC9C,MAAM,OAAO;EACb,aAAa,OAAO;EACpB,WAAW;EACX,YAAY;EACZ,eAAe,QAAmB;GAChC,IAAI,IAAI,SAAS,KAAK,QACpB,MAAM,IAAI,aAAa,GAAG,OAAO,KAAK,iCAAiC,IAAI,MAAM;GAEnF,OAAO,MAAM,IAAI,KAAK;EACxB;CACF,CAAC;AACH"}

package/dist/hono.d.mts

@@ -4,7 +4,7 @@ import { ContentfulStatusCode } from "hono/utils/http-status";
 import { Context, MiddlewareHandler } from "hono";
 
 //#region src/adapters/hono.d.ts
-/** Options for `idParam`. All fields are optional. */
+/** Options for `idParam` and `idQuery`. All fields are optional. */
 type IdParamOptions = {
   /**
   * Called instead of throwing when provided. The hook owns the response entirely —
@@ -61,6 +61,48 @@ type IdParamOptions = {
 declare function idParam<ParamKey extends string, Brand extends string>(paramName: ParamKey, codec: IdCodec<Brand>, options?: IdParamOptions): MiddlewareHandler<{
   Variables: Record<ParamKey, Id<Brand>>;
 }>;
+/**
+* Hono middleware that validates a named query-string param against a codec via `safeParse`.
+*
+* Same failure contract as `idParam` — same `IdParamFailure` shape, same `onError` / `status`
+* options — but reads `c.req.query(queryName)` instead of `c.req.param(queryName)`.
+*
+* **Default (no options):** throws `HTTPException(status)` so the app's existing `onError` handler
+* controls rendering and content negotiation. The adapter does not write a response body itself.
+*
+* **`options.onError`:** when provided, the hook owns the response entirely — the adapter neither
+* throws nor writes a response.
+*
+* **`options.status`:** remaps the default HTTP status for a reason without a full handler.
+*
+* - **Brand mismatch (`invalid_prefix`) → `reason: "brand_mismatch"`, default 404**
+* - **Malformed or missing query param → `reason: "malformed"`, default 400**
+*
+* On success, stores the canonical `Id<Brand>` in the Hono context under `queryName`
+* and calls `next()`.
+*
+* @example
+* ```ts
+* import { idQuery } from "@smonn/ids/hono";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+*
+* // Default: throws HTTPException → app.onError renders it
+* // GET /users?userId=usr_...
+* app.get("/users", idQuery("userId", usr), (c) => {
+*   const userId = c.get("userId"); // Id<"usr">, canonical
+* });
+*
+* // Override: consumer fully owns the response
+* app.get("/search", idQuery("cursor", usr, {
+*   onError: (failure, c) => c.json({ error: failure.reason }, failure.status),
+* }), handler);
+* ```
+*/
+declare function idQuery<ParamKey extends string, Brand extends string>(queryName: ParamKey, codec: IdCodec<Brand>, options?: IdParamOptions): MiddlewareHandler<{
+  Variables: Record<ParamKey, Id<Brand>>;
+}>;
 //#endregion
-export { type IdParamFailure, IdParamOptions, idParam };
+export { type IdParamFailure, IdParamOptions, idParam, idQuery };
 //# sourceMappingURL=hono.d.mts.map

package/dist/hono.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"hono.d.mts","names":[],"sources":["../src/adapters/hono.ts"],"mappings":";;;;;;;KASY,cAAA;EAAA;;;;EAKV,OAAA,IAAW,OAAA,EAAS,cAAA,EAAgB,CAAA,EAAG,OAAA,KAAY,QAAA,GAAW,OAAA,CAAQ,QAAA;;;;;EAKtE,MAAA;IAAW,cAAA,GAAiB,oBAAA;IAAsB,SAAA,GAAY,oBAAA;EAAA;AAAA;;;;;;;;;;;;AAAA;AAyChE;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAgB,OAAA,gDACd,SAAA,EAAW,QAAA,EACX,KAAA,EAAO,OAAA,CAAQ,KAAA,GACf,OAAA,GAAU,cAAA,GACT,iBAAA;EAAoB,SAAA,EAAW,MAAA,CAAO,QAAA,EAAU,EAAA,CAAG,KAAA;AAAA"}
+{"version":3,"file":"hono.d.mts","names":[],"sources":["../src/adapters/hono.ts"],"mappings":";;;;;;;KASY,cAAA;EAAA;;;;EAKV,OAAA,IAAW,OAAA,EAAS,cAAA,EAAgB,CAAA,EAAG,OAAA,KAAY,QAAA,GAAW,OAAA,CAAQ,QAAA;;;;;EAKtE,MAAA;IAAW,cAAA,GAAiB,oBAAA;IAAsB,SAAA,GAAY,oBAAA;EAAA;AAAA;;;;;;;;;;;;AAAA;AAyChE;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAgB,OAAA,gDACd,SAAA,EAAW,QAAA,EACX,KAAA,EAAO,OAAA,CAAQ,KAAA,GACf,OAAA,GAAU,cAAA,GACT,iBAAA;EAAoB,SAAA,EAAW,MAAA,CAAO,QAAA,EAAU,EAAA,CAAG,KAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4DA;;;;;;;;;;iBAJtC,OAAA,gDACd,SAAA,EAAW,QAAA,EACX,KAAA,EAAO,OAAA,CAAQ,KAAA,GACf,OAAA,GAAU,cAAA,GACT,iBAAA;EAAoB,SAAA,EAAW,MAAA,CAAO,QAAA,EAAU,EAAA,CAAG,KAAA;AAAA"}

package/dist/hono.mjs

@@ -1,4 +1,4 @@
-import { n as resolveIdParamFailure } from "./adapter-types-7wWdELSh.mjs";
+import { r as resolveIdParamFailure } from "./adapter-types-CjzFNDcJ.mjs";
 import { HTTPException } from "hono/http-exception";
 //#region src/adapters/hono.ts
 /**
@@ -52,7 +52,59 @@ function idParam(paramName, codec, options) {
 		await next();
 	};
 }
+/**
+* Hono middleware that validates a named query-string param against a codec via `safeParse`.
+*
+* Same failure contract as `idParam` — same `IdParamFailure` shape, same `onError` / `status`
+* options — but reads `c.req.query(queryName)` instead of `c.req.param(queryName)`.
+*
+* **Default (no options):** throws `HTTPException(status)` so the app's existing `onError` handler
+* controls rendering and content negotiation. The adapter does not write a response body itself.
+*
+* **`options.onError`:** when provided, the hook owns the response entirely — the adapter neither
+* throws nor writes a response.
+*
+* **`options.status`:** remaps the default HTTP status for a reason without a full handler.
+*
+* - **Brand mismatch (`invalid_prefix`) → `reason: "brand_mismatch"`, default 404**
+* - **Malformed or missing query param → `reason: "malformed"`, default 400**
+*
+* On success, stores the canonical `Id<Brand>` in the Hono context under `queryName`
+* and calls `next()`.
+*
+* @example
+* ```ts
+* import { idQuery } from "@smonn/ids/hono";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+*
+* // Default: throws HTTPException → app.onError renders it
+* // GET /users?userId=usr_...
+* app.get("/users", idQuery("userId", usr), (c) => {
+*   const userId = c.get("userId"); // Id<"usr">, canonical
+* });
+*
+* // Override: consumer fully owns the response
+* app.get("/search", idQuery("cursor", usr, {
+*   onError: (failure, c) => c.json({ error: failure.reason }, failure.status),
+* }), handler);
+* ```
+*/
+function idQuery(queryName, codec, options) {
+	return async (c, next) => {
+		const raw = c.req.query(queryName);
+		const result = codec.safeParse(raw);
+		if (!result.ok) {
+			const failure = resolveIdParamFailure(result.error, options);
+			if (options?.onError) return options.onError(failure, c);
+			throw new HTTPException(failure.status);
+		}
+		c.set(queryName, result.id);
+		await next();
+	};
+}
 //#endregion
-export { idParam };
+export { idParam, idQuery };
 
 //# sourceMappingURL=hono.mjs.map

package/dist/hono.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"hono.mjs","names":[],"sources":["../src/adapters/hono.ts"],"sourcesContent":["import { HTTPException } from \"hono/http-exception\";\nimport type { ContentfulStatusCode } from \"hono/utils/http-status\";\nimport type { Context, MiddlewareHandler } from \"hono\";\nimport { type IdCodec, type IdParamFailure, resolveIdParamFailure } from \"./adapter-types.js\";\nimport type { Id } from \"../types.js\";\n\nexport type { IdParamFailure };\n\n/** Options for `idParam`. All fields are optional. */\nexport type IdParamOptions = {\n  /**\n   * Called instead of throwing when provided. The hook owns the response entirely —\n   * the adapter neither throws nor writes a body.\n   */\n  onError?: (failure: IdParamFailure, c: Context) => Response | Promise<Response>;\n  /**\n   * Remap the default HTTP status for a failure reason without a full handler.\n   * e.g. `{ brand_mismatch: 400 }` treats both failure kinds as 400.\n   */\n  status?: { brand_mismatch?: ContentfulStatusCode; malformed?: ContentfulStatusCode };\n};\n\n/**\n * Hono middleware that validates a named route param against a codec via `safeParse`.\n *\n * **Default (no options):** throws `HTTPException(status)` so the app's existing `onError` handler\n * controls rendering and content negotiation. The adapter does not write a response body itself.\n *\n * **`options.onError`:** when provided, the hook owns the response entirely — the adapter neither\n * throws nor writes a response.\n *\n * **`options.status`:** remaps the default HTTP status for a reason without a full handler.\n *\n * - **Brand mismatch (`invalid_prefix`) → `reason: \"brand_mismatch\"`, default 404**\n * - **Malformed or missing ID → `reason: \"malformed\"`, default 400**\n *\n * On success, stores the canonical `Id<Brand>` in the Hono context under `paramName`\n * and calls `next()`.\n *\n * @example\n * ```ts\n * import { idParam } from \"@smonn/ids/hono\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n *\n * // Default: throws HTTPException → app.onError renders it\n * app.get(\"/users/:id\", idParam(\"id\", usr), (c) => {\n *   const id = c.get(\"id\"); // Id<\"usr\">, canonical\n * });\n *\n * // Override: consumer fully owns the response\n * app.get(\"/orgs/:id\", idParam(\"id\", org, {\n *   onError: (failure, c) => c.json({ error: failure.reason }, failure.status),\n * }), handler);\n *\n * // Or a lightweight status remap without a full handler\n * app.get(\"/things/:id\", idParam(\"id\", thing, { status: { brand_mismatch: 400 } }), handler);\n * ```\n */\nexport function idParam<ParamKey extends string, Brand extends string>(\n  paramName: ParamKey,\n  codec: IdCodec<Brand>,\n  options?: IdParamOptions,\n): MiddlewareHandler<{ Variables: Record<ParamKey, Id<Brand>> }> {\n  return async (c, next) => {\n    const raw = c.req.param(paramName);\n    const result = codec.safeParse(raw);\n    if (!result.ok) {\n      const failure = resolveIdParamFailure(result.error, options);\n      if (options?.onError) {\n        return options.onError(failure, c);\n      }\n      throw new HTTPException(failure.status as ContentfulStatusCode);\n    }\n    c.set(paramName, result.id);\n    await next();\n    return;\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4DA,SAAgB,QACd,WACA,OACA,SAC+D;CAC/D,OAAO,OAAO,GAAG,SAAS;EACxB,MAAM,MAAM,EAAE,IAAI,MAAM,SAAS;EACjC,MAAM,SAAS,MAAM,UAAU,GAAG;EAClC,IAAI,CAAC,OAAO,IAAI;GACd,MAAM,UAAU,sBAAsB,OAAO,OAAO,OAAO;GAC3D,IAAI,SAAS,SACX,OAAO,QAAQ,QAAQ,SAAS,CAAC;GAEnC,MAAM,IAAI,cAAc,QAAQ,MAA8B;EAChE;EACA,EAAE,IAAI,WAAW,OAAO,EAAE;EAC1B,MAAM,KAAK;CAEb;AACF"}
+{"version":3,"file":"hono.mjs","names":[],"sources":["../src/adapters/hono.ts"],"sourcesContent":["import { HTTPException } from \"hono/http-exception\";\nimport type { ContentfulStatusCode } from \"hono/utils/http-status\";\nimport type { Context, MiddlewareHandler } from \"hono\";\nimport { type IdCodec, type IdParamFailure, resolveIdParamFailure } from \"./adapter-types.js\";\nimport type { Id } from \"../types.js\";\n\nexport type { IdParamFailure };\n\n/** Options for `idParam` and `idQuery`. All fields are optional. */\nexport type IdParamOptions = {\n  /**\n   * Called instead of throwing when provided. The hook owns the response entirely —\n   * the adapter neither throws nor writes a body.\n   */\n  onError?: (failure: IdParamFailure, c: Context) => Response | Promise<Response>;\n  /**\n   * Remap the default HTTP status for a failure reason without a full handler.\n   * e.g. `{ brand_mismatch: 400 }` treats both failure kinds as 400.\n   */\n  status?: { brand_mismatch?: ContentfulStatusCode; malformed?: ContentfulStatusCode };\n};\n\n/**\n * Hono middleware that validates a named route param against a codec via `safeParse`.\n *\n * **Default (no options):** throws `HTTPException(status)` so the app's existing `onError` handler\n * controls rendering and content negotiation. The adapter does not write a response body itself.\n *\n * **`options.onError`:** when provided, the hook owns the response entirely — the adapter neither\n * throws nor writes a response.\n *\n * **`options.status`:** remaps the default HTTP status for a reason without a full handler.\n *\n * - **Brand mismatch (`invalid_prefix`) → `reason: \"brand_mismatch\"`, default 404**\n * - **Malformed or missing ID → `reason: \"malformed\"`, default 400**\n *\n * On success, stores the canonical `Id<Brand>` in the Hono context under `paramName`\n * and calls `next()`.\n *\n * @example\n * ```ts\n * import { idParam } from \"@smonn/ids/hono\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n *\n * // Default: throws HTTPException → app.onError renders it\n * app.get(\"/users/:id\", idParam(\"id\", usr), (c) => {\n *   const id = c.get(\"id\"); // Id<\"usr\">, canonical\n * });\n *\n * // Override: consumer fully owns the response\n * app.get(\"/orgs/:id\", idParam(\"id\", org, {\n *   onError: (failure, c) => c.json({ error: failure.reason }, failure.status),\n * }), handler);\n *\n * // Or a lightweight status remap without a full handler\n * app.get(\"/things/:id\", idParam(\"id\", thing, { status: { brand_mismatch: 400 } }), handler);\n * ```\n */\nexport function idParam<ParamKey extends string, Brand extends string>(\n  paramName: ParamKey,\n  codec: IdCodec<Brand>,\n  options?: IdParamOptions,\n): MiddlewareHandler<{ Variables: Record<ParamKey, Id<Brand>> }> {\n  return async (c, next) => {\n    const raw = c.req.param(paramName);\n    const result = codec.safeParse(raw);\n    if (!result.ok) {\n      const failure = resolveIdParamFailure(result.error, options);\n      if (options?.onError) {\n        return options.onError(failure, c);\n      }\n      throw new HTTPException(failure.status as ContentfulStatusCode);\n    }\n    c.set(paramName, result.id);\n    await next();\n    return;\n  };\n}\n\n/**\n * Hono middleware that validates a named query-string param against a codec via `safeParse`.\n *\n * Same failure contract as `idParam` — same `IdParamFailure` shape, same `onError` / `status`\n * options — but reads `c.req.query(queryName)` instead of `c.req.param(queryName)`.\n *\n * **Default (no options):** throws `HTTPException(status)` so the app's existing `onError` handler\n * controls rendering and content negotiation. The adapter does not write a response body itself.\n *\n * **`options.onError`:** when provided, the hook owns the response entirely — the adapter neither\n * throws nor writes a response.\n *\n * **`options.status`:** remaps the default HTTP status for a reason without a full handler.\n *\n * - **Brand mismatch (`invalid_prefix`) → `reason: \"brand_mismatch\"`, default 404**\n * - **Malformed or missing query param → `reason: \"malformed\"`, default 400**\n *\n * On success, stores the canonical `Id<Brand>` in the Hono context under `queryName`\n * and calls `next()`.\n *\n * @example\n * ```ts\n * import { idQuery } from \"@smonn/ids/hono\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n *\n * // Default: throws HTTPException → app.onError renders it\n * // GET /users?userId=usr_...\n * app.get(\"/users\", idQuery(\"userId\", usr), (c) => {\n *   const userId = c.get(\"userId\"); // Id<\"usr\">, canonical\n * });\n *\n * // Override: consumer fully owns the response\n * app.get(\"/search\", idQuery(\"cursor\", usr, {\n *   onError: (failure, c) => c.json({ error: failure.reason }, failure.status),\n * }), handler);\n * ```\n */\nexport function idQuery<ParamKey extends string, Brand extends string>(\n  queryName: ParamKey,\n  codec: IdCodec<Brand>,\n  options?: IdParamOptions,\n): MiddlewareHandler<{ Variables: Record<ParamKey, Id<Brand>> }> {\n  return async (c, next) => {\n    const raw = c.req.query(queryName);\n    const result = codec.safeParse(raw);\n    if (!result.ok) {\n      const failure = resolveIdParamFailure(result.error, options);\n      if (options?.onError) {\n        return options.onError(failure, c);\n      }\n      throw new HTTPException(failure.status as ContentfulStatusCode);\n    }\n    c.set(queryName, result.id);\n    await next();\n    return;\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4DA,SAAgB,QACd,WACA,OACA,SAC+D;CAC/D,OAAO,OAAO,GAAG,SAAS;EACxB,MAAM,MAAM,EAAE,IAAI,MAAM,SAAS;EACjC,MAAM,SAAS,MAAM,UAAU,GAAG;EAClC,IAAI,CAAC,OAAO,IAAI;GACd,MAAM,UAAU,sBAAsB,OAAO,OAAO,OAAO;GAC3D,IAAI,SAAS,SACX,OAAO,QAAQ,QAAQ,SAAS,CAAC;GAEnC,MAAM,IAAI,cAAc,QAAQ,MAA8B;EAChE;EACA,EAAE,IAAI,WAAW,OAAO,EAAE;EAC1B,MAAM,KAAK;CAEb;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,SAAgB,QACd,WACA,OACA,SAC+D;CAC/D,OAAO,OAAO,GAAG,SAAS;EACxB,MAAM,MAAM,EAAE,IAAI,MAAM,SAAS;EACjC,MAAM,SAAS,MAAM,UAAU,GAAG;EAClC,IAAI,CAAC,OAAO,IAAI;GACd,MAAM,UAAU,sBAAsB,OAAO,OAAO,OAAO;GAC3D,IAAI,SAAS,SACX,OAAO,QAAQ,QAAQ,SAAS,CAAC;GAEnC,MAAM,IAAI,cAAc,QAAQ,MAA8B;EAChE;EACA,EAAE,IAAI,WAAW,OAAO,EAAE;EAC1B,MAAM,KAAK;CAEb;AACF"}

package/dist/kysely.d.mts

@@ -1,7 +1,7 @@
 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 { ColumnType } from "kysely";
+import { ColumnType, KyselyPlugin } from "kysely";
 
 //#region src/adapters/kysely.d.ts
 /**
@@ -23,6 +23,24 @@ import { ColumnType } from "kysely";
 */
 type IdColumnType<Brand extends string> = ColumnType<Id<Brand>, Id<Brand>, Id<Brand>>;
 /**
+* Kysely column type mapping for a nullable `Id<Brand>` column.
+*
+* Use in your Kysely `Database` interface for optional foreign keys or any
+* column that can be `NULL`. Pair with `nullableIdColumn(codec)` for runtime
+* transformation.
+*
+* @example
+* ```ts
+* import type { NullableIdColumnType } from "@smonn/ids/kysely";
+* import type { Id } from "@smonn/ids";
+*
+* interface Database {
+*   posts: { authorId: NullableIdColumnType<"usr"> };
+* }
+* ```
+*/
+type NullableIdColumnType<Brand extends string> = ColumnType<Id<Brand> | null, Id<Brand> | null, Id<Brand> | null>;
+/**
 * Kysely column adapter bound to a codec.
 *
 * Returns an object with `fromDriver` / `toDriver` helpers that mirror the read/write
@@ -51,6 +69,59 @@ declare function idColumn<Brand extends string>(codec: IdColumnCodec<Brand>): {
   toDriver(value: Id<Brand>): string;
   fromDriver(value: string): Id<Brand>;
 };
+/**
+* Kysely plugin that automatically transforms result columns using the provided codec map.
+*
+* Keys in `map` are plain column names (`"id"`) or `"table.column"` qualified names
+* (`"users.id"`). Plain names match any result column with that name; qualified names
+* match by the column-name part (after the last `.`). If both a plain key and a qualified
+* key resolve to the same column name, the qualified key takes precedence.
+*
+* `transformResult` calls `readIdColumn(codec, rawValue)` for each matched column, returning
+* a branded `Id<Brand>` on success and throwing `IdsError("invalid_id")` on parse failure.
+* `transformQuery` is a no-op identity pass-through.
+*
+* @example
+* ```ts
+* import { idPlugin } from "@smonn/ids/kysely";
+* import { createTimestampId } from "@smonn/ids";
+* import { Kysely } from "kysely";
+*
+* const usr = createTimestampId("usr");
+*
+* const db = new Kysely<Database>({
+*   // ...
+*   plugins: [idPlugin({ "users.id": usr })],
+* });
+*
+* // result.id is automatically validated and branded as Id<"usr">
+* const row = await db.selectFrom("users").selectAll().executeTakeFirstOrThrow();
+* ```
+*/
+declare function idPlugin(map: Record<string, IdColumnCodec<string>>): KyselyPlugin;
+/**
+* Kysely column adapter for a **nullable** `Id<Brand>` column.
+*
+* Behaves like {@link idColumn} but `fromDriver` returns `null` for `null` /
+* `undefined` driver values and `toDriver` passes `null` through unchanged.
+* Use for optional foreign keys and `LEFT JOIN` results.
+*
+* @example
+* ```ts
+* import { nullableIdColumn } from "@smonn/ids/kysely";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+* const authorCol = nullableIdColumn(usr);
+*
+* // In a query result handler:
+* const authorId = authorCol.fromDriver(row.author_id); // Id<"usr"> | null
+* ```
+*/
+declare function nullableIdColumn<Brand extends string>(codec: IdColumnCodec<Brand>): {
+  toDriver(value: Id<Brand> | null): string | null;
+  fromDriver(value: string | null): Id<Brand> | null;
+};
 //#endregion
-export { type IdColumnCodec, IdColumnType, IdsError, type IdsErrorCode, idColumn, isIdsError };
+export { type IdColumnCodec, IdColumnType, IdsError, type IdsErrorCode, NullableIdColumnType, idColumn, idPlugin, isIdsError, nullableIdColumn };
 //# sourceMappingURL=kysely.d.mts.map

package/dist/kysely.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"kysely.d.mts","names":[],"sources":["../src/adapters/kysely.ts"],"mappings":";;;;;;AAyBA;;;;;;;;;;;;;;;;;AAAA,KAAY,YAAA,yBAAqC,UAAA,CAAW,EAAA,CAAG,KAAA,GAAQ,EAAA,CAAG,KAAA,GAAQ,EAAA,CAAG,KAAA;;;;AAAA;AA2BrF;;;;;;;;;;;;;;;;;;;;;iBAAgB,QAAA,uBACd,KAAA,EAAO,aAAA,CAAc,KAAA;EAErB,QAAA,CAAS,KAAA,EAAO,EAAA,CAAG,KAAA;EACnB,UAAA,CAAW,KAAA,WAAgB,EAAA,CAAG,KAAA;AAAA"}
+{"version":3,"file":"kysely.d.mts","names":[],"sources":["../src/adapters/kysely.ts"],"mappings":";;;;;;AAgCA;;;;;;;;;;;;;;;;;AAAA,KAAY,YAAA,yBAAqC,UAAA,CAAW,EAAA,CAAG,KAAA,GAAQ,EAAA,CAAG,KAAA,GAAQ,EAAA,CAAG,KAAA;;;;AAAA;AAmBrF;;;;;;;;;;;;;KAAY,oBAAA,yBAA6C,UAAA,CACvD,EAAA,CAAG,KAAA,UACH,EAAA,CAAG,KAAA,UACH,EAAA,CAAG,KAAA;;;;;;;;AAAA;AA4BL;;;;;;;;;;;;;;;;;iBAAgB,QAAA,uBACd,KAAA,EAAO,aAAA,CAAc,KAAA;EAErB,QAAA,CAAS,KAAA,EAAO,EAAA,CAAG,KAAA;EACnB,UAAA,CAAW,KAAA,WAAgB,EAAA,CAAG,KAAA;AAAA;;;;AAAA;AAyChC;;;;;;;;;;;;;AAAsE;AAqDtE;;;;;;;;;;;iBArDgB,QAAA,CAAS,GAAA,EAAK,MAAA,SAAe,aAAA,YAAyB,YAAA;;;;;;;;;;;;;AAyD/B;;;;;;;iBAJvB,gBAAA,uBACd,KAAA,EAAO,aAAA,CAAc,KAAA;EAErB,QAAA,CAAS,KAAA,EAAO,EAAA,CAAG,KAAA;EACnB,UAAA,CAAW,KAAA,kBAAuB,EAAA,CAAG,KAAA;AAAA"}

package/dist/kysely.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/kysely.ts
 /**
 * Kysely column adapter bound to a codec.
@@ -36,7 +36,89 @@ function idColumn(codec) {
 		}
 	};
 }
+/**
+* Kysely plugin that automatically transforms result columns using the provided codec map.
+*
+* Keys in `map` are plain column names (`"id"`) or `"table.column"` qualified names
+* (`"users.id"`). Plain names match any result column with that name; qualified names
+* match by the column-name part (after the last `.`). If both a plain key and a qualified
+* key resolve to the same column name, the qualified key takes precedence.
+*
+* `transformResult` calls `readIdColumn(codec, rawValue)` for each matched column, returning
+* a branded `Id<Brand>` on success and throwing `IdsError("invalid_id")` on parse failure.
+* `transformQuery` is a no-op identity pass-through.
+*
+* @example
+* ```ts
+* import { idPlugin } from "@smonn/ids/kysely";
+* import { createTimestampId } from "@smonn/ids";
+* import { Kysely } from "kysely";
+*
+* const usr = createTimestampId("usr");
+*
+* const db = new Kysely<Database>({
+*   // ...
+*   plugins: [idPlugin({ "users.id": usr })],
+* });
+*
+* // result.id is automatically validated and branded as Id<"usr">
+* const row = await db.selectFrom("users").selectAll().executeTakeFirstOrThrow();
+* ```
+*/
+function idPlugin(map) {
+	const lookup = /* @__PURE__ */ new Map();
+	for (const [key, codec] of Object.entries(map)) if (!key.includes(".")) lookup.set(key, codec);
+	for (const [key, codec] of Object.entries(map)) if (key.includes(".")) lookup.set(key.slice(key.lastIndexOf(".") + 1), codec);
+	return {
+		transformQuery(args) {
+			return args.node;
+		},
+		async transformResult(args) {
+			const rows = args.result.rows.map((row) => {
+				const newRow = {};
+				for (const [colName, value] of Object.entries(row)) {
+					const codec = lookup.get(colName);
+					newRow[colName] = codec !== void 0 ? readIdColumn(codec, value) : value;
+				}
+				return newRow;
+			});
+			return {
+				...args.result,
+				rows
+			};
+		}
+	};
+}
+/**
+* Kysely column adapter for a **nullable** `Id<Brand>` column.
+*
+* Behaves like {@link idColumn} but `fromDriver` returns `null` for `null` /
+* `undefined` driver values and `toDriver` passes `null` through unchanged.
+* Use for optional foreign keys and `LEFT JOIN` results.
+*
+* @example
+* ```ts
+* import { nullableIdColumn } from "@smonn/ids/kysely";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+* const authorCol = nullableIdColumn(usr);
+*
+* // In a query result handler:
+* const authorId = authorCol.fromDriver(row.author_id); // Id<"usr"> | null
+* ```
+*/
+function nullableIdColumn(codec) {
+	return {
+		toDriver(value) {
+			return value;
+		},
+		fromDriver(value) {
+			return readIdColumnNullable(codec, value);
+		}
+	};
+}
 //#endregion
-export { IdsError, idColumn, isIdsError };
+export { IdsError, idColumn, idPlugin, isIdsError, nullableIdColumn };
 
 //# sourceMappingURL=kysely.mjs.map

package/dist/kysely.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"kysely.mjs","names":[],"sources":["../src/adapters/kysely.ts"],"sourcesContent":["import type { ColumnType } from \"kysely\";\nimport { readIdColumn, type IdColumnCodec } from \"./adapter-types.js\";\nimport type { Id } from \"../types.js\";\n\nexport type { IdColumnCodec } from \"./adapter-types.js\";\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\n/**\n * Kysely column type mapping for `Id<Brand>`.\n *\n * Use this in your Kysely `Database` interface to type a column as `Id<Brand>` at\n * the TypeScript level. Pair it with `idColumn(codec)` for runtime read/write\n * transformation.\n *\n * @example\n * ```ts\n * import type { IdColumnType } from \"@smonn/ids/kysely\";\n * import type { Id } from \"@smonn/ids\";\n *\n * interface Database {\n *   users: { id: IdColumnType<\"usr\"> };\n * }\n * ```\n */\nexport type IdColumnType<Brand extends string> = ColumnType<Id<Brand>, Id<Brand>, Id<Brand>>;\n\n/**\n * Kysely column adapter bound to a codec.\n *\n * Returns an object with `fromDriver` / `toDriver` helpers that mirror the read/write\n * contract of the Drizzle adapter — same error message, same strictness (safeParse on\n * read, identity on write).\n *\n * **Write path:** passes the `Id<Brand>` directly to the driver — it is already\n * the canonical string form.\n *\n * **Read path:** normalises the raw DB string via `codec.safeParse()`. Throws if\n * the value does not parse as a valid `Id<Brand>`.\n *\n * @example\n * ```ts\n * import { idColumn } from \"@smonn/ids/kysely\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n * const usrCol = idColumn(usr);\n *\n * // In a query result handler:\n * const id = usrCol.fromDriver(row.id);\n * ```\n */\nexport function idColumn<Brand extends string>(\n  codec: IdColumnCodec<Brand>,\n): {\n  toDriver(value: Id<Brand>): string;\n  fromDriver(value: string): Id<Brand>;\n} {\n  return {\n    toDriver(value: Id<Brand>): string {\n      return value;\n    },\n    fromDriver(value: string): Id<Brand> {\n      return readIdColumn(codec, value);\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoDA,SAAgB,SACd,OAIA;CACA,OAAO;EACL,SAAS,OAA0B;GACjC,OAAO;EACT;EACA,WAAW,OAA0B;GACnC,OAAO,aAAa,OAAO,KAAK;EAClC;CACF;AACF"}
+{"version":3,"file":"kysely.mjs","names":[],"sources":["../src/adapters/kysely.ts"],"sourcesContent":["import type {\n  ColumnType,\n  KyselyPlugin,\n  PluginTransformQueryArgs,\n  PluginTransformResultArgs,\n  QueryResult,\n  UnknownRow,\n} from \"kysely\";\nimport { readIdColumn, readIdColumnNullable, type IdColumnCodec } from \"./adapter-types.js\";\nimport type { Id } from \"../types.js\";\n\nexport type { IdColumnCodec } from \"./adapter-types.js\";\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\n/**\n * Kysely column type mapping for `Id<Brand>`.\n *\n * Use this in your Kysely `Database` interface to type a column as `Id<Brand>` at\n * the TypeScript level. Pair it with `idColumn(codec)` for runtime read/write\n * transformation.\n *\n * @example\n * ```ts\n * import type { IdColumnType } from \"@smonn/ids/kysely\";\n * import type { Id } from \"@smonn/ids\";\n *\n * interface Database {\n *   users: { id: IdColumnType<\"usr\"> };\n * }\n * ```\n */\nexport type IdColumnType<Brand extends string> = ColumnType<Id<Brand>, Id<Brand>, Id<Brand>>;\n\n/**\n * Kysely column type mapping for a nullable `Id<Brand>` column.\n *\n * Use in your Kysely `Database` interface for optional foreign keys or any\n * column that can be `NULL`. Pair with `nullableIdColumn(codec)` for runtime\n * transformation.\n *\n * @example\n * ```ts\n * import type { NullableIdColumnType } from \"@smonn/ids/kysely\";\n * import type { Id } from \"@smonn/ids\";\n *\n * interface Database {\n *   posts: { authorId: NullableIdColumnType<\"usr\"> };\n * }\n * ```\n */\nexport type NullableIdColumnType<Brand extends string> = ColumnType<\n  Id<Brand> | null,\n  Id<Brand> | null,\n  Id<Brand> | null\n>;\n\n/**\n * Kysely column adapter bound to a codec.\n *\n * Returns an object with `fromDriver` / `toDriver` helpers that mirror the read/write\n * contract of the Drizzle adapter — same error message, same strictness (safeParse on\n * read, identity on write).\n *\n * **Write path:** passes the `Id<Brand>` directly to the driver — it is already\n * the canonical string form.\n *\n * **Read path:** normalises the raw DB string via `codec.safeParse()`. Throws if\n * the value does not parse as a valid `Id<Brand>`.\n *\n * @example\n * ```ts\n * import { idColumn } from \"@smonn/ids/kysely\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n * const usrCol = idColumn(usr);\n *\n * // In a query result handler:\n * const id = usrCol.fromDriver(row.id);\n * ```\n */\nexport function idColumn<Brand extends string>(\n  codec: IdColumnCodec<Brand>,\n): {\n  toDriver(value: Id<Brand>): string;\n  fromDriver(value: string): Id<Brand>;\n} {\n  return {\n    toDriver(value: Id<Brand>): string {\n      return value;\n    },\n    fromDriver(value: string): Id<Brand> {\n      return readIdColumn(codec, value);\n    },\n  };\n}\n\n/**\n * Kysely plugin that automatically transforms result columns using the provided codec map.\n *\n * Keys in `map` are plain column names (`\"id\"`) or `\"table.column\"` qualified names\n * (`\"users.id\"`). Plain names match any result column with that name; qualified names\n * match by the column-name part (after the last `.`). If both a plain key and a qualified\n * key resolve to the same column name, the qualified key takes precedence.\n *\n * `transformResult` calls `readIdColumn(codec, rawValue)` for each matched column, returning\n * a branded `Id<Brand>` on success and throwing `IdsError(\"invalid_id\")` on parse failure.\n * `transformQuery` is a no-op identity pass-through.\n *\n * @example\n * ```ts\n * import { idPlugin } from \"@smonn/ids/kysely\";\n * import { createTimestampId } from \"@smonn/ids\";\n * import { Kysely } from \"kysely\";\n *\n * const usr = createTimestampId(\"usr\");\n *\n * const db = new Kysely<Database>({\n *   // ...\n *   plugins: [idPlugin({ \"users.id\": usr })],\n * });\n *\n * // result.id is automatically validated and branded as Id<\"usr\">\n * const row = await db.selectFrom(\"users\").selectAll().executeTakeFirstOrThrow();\n * ```\n */\nexport function idPlugin(map: Record<string, IdColumnCodec<string>>): KyselyPlugin {\n  // Build a lookup keyed by the bare column name.\n  // Plain keys (\"id\") are added first; qualified keys (\"users.id\") are added second\n  // so they override the plain key when both resolve to the same column name.\n  const lookup = new Map<string, IdColumnCodec<string>>();\n  for (const [key, codec] of Object.entries(map)) {\n    if (!key.includes(\".\")) {\n      lookup.set(key, codec);\n    }\n  }\n  for (const [key, codec] of Object.entries(map)) {\n    if (key.includes(\".\")) {\n      lookup.set(key.slice(key.lastIndexOf(\".\") + 1), codec);\n    }\n  }\n\n  return {\n    transformQuery(args: PluginTransformQueryArgs) {\n      return args.node;\n    },\n    async transformResult(args: PluginTransformResultArgs): Promise<QueryResult<UnknownRow>> {\n      const rows = args.result.rows.map((row) => {\n        const newRow: Record<string, unknown> = {};\n        for (const [colName, value] of Object.entries(row)) {\n          const codec = lookup.get(colName);\n          newRow[colName] = codec !== undefined ? readIdColumn(codec, value) : value;\n        }\n        return newRow;\n      });\n      return { ...args.result, rows };\n    },\n  };\n}\n\n/**\n * Kysely column adapter for a **nullable** `Id<Brand>` column.\n *\n * Behaves like {@link idColumn} but `fromDriver` returns `null` for `null` /\n * `undefined` driver values and `toDriver` passes `null` through unchanged.\n * Use for optional foreign keys and `LEFT JOIN` results.\n *\n * @example\n * ```ts\n * import { nullableIdColumn } from \"@smonn/ids/kysely\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n * const authorCol = nullableIdColumn(usr);\n *\n * // In a query result handler:\n * const authorId = authorCol.fromDriver(row.author_id); // Id<\"usr\"> | null\n * ```\n */\nexport function nullableIdColumn<Brand extends string>(\n  codec: IdColumnCodec<Brand>,\n): {\n  toDriver(value: Id<Brand> | null): string | null;\n  fromDriver(value: string | null): Id<Brand> | null;\n} {\n  return {\n    toDriver(value: Id<Brand> | null): string | null {\n      return value;\n    },\n    fromDriver(value: string | null): Id<Brand> | null {\n      return readIdColumnNullable(codec, value);\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkFA,SAAgB,SACd,OAIA;CACA,OAAO;EACL,SAAS,OAA0B;GACjC,OAAO;EACT;EACA,WAAW,OAA0B;GACnC,OAAO,aAAa,OAAO,KAAK;EAClC;CACF;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,SAAgB,SAAS,KAA0D;CAIjF,MAAM,yBAAS,IAAI,IAAmC;CACtD,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,GAAG,GAC3C,IAAI,CAAC,IAAI,SAAS,GAAG,GACnB,OAAO,IAAI,KAAK,KAAK;CAGzB,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,GAAG,GAC3C,IAAI,IAAI,SAAS,GAAG,GAClB,OAAO,IAAI,IAAI,MAAM,IAAI,YAAY,GAAG,IAAI,CAAC,GAAG,KAAK;CAIzD,OAAO;EACL,eAAe,MAAgC;GAC7C,OAAO,KAAK;EACd;EACA,MAAM,gBAAgB,MAAmE;GACvF,MAAM,OAAO,KAAK,OAAO,KAAK,KAAK,QAAQ;IACzC,MAAM,SAAkC,CAAC;IACzC,KAAK,MAAM,CAAC,SAAS,UAAU,OAAO,QAAQ,GAAG,GAAG;KAClD,MAAM,QAAQ,OAAO,IAAI,OAAO;KAChC,OAAO,WAAW,UAAU,KAAA,IAAY,aAAa,OAAO,KAAK,IAAI;IACvE;IACA,OAAO;GACT,CAAC;GACD,OAAO;IAAE,GAAG,KAAK;IAAQ;GAAK;EAChC;CACF;AACF;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,iBACd,OAIA;CACA,OAAO;EACL,SAAS,OAAwC;GAC/C,OAAO;EACT;EACA,WAAW,OAAwC;GACjD,OAAO,qBAAqB,OAAO,KAAK;EAC1C;CACF;AACF"}

package/dist/mikro-orm.d.mts

@@ -14,7 +14,14 @@ import { Type } from "@mikro-orm/core";
 * `codec.safeParse()`. Throws `IdsError("invalid_id")` if the stored value
 * does not parse as a valid `Id<Brand>`.
 *
-* **Column type** (`getColumnType`): returns `"text"`.
+* **Column type** (`getColumnType`): returns `"text"` by default, or the
+* `options.columnType` override when provided.
+*
+* @param codec - The brand-scoped codec used to parse values read from the database.
+* @param options - Optional column configuration.
+* @param options.columnType - SQL column type to use (default: `"text"`). Pass
+*   `"varchar(30)"` or `"char(26)"` to match an existing DDL or index strategy.
+*   The value is passed through verbatim — no validation is performed.
 *
 * @example
 * ```ts
@@ -25,13 +32,45 @@ import { Type } from "@mikro-orm/core";
 *
 * const usr = createTimestampId("usr");
 *
+* // default: text column
 * class User {
 *   @PrimaryKey({ type: idType(usr) })
 *   id!: Id<"usr">;
 * }
+*
+* // explicit varchar column
+* class Org {
+*   @PrimaryKey({ type: idType(usr, { columnType: "varchar(30)" }) })
+*   id!: Id<"usr">;
+* }
+* ```
+*/
+declare function idType<Brand extends string>(codec: IdColumnCodec<Brand>, options?: {
+  columnType?: string;
+}): new () => Type<Id<Brand>, string>;
+/**
+* Factory that returns a MikroORM `Type` subclass for a **nullable** `Id<Brand>` column.
+*
+* Behaves like {@link idType} but `convertToJSValue` returns `null` for `null` /
+* `undefined` database values and `convertToDatabaseValue` passes `null` through
+* unchanged. Use for optional foreign keys.
+*
+* @example
+* ```ts
+* import { Property } from "@mikro-orm/core";
+* import { nullableIdType } from "@smonn/ids/mikro-orm";
+* import { createTimestampId } from "@smonn/ids";
+* import type { Id } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+*
+* class Post {
+*   @Property({ type: nullableIdType(usr), nullable: true })
+*   authorId!: Id<"usr"> | null;
+* }
 * ```
 */
-declare function idType<Brand extends string>(codec: IdColumnCodec<Brand>): new () => Type<Id<Brand>, string>;
+declare function nullableIdType<Brand extends string>(codec: IdColumnCodec<Brand>): new () => Type<Id<Brand> | null, string | null>;
 //#endregion
-export { type IdColumnCodec, IdsError, type IdsErrorCode, idType, isIdsError };
+export { type IdColumnCodec, IdsError, type IdsErrorCode, idType, isIdsError, nullableIdType };
 //# sourceMappingURL=mikro-orm.d.mts.map

package/dist/mikro-orm.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"mikro-orm.d.mts","names":[],"sources":["../src/adapters/mikro-orm.ts"],"mappings":";;;;;;AAoCA;;;;;;;;;;;;;;;;;;AAEqB;;;;;;;;;AAFrB,iBAAgB,MAAA,uBACd,KAAA,EAAO,aAAA,CAAc,KAAA,cACV,IAAA,CAAK,EAAA,CAAG,KAAA"}
+{"version":3,"file":"mikro-orm.d.mts","names":[],"sources":["../src/adapters/mikro-orm.ts"],"mappings":";;;;;;AAkDA;;;;;;;;;;;;;;;;;;;;AAGqB;AAqCrB;;;;;;;;;;;;;;;;;;AAEqB;;AA1CrB,iBAAgB,MAAA,uBACd,KAAA,EAAO,aAAA,CAAc,KAAA,GACrB,OAAA;EAAY,UAAA;AAAA,cACD,IAAA,CAAK,EAAA,CAAG,KAAA;;;;;;;;;;;;;;;;;;;;;;;iBAqCL,cAAA,uBACd,KAAA,EAAO,aAAA,CAAc,KAAA,cACV,IAAA,CAAK,EAAA,CAAG,KAAA"}

package/dist/mikro-orm.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";
 import { Type } from "@mikro-orm/core";
 //#region src/adapters/mikro-orm.ts
 /**
@@ -12,7 +12,14 @@ import { Type } from "@mikro-orm/core";
 * `codec.safeParse()`. Throws `IdsError("invalid_id")` if the stored value
 * does not parse as a valid `Id<Brand>`.
 *
-* **Column type** (`getColumnType`): returns `"text"`.
+* **Column type** (`getColumnType`): returns `"text"` by default, or the
+* `options.columnType` override when provided.
+*
+* @param codec - The brand-scoped codec used to parse values read from the database.
+* @param options - Optional column configuration.
+* @param options.columnType - SQL column type to use (default: `"text"`). Pass
+*   `"varchar(30)"` or `"char(26)"` to match an existing DDL or index strategy.
+*   The value is passed through verbatim — no validation is performed.
 *
 * @example
 * ```ts
@@ -23,13 +30,21 @@ import { Type } from "@mikro-orm/core";
 *
 * const usr = createTimestampId("usr");
 *
+* // default: text column
 * class User {
 *   @PrimaryKey({ type: idType(usr) })
 *   id!: Id<"usr">;
 * }
+*
+* // explicit varchar column
+* class Org {
+*   @PrimaryKey({ type: idType(usr, { columnType: "varchar(30)" }) })
+*   id!: Id<"usr">;
+* }
 * ```
 */
-function idType(codec) {
+function idType(codec, options) {
+	const columnType = options?.columnType ?? "text";
 	return class extends Type {
 		convertToDatabaseValue(value) {
 			return value;
@@ -37,12 +52,47 @@ function idType(codec) {
 		convertToJSValue(value) {
 			return readIdColumn(codec, value);
 		}
+		getColumnType() {
+			return columnType;
+		}
+	};
+}
+/**
+* Factory that returns a MikroORM `Type` subclass for a **nullable** `Id<Brand>` column.
+*
+* Behaves like {@link idType} but `convertToJSValue` returns `null` for `null` /
+* `undefined` database values and `convertToDatabaseValue` passes `null` through
+* unchanged. Use for optional foreign keys.
+*
+* @example
+* ```ts
+* import { Property } from "@mikro-orm/core";
+* import { nullableIdType } from "@smonn/ids/mikro-orm";
+* import { createTimestampId } from "@smonn/ids";
+* import type { Id } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+*
+* class Post {
+*   @Property({ type: nullableIdType(usr), nullable: true })
+*   authorId!: Id<"usr"> | null;
+* }
+* ```
+*/
+function nullableIdType(codec) {
+	return class extends Type {
+		convertToDatabaseValue(value) {
+			return value;
+		}
+		convertToJSValue(value) {
+			return readIdColumnNullable(codec, value);
+		}
 		getColumnType() {
 			return "text";
 		}
 	};
 }
 //#endregion
-export { IdsError, idType, isIdsError };
+export { IdsError, idType, isIdsError, nullableIdType };
 
 //# sourceMappingURL=mikro-orm.mjs.map

package/dist/mikro-orm.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"mikro-orm.mjs","names":[],"sources":["../src/adapters/mikro-orm.ts"],"sourcesContent":["import { Type } from \"@mikro-orm/core\";\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 * Factory that returns a MikroORM `Type` subclass bound to a codec.\n *\n * **Write path** (`convertToDatabaseValue`): passes the `Id<Brand>` through\n * unchanged — it is already the canonical string form.\n *\n * **Read path** (`convertToJSValue`): normalises the raw DB value via\n * `codec.safeParse()`. Throws `IdsError(\"invalid_id\")` if the stored value\n * does not parse as a valid `Id<Brand>`.\n *\n * **Column type** (`getColumnType`): returns `\"text\"`.\n *\n * @example\n * ```ts\n * import { PrimaryKey } from \"@mikro-orm/core\";\n * import { idType } from \"@smonn/ids/mikro-orm\";\n * import { createTimestampId } from \"@smonn/ids\";\n * import type { Id } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n *\n * class User {\n *   @PrimaryKey({ type: idType(usr) })\n *   id!: Id<\"usr\">;\n * }\n * ```\n */\nexport function idType<Brand extends string>(\n  codec: IdColumnCodec<Brand>,\n): new () => Type<Id<Brand>, string> {\n  return class extends Type<Id<Brand>, string> {\n    override convertToDatabaseValue(value: Id<Brand>): string {\n      return value;\n    }\n    override convertToJSValue(value: string): Id<Brand> {\n      return readIdColumn(codec, value);\n    }\n    override getColumnType(): string {\n      return \"text\";\n    }\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCA,SAAgB,OACd,OACmC;CACnC,OAAO,cAAc,KAAwB;EAC3C,uBAAgC,OAA0B;GACxD,OAAO;EACT;EACA,iBAA0B,OAA0B;GAClD,OAAO,aAAa,OAAO,KAAK;EAClC;EACA,gBAAiC;GAC/B,OAAO;EACT;CACF;AACF"}
+{"version":3,"file":"mikro-orm.mjs","names":[],"sources":["../src/adapters/mikro-orm.ts"],"sourcesContent":["import { Type } from \"@mikro-orm/core\";\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 * Factory that returns a MikroORM `Type` subclass bound to a codec.\n *\n * **Write path** (`convertToDatabaseValue`): passes the `Id<Brand>` through\n * unchanged — it is already the canonical string form.\n *\n * **Read path** (`convertToJSValue`): normalises the raw DB value via\n * `codec.safeParse()`. Throws `IdsError(\"invalid_id\")` if the stored value\n * does not parse as a valid `Id<Brand>`.\n *\n * **Column type** (`getColumnType`): returns `\"text\"` by default, or the\n * `options.columnType` override when provided.\n *\n * @param codec - The brand-scoped codec used to parse values read from the database.\n * @param options - Optional column configuration.\n * @param options.columnType - SQL column type to use (default: `\"text\"`). Pass\n *   `\"varchar(30)\"` or `\"char(26)\"` to match an existing DDL or index strategy.\n *   The value is passed through verbatim — no validation is performed.\n *\n * @example\n * ```ts\n * import { PrimaryKey } from \"@mikro-orm/core\";\n * import { idType } from \"@smonn/ids/mikro-orm\";\n * import { createTimestampId } from \"@smonn/ids\";\n * import type { Id } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n *\n * // default: text column\n * class User {\n *   @PrimaryKey({ type: idType(usr) })\n *   id!: Id<\"usr\">;\n * }\n *\n * // explicit varchar column\n * class Org {\n *   @PrimaryKey({ type: idType(usr, { columnType: \"varchar(30)\" }) })\n *   id!: Id<\"usr\">;\n * }\n * ```\n */\nexport function idType<Brand extends string>(\n  codec: IdColumnCodec<Brand>,\n  options?: { columnType?: string },\n): new () => Type<Id<Brand>, string> {\n  const columnType = options?.columnType ?? \"text\";\n  return class extends Type<Id<Brand>, string> {\n    override convertToDatabaseValue(value: Id<Brand>): string {\n      return value;\n    }\n    override convertToJSValue(value: string): Id<Brand> {\n      return readIdColumn(codec, value);\n    }\n    override getColumnType(): string {\n      return columnType;\n    }\n  };\n}\n\n/**\n * Factory that returns a MikroORM `Type` subclass for a **nullable** `Id<Brand>` column.\n *\n * Behaves like {@link idType} but `convertToJSValue` returns `null` for `null` /\n * `undefined` database values and `convertToDatabaseValue` passes `null` through\n * unchanged. Use for optional foreign keys.\n *\n * @example\n * ```ts\n * import { Property } from \"@mikro-orm/core\";\n * import { nullableIdType } from \"@smonn/ids/mikro-orm\";\n * import { createTimestampId } from \"@smonn/ids\";\n * import type { Id } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n *\n * class Post {\n *   @Property({ type: nullableIdType(usr), nullable: true })\n *   authorId!: Id<\"usr\"> | null;\n * }\n * ```\n */\nexport function nullableIdType<Brand extends string>(\n  codec: IdColumnCodec<Brand>,\n): new () => Type<Id<Brand> | null, string | null> {\n  return class extends Type<Id<Brand> | null, string | null> {\n    override convertToDatabaseValue(value: Id<Brand> | null): string | null {\n      return value;\n    }\n    override convertToJSValue(value: string | null): Id<Brand> | null {\n      return readIdColumnNullable(codec, value);\n    }\n    override getColumnType(): string {\n      return \"text\";\n    }\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkDA,SAAgB,OACd,OACA,SACmC;CACnC,MAAM,aAAa,SAAS,cAAc;CAC1C,OAAO,cAAc,KAAwB;EAC3C,uBAAgC,OAA0B;GACxD,OAAO;EACT;EACA,iBAA0B,OAA0B;GAClD,OAAO,aAAa,OAAO,KAAK;EAClC;EACA,gBAAiC;GAC/B,OAAO;EACT;CACF;AACF;;;;;;;;;;;;;;;;;;;;;;;AAwBA,SAAgB,eACd,OACiD;CACjD,OAAO,cAAc,KAAsC;EACzD,uBAAgC,OAAwC;GACtE,OAAO;EACT;EACA,iBAA0B,OAAwC;GAChE,OAAO,qBAAqB,OAAO,KAAK;EAC1C;EACA,gBAAiC;GAC/B,OAAO;EACT;CACF;AACF"}

package/dist/nestjs.mjs

@@ -1,4 +1,4 @@
-import { n as resolveIdParamFailure } from "./adapter-types-7wWdELSh.mjs";
+import { r as resolveIdParamFailure } from "./adapter-types-CjzFNDcJ.mjs";
 import { BadRequestException, HttpException, Injectable, NotFoundException } from "@nestjs/common";
 //#region src/adapters/nestjs.ts
 /**