@nifrajs/schema 1.0.0-beta.4 → 1.1.0

package/dist/adapter.d.ts

@@ -28,6 +28,14 @@ export type NifraSchema<T extends TSchema = TSchema> = StandardSchemaV1<Static<T
  *
  * Exposed (not just used internally by `t`) so a TypeBox schema authored directly can
  * be adapted without leaving the Standard Schema world.
+ *
+ * `options.coerce` runs TypeBox's `Value.Convert` (string→number/integer/boolean, per the schema)
+ * BEFORE validating. Query values always arrive as strings (`?limit=20` → `"20"`), so a query schema
+ * with a numeric field can't validate without this — it's how `t.pageQuery` yields a real `number`.
+ * Leave it OFF (the default) for body/JSON schemas: a JSON number is already a number, and coercing
+ * would silently accept `"20"` where the contract said `20`.
  */
-export declare function fromTypeBox<T extends TSchema>(schema: T): NifraSchema<T>;
+export declare function fromTypeBox<T extends TSchema>(schema: T, options?: {
+    readonly coerce?: boolean;
+}): NifraSchema<T>;
 //# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiC,gBAAgB,EAAiB,MAAM,eAAe,CAAA;AACnG,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAKxD;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,IAAI,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG;IAC9F,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAA;CACvB,CAAA;AAeD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,OAAO,EAAE,MAAM,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAiCxE"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiC,gBAAgB,EAAiB,MAAM,eAAe,CAAA;AACnG,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAKxD;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,IAAI,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG;IAC9F,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAA;CACvB,CAAA;AAeD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,OAAO,EAC3C,MAAM,EAAE,CAAC,EACT,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GACtC,WAAW,CAAC,CAAC,CAAC,CAsChB"}

package/dist/adapter.js

@@ -30,8 +30,15 @@ function toIssue(error) {
  *
  * Exposed (not just used internally by `t`) so a TypeBox schema authored directly can
  * be adapted without leaving the Standard Schema world.
+ *
+ * `options.coerce` runs TypeBox's `Value.Convert` (string→number/integer/boolean, per the schema)
+ * BEFORE validating. Query values always arrive as strings (`?limit=20` → `"20"`), so a query schema
+ * with a numeric field can't validate without this — it's how `t.pageQuery` yields a real `number`.
+ * Leave it OFF (the default) for body/JSON schemas: a JSON number is already a number, and coercing
+ * would silently accept `"20"` where the contract said `20`.
  */
-export function fromTypeBox(schema) {
+export function fromTypeBox(schema, options) {
+    const coerce = options?.coerce ?? false;
     let compiled;
     let evalFree = false;
     return {
@@ -43,6 +50,10 @@ export function fromTypeBox(schema) {
                 // reachable path (not a top-level import side effect) so a production bundle can't
                 // tree-shake the registration away — see ./formats.ts. Idempotent, ~free after first call.
                 ensureDefaultFormats();
+                // Coerce first when asked (query schemas): `Value.Convert` turns "20"→20 per the schema, so the
+                // compiled/eval-free Check below sees the target type. A non-convertible value (e.g. "abc" for an
+                // integer) is left as-is and fails Check → a proper 400.
+                const input = coerce ? Value.Convert(schema, value) : value;
                 if (compiled === undefined && !evalFree) {
                     try {
                         compiled = TypeCompiler.Compile(schema);
@@ -53,13 +64,13 @@ export function fromTypeBox(schema) {
                     }
                 }
                 if (compiled !== undefined) {
-                    if (compiled.Check(value))
-                        return { value };
-                    return { issues: [...compiled.Errors(value)].map(toIssue) };
+                    if (compiled.Check(input))
+                        return { value: input };
+                    return { issues: [...compiled.Errors(input)].map(toIssue) };
                 }
-                if (Value.Check(schema, value))
-                    return { value };
-                return { issues: [...Value.Errors(schema, value)].map(toIssue) };
+                if (Value.Check(schema, input))
+                    return { value: input };
+                return { issues: [...Value.Errors(schema, input)].map(toIssue) };
             },
             // Phantom: `types` carries no runtime value; this cast supplies the
             // compile-time `Static<T>` that nifra's `InferOutput` reads to type `c.body`.

package/dist/adapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAEA,OAAO,EAAkB,YAAY,EAAE,MAAM,4BAA4B,CAAA;AACzE,OAAO,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAA;AAC/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AAcnD;;;;;GAKG;AACH,SAAS,OAAO,CAAC,KAA0D;IACzE,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,IAAI,EAAE,KAAK,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC;KACrE,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,WAAW,CAAoB,MAAS;IACtD,IAAI,QAAkC,CAAA;IACtC,IAAI,QAAQ,GAAG,KAAK,CAAA;IACpB,OAAO;QACL,WAAW,EAAE;YACX,OAAO,EAAE,CAAC;YACV,MAAM,EAAE,OAAO;YACf,QAAQ,EAAE,CAAC,KAAc,EAA6B,EAAE;gBACtD,uFAAuF;gBACvF,mFAAmF;gBACnF,2FAA2F;gBAC3F,oBAAoB,EAAE,CAAA;gBACtB,IAAI,QAAQ,KAAK,SAAS,IAAI,CAAC,QAAQ,EAAE,CAAC;oBACxC,IAAI,CAAC;wBACH,QAAQ,GAAG,YAAY,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;oBACzC,CAAC;oBAAC,MAAM,CAAC;wBACP,8EAA8E;wBAC9E,QAAQ,GAAG,IAAI,CAAA;oBACjB,CAAC;gBACH,CAAC;gBACD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;oBAC3B,IAAI,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC;wBAAE,OAAO,EAAE,KAAK,EAAE,CAAA;oBAC3C,OAAO,EAAE,MAAM,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAA;gBAC7D,CAAC;gBACD,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC;oBAAE,OAAO,EAAE,KAAK,EAAE,CAAA;gBAChD,OAAO,EAAE,MAAM,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAA;YAClE,CAAC;YACD,oEAAoE;YACpE,8EAA8E;YAC9E,KAAK,EAAE,SAA2D;SACnE;QACD,UAAU,EAAE,MAAM;KACnB,CAAA;AACH,CAAC"}
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAEA,OAAO,EAAkB,YAAY,EAAE,MAAM,4BAA4B,CAAA;AACzE,OAAO,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAA;AAC/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AAcnD;;;;;GAKG;AACH,SAAS,OAAO,CAAC,KAA0D;IACzE,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,IAAI,EAAE,KAAK,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC;KACrE,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,WAAW,CACzB,MAAS,EACT,OAAuC;IAEvC,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,IAAI,KAAK,CAAA;IACvC,IAAI,QAAkC,CAAA;IACtC,IAAI,QAAQ,GAAG,KAAK,CAAA;IACpB,OAAO;QACL,WAAW,EAAE;YACX,OAAO,EAAE,CAAC;YACV,MAAM,EAAE,OAAO;YACf,QAAQ,EAAE,CAAC,KAAc,EAA6B,EAAE;gBACtD,uFAAuF;gBACvF,mFAAmF;gBACnF,2FAA2F;gBAC3F,oBAAoB,EAAE,CAAA;gBACtB,gGAAgG;gBAChG,kGAAkG;gBAClG,yDAAyD;gBACzD,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAA;gBAC3D,IAAI,QAAQ,KAAK,SAAS,IAAI,CAAC,QAAQ,EAAE,CAAC;oBACxC,IAAI,CAAC;wBACH,QAAQ,GAAG,YAAY,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;oBACzC,CAAC;oBAAC,MAAM,CAAC;wBACP,8EAA8E;wBAC9E,QAAQ,GAAG,IAAI,CAAA;oBACjB,CAAC;gBACH,CAAC;gBACD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;oBAC3B,IAAI,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC;wBAAE,OAAO,EAAE,KAAK,EAAE,KAAkB,EAAE,CAAA;oBAC/D,OAAO,EAAE,MAAM,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAA;gBAC7D,CAAC;gBACD,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC;oBAAE,OAAO,EAAE,KAAK,EAAE,KAAkB,EAAE,CAAA;gBACpE,OAAO,EAAE,MAAM,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAA;YAClE,CAAC;YACD,oEAAoE;YACpE,8EAA8E;YAC9E,KAAK,EAAE,SAA2D;SACnE;QACD,UAAU,EAAE,MAAM;KACnB,CAAA;AACH,CAAC"}

package/dist/index.d.ts

@@ -9,5 +9,6 @@
 export { fromTypeBox, type NifraSchema } from "./adapter.js";
 export { registerFormat } from "./formats.js";
 export { type OpenAPIDocument, type OpenAPIInfo, toOpenAPI } from "./openapi.js";
+export { decodeCursor, encodeCursor, type Page, paginate } from "./pagination.js";
 export { t } from "./t.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAA;AAI5D,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAC7C,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,WAAW,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAChF,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAA;AAI5D,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAC7C,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,WAAW,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAEhF,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,KAAK,IAAI,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AACjF,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA"}

package/dist/index.js

@@ -12,5 +12,7 @@ export { fromTypeBox } from "./adapter.js";
 // effect of this module, which a production bundler would tree-shake away.
 export { registerFormat } from "./formats.js";
 export { toOpenAPI } from "./openapi.js";
+// Cursor-pagination runtime helpers — pair with `t.paginated` / `t.pageQuery`.
+export { decodeCursor, encodeCursor, paginate } from "./pagination.js";
 export { t } from "./t.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,WAAW,EAAoB,MAAM,cAAc,CAAA;AAC5D,gGAAgG;AAChG,8FAA8F;AAC9F,2EAA2E;AAC3E,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAC7C,OAAO,EAA0C,SAAS,EAAE,MAAM,cAAc,CAAA;AAChF,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,WAAW,EAAoB,MAAM,cAAc,CAAA;AAC5D,gGAAgG;AAChG,8FAA8F;AAC9F,2EAA2E;AAC3E,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAC7C,OAAO,EAA0C,SAAS,EAAE,MAAM,cAAc,CAAA;AAChF,+EAA+E;AAC/E,OAAO,EAAE,YAAY,EAAE,YAAY,EAAa,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AACjF,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA"}

package/dist/pagination.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Cursor-pagination runtime helpers — an opaque cursor codec + a page builder. Pair with `t.paginated`
+ * (the response schema) and `t.pageQuery` (the request schema).
+ *
+ * Edge-safe: `btoa`/`atob` + `TextEncoder`/`TextDecoder` (no `Buffer`), so it runs on Bun/Node/Deno/
+ * Workers. Cursors are opaque but NOT signed — treat a decoded cursor as untrusted client input: validate
+ * its shape before keying a DB query off it (it's a position hint, not an authorization token).
+ */
+/** Encode any JSON-serializable value (e.g. the last row's sort key) into an opaque cursor string. */
+export declare function encodeCursor(value: unknown): string;
+/** Decode a cursor back to its value. Returns `undefined` for a null/empty/malformed cursor — treat that
+ * as "start from the beginning" rather than erroring on a client-supplied string. */
+export declare function decodeCursor<T = unknown>(cursor: string | null | undefined): T | undefined;
+/** A cursor-pagination page — matches the shape of `t.paginated(item)`. */
+export interface Page<Item> {
+    readonly items: Item[];
+    readonly nextCursor: string | null;
+}
+/**
+ * Build a page from rows you fetched with `limit + 1`. If the extra row came back there are more pages:
+ * drop it and emit a `nextCursor` from the last KEPT row via `cursorOf`; otherwise `nextCursor` is `null`.
+ *
+ *   const rows = await db.notes.after(decodeCursor(query.cursor)).take(limit + 1)
+ *   return paginate(rows, limit, (note) => note.id)
+ */
+export declare function paginate<Row>(rows: readonly Row[], limit: number, cursorOf: (row: Row) => unknown): Page<Row>;
+//# sourceMappingURL=pagination.d.ts.map

package/dist/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAiBH,sGAAsG;AACtG,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEnD;AAED;qFACqF;AACrF,wBAAgB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,CAAC,GAAG,SAAS,CAO1F;AAED,2EAA2E;AAC3E,MAAM,WAAW,IAAI,CAAC,IAAI;IACxB,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,CAAA;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CACnC;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAC1B,IAAI,EAAE,SAAS,GAAG,EAAE,EACpB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,GAC9B,IAAI,CAAC,GAAG,CAAC,CAMX"}

package/dist/pagination.js

@@ -0,0 +1,53 @@
+/**
+ * Cursor-pagination runtime helpers — an opaque cursor codec + a page builder. Pair with `t.paginated`
+ * (the response schema) and `t.pageQuery` (the request schema).
+ *
+ * Edge-safe: `btoa`/`atob` + `TextEncoder`/`TextDecoder` (no `Buffer`), so it runs on Bun/Node/Deno/
+ * Workers. Cursors are opaque but NOT signed — treat a decoded cursor as untrusted client input: validate
+ * its shape before keying a DB query off it (it's a position hint, not an authorization token).
+ */
+/** UTF-8 → URL-safe base64 (no padding). */
+function toBase64Url(input) {
+    const bytes = new TextEncoder().encode(input);
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/** URL-safe base64 → UTF-8. Throws on malformed input (callers below catch it). */
+function fromBase64Url(input) {
+    const binary = atob(input.replace(/-/g, "+").replace(/_/g, "/"));
+    const bytes = Uint8Array.from(binary, (ch) => ch.charCodeAt(0));
+    return new TextDecoder().decode(bytes);
+}
+/** Encode any JSON-serializable value (e.g. the last row's sort key) into an opaque cursor string. */
+export function encodeCursor(value) {
+    return toBase64Url(JSON.stringify(value));
+}
+/** Decode a cursor back to its value. Returns `undefined` for a null/empty/malformed cursor — treat that
+ * as "start from the beginning" rather than erroring on a client-supplied string. */
+export function decodeCursor(cursor) {
+    if (cursor === null || cursor === undefined || cursor === "")
+        return undefined;
+    try {
+        return JSON.parse(fromBase64Url(cursor));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Build a page from rows you fetched with `limit + 1`. If the extra row came back there are more pages:
+ * drop it and emit a `nextCursor` from the last KEPT row via `cursorOf`; otherwise `nextCursor` is `null`.
+ *
+ *   const rows = await db.notes.after(decodeCursor(query.cursor)).take(limit + 1)
+ *   return paginate(rows, limit, (note) => note.id)
+ */
+export function paginate(rows, limit, cursorOf) {
+    const hasMore = rows.length > limit;
+    const items = hasMore ? rows.slice(0, limit) : [...rows];
+    const last = items[items.length - 1];
+    const nextCursor = hasMore && last !== undefined ? encodeCursor(cursorOf(last)) : null;
+    return { items, nextCursor };
+}
+//# sourceMappingURL=pagination.js.map

package/dist/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,4CAA4C;AAC5C,SAAS,WAAW,CAAC,KAAa;IAChC,MAAM,KAAK,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IAC7C,IAAI,MAAM,GAAG,EAAE,CAAA;IACf,KAAK,MAAM,IAAI,IAAI,KAAK;QAAE,MAAM,IAAI,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAA;IAC7D,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAA;AAChF,CAAC;AAED,mFAAmF;AACnF,SAAS,aAAa,CAAC,KAAa;IAClC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAA;IAChE,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAA;IAC/D,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;AACxC,CAAC;AAED,sGAAsG;AACtG,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAA;AAC3C,CAAC;AAED;qFACqF;AACrF,MAAM,UAAU,YAAY,CAAc,MAAiC;IACzE,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,EAAE;QAAE,OAAO,SAAS,CAAA;IAC9E,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC,CAAM,CAAA;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAA;IAClB,CAAC;AACH,CAAC;AAQD;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CACtB,IAAoB,EACpB,KAAa,EACb,QAA+B;IAE/B,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,GAAG,KAAK,CAAA;IACnC,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;IACxD,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IACpC,MAAM,UAAU,GAAG,OAAO,IAAI,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;IACtF,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,CAAA;AAC9B,CAAC"}

package/dist/t.d.ts

@@ -29,6 +29,21 @@ export declare const t: {
     readonly optional: <T extends TSchema>(schema: NifraSchema<T>) => NifraSchema<T extends import("@sinclair/typebox").TOptional<infer S extends TSchema> ? import("@sinclair/typebox").TOptional<S> : import("@sinclair/typebox").Ensure<import("@sinclair/typebox").TOptional<T>>>;
     readonly union: <const S extends readonly NifraSchema[]>(schemas: S) => NifraSchema<TUnion<{ -readonly [K in keyof S]: S[K]["jsonSchema"]; }>>;
     readonly record: <T extends TSchema>(value: NifraSchema<T>, options?: ObjectOptions) => NifraSchema<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, T>>;
+    /** A cursor-pagination response envelope: `{ items: T[]; nextCursor: string | null }` (`null` = last page). */
+    readonly paginated: <T extends TSchema>(item: NifraSchema<T>, options?: ObjectOptions) => NifraSchema<import("@sinclair/typebox").TObject<{
+        items: import("@sinclair/typebox").TArray<T>;
+        nextCursor: TUnion<[import("@sinclair/typebox").TString, import("@sinclair/typebox").TNull]>;
+    }>>;
+    /** A request query schema for cursor pagination: `{ cursor?: string; limit?: number }`. `maxLimit`
+     * caps `limit` — a larger value fails validation (a 400), so a client can't request an unbounded page.
+     * `coerce` is on because query values arrive as strings (`?limit=20` → `"20"`); it's what makes `limit`
+     * a real `number` in the handler (`c.query.limit`), not a string. */
+    readonly pageQuery: (options?: {
+        maxLimit?: number;
+    }) => NifraSchema<import("@sinclair/typebox").TObject<{
+        cursor: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    }>>;
 };
 export {};
 //# sourceMappingURL=t.d.ts.map

package/dist/t.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"t.d.ts","sourceRoot":"","sources":["../src/t.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,OAAO,EACZ,KAAK,MAAM,EAEZ,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,cAAc,CAAA;AAE5D,KAAK,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;AAUxC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,CAAC;gCACO,aAAa;gCACb,aAAa;iCACZ,cAAc;;;6BAGlB,CAAC,SAAS,aAAa,SAAS,CAAC;sBAMxC,CAAC,SAAS,KAAK,SAAS,CAAC,YAAY,aAAa,wDA/Bd,CAAC;IAiC9C;qFACiF;2BACnE,CAAC,SAAS,KAAK,SAAS,CAAC,YAAY,aAAa,wDAnCnB,CAAC;qBAqCtC,CAAC,SAAS,OAAO,QAAQ,WAAW,CAAC,CAAC,CAAC,YAAY,YAAY;IAEvE,qFAAqF;wBAC1E,CAAC,SAAS,OAAO,UAAU,WAAW,CAAC,CAAC,CAAC;2BAOtC,CAAC,SAAS,SAAS,WAAW,EAAE,WAAW,CAAC,KAGnD,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,GAAE,CAAC,CAAC;sBACnE,CAAC,SAAS,OAAO,SAAS,WAAW,CAAC,CAAC,CAAC,YAAY,aAAa;CAElE,CAAA"}
+{"version":3,"file":"t.d.ts","sourceRoot":"","sources":["../src/t.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,OAAO,EACZ,KAAK,MAAM,EAEZ,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,cAAc,CAAA;AAE5D,KAAK,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;AAUxC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,CAAC;gCACO,aAAa;gCACb,aAAa;iCACZ,cAAc;;;6BAGlB,CAAC,SAAS,aAAa,SAAS,CAAC;sBAMxC,CAAC,SAAS,KAAK,SAAS,CAAC,YAAY,aAAa,wDA/Bd,CAAC;IAiC9C;qFACiF;2BACnE,CAAC,SAAS,KAAK,SAAS,CAAC,YAAY,aAAa,wDAnCnB,CAAC;qBAqCtC,CAAC,SAAS,OAAO,QAAQ,WAAW,CAAC,CAAC,CAAC,YAAY,YAAY;IAEvE,qFAAqF;wBAC1E,CAAC,SAAS,OAAO,UAAU,WAAW,CAAC,CAAC,CAAC;2BAOtC,CAAC,SAAS,SAAS,WAAW,EAAE,WAAW,CAAC,KAGnD,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,GAAE,CAAC,CAAC;sBACnE,CAAC,SAAS,OAAO,SAAS,WAAW,CAAC,CAAC,CAAC,YAAY,aAAa;IAM1E,+GAA+G;yBACnG,CAAC,SAAS,OAAO,QAAQ,WAAW,CAAC,CAAC,CAAC,YAAY,aAAa;;;;IAU5E;;;yEAGqE;mCAC/C;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE;;;;CAWnC,CAAA"}

package/dist/t.js

@@ -45,5 +45,21 @@ export const t = {
     // (order/length are preserved by `map`, so the tuple shape is sound).
     union: (schemas) => fromTypeBox(Type.Union(schemas.map((schema) => schema.jsonSchema))),
     record: (value, options) => fromTypeBox(Type.Record(Type.String(), value.jsonSchema, options)),
+    // Composed from TypeBox directly (not `t.object`/`t.array`) so the `t` literal doesn't reference
+    // itself during inference. Cursor pagination — not OFFSET — is the production default: stable under
+    // concurrent inserts and O(1) per page. Build pages with `paginate()` + `encodeCursor`/`decodeCursor`.
+    /** A cursor-pagination response envelope: `{ items: T[]; nextCursor: string | null }` (`null` = last page). */
+    paginated: (item, options) => fromTypeBox(Type.Object({
+        items: Type.Array(item.jsonSchema),
+        nextCursor: Type.Union([Type.String(), Type.Null()]),
+    }, { additionalProperties: false, ...options })),
+    /** A request query schema for cursor pagination: `{ cursor?: string; limit?: number }`. `maxLimit`
+     * caps `limit` — a larger value fails validation (a 400), so a client can't request an unbounded page.
+     * `coerce` is on because query values arrive as strings (`?limit=20` → `"20"`); it's what makes `limit`
+     * a real `number` in the handler (`c.query.limit`), not a string. */
+    pageQuery: (options) => fromTypeBox(Type.Object({
+        cursor: Type.Optional(Type.String()),
+        limit: Type.Optional(Type.Integer({ minimum: 1, maximum: options?.maxLimit ?? 100 })),
+    }, { additionalProperties: false }), { coerce: true }),
 };
 //# sourceMappingURL=t.js.map

package/dist/t.js.map

@@ -1 +1 @@
-{"version":3,"file":"t.js","sourceRoot":"","sources":["../src/t.ts"],"names":[],"mappings":"AAAA,OAAO,EASL,IAAI,GACL,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,WAAW,EAAoB,MAAM,cAAc,CAAA;AAI5D,gFAAgF;AAChF,SAAS,MAAM,CAAkB,KAAQ;IACvC,MAAM,GAAG,GAA4B,EAAE,CAAA;IACvC,wEAAwE;IACxE,KAAK,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,GAAG,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,UAAU,CAAA;IAC/E,OAAO,GAA6C,CAAA;AACtD,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,CAAC,GAAG;IACf,MAAM,EAAE,CAAC,OAAuB,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACtE,MAAM,EAAE,CAAC,OAAuB,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACtE,OAAO,EAAE,CAAC,OAAwB,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACzE,OAAO,EAAE,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;IAC1C,IAAI,EAAE,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IACpC,OAAO,EAAE,CAAgC,KAAQ,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAEtF,oGAAoG;IACpG,qGAAqG;IACrG,qGAAqG;IACrG,oGAAoG;IACpG,MAAM,EAAE,CAAkB,KAAQ,EAAE,OAAuB,EAAE,EAAE,CAC7D,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,oBAAoB,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACtF;qFACiF;IACjF,WAAW,EAAE,CAAkB,KAAQ,EAAE,OAAuB,EAAE,EAAE,CAClE,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,oBAAoB,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACrF,KAAK,EAAE,CAAoB,IAAoB,EAAE,OAAsB,EAAE,EAAE,CACzE,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IACnD,qFAAqF;IACrF,QAAQ,EAAE,CAAoB,MAAsB,EAAE,EAAE,CACtD,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAC/C,iFAAiF;IACjF,6EAA6E;IAC7E,6EAA6E;IAC7E,6EAA6E;IAC7E,sEAAsE;IACtE,KAAK,EAAE,CAAyC,OAAU,EAAE,EAAE,CAC5D,WAAW,CACT,IAAI,CAAC,KAAK,CAAE,OAAkC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CACV;IAC5E,MAAM,EAAE,CAAoB,KAAqB,EAAE,OAAuB,EAAE,EAAE,CAC5E,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,KAAK,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;CAC5D,CAAA"}
+{"version":3,"file":"t.js","sourceRoot":"","sources":["../src/t.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/schema",
-  "version": "1.0.0-beta.4",
+  "version": "1.1.0",
   "description": "Built-in schema builder `t` — TypeBox-backed (free JSON Schema + compiled validators), implements Standard Schema so nifra routes validate it natively.",
   "keywords": [
     "bun",
@@ -48,7 +48,7 @@
     "@sinclair/typebox": "^0.34.49"
   },
   "peerDependencies": {
-    "@nifrajs/core": "1.0.0-beta.4"
+    "@nifrajs/core": "^1.1.0"
   },
   "devDependencies": {
     "@nifrajs/core": "workspace:*",

package/src/adapter.ts

@@ -46,8 +46,18 @@ function toIssue(error: { readonly message: string; readonly path: string }): St
  *
  * Exposed (not just used internally by `t`) so a TypeBox schema authored directly can
  * be adapted without leaving the Standard Schema world.
+ *
+ * `options.coerce` runs TypeBox's `Value.Convert` (string→number/integer/boolean, per the schema)
+ * BEFORE validating. Query values always arrive as strings (`?limit=20` → `"20"`), so a query schema
+ * with a numeric field can't validate without this — it's how `t.pageQuery` yields a real `number`.
+ * Leave it OFF (the default) for body/JSON schemas: a JSON number is already a number, and coercing
+ * would silently accept `"20"` where the contract said `20`.
  */
-export function fromTypeBox<T extends TSchema>(schema: T): NifraSchema<T> {
+export function fromTypeBox<T extends TSchema>(
+  schema: T,
+  options?: { readonly coerce?: boolean },
+): NifraSchema<T> {
+  const coerce = options?.coerce ?? false
   let compiled: TypeCheck<T> | undefined
   let evalFree = false
   return {
@@ -59,6 +69,10 @@ export function fromTypeBox<T extends TSchema>(schema: T): NifraSchema<T> {
         // reachable path (not a top-level import side effect) so a production bundle can't
         // tree-shake the registration away — see ./formats.ts. Idempotent, ~free after first call.
         ensureDefaultFormats()
+        // Coerce first when asked (query schemas): `Value.Convert` turns "20"→20 per the schema, so the
+        // compiled/eval-free Check below sees the target type. A non-convertible value (e.g. "abc" for an
+        // integer) is left as-is and fails Check → a proper 400.
+        const input = coerce ? Value.Convert(schema, value) : value
         if (compiled === undefined && !evalFree) {
           try {
             compiled = TypeCompiler.Compile(schema)
@@ -68,11 +82,11 @@ export function fromTypeBox<T extends TSchema>(schema: T): NifraSchema<T> {
           }
         }
         if (compiled !== undefined) {
-          if (compiled.Check(value)) return { value }
-          return { issues: [...compiled.Errors(value)].map(toIssue) }
+          if (compiled.Check(input)) return { value: input as Static<T> }
+          return { issues: [...compiled.Errors(input)].map(toIssue) }
         }
-        if (Value.Check(schema, value)) return { value }
-        return { issues: [...Value.Errors(schema, value)].map(toIssue) }
+        if (Value.Check(schema, input)) return { value: input as Static<T> }
+        return { issues: [...Value.Errors(schema, input)].map(toIssue) }
       },
       // Phantom: `types` carries no runtime value; this cast supplies the
       // compile-time `Static<T>` that nifra's `InferOutput` reads to type `c.body`.

package/src/index.ts

@@ -12,4 +12,6 @@ export { fromTypeBox, type NifraSchema } from "./adapter.ts"
 // effect of this module, which a production bundler would tree-shake away.
 export { registerFormat } from "./formats.ts"
 export { type OpenAPIDocument, type OpenAPIInfo, toOpenAPI } from "./openapi.ts"
+// Cursor-pagination runtime helpers — pair with `t.paginated` / `t.pageQuery`.
+export { decodeCursor, encodeCursor, type Page, paginate } from "./pagination.ts"
 export { t } from "./t.ts"

package/src/pagination.ts

@@ -0,0 +1,64 @@
+/**
+ * Cursor-pagination runtime helpers — an opaque cursor codec + a page builder. Pair with `t.paginated`
+ * (the response schema) and `t.pageQuery` (the request schema).
+ *
+ * Edge-safe: `btoa`/`atob` + `TextEncoder`/`TextDecoder` (no `Buffer`), so it runs on Bun/Node/Deno/
+ * Workers. Cursors are opaque but NOT signed — treat a decoded cursor as untrusted client input: validate
+ * its shape before keying a DB query off it (it's a position hint, not an authorization token).
+ */
+
+/** UTF-8 → URL-safe base64 (no padding). */
+function toBase64Url(input: string): string {
+  const bytes = new TextEncoder().encode(input)
+  let binary = ""
+  for (const byte of bytes) binary += String.fromCharCode(byte)
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "")
+}
+
+/** URL-safe base64 → UTF-8. Throws on malformed input (callers below catch it). */
+function fromBase64Url(input: string): string {
+  const binary = atob(input.replace(/-/g, "+").replace(/_/g, "/"))
+  const bytes = Uint8Array.from(binary, (ch) => ch.charCodeAt(0))
+  return new TextDecoder().decode(bytes)
+}
+
+/** Encode any JSON-serializable value (e.g. the last row's sort key) into an opaque cursor string. */
+export function encodeCursor(value: unknown): string {
+  return toBase64Url(JSON.stringify(value))
+}
+
+/** Decode a cursor back to its value. Returns `undefined` for a null/empty/malformed cursor — treat that
+ * as "start from the beginning" rather than erroring on a client-supplied string. */
+export function decodeCursor<T = unknown>(cursor: string | null | undefined): T | undefined {
+  if (cursor === null || cursor === undefined || cursor === "") return undefined
+  try {
+    return JSON.parse(fromBase64Url(cursor)) as T
+  } catch {
+    return undefined
+  }
+}
+
+/** A cursor-pagination page — matches the shape of `t.paginated(item)`. */
+export interface Page<Item> {
+  readonly items: Item[]
+  readonly nextCursor: string | null
+}
+
+/**
+ * Build a page from rows you fetched with `limit + 1`. If the extra row came back there are more pages:
+ * drop it and emit a `nextCursor` from the last KEPT row via `cursorOf`; otherwise `nextCursor` is `null`.
+ *
+ *   const rows = await db.notes.after(decodeCursor(query.cursor)).take(limit + 1)
+ *   return paginate(rows, limit, (note) => note.id)
+ */
+export function paginate<Row>(
+  rows: readonly Row[],
+  limit: number,
+  cursorOf: (row: Row) => unknown,
+): Page<Row> {
+  const hasMore = rows.length > limit
+  const items = hasMore ? rows.slice(0, limit) : [...rows]
+  const last = items[items.length - 1]
+  const nextCursor = hasMore && last !== undefined ? encodeCursor(cursorOf(last)) : null
+  return { items, nextCursor }
+}

package/src/t.ts

@@ -67,4 +67,34 @@ export const t = {
     ) as NifraSchema<TUnion<{ -readonly [K in keyof S]: S[K]["jsonSchema"] }>>,
   record: <T extends TSchema>(value: NifraSchema<T>, options?: ObjectOptions) =>
     fromTypeBox(Type.Record(Type.String(), value.jsonSchema, options)),
+
+  // Composed from TypeBox directly (not `t.object`/`t.array`) so the `t` literal doesn't reference
+  // itself during inference. Cursor pagination — not OFFSET — is the production default: stable under
+  // concurrent inserts and O(1) per page. Build pages with `paginate()` + `encodeCursor`/`decodeCursor`.
+  /** A cursor-pagination response envelope: `{ items: T[]; nextCursor: string | null }` (`null` = last page). */
+  paginated: <T extends TSchema>(item: NifraSchema<T>, options?: ObjectOptions) =>
+    fromTypeBox(
+      Type.Object(
+        {
+          items: Type.Array(item.jsonSchema),
+          nextCursor: Type.Union([Type.String(), Type.Null()]),
+        },
+        { additionalProperties: false, ...options },
+      ),
+    ),
+  /** A request query schema for cursor pagination: `{ cursor?: string; limit?: number }`. `maxLimit`
+   * caps `limit` — a larger value fails validation (a 400), so a client can't request an unbounded page.
+   * `coerce` is on because query values arrive as strings (`?limit=20` → `"20"`); it's what makes `limit`
+   * a real `number` in the handler (`c.query.limit`), not a string. */
+  pageQuery: (options?: { maxLimit?: number }) =>
+    fromTypeBox(
+      Type.Object(
+        {
+          cursor: Type.Optional(Type.String()),
+          limit: Type.Optional(Type.Integer({ minimum: 1, maximum: options?.maxLimit ?? 100 })),
+        },
+        { additionalProperties: false },
+      ),
+      { coerce: true },
+    ),
 } as const