@smonn/ids 0.15.0 → 1.0.0-rc.0

package/dist/drizzle.d.mts

@@ -2,10 +2,12 @@ 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 { ConvertCustomConfig, PgCustomColumnBuilder } from "drizzle-orm/pg-core";
+import { ConvertCustomConfig as ConvertCustomConfig$1, MySqlCustomColumnBuilder } from "drizzle-orm/mysql-core";
+import { ConvertCustomConfig as ConvertCustomConfig$2, SQLiteCustomColumnBuilder } from "drizzle-orm/sqlite-core";
 
 //#region src/adapters/drizzle.d.ts
 /**
-* Drizzle custom column type that stores an `Id<Brand>` as a canonical `text` value.
+* Drizzle custom column type that stores an `Id<Brand>` as a canonical SQL string value in PostgreSQL.
 *
 * **Write path:** passes the `Id<Brand>` directly to the driver — it is already
 * the canonical string form.
@@ -15,20 +17,102 @@ import { ConvertCustomConfig, PgCustomColumnBuilder } from "drizzle-orm/pg-core"
 * is a safe boundary in case stale non-canonical values exist. Throws if the
 * value from the database does not parse as a valid `Id<Brand>`.
 *
+* @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
 * import { idColumn } from "@smonn/ids/drizzle";
 * import { createTimestampId } from "@smonn/ids";
 *
 * const usr = createTimestampId("usr");
+* // default: text column
 * export const users = pgTable("users", { id: idColumn(usr).primaryKey() });
+* // explicit varchar column
+* export const orgs = pgTable("orgs", { id: idColumn(usr, { columnType: "varchar(30)" }).primaryKey() });
+* ```
+*/
+declare function idColumn<Brand extends string>(codec: IdColumnCodec<Brand>, options?: {
+  columnType?: string;
+}): PgCustomColumnBuilder<ConvertCustomConfig<"", {
+  data: Id<Brand>;
+  driverData: string;
+}>>;
+/**
+* Drizzle custom column type that stores an `Id<Brand>` as a canonical `text` value in MySQL.
+*
+* **Write path:** passes the `Id<Brand>` directly to the driver — it is already
+* the canonical string form.
+*
+* **Read path:** normalises the raw DB string via `codec.safeParse()`, not strict
+* `is()`. Throws `IdsError("invalid_id")` if the value from the database does not
+* parse as a valid `Id<Brand>`.
+*
+* @example
+* ```ts
+* import { idColumnMysql } from "@smonn/ids/drizzle";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+* export const users = mysqlTable("users", { id: idColumnMysql(usr).primaryKey() });
 * // users.id is Id<"usr"> end-to-end
 * ```
 */
-declare function idColumn<Brand extends string>(codec: IdColumnCodec<Brand>): PgCustomColumnBuilder<ConvertCustomConfig<"", {
+declare function idColumnMysql<Brand extends string>(codec: IdColumnCodec<Brand>): MySqlCustomColumnBuilder<ConvertCustomConfig$1<"", {
   data: Id<Brand>;
   driverData: string;
 }>>;
+/**
+* Drizzle custom column type that stores an `Id<Brand>` as a canonical `text` value in SQLite.
+*
+* **Write path:** passes the `Id<Brand>` directly to the driver — it is already
+* the canonical string form.
+*
+* **Read path:** normalises the raw DB string via `codec.safeParse()`, not strict
+* `is()`. Throws `IdsError("invalid_id")` if the value from the database does not
+* parse as a valid `Id<Brand>`.
+*
+* @example
+* ```ts
+* import { idColumnSqlite } from "@smonn/ids/drizzle";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+* export const users = sqliteTable("users", { id: idColumnSqlite(usr).primaryKey() });
+* // users.id is Id<"usr"> end-to-end
+* ```
+*/
+declare function idColumnSqlite<Brand extends string>(codec: IdColumnCodec<Brand>): SQLiteCustomColumnBuilder<ConvertCustomConfig$2<"", {
+  data: Id<Brand>;
+  driverData: string;
+}>>;
+/**
+* Drizzle custom column type for a **nullable** `Id<Brand>` column.
+*
+* Behaves identically to {@link idColumn} except that `null` and `undefined`
+* driver values are passed through as `null` rather than throwing. Use for
+* optional foreign keys, `LEFT JOIN` results, and any column that is
+* legitimately absent.
+*
+* @example
+* ```ts
+* import { nullableIdColumn } from "@smonn/ids/drizzle";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+* export const posts = pgTable("posts", {
+*   authorId: nullableIdColumn(usr),
+* });
+* // posts.authorId is Id<"usr"> | null end-to-end
+* ```
+*/
+declare function nullableIdColumn<Brand extends string>(codec: IdColumnCodec<Brand>): PgCustomColumnBuilder<ConvertCustomConfig<"", {
+  data: Id<Brand> | null;
+  driverData: string | null;
+}>>;
 //#endregion
-export { type IdColumnCodec, IdsError, type IdsErrorCode, idColumn, isIdsError };
+export { type IdColumnCodec, IdsError, type IdsErrorCode, idColumn, idColumnMysql, idColumnSqlite, isIdsError, nullableIdColumn };
 //# sourceMappingURL=drizzle.d.mts.map

package/dist/drizzle.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"drizzle.d.mts","names":[],"sources":["../src/adapters/drizzle.ts"],"mappings":";;;;;;AAkCA;;;;;;;;;;;;;;;;;;;;;AAAA,iBAAgB,QAAA,uBACd,KAAA,EAAO,aAAA,CAAc,KAAA,IACpB,qBAAA,CAAsB,mBAAA;EAA0B,IAAA,EAAM,EAAA,CAAG,KAAA;EAAQ,UAAA;AAAA"}
+{"version":3,"file":"drizzle.d.mts","names":[],"sources":["../src/adapters/drizzle.ts"],"mappings":";;;;;;;;AAoDA;;;;;;;;;;;;;;;;;;;;;;;;AAGoE;AAmCpE;;;;AAtCA,iBAAgB,QAAA,uBACd,KAAA,EAAO,aAAA,CAAc,KAAA,GACrB,OAAA;EAAY,UAAA;AAAA,IACX,qBAAA,CAAsB,mBAAA;EAA0B,IAAA,EAAM,EAAA,CAAG,KAAA;EAAQ,UAAA;AAAA;;;;;;;;;;;;;AAqCQ;AAkC5E;;;;;;;iBApCgB,aAAA,uBACd,KAAA,EAAO,aAAA,CAAc,KAAA,IACpB,wBAAA,CAAyB,qBAAA;EAA+B,IAAA,EAAM,EAAA,CAAG,KAAA;EAAQ,UAAA;AAAA;;;;;;;;;;;;AAqCzB;AAmCnD;;;;;;;;iBAtCgB,cAAA,uBACd,KAAA,EAAO,aAAA,CAAc,KAAA,IACpB,yBAAA,CACD,qBAAA;EAAgC,IAAA,EAAM,EAAA,CAAG,KAAA;EAAQ,UAAA;AAAA;;;;;;;;;;;AAsCC;;;;;;;;;;iBAHpC,gBAAA,uBACd,KAAA,EAAO,aAAA,CAAc,KAAA,IACpB,qBAAA,CACD,mBAAA;EAA0B,IAAA,EAAM,EAAA,CAAG,KAAA;EAAe,UAAA;AAAA"}

package/dist/drizzle.mjs

@@ -1,9 +1,11 @@
 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 { customType } from "drizzle-orm/pg-core";
+import { customType as customType$1 } from "drizzle-orm/mysql-core";
+import { customType as customType$2 } from "drizzle-orm/sqlite-core";
 //#region src/adapters/drizzle.ts
 /**
-* Drizzle custom column type that stores an `Id<Brand>` as a canonical `text` value.
+* Drizzle custom column type that stores an `Id<Brand>` as a canonical SQL string value in PostgreSQL.
 *
 * **Write path:** passes the `Id<Brand>` directly to the driver — it is already
 * the canonical string form.
@@ -13,18 +15,93 @@ import { customType } from "drizzle-orm/pg-core";
 * is a safe boundary in case stale non-canonical values exist. Throws if the
 * value from the database does not parse as a valid `Id<Brand>`.
 *
+* @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
 * import { idColumn } from "@smonn/ids/drizzle";
 * import { createTimestampId } from "@smonn/ids";
 *
 * const usr = createTimestampId("usr");
+* // default: text column
 * export const users = pgTable("users", { id: idColumn(usr).primaryKey() });
-* // users.id is Id<"usr"> end-to-end
+* // explicit varchar column
+* export const orgs = pgTable("orgs", { id: idColumn(usr, { columnType: "varchar(30)" }).primaryKey() });
 * ```
 */
-function idColumn(codec) {
+function idColumn(codec, options) {
+	const columnType = options?.columnType ?? "text";
 	return customType({
+		dataType() {
+			return columnType;
+		},
+		toDriver(value) {
+			return value;
+		},
+		fromDriver(value) {
+			return readIdColumn(codec, value);
+		}
+	})();
+}
+/**
+* Drizzle custom column type that stores an `Id<Brand>` as a canonical `text` value in MySQL.
+*
+* **Write path:** passes the `Id<Brand>` directly to the driver — it is already
+* the canonical string form.
+*
+* **Read path:** normalises the raw DB string via `codec.safeParse()`, not strict
+* `is()`. Throws `IdsError("invalid_id")` if the value from the database does not
+* parse as a valid `Id<Brand>`.
+*
+* @example
+* ```ts
+* import { idColumnMysql } from "@smonn/ids/drizzle";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+* export const users = mysqlTable("users", { id: idColumnMysql(usr).primaryKey() });
+* // users.id is Id<"usr"> end-to-end
+* ```
+*/
+function idColumnMysql(codec) {
+	return customType$1({
+		dataType() {
+			return "text";
+		},
+		toDriver(value) {
+			return value;
+		},
+		fromDriver(value) {
+			return readIdColumn(codec, value);
+		}
+	})();
+}
+/**
+* Drizzle custom column type that stores an `Id<Brand>` as a canonical `text` value in SQLite.
+*
+* **Write path:** passes the `Id<Brand>` directly to the driver — it is already
+* the canonical string form.
+*
+* **Read path:** normalises the raw DB string via `codec.safeParse()`, not strict
+* `is()`. Throws `IdsError("invalid_id")` if the value from the database does not
+* parse as a valid `Id<Brand>`.
+*
+* @example
+* ```ts
+* import { idColumnSqlite } from "@smonn/ids/drizzle";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+* export const users = sqliteTable("users", { id: idColumnSqlite(usr).primaryKey() });
+* // users.id is Id<"usr"> end-to-end
+* ```
+*/
+function idColumnSqlite(codec) {
+	return customType$2({
 		dataType() {
 			return "text";
 		},
@@ -36,7 +113,40 @@ function idColumn(codec) {
 		}
 	})();
 }
+/**
+* Drizzle custom column type for a **nullable** `Id<Brand>` column.
+*
+* Behaves identically to {@link idColumn} except that `null` and `undefined`
+* driver values are passed through as `null` rather than throwing. Use for
+* optional foreign keys, `LEFT JOIN` results, and any column that is
+* legitimately absent.
+*
+* @example
+* ```ts
+* import { nullableIdColumn } from "@smonn/ids/drizzle";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+* export const posts = pgTable("posts", {
+*   authorId: nullableIdColumn(usr),
+* });
+* // posts.authorId is Id<"usr"> | null end-to-end
+* ```
+*/
+function nullableIdColumn(codec) {
+	return customType({
+		dataType() {
+			return "text";
+		},
+		toDriver(value) {
+			return value;
+		},
+		fromDriver(value) {
+			return readIdColumnNullable(codec, value);
+		}
+	})();
+}
 //#endregion
-export { IdsError, idColumn, isIdsError };
+export { IdsError, idColumn, idColumnMysql, idColumnSqlite, isIdsError, nullableIdColumn };
 
 //# sourceMappingURL=drizzle.mjs.map

package/dist/drizzle.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"drizzle.mjs","names":[],"sources":["../src/adapters/drizzle.ts"],"sourcesContent":["import {\n  customType,\n  type ConvertCustomConfig,\n  type PgCustomColumnBuilder,\n} from \"drizzle-orm/pg-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 * Drizzle custom column type that stores an `Id<Brand>` as a canonical `text` value.\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()`, not strict\n * `is()`. Data at rest should already be canonical per ADR-0003, but `safeParse`\n * is a safe boundary in case stale non-canonical values exist. Throws if the\n * value from the database does not parse as a valid `Id<Brand>`.\n *\n * @example\n * ```ts\n * import { idColumn } from \"@smonn/ids/drizzle\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n * export const users = pgTable(\"users\", { id: idColumn(usr).primaryKey() });\n * // users.id is Id<\"usr\"> end-to-end\n * ```\n */\nexport function idColumn<Brand extends string>(\n  codec: IdColumnCodec<Brand>,\n): PgCustomColumnBuilder<ConvertCustomConfig<\"\", { data: Id<Brand>; driverData: string }>> {\n  return customType<{ data: Id<Brand>; driverData: string }>({\n    dataType() {\n      return \"text\";\n    },\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":";;;;;;;;;;;;;;;;;;;;;;;;;AAkCA,SAAgB,SACd,OACyF;CACzF,OAAO,WAAoD;EACzD,WAAW;GACT,OAAO;EACT;EACA,SAAS,OAA0B;GACjC,OAAO;EACT;EACA,WAAW,OAA0B;GACnC,OAAO,aAAa,OAAO,KAAK;EAClC;CACF,CAAC,CAAC,CAAC;AACL"}
+{"version":3,"file":"drizzle.mjs","names":["customTypeMysql","customTypeSqlite"],"sources":["../src/adapters/drizzle.ts"],"sourcesContent":["import {\n  customType,\n  type ConvertCustomConfig,\n  type PgCustomColumnBuilder,\n} from \"drizzle-orm/pg-core\";\nimport {\n  customType as customTypeMysql,\n  type ConvertCustomConfig as ConvertCustomConfigMysql,\n  type MySqlCustomColumnBuilder,\n} from \"drizzle-orm/mysql-core\";\nimport {\n  customType as customTypeSqlite,\n  type ConvertCustomConfig as ConvertCustomConfigSqlite,\n  type SQLiteCustomColumnBuilder,\n} from \"drizzle-orm/sqlite-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 * Drizzle custom column type that stores an `Id<Brand>` as a canonical SQL string value in PostgreSQL.\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()`, not strict\n * `is()`. Data at rest should already be canonical per ADR-0003, but `safeParse`\n * is a safe boundary in case stale non-canonical values exist. Throws if the\n * value from the database does not parse as a valid `Id<Brand>`.\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 { idColumn } from \"@smonn/ids/drizzle\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n * // default: text column\n * export const users = pgTable(\"users\", { id: idColumn(usr).primaryKey() });\n * // explicit varchar column\n * export const orgs = pgTable(\"orgs\", { id: idColumn(usr, { columnType: \"varchar(30)\" }).primaryKey() });\n * ```\n */\nexport function idColumn<Brand extends string>(\n  codec: IdColumnCodec<Brand>,\n  options?: { columnType?: string },\n): PgCustomColumnBuilder<ConvertCustomConfig<\"\", { data: Id<Brand>; driverData: string }>> {\n  const columnType = options?.columnType ?? \"text\";\n  return customType<{ data: Id<Brand>; driverData: string }>({\n    dataType() {\n      return columnType;\n    },\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 * Drizzle custom column type that stores an `Id<Brand>` as a canonical `text` value in MySQL.\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()`, not strict\n * `is()`. Throws `IdsError(\"invalid_id\")` if the value from the database does not\n * parse as a valid `Id<Brand>`.\n *\n * @example\n * ```ts\n * import { idColumnMysql } from \"@smonn/ids/drizzle\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n * export const users = mysqlTable(\"users\", { id: idColumnMysql(usr).primaryKey() });\n * // users.id is Id<\"usr\"> end-to-end\n * ```\n */\nexport function idColumnMysql<Brand extends string>(\n  codec: IdColumnCodec<Brand>,\n): MySqlCustomColumnBuilder<ConvertCustomConfigMysql<\"\", { data: Id<Brand>; driverData: string }>> {\n  return customTypeMysql<{ data: Id<Brand>; driverData: string }>({\n    dataType() {\n      return \"text\";\n    },\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 * Drizzle custom column type that stores an `Id<Brand>` as a canonical `text` value in SQLite.\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()`, not strict\n * `is()`. Throws `IdsError(\"invalid_id\")` if the value from the database does not\n * parse as a valid `Id<Brand>`.\n *\n * @example\n * ```ts\n * import { idColumnSqlite } from \"@smonn/ids/drizzle\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n * export const users = sqliteTable(\"users\", { id: idColumnSqlite(usr).primaryKey() });\n * // users.id is Id<\"usr\"> end-to-end\n * ```\n */\nexport function idColumnSqlite<Brand extends string>(\n  codec: IdColumnCodec<Brand>,\n): SQLiteCustomColumnBuilder<\n  ConvertCustomConfigSqlite<\"\", { data: Id<Brand>; driverData: string }>\n> {\n  return customTypeSqlite<{ data: Id<Brand>; driverData: string }>({\n    dataType() {\n      return \"text\";\n    },\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 * Drizzle custom column type for a **nullable** `Id<Brand>` column.\n *\n * Behaves identically to {@link idColumn} except that `null` and `undefined`\n * driver values are passed through as `null` rather than throwing. Use for\n * optional foreign keys, `LEFT JOIN` results, and any column that is\n * legitimately absent.\n *\n * @example\n * ```ts\n * import { nullableIdColumn } from \"@smonn/ids/drizzle\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n * export const posts = pgTable(\"posts\", {\n *   authorId: nullableIdColumn(usr),\n * });\n * // posts.authorId is Id<\"usr\"> | null end-to-end\n * ```\n */\nexport function nullableIdColumn<Brand extends string>(\n  codec: IdColumnCodec<Brand>,\n): PgCustomColumnBuilder<\n  ConvertCustomConfig<\"\", { data: Id<Brand> | null; driverData: string | null }>\n> {\n  return customType<{ data: Id<Brand> | null; driverData: string | null }>({\n    dataType() {\n      return \"text\";\n    },\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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoDA,SAAgB,SACd,OACA,SACyF;CACzF,MAAM,aAAa,SAAS,cAAc;CAC1C,OAAO,WAAoD;EACzD,WAAW;GACT,OAAO;EACT;EACA,SAAS,OAA0B;GACjC,OAAO;EACT;EACA,WAAW,OAA0B;GACnC,OAAO,aAAa,OAAO,KAAK;EAClC;CACF,CAAC,CAAC,CAAC;AACL;;;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,cACd,OACiG;CACjG,OAAOA,aAAyD;EAC9D,WAAW;GACT,OAAO;EACT;EACA,SAAS,OAA0B;GACjC,OAAO;EACT;EACA,WAAW,OAA0B;GACnC,OAAO,aAAa,OAAO,KAAK;EAClC;CACF,CAAC,CAAC,CAAC;AACL;;;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,eACd,OAGA;CACA,OAAOC,aAA0D;EAC/D,WAAW;GACT,OAAO;EACT;EACA,SAAS,OAA0B;GACjC,OAAO;EACT;EACA,WAAW,OAA0B;GACnC,OAAO,aAAa,OAAO,KAAK;EAClC;CACF,CAAC,CAAC,CAAC;AACL;;;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,iBACd,OAGA;CACA,OAAO,WAAkE;EACvE,WAAW;GACT,OAAO;EACT;EACA,SAAS,OAAwC;GAC/C,OAAO;EACT;EACA,WAAW,OAAwC;GACjD,OAAO,qBAAqB,OAAO,KAAK;EAC1C;CACF,CAAC,CAAC,CAAC;AACL"}

package/dist/express.d.mts

@@ -12,7 +12,7 @@ declare class IdParamError extends Error {
   readonly reason: "brand_mismatch" | "malformed";
   constructor(reason: "brand_mismatch" | "malformed", status: number);
 }
-/** Options for `idParam`. All fields are optional. */
+/** Options for `idParam` and `idQuery`. All fields are optional. */
 type IdParamOptions = {
   /**
   * Called instead of forwarding to `next(err)` when provided. The hook owns the response
@@ -77,6 +77,48 @@ type IdParamOptions = {
 * ```
 */
 declare function idParam<ParamKey extends string, Brand extends string>(paramName: ParamKey, codec: IdCodec<Brand>, options?: IdParamOptions): (req: Request, res: Response<unknown, Record<ParamKey, Id<Brand>>>, next: NextFunction) => void;
+/**
+* Express middleware that validates a named query-string param against a codec via `safeParse`.
+*
+* Same failure contract as `idParam` — same `IdParamOptions` / `IdParamFailure` shape, same
+* `IdParamError` forwarded to `next(err)` — but reads `req.query[queryName]` instead of
+* `req.params[queryName]`.
+*
+* **Default (no options):** calls `next(err)` with an `IdParamError` carrying `status` and
+* `reason`, so the app's existing error-handling middleware controls rendering. The adapter
+* does not write a response body itself.
+*
+* **`options.onError`:** when provided, the hook owns the response entirely — the adapter does
+* not call `next(err)`.
+*
+* **`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 `res.locals` under `queryName`
+* and calls `next()`.
+*
+* @example
+* ```ts
+* import { idQuery, IdParamError } from "@smonn/ids/express";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+*
+* // Default: forwards error to app error-handling middleware
+* // GET /users?userId=usr_...
+* app.get("/users", idQuery("userId", usr), (req, res) => {
+*   const userId = res.locals.userId; // Id<"usr">, canonical
+* });
+*
+* // Override: consumer fully owns the response
+* app.get("/search", idQuery("cursor", usr, {
+*   onError: (failure, req, res) => res.status(failure.status).json({ error: failure.reason }),
+* }), handler);
+* ```
+*/
+declare function idQuery<ParamKey extends string, Brand extends string>(queryName: ParamKey, codec: IdCodec<Brand>, options?: IdParamOptions): (req: Request, res: Response<unknown, Record<ParamKey, Id<Brand>>>, next: NextFunction) => void;
 //#endregion
-export { IdParamError, type IdParamFailure, IdParamOptions, idParam };
+export { IdParamError, type IdParamFailure, IdParamOptions, idParam, idQuery };
 //# sourceMappingURL=express.d.mts.map

package/dist/express.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"express.d.mts","names":[],"sources":["../src/adapters/express.ts"],"mappings":";;;;;;AAUA;;;cAAa,YAAA,SAAqB,KAAA;EAAA,SACvB,MAAA;EAAA,SACA,MAAA;EAET,WAAA,CAAY,MAAA,kCAAwC,MAAA;AAAA;;KAS1C,cAAA;EAT0C;AAAA;AAStD;;EAKE,OAAA,IAAW,OAAA,EAAS,cAAA,EAAgB,GAAA,EAAK,OAAA,EAAS,GAAA,EAAK,QAAA,EAAU,IAAA,EAAM,YAAA;;;;;EAKvE,MAAA;IAAW,cAAA;IAAyB,SAAA;EAAA;AAAA;;;;;;;;;;;AAAA;AAmDtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAI6E;iBAJ7D,OAAA,gDACd,SAAA,EAAW,QAAA,EACX,KAAA,EAAO,OAAA,CAAQ,KAAA,GACf,OAAA,GAAU,cAAA,IACR,GAAA,EAAK,OAAA,EAAS,GAAA,EAAK,QAAA,UAAkB,MAAA,CAAO,QAAA,EAAU,EAAA,CAAG,KAAA,KAAU,IAAA,EAAM,YAAA"}
+{"version":3,"file":"express.d.mts","names":[],"sources":["../src/adapters/express.ts"],"mappings":";;;;;;AAUA;;;cAAa,YAAA,SAAqB,KAAA;EAAA,SACvB,MAAA;EAAA,SACA,MAAA;EAET,WAAA,CAAY,MAAA,kCAAwC,MAAA;AAAA;;KAS1C,cAAA;EAT0C;AAAA;AAStD;;EAKE,OAAA,IAAW,OAAA,EAAS,cAAA,EAAgB,GAAA,EAAK,OAAA,EAAS,GAAA,EAAK,QAAA,EAAU,IAAA,EAAM,YAAA;;;;;EAKvE,MAAA;IAAW,cAAA;IAAyB,SAAA;EAAA;AAAA;;;;;;;;;;;AAAA;AAmDtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAI6E;iBAJ7D,OAAA,gDACd,SAAA,EAAW,QAAA,EACX,KAAA,EAAO,OAAA,CAAQ,KAAA,GACf,OAAA,GAAU,cAAA,IACR,GAAA,EAAK,OAAA,EAAS,GAAA,EAAK,QAAA,UAAkB,MAAA,CAAO,QAAA,EAAU,EAAA,CAAG,KAAA,KAAU,IAAA,EAAM,YAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+DA;;;;;;;;;iBAJ7D,OAAA,gDACd,SAAA,EAAW,QAAA,EACX,KAAA,EAAO,OAAA,CAAQ,KAAA,GACf,OAAA,GAAU,cAAA,IACR,GAAA,EAAK,OAAA,EAAS,GAAA,EAAK,QAAA,UAAkB,MAAA,CAAO,QAAA,EAAU,EAAA,CAAG,KAAA,KAAU,IAAA,EAAM,YAAA"}

package/dist/express.mjs

@@ -1,4 +1,4 @@
-import { n as resolveIdParamFailure } from "./adapter-types-7wWdELSh.mjs";
+import { r as resolveIdParamFailure } from "./adapter-types-CjzFNDcJ.mjs";
 //#region src/adapters/express.ts
 /**
 * Typed error forwarded to Express's error pipeline (`next(err)`) on validation failure.
@@ -79,7 +79,65 @@ function idParam(paramName, codec, options) {
 		next();
 	};
 }
+/**
+* Express middleware that validates a named query-string param against a codec via `safeParse`.
+*
+* Same failure contract as `idParam` — same `IdParamOptions` / `IdParamFailure` shape, same
+* `IdParamError` forwarded to `next(err)` — but reads `req.query[queryName]` instead of
+* `req.params[queryName]`.
+*
+* **Default (no options):** calls `next(err)` with an `IdParamError` carrying `status` and
+* `reason`, so the app's existing error-handling middleware controls rendering. The adapter
+* does not write a response body itself.
+*
+* **`options.onError`:** when provided, the hook owns the response entirely — the adapter does
+* not call `next(err)`.
+*
+* **`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 `res.locals` under `queryName`
+* and calls `next()`.
+*
+* @example
+* ```ts
+* import { idQuery, IdParamError } from "@smonn/ids/express";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+*
+* // Default: forwards error to app error-handling middleware
+* // GET /users?userId=usr_...
+* app.get("/users", idQuery("userId", usr), (req, res) => {
+*   const userId = res.locals.userId; // Id<"usr">, canonical
+* });
+*
+* // Override: consumer fully owns the response
+* app.get("/search", idQuery("cursor", usr, {
+*   onError: (failure, req, res) => res.status(failure.status).json({ error: failure.reason }),
+* }), handler);
+* ```
+*/
+function idQuery(queryName, codec, options) {
+	return (req, res, next) => {
+		const raw = req.query[queryName];
+		const result = codec.safeParse(raw);
+		if (!result.ok) {
+			const failure = resolveIdParamFailure(result.error, options);
+			if (options?.onError) {
+				options.onError(failure, req, res, next);
+				return;
+			}
+			next(new IdParamError(failure.reason, failure.status));
+			return;
+		}
+		res.locals[queryName] = result.id;
+		next();
+	};
+}
 //#endregion
-export { IdParamError, idParam };
+export { IdParamError, idParam, idQuery };
 
 //# sourceMappingURL=express.mjs.map

package/dist/express.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"express.mjs","names":[],"sources":["../src/adapters/express.ts"],"sourcesContent":["import type { NextFunction, Request, Response } from \"express\";\nimport { type IdCodec, type IdParamFailure, resolveIdParamFailure } from \"./adapter-types.js\";\nimport type { Id } from \"../types.js\";\n\nexport type { IdParamFailure };\n\n/**\n * Typed error forwarded to Express's error pipeline (`next(err)`) on validation failure.\n * Inspect `err.reason` and `err.status` in error-handling middleware.\n */\nexport class IdParamError extends Error {\n  readonly status: number;\n  readonly reason: \"brand_mismatch\" | \"malformed\";\n\n  constructor(reason: \"brand_mismatch\" | \"malformed\", status: number) {\n    super(`ID validation failed: ${reason}`);\n    this.name = \"IdParamError\";\n    this.reason = reason;\n    this.status = status;\n  }\n}\n\n/** Options for `idParam`. All fields are optional. */\nexport type IdParamOptions = {\n  /**\n   * Called instead of forwarding to `next(err)` when provided. The hook owns the response\n   * entirely — the adapter does not call `next(err)` itself.\n   */\n  onError?: (failure: IdParamFailure, req: Request, res: Response, next: NextFunction) => void;\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?: number; malformed?: number };\n};\n\n/**\n * Express middleware that validates a named route param against a codec via `safeParse`.\n *\n * **Default (no options):** calls `next(err)` with an `IdParamError` carrying `status` and `reason`,\n * so the app's existing error-handling middleware controls rendering. The adapter does not write\n * a response body itself.\n *\n * **`options.onError`:** when provided, the hook owns the response entirely — the adapter does\n * not call `next(err)`.\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 `res.locals` under `paramName`\n * and calls `next()`.\n *\n * @example\n * ```ts\n * import { idParam, IdParamError } from \"@smonn/ids/express\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n *\n * // Default: forwards error to app error-handling middleware\n * app.get(\"/users/:id\", idParam(\"id\", usr), (req, res) => {\n *   const id = res.locals.id; // Id<\"usr\">, canonical\n * });\n *\n * // Error-handling middleware receives the typed error\n * app.use((err, req, res, next) => {\n *   if (err instanceof IdParamError) {\n *     res.status(err.status).json({ error: err.reason });\n *     return;\n *   }\n *   next(err);\n * });\n *\n * // Override: consumer fully owns the response\n * app.get(\"/orgs/:id\", idParam(\"id\", org, {\n *   onError: (failure, req, res) => res.status(failure.status).json({ error: failure.reason }),\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): (req: Request, res: Response<unknown, Record<ParamKey, Id<Brand>>>, next: NextFunction) => void {\n  return (req, res, next): void => {\n    const raw = req.params[paramName];\n    const result = codec.safeParse(raw);\n    if (!result.ok) {\n      const failure = resolveIdParamFailure(result.error, options);\n      if (options?.onError) {\n        options.onError(failure, req, res, next);\n        return;\n      }\n      next(new IdParamError(failure.reason, failure.status));\n      return;\n    }\n    (res.locals as Record<string, unknown>)[paramName] = result.id;\n    next();\n  };\n}\n"],"mappings":";;;;;;AAUA,IAAa,eAAb,cAAkC,MAAM;CACtC;CACA;CAEA,YAAY,QAAwC,QAAgB;EAClE,MAAM,yBAAyB,QAAQ;EACvC,KAAK,OAAO;EACZ,KAAK,SAAS;EACd,KAAK,SAAS;CAChB;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgEA,SAAgB,QACd,WACA,OACA,SACiG;CACjG,QAAQ,KAAK,KAAK,SAAe;EAC/B,MAAM,MAAM,IAAI,OAAO;EACvB,MAAM,SAAS,MAAM,UAAU,GAAG;EAClC,IAAI,CAAC,OAAO,IAAI;GACd,MAAM,UAAU,sBAAsB,OAAO,OAAO,OAAO;GAC3D,IAAI,SAAS,SAAS;IACpB,QAAQ,QAAQ,SAAS,KAAK,KAAK,IAAI;IACvC;GACF;GACA,KAAK,IAAI,aAAa,QAAQ,QAAQ,QAAQ,MAAM,CAAC;GACrD;EACF;EACA,IAAK,OAAmC,aAAa,OAAO;EAC5D,KAAK;CACP;AACF"}
+{"version":3,"file":"express.mjs","names":[],"sources":["../src/adapters/express.ts"],"sourcesContent":["import type { NextFunction, Request, Response } from \"express\";\nimport { type IdCodec, type IdParamFailure, resolveIdParamFailure } from \"./adapter-types.js\";\nimport type { Id } from \"../types.js\";\n\nexport type { IdParamFailure };\n\n/**\n * Typed error forwarded to Express's error pipeline (`next(err)`) on validation failure.\n * Inspect `err.reason` and `err.status` in error-handling middleware.\n */\nexport class IdParamError extends Error {\n  readonly status: number;\n  readonly reason: \"brand_mismatch\" | \"malformed\";\n\n  constructor(reason: \"brand_mismatch\" | \"malformed\", status: number) {\n    super(`ID validation failed: ${reason}`);\n    this.name = \"IdParamError\";\n    this.reason = reason;\n    this.status = status;\n  }\n}\n\n/** Options for `idParam` and `idQuery`. All fields are optional. */\nexport type IdParamOptions = {\n  /**\n   * Called instead of forwarding to `next(err)` when provided. The hook owns the response\n   * entirely — the adapter does not call `next(err)` itself.\n   */\n  onError?: (failure: IdParamFailure, req: Request, res: Response, next: NextFunction) => void;\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?: number; malformed?: number };\n};\n\n/**\n * Express middleware that validates a named route param against a codec via `safeParse`.\n *\n * **Default (no options):** calls `next(err)` with an `IdParamError` carrying `status` and `reason`,\n * so the app's existing error-handling middleware controls rendering. The adapter does not write\n * a response body itself.\n *\n * **`options.onError`:** when provided, the hook owns the response entirely — the adapter does\n * not call `next(err)`.\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 `res.locals` under `paramName`\n * and calls `next()`.\n *\n * @example\n * ```ts\n * import { idParam, IdParamError } from \"@smonn/ids/express\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n *\n * // Default: forwards error to app error-handling middleware\n * app.get(\"/users/:id\", idParam(\"id\", usr), (req, res) => {\n *   const id = res.locals.id; // Id<\"usr\">, canonical\n * });\n *\n * // Error-handling middleware receives the typed error\n * app.use((err, req, res, next) => {\n *   if (err instanceof IdParamError) {\n *     res.status(err.status).json({ error: err.reason });\n *     return;\n *   }\n *   next(err);\n * });\n *\n * // Override: consumer fully owns the response\n * app.get(\"/orgs/:id\", idParam(\"id\", org, {\n *   onError: (failure, req, res) => res.status(failure.status).json({ error: failure.reason }),\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): (req: Request, res: Response<unknown, Record<ParamKey, Id<Brand>>>, next: NextFunction) => void {\n  return (req, res, next): void => {\n    const raw = req.params[paramName];\n    const result = codec.safeParse(raw);\n    if (!result.ok) {\n      const failure = resolveIdParamFailure(result.error, options);\n      if (options?.onError) {\n        options.onError(failure, req, res, next);\n        return;\n      }\n      next(new IdParamError(failure.reason, failure.status));\n      return;\n    }\n    (res.locals as Record<string, unknown>)[paramName] = result.id;\n    next();\n  };\n}\n\n/**\n * Express middleware that validates a named query-string param against a codec via `safeParse`.\n *\n * Same failure contract as `idParam` — same `IdParamOptions` / `IdParamFailure` shape, same\n * `IdParamError` forwarded to `next(err)` — but reads `req.query[queryName]` instead of\n * `req.params[queryName]`.\n *\n * **Default (no options):** calls `next(err)` with an `IdParamError` carrying `status` and\n * `reason`, so the app's existing error-handling middleware controls rendering. The adapter\n * does not write a response body itself.\n *\n * **`options.onError`:** when provided, the hook owns the response entirely — the adapter does\n * not call `next(err)`.\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 `res.locals` under `queryName`\n * and calls `next()`.\n *\n * @example\n * ```ts\n * import { idQuery, IdParamError } from \"@smonn/ids/express\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n *\n * // Default: forwards error to app error-handling middleware\n * // GET /users?userId=usr_...\n * app.get(\"/users\", idQuery(\"userId\", usr), (req, res) => {\n *   const userId = res.locals.userId; // Id<\"usr\">, canonical\n * });\n *\n * // Override: consumer fully owns the response\n * app.get(\"/search\", idQuery(\"cursor\", usr, {\n *   onError: (failure, req, res) => res.status(failure.status).json({ error: failure.reason }),\n * }), handler);\n * ```\n */\nexport function idQuery<ParamKey extends string, Brand extends string>(\n  queryName: ParamKey,\n  codec: IdCodec<Brand>,\n  options?: IdParamOptions,\n): (req: Request, res: Response<unknown, Record<ParamKey, Id<Brand>>>, next: NextFunction) => void {\n  return (req, res, next): void => {\n    const raw = req.query[queryName] as string | undefined;\n    const result = codec.safeParse(raw);\n    if (!result.ok) {\n      const failure = resolveIdParamFailure(result.error, options);\n      if (options?.onError) {\n        options.onError(failure, req, res, next);\n        return;\n      }\n      next(new IdParamError(failure.reason, failure.status));\n      return;\n    }\n    (res.locals as Record<string, unknown>)[queryName] = result.id;\n    next();\n  };\n}\n"],"mappings":";;;;;;AAUA,IAAa,eAAb,cAAkC,MAAM;CACtC;CACA;CAEA,YAAY,QAAwC,QAAgB;EAClE,MAAM,yBAAyB,QAAQ;EACvC,KAAK,OAAO;EACZ,KAAK,SAAS;EACd,KAAK,SAAS;CAChB;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgEA,SAAgB,QACd,WACA,OACA,SACiG;CACjG,QAAQ,KAAK,KAAK,SAAe;EAC/B,MAAM,MAAM,IAAI,OAAO;EACvB,MAAM,SAAS,MAAM,UAAU,GAAG;EAClC,IAAI,CAAC,OAAO,IAAI;GACd,MAAM,UAAU,sBAAsB,OAAO,OAAO,OAAO;GAC3D,IAAI,SAAS,SAAS;IACpB,QAAQ,QAAQ,SAAS,KAAK,KAAK,IAAI;IACvC;GACF;GACA,KAAK,IAAI,aAAa,QAAQ,QAAQ,QAAQ,MAAM,CAAC;GACrD;EACF;EACA,IAAK,OAAmC,aAAa,OAAO;EAC5D,KAAK;CACP;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2CA,SAAgB,QACd,WACA,OACA,SACiG;CACjG,QAAQ,KAAK,KAAK,SAAe;EAC/B,MAAM,MAAM,IAAI,MAAM;EACtB,MAAM,SAAS,MAAM,UAAU,GAAG;EAClC,IAAI,CAAC,OAAO,IAAI;GACd,MAAM,UAAU,sBAAsB,OAAO,OAAO,OAAO;GAC3D,IAAI,SAAS,SAAS;IACpB,QAAQ,QAAQ,SAAS,KAAK,KAAK,IAAI;IACvC;GACF;GACA,KAAK,IAAI,aAAa,QAAQ,QAAQ,QAAQ,MAAM,CAAC;GACrD;EACF;EACA,IAAK,OAAmC,aAAa,OAAO;EAC5D,KAAK;CACP;AACF"}

package/dist/fastify.d.mts

@@ -12,7 +12,7 @@ declare class IdParamError extends Error {
   readonly reason: "brand_mismatch" | "malformed";
   constructor(reason: "brand_mismatch" | "malformed", statusCode: number);
 }
-/** 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 —
@@ -89,6 +89,53 @@ type IdParamOptions = {
 declare function idParam<ParamKey extends string, Brand extends string>(paramName: ParamKey, codec: IdCodec<Brand>, options?: IdParamOptions): (request: FastifyRequest<{
   Params: Record<string, Id<Brand>>;
 }>, reply: FastifyReply) => Promise<void>;
+/**
+* Fastify `preHandler` hook factory that validates a named query-string param against a codec
+* via `safeParse`.
+*
+* Same failure contract as `idParam` — same `IdParamOptions` / `IdParamFailure` shape, same
+* `IdParamError` thrown into `setErrorHandler` — but reads `request.query[queryName]` instead of
+* `request.params`.
+*
+* **Default (no options):** throws `IdParamError` carrying `statusCode` and `reason` so the
+* app's existing `setErrorHandler` controls rendering. The adapter does not write a response
+* body itself.
+*
+* **`options.onError`:** when provided, the hook calls `onError` and does not throw; the
+* consumer fully owns the response via `reply`.
+*
+* **`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 `request.query` under `queryName`.
+*
+* @example
+* ```ts
+* import { idQuery, IdParamError } from "@smonn/ids/fastify";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+*
+* // Default: throws IdParamError → setErrorHandler renders it
+* // GET /users?userId=usr_...
+* fastify.get("/users", { preHandler: idQuery("userId", usr) }, (request, reply) => {
+*   const userId = request.query.userId; // string (compile-time); Id<"usr"> at runtime
+* });
+*
+* // Override: consumer fully owns the error response
+* fastify.get("/search", {
+*   preHandler: idQuery("cursor", usr, {
+*     onError: (failure, request, reply) =>
+*       reply.status(failure.status).send({ error: failure.reason }),
+*   }),
+* }, handler);
+* ```
+*/
+declare function idQuery<ParamKey extends string, Brand extends string>(queryName: ParamKey, codec: IdCodec<Brand>, options?: IdParamOptions): (request: FastifyRequest<{
+  Querystring: Record<string, Id<Brand>>;
+}>, reply: FastifyReply) => Promise<void>;
 //#endregion
-export { IdParamError, type IdParamFailure, IdParamOptions, idParam };
+export { IdParamError, type IdParamFailure, IdParamOptions, idParam, idQuery };
 //# sourceMappingURL=fastify.d.mts.map

package/dist/fastify.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"fastify.d.mts","names":[],"sources":["../src/adapters/fastify.ts"],"mappings":";;;;;;AAUA;;;cAAa,YAAA,SAAqB,KAAA;EAAA,SACvB,UAAA;EAAA,SACA,MAAA;EAET,WAAA,CAAY,MAAA,kCAAwC,UAAA;AAAA;;KAS1C,cAAA;EAT0C;AAAA;AAStD;;EAKE,OAAA,IACE,OAAA,EAAS,cAAA,EACT,OAAA,EAAS,cAAA,EACT,KAAA,EAAO,YAAA,YACG,OAAA;;;;;EAKZ,MAAA;IAAW,cAAA;IAAyB,SAAA;EAAA;AAAA;;;;;;;;;;AAAA;AA6DtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAOK;;;;;;;;;;;;;;iBAPW,OAAA,gDACd,SAAA,EAAW,QAAA,EACX,KAAA,EAAO,OAAA,CAAQ,KAAA,GACf,OAAA,GAAU,cAAA,IAEV,OAAA,EAAS,cAAA;EAAiB,MAAA,EAAQ,MAAA,SAAe,EAAA,CAAG,KAAA;AAAA,IACpD,KAAA,EAAO,YAAA,KACJ,OAAA"}
+{"version":3,"file":"fastify.d.mts","names":[],"sources":["../src/adapters/fastify.ts"],"mappings":";;;;;;AAUA;;;cAAa,YAAA,SAAqB,KAAA;EAAA,SACvB,UAAA;EAAA,SACA,MAAA;EAET,WAAA,CAAY,MAAA,kCAAwC,UAAA;AAAA;;KAS1C,cAAA;EAT0C;AAAA;AAStD;;EAKE,OAAA,IACE,OAAA,EAAS,cAAA,EACT,OAAA,EAAS,cAAA,EACT,KAAA,EAAO,YAAA,YACG,OAAA;;;;;EAKZ,MAAA;IAAW,cAAA;IAAyB,SAAA;EAAA;AAAA;;;;;;;;;;AAAA;AA6DtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAOK;AA4DL;;;;;;;;;;;;;iBAnEgB,OAAA,gDACd,SAAA,EAAW,QAAA,EACX,KAAA,EAAO,OAAA,CAAQ,KAAA,GACf,OAAA,GAAU,cAAA,IAEV,OAAA,EAAS,cAAA;EAAiB,MAAA,EAAQ,MAAA,SAAe,EAAA,CAAG,KAAA;AAAA,IACpD,KAAA,EAAO,YAAA,KACJ,OAAA;;;;;;;;;;;;;;;;AAmEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAPW,OAAA,gDACd,SAAA,EAAW,QAAA,EACX,KAAA,EAAO,OAAA,CAAQ,KAAA,GACf,OAAA,GAAU,cAAA,IAEV,OAAA,EAAS,cAAA;EAAiB,WAAA,EAAa,MAAA,SAAe,EAAA,CAAG,KAAA;AAAA,IACzD,KAAA,EAAO,YAAA,KACJ,OAAA"}

package/dist/fastify.mjs

@@ -1,4 +1,4 @@
-import { n as resolveIdParamFailure } from "./adapter-types-7wWdELSh.mjs";
+import { r as resolveIdParamFailure } from "./adapter-types-CjzFNDcJ.mjs";
 //#region src/adapters/fastify.ts
 /**
 * Typed error thrown into Fastify's `setErrorHandler` on validation failure.
@@ -87,7 +87,66 @@ function idParam(paramName, codec, options) {
 		request.params[paramName] = result.id;
 	};
 }
+/**
+* Fastify `preHandler` hook factory that validates a named query-string param against a codec
+* via `safeParse`.
+*
+* Same failure contract as `idParam` — same `IdParamOptions` / `IdParamFailure` shape, same
+* `IdParamError` thrown into `setErrorHandler` — but reads `request.query[queryName]` instead of
+* `request.params`.
+*
+* **Default (no options):** throws `IdParamError` carrying `statusCode` and `reason` so the
+* app's existing `setErrorHandler` controls rendering. The adapter does not write a response
+* body itself.
+*
+* **`options.onError`:** when provided, the hook calls `onError` and does not throw; the
+* consumer fully owns the response via `reply`.
+*
+* **`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 `request.query` under `queryName`.
+*
+* @example
+* ```ts
+* import { idQuery, IdParamError } from "@smonn/ids/fastify";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+*
+* // Default: throws IdParamError → setErrorHandler renders it
+* // GET /users?userId=usr_...
+* fastify.get("/users", { preHandler: idQuery("userId", usr) }, (request, reply) => {
+*   const userId = request.query.userId; // string (compile-time); Id<"usr"> at runtime
+* });
+*
+* // Override: consumer fully owns the error response
+* fastify.get("/search", {
+*   preHandler: idQuery("cursor", usr, {
+*     onError: (failure, request, reply) =>
+*       reply.status(failure.status).send({ error: failure.reason }),
+*   }),
+* }, handler);
+* ```
+*/
+function idQuery(queryName, codec, options) {
+	return async (request, reply) => {
+		const raw = request.query[queryName];
+		const result = codec.safeParse(raw);
+		if (!result.ok) {
+			const failure = resolveIdParamFailure(result.error, options);
+			if (options?.onError) {
+				await options.onError(failure, request, reply);
+				return;
+			}
+			throw new IdParamError(failure.reason, failure.status);
+		}
+		request.query[queryName] = result.id;
+	};
+}
 //#endregion
-export { IdParamError, idParam };
+export { IdParamError, idParam, idQuery };
 
 //# sourceMappingURL=fastify.mjs.map

package/dist/fastify.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"fastify.mjs","names":[],"sources":["../src/adapters/fastify.ts"],"sourcesContent":["import type { FastifyReply, FastifyRequest } from \"fastify\";\nimport { type IdCodec, type IdParamFailure, resolveIdParamFailure } from \"./adapter-types.js\";\nimport type { Id } from \"../types.js\";\n\nexport type { IdParamFailure };\n\n/**\n * Typed error thrown into Fastify's `setErrorHandler` on validation failure.\n * Inspect `err.reason` and `err.statusCode` in your error handler.\n */\nexport class IdParamError extends Error {\n  readonly statusCode: number;\n  readonly reason: \"brand_mismatch\" | \"malformed\";\n\n  constructor(reason: \"brand_mismatch\" | \"malformed\", statusCode: number) {\n    super(`ID validation failed: ${reason}`);\n    this.name = \"IdParamError\";\n    this.reason = reason;\n    this.statusCode = statusCode;\n  }\n}\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 does not throw.\n   */\n  onError?: (\n    failure: IdParamFailure,\n    request: FastifyRequest,\n    reply: FastifyReply,\n  ) => void | Promise<void>;\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?: number; malformed?: number };\n};\n\n/**\n * Fastify `preHandler` hook factory that validates a named route param against a codec via `safeParse`.\n *\n * **Default (no options):** throws `IdParamError` carrying `statusCode` and `reason` so the app's\n * existing `setErrorHandler` controls rendering. The adapter does not write a response body itself.\n *\n * **`options.onError`:** when provided, the hook calls `onError` and does not throw; the consumer\n * fully owns the response via `reply`.\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 `request.params` under `paramName`.\n *\n * **Return type note:** the returned hook is typed as\n * `(request: FastifyRequest<{ Params: Record<string, Id<Brand>> }>, reply: FastifyReply) => Promise<void>`.\n * Assigning it to a Fastify `preHandler` slot is backward-compatible (method-signature bivariance applies).\n * However, a locally-annotated variable typed as the bare `(request: FastifyRequest, reply: FastifyReply) => Promise<void>`\n * will produce a TypeScript error under `--strictFunctionTypes` because function parameter types are contravariant.\n * Use `preHandler` assignment or let TypeScript infer the type to avoid this.\n *\n * @example\n * ```ts\n * import { idParam, IdParamError } from \"@smonn/ids/fastify\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n *\n * // Default: throws IdParamError → setErrorHandler renders it\n * fastify.get(\"/users/:id\", { preHandler: idParam(\"id\", usr) }, (request, reply) => {\n *   const id = request.params.id; // string (compile-time); Id<\"usr\"> at runtime after preHandler\n * });\n *\n * // Error handler receives the typed error\n * fastify.setErrorHandler((err, request, reply) => {\n *   if (err instanceof IdParamError) {\n *     reply.status(err.statusCode).send({ error: err.reason });\n *     return;\n *   }\n *   reply.send(err);\n * });\n *\n * // Override: consumer fully owns the error response\n * fastify.get(\"/orgs/:id\", {\n *   preHandler: idParam(\"id\", org, {\n *     onError: (failure, request, reply) =>\n *       reply.status(failure.status).send({ error: failure.reason }),\n *   }),\n * }, handler);\n *\n * // Or a lightweight status remap without a full handler\n * fastify.get(\"/things/:id\", {\n *   preHandler: idParam(\"id\", thing, { status: { brand_mismatch: 400 } }),\n * }, handler);\n * ```\n */\nexport function idParam<ParamKey extends string, Brand extends string>(\n  paramName: ParamKey,\n  codec: IdCodec<Brand>,\n  options?: IdParamOptions,\n): (\n  request: FastifyRequest<{ Params: Record<string, Id<Brand>> }>,\n  reply: FastifyReply,\n) => Promise<void> {\n  return async (request, reply): Promise<void> => {\n    const raw = request.params[paramName];\n    const result = codec.safeParse(raw);\n    if (!result.ok) {\n      const failure = resolveIdParamFailure(result.error, options);\n      if (options?.onError) {\n        await options.onError(failure, request, reply);\n        return;\n      }\n      throw new IdParamError(failure.reason, failure.status);\n    }\n    request.params[paramName] = result.id;\n  };\n}\n"],"mappings":";;;;;;AAUA,IAAa,eAAb,cAAkC,MAAM;CACtC;CACA;CAEA,YAAY,QAAwC,YAAoB;EACtE,MAAM,yBAAyB,QAAQ;EACvC,KAAK,OAAO;EACZ,KAAK,SAAS;EACd,KAAK,aAAa;CACpB;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8EA,SAAgB,QACd,WACA,OACA,SAIiB;CACjB,OAAO,OAAO,SAAS,UAAyB;EAC9C,MAAM,MAAM,QAAQ,OAAO;EAC3B,MAAM,SAAS,MAAM,UAAU,GAAG;EAClC,IAAI,CAAC,OAAO,IAAI;GACd,MAAM,UAAU,sBAAsB,OAAO,OAAO,OAAO;GAC3D,IAAI,SAAS,SAAS;IACpB,MAAM,QAAQ,QAAQ,SAAS,SAAS,KAAK;IAC7C;GACF;GACA,MAAM,IAAI,aAAa,QAAQ,QAAQ,QAAQ,MAAM;EACvD;EACA,QAAQ,OAAO,aAAa,OAAO;CACrC;AACF"}
+{"version":3,"file":"fastify.mjs","names":[],"sources":["../src/adapters/fastify.ts"],"sourcesContent":["import type { FastifyReply, FastifyRequest } from \"fastify\";\nimport { type IdCodec, type IdParamFailure, resolveIdParamFailure } from \"./adapter-types.js\";\nimport type { Id } from \"../types.js\";\n\nexport type { IdParamFailure };\n\n/**\n * Typed error thrown into Fastify's `setErrorHandler` on validation failure.\n * Inspect `err.reason` and `err.statusCode` in your error handler.\n */\nexport class IdParamError extends Error {\n  readonly statusCode: number;\n  readonly reason: \"brand_mismatch\" | \"malformed\";\n\n  constructor(reason: \"brand_mismatch\" | \"malformed\", statusCode: number) {\n    super(`ID validation failed: ${reason}`);\n    this.name = \"IdParamError\";\n    this.reason = reason;\n    this.statusCode = statusCode;\n  }\n}\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 does not throw.\n   */\n  onError?: (\n    failure: IdParamFailure,\n    request: FastifyRequest,\n    reply: FastifyReply,\n  ) => void | Promise<void>;\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?: number; malformed?: number };\n};\n\n/**\n * Fastify `preHandler` hook factory that validates a named route param against a codec via `safeParse`.\n *\n * **Default (no options):** throws `IdParamError` carrying `statusCode` and `reason` so the app's\n * existing `setErrorHandler` controls rendering. The adapter does not write a response body itself.\n *\n * **`options.onError`:** when provided, the hook calls `onError` and does not throw; the consumer\n * fully owns the response via `reply`.\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 `request.params` under `paramName`.\n *\n * **Return type note:** the returned hook is typed as\n * `(request: FastifyRequest<{ Params: Record<string, Id<Brand>> }>, reply: FastifyReply) => Promise<void>`.\n * Assigning it to a Fastify `preHandler` slot is backward-compatible (method-signature bivariance applies).\n * However, a locally-annotated variable typed as the bare `(request: FastifyRequest, reply: FastifyReply) => Promise<void>`\n * will produce a TypeScript error under `--strictFunctionTypes` because function parameter types are contravariant.\n * Use `preHandler` assignment or let TypeScript infer the type to avoid this.\n *\n * @example\n * ```ts\n * import { idParam, IdParamError } from \"@smonn/ids/fastify\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n *\n * // Default: throws IdParamError → setErrorHandler renders it\n * fastify.get(\"/users/:id\", { preHandler: idParam(\"id\", usr) }, (request, reply) => {\n *   const id = request.params.id; // string (compile-time); Id<\"usr\"> at runtime after preHandler\n * });\n *\n * // Error handler receives the typed error\n * fastify.setErrorHandler((err, request, reply) => {\n *   if (err instanceof IdParamError) {\n *     reply.status(err.statusCode).send({ error: err.reason });\n *     return;\n *   }\n *   reply.send(err);\n * });\n *\n * // Override: consumer fully owns the error response\n * fastify.get(\"/orgs/:id\", {\n *   preHandler: idParam(\"id\", org, {\n *     onError: (failure, request, reply) =>\n *       reply.status(failure.status).send({ error: failure.reason }),\n *   }),\n * }, handler);\n *\n * // Or a lightweight status remap without a full handler\n * fastify.get(\"/things/:id\", {\n *   preHandler: idParam(\"id\", thing, { status: { brand_mismatch: 400 } }),\n * }, handler);\n * ```\n */\nexport function idParam<ParamKey extends string, Brand extends string>(\n  paramName: ParamKey,\n  codec: IdCodec<Brand>,\n  options?: IdParamOptions,\n): (\n  request: FastifyRequest<{ Params: Record<string, Id<Brand>> }>,\n  reply: FastifyReply,\n) => Promise<void> {\n  return async (request, reply): Promise<void> => {\n    const raw = request.params[paramName];\n    const result = codec.safeParse(raw);\n    if (!result.ok) {\n      const failure = resolveIdParamFailure(result.error, options);\n      if (options?.onError) {\n        await options.onError(failure, request, reply);\n        return;\n      }\n      throw new IdParamError(failure.reason, failure.status);\n    }\n    request.params[paramName] = result.id;\n  };\n}\n\n/**\n * Fastify `preHandler` hook factory that validates a named query-string param against a codec\n * via `safeParse`.\n *\n * Same failure contract as `idParam` — same `IdParamOptions` / `IdParamFailure` shape, same\n * `IdParamError` thrown into `setErrorHandler` — but reads `request.query[queryName]` instead of\n * `request.params`.\n *\n * **Default (no options):** throws `IdParamError` carrying `statusCode` and `reason` so the\n * app's existing `setErrorHandler` controls rendering. The adapter does not write a response\n * body itself.\n *\n * **`options.onError`:** when provided, the hook calls `onError` and does not throw; the\n * consumer fully owns the response via `reply`.\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 `request.query` under `queryName`.\n *\n * @example\n * ```ts\n * import { idQuery, IdParamError } from \"@smonn/ids/fastify\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n *\n * // Default: throws IdParamError → setErrorHandler renders it\n * // GET /users?userId=usr_...\n * fastify.get(\"/users\", { preHandler: idQuery(\"userId\", usr) }, (request, reply) => {\n *   const userId = request.query.userId; // string (compile-time); Id<\"usr\"> at runtime\n * });\n *\n * // Override: consumer fully owns the error response\n * fastify.get(\"/search\", {\n *   preHandler: idQuery(\"cursor\", usr, {\n *     onError: (failure, request, reply) =>\n *       reply.status(failure.status).send({ error: failure.reason }),\n *   }),\n * }, handler);\n * ```\n */\nexport function idQuery<ParamKey extends string, Brand extends string>(\n  queryName: ParamKey,\n  codec: IdCodec<Brand>,\n  options?: IdParamOptions,\n): (\n  request: FastifyRequest<{ Querystring: Record<string, Id<Brand>> }>,\n  reply: FastifyReply,\n) => Promise<void> {\n  return async (request, reply): Promise<void> => {\n    const raw = request.query[queryName];\n    const result = codec.safeParse(raw);\n    if (!result.ok) {\n      const failure = resolveIdParamFailure(result.error, options);\n      if (options?.onError) {\n        await options.onError(failure, request, reply);\n        return;\n      }\n      throw new IdParamError(failure.reason, failure.status);\n    }\n    request.query[queryName] = result.id;\n  };\n}\n"],"mappings":";;;;;;AAUA,IAAa,eAAb,cAAkC,MAAM;CACtC;CACA;CAEA,YAAY,QAAwC,YAAoB;EACtE,MAAM,yBAAyB,QAAQ;EACvC,KAAK,OAAO;EACZ,KAAK,SAAS;EACd,KAAK,aAAa;CACpB;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8EA,SAAgB,QACd,WACA,OACA,SAIiB;CACjB,OAAO,OAAO,SAAS,UAAyB;EAC9C,MAAM,MAAM,QAAQ,OAAO;EAC3B,MAAM,SAAS,MAAM,UAAU,GAAG;EAClC,IAAI,CAAC,OAAO,IAAI;GACd,MAAM,UAAU,sBAAsB,OAAO,OAAO,OAAO;GAC3D,IAAI,SAAS,SAAS;IACpB,MAAM,QAAQ,QAAQ,SAAS,SAAS,KAAK;IAC7C;GACF;GACA,MAAM,IAAI,aAAa,QAAQ,QAAQ,QAAQ,MAAM;EACvD;EACA,QAAQ,OAAO,aAAa,OAAO;CACrC;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8CA,SAAgB,QACd,WACA,OACA,SAIiB;CACjB,OAAO,OAAO,SAAS,UAAyB;EAC9C,MAAM,MAAM,QAAQ,MAAM;EAC1B,MAAM,SAAS,MAAM,UAAU,GAAG;EAClC,IAAI,CAAC,OAAO,IAAI;GACd,MAAM,UAAU,sBAAsB,OAAO,OAAO,OAAO;GAC3D,IAAI,SAAS,SAAS;IACpB,MAAM,QAAQ,QAAQ,SAAS,SAAS,KAAK;IAC7C;GACF;GACA,MAAM,IAAI,aAAa,QAAQ,QAAQ,QAAQ,MAAM;EACvD;EACA,QAAQ,MAAM,aAAa,OAAO;CACpC;AACF"}