@pithy-sh/core 0.1.1 → 0.1.3

package/dist/createEntrypoint.d.ts

@@ -0,0 +1,53 @@
+import type { ExecutionContext, ForwardableEmailMessage } from "@cloudflare/workers-types";
+import type { Capability } from "./capability/capability";
+import { type CreateBackendOptions } from "./createBackend";
+/**
+ * A deployable Worker entrypoint: `fetch`, the single inbound `email` handler the runtime permits
+ * per Worker, and the single `scheduled` handler it permits for cron triggers. `createBackend`
+ * already produces the `fetch` side (a Hono app); this wraps it and composes every capability's
+ * inbound-email handler and every cron-carrying durable job behind those two entries, so a Worker
+ * that mounts `@pithy-sh/email` receives bounce/complaint mail — and fires its scheduler — without
+ * the user authoring a handler.
+ */
+export interface PithyEntrypoint {
+    /** The Worker `fetch` handler — the composed Hono app. */
+    fetch: (request: Request, env: Record<string, unknown>, ctx: ExecutionContext) => Response | Promise<Response>;
+    /**
+     * The Worker `email` handler — fans each incoming message to every capability that declares one.
+     * **Present only when at least one capability handles inbound mail.** Omitted otherwise, so a Worker
+     * that no capability wired for email doesn't expose a no-op `email()` that would silently *drop* any
+     * message routed to it (an exported-but-inert handler consumes the message without forwarding or
+     * rejecting it).
+     */
+    email?: (message: ForwardableEmailMessage, env: Record<string, unknown>, ctx: ExecutionContext) => Promise<void>;
+    /**
+     * The Worker `scheduled` handler — starts every registered job that declares a `schedule`.
+     *
+     * **Present only when at least one job carries a cron.** The reason differs from `email`'s: an
+     * inert `email()` silently *drops* mail, which is a correctness bug, whereas an inert `scheduled()`
+     * is merely harmless. It is omitted anyway so that the export tracks the composition: a Worker
+     * mounting no scheduled job does not advertise a schedule it has none of.
+     *
+     * The converse does happen and is deliberate. A capability whose cron belongs to its *prebuilt host*
+     * — `@pithy-sh/email`'s every-minute scheduler is the shipped example — still declares that schedule
+     * on its spec, so an app worker composing it exports a `scheduled` handler while its own
+     * `wrangler.jsonc` declares no `triggers.crons`. Nothing ever invokes it, and if something did, the
+     * job's binding lives only on the host, so dispatch degrades with a logged warning. Deriving the
+     * export from "does this deployment declare crons" is not available here: `createEntrypoint` sees
+     * the composed capabilities, never the wrangler config.
+     *
+     * A cron is an *additional* entry point, never the only one: every scheduled job stays dispatchable
+     * through `c.var.workflows.trigger(...)`, because a backfill nobody can run on demand cannot be
+     * tested in staging.
+     */
+    scheduled?: (controller: unknown, env: Record<string, unknown>, ctx: ExecutionContext) => Promise<void>;
+}
+/**
+ * Assemble capabilities into a Worker entrypoint object — `{ fetch, email }`. Use this instead of
+ * `createBackend` directly when any capability handles inbound email (e.g. `@pithy-sh/email`'s bounce
+ * handler). `fetch` is the same Hono app `createBackend` returns; `email` fans each incoming message
+ * to every capability's `email` handler, replaying the single-use raw stream so each sees the full
+ * message. Handlers run sequentially in registration order.
+ */
+export declare function createEntrypoint<const Caps extends readonly Capability[], const App extends Capability = Capability<Record<never, never>, Record<never, never>>>(options: CreateBackendOptions<Caps, App>): PithyEntrypoint;
+//# sourceMappingURL=createEntrypoint.d.ts.map

package/dist/createEntrypoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createEntrypoint.d.ts","sourceRoot":"","sources":["../src/createEntrypoint.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAC3F,OAAO,KAAK,EAAE,UAAU,EAA0B,MAAM,yBAAyB,CAAC;AAClF,OAAO,EAAE,KAAK,oBAAoB,EAAiB,MAAM,iBAAiB,CAAC;AAI3E;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,0DAA0D;IAC1D,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,gBAAgB,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC/G;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,uBAAuB,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjH;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAAS,CAAC,EAAE,CAAC,UAAU,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACzG;AAkBD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,CAAC,IAAI,SAAS,SAAS,UAAU,EAAE,EACxC,KAAK,CAAC,GAAG,SAAS,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,EACrF,OAAO,EAAE,oBAAoB,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,eAAe,CA+C3D"}

package/dist/createEntrypoint.js

@@ -0,0 +1,52 @@
+import { triggerWorkflow } from "./workflow/dispatch.js";
+import { composeWorkflows, scheduledWorkflows } from "./workflow/register.js";
+import { createBackend } from "./createBackend.js";
+//#region src/createEntrypoint.ts
+/**
+* The raw MIME stream of a `ForwardableEmailMessage` is **single-use** — once one handler reads it,
+* the next sees an empty stream. When more than one capability handles inbound mail we buffer the
+* body once and hand each handler a proxy whose `raw` yields a fresh stream over that buffer; every
+* other property/method delegates to (and stays bound to) the real message.
+*/
+function replayable(message, raw) {
+	return new Proxy(message, { get(target, prop, receiver) {
+		if (prop === "raw") return new Response(raw.slice(0)).body;
+		const value = Reflect.get(target, prop, receiver);
+		return typeof value === "function" ? value.bind(target) : value;
+	} });
+}
+/**
+* Assemble capabilities into a Worker entrypoint object — `{ fetch, email }`. Use this instead of
+* `createBackend` directly when any capability handles inbound email (e.g. `@pithy-sh/email`'s bounce
+* handler). `fetch` is the same Hono app `createBackend` returns; `email` fans each incoming message
+* to every capability's `email` handler, replaying the single-use raw stream so each sees the full
+* message. Handlers run sequentially in registration order.
+*/
+function createEntrypoint(options) {
+	const app = createBackend(options);
+	const all = options.app ? [...options.capabilities, options.app] : [...options.capabilities];
+	const handlers = all.flatMap((cap) => cap.email ? [cap.email] : []);
+	const registry = composeWorkflows(all);
+	const scheduled = scheduledWorkflows(registry);
+	const entrypoint = { fetch: (request, env, ctx) => app.fetch(request, env, ctx) };
+	if (scheduled.length > 0) entrypoint.scheduled = async (_controller, env) => {
+		const failures = [];
+		for (const entry of scheduled) try {
+			await triggerWorkflow(env, registry, entry.key, {});
+		} catch (error) {
+			failures.push(error);
+		}
+		if (failures[0] !== void 0) throw failures[0];
+	};
+	if (handlers.length > 0) entrypoint.email = async (message, env, ctx) => {
+		if (handlers.length === 1) {
+			await handlers[0]?.(message, env, ctx);
+			return;
+		}
+		const raw = await new Response(message.raw).arrayBuffer();
+		for (const handler of handlers) await handler(replayable(message, raw), env, ctx);
+	};
+	return entrypoint;
+}
+//#endregion
+export { createEntrypoint };

package/dist/data/boundParameters.d.ts

@@ -0,0 +1,83 @@
+import type { D1Database } from "@cloudflare/workers-types";
+/**
+ * D1's bound-parameter ceiling, and the chunking every `in (...)` list needs to stay under it.
+ *
+ * D1 rejects a statement carrying more than 100 bound parameters. The failure mode is the nastiest kind:
+ * every small test passes, and the query only breaks once real data arrives. Worse, the naive fix —
+ * chunking the list at exactly 100 — is *also* wrong whenever the statement binds anything else. A
+ * `where("indexName", "=", name).where("id", "in", <100 ids>)` binds 101, and an `update … set(a, b)`
+ * ahead of the list binds two more before a single id is counted.
+ *
+ * So the unit here is not "the cap" but **the budget left after the statement's own fixed parameters**.
+ * A call site names how many parameters its statement binds besides the list, and the chunk size is
+ * derived. Adding a `where` to one of those queries is then a one-number edit next to it, not a silent
+ * re-break of a limit nobody re-derived.
+ *
+ * Lives in core rather than in each capability because the arithmetic is the part that was got wrong,
+ * and because `data/` is already where D1's quirks live (see `withD1Retry`).
+ */
+/** D1's hard cap on bound parameters in one statement. Cloudflare documents it; over it is an error, not a truncation. */
+export declare const MAX_BOUND_PARAMETERS = 100;
+/**
+ * How many list values one statement may still bind once its fixed parameters are paid for.
+ *
+ * `fixed` is everything the statement binds that is *not* part of the chunked list — each `where` value,
+ * each `set` column, each limit. Throws when a statement leaves no room at all: that is a bug in the
+ * query, not a runtime condition, and silently returning zero would spin the caller's loop forever.
+ */
+export declare function boundParameterBudget(fixed: number): number;
+/**
+ * Split `values` into chunks, each small enough that one statement binding `fixed` other parameters
+ * stays under D1's cap. An empty input yields no chunks, so a caller's loop simply does not run.
+ */
+export declare function chunkByBoundParameters<T>(values: readonly T[], fixed: number): T[][];
+/**
+ * Split `rows` into chunks small enough that one multi-row `insert` stays under D1's cap.
+ *
+ * The sibling of {@link chunkByBoundParameters}, and a separate function because the arithmetic is
+ * genuinely different: an `in (…)` list binds **one** parameter per value, while an insert binds one
+ * per *column* per row. Reusing the list chunker for an insert silently allows `columns` times too
+ * many rows, which is a bug that passes every small test and only appears once real data arrives —
+ * `@pithy-sh/support` shipped exactly that, capping attachments at 10 rows of 11 columns and losing
+ * every one of them to `too many SQL variables`.
+ */
+export declare function chunkRowsByBoundParameters<T>(rows: readonly T[], columnsPerRow: number, fixed?: number): T[][];
+/**
+ * D1, wrapped so a statement over the cap fails as **the rule** rather than as SQLite's complaint.
+ *
+ * `createDatabase` applies this to every database it builds, which is the whole point: the rule lives at
+ * the thing being called, not at each of the query sites that call it. A capability written next month
+ * that has never heard of the cap is covered by it, and so is one written last year — which matters,
+ * because the list of sites that got this wrong has been wrong five times running. Four capabilities
+ * bound past the cap while the arithmetic to avoid it sat in this file, unimported (#250).
+ *
+ * The check is at `bind`, because that is the only place the number is real: it is what the driver hands
+ * the platform, after Kysely has compiled the statement and after any chunking a caller did. Anything
+ * measured earlier measures intent.
+ *
+ * It does not chunk. It cannot — splitting an arbitrary statement is the caller's arithmetic, and
+ * {@link chunkByBoundParameters} and {@link chunkRowsByBoundParameters} are where it belongs. What this
+ * buys is that the failure names the rule that was broken, one statement before the platform says
+ * `too many SQL variables` and leaves the author to work out which list was too long.
+ */
+export declare function guardBoundParameters(d1: D1Database): D1Database;
+/** What one recorded run bound, and whatever it threw. */
+export interface BoundParameterRecording {
+    /** Every parameter count D1 was asked to bind, in the order the statements ran. */
+    counts: number[];
+    /** What `run` threw, or `undefined`. Returned rather than propagated — see below. */
+    error: unknown;
+}
+/**
+ * Run `run` against a recording D1 and report every parameter count it bound.
+ *
+ * A gate wants to assert the ceiling *before* it rethrows, so the failure an author reads is the
+ * invariant rather than whatever the platform said about it. Hence the throw comes back in the result
+ * instead of propagating: the caller asserts the counts, then rethrows anything left.
+ *
+ * The counterpart to {@link guardBoundParameters} rather than a duplicate of it. The guard proves a
+ * statement was *refused*; this proves what was *bound* — that chunks fill the budget rather than
+ * creeping under it, and that chunking lost no rows on the way.
+ */
+export declare function recordBoundParameters(d1: D1Database, run: (d1: D1Database) => Promise<void>): Promise<BoundParameterRecording>;
+//# sourceMappingURL=boundParameters.d.ts.map

package/dist/data/boundParameters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boundParameters.d.ts","sourceRoot":"","sources":["../../src/data/boundParameters.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAuB,MAAM,2BAA2B,CAAC;AAGjF;;;;;;;;;;;;;;;;GAgBG;AAEH,0HAA0H;AAC1H,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAe1D;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,EAAE,EAAE,CAKpF;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,EAAE,EAAE,aAAa,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,CAAC,EAAE,EAAE,CAiBzG;AAcD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,UAAU,GAAG,UAAU,CA0B/D;AAED,0DAA0D;AAC1D,MAAM,WAAW,uBAAuB;IACtC,mFAAmF;IACnF,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,qFAAqF;IACrF,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,CACzC,EAAE,EAAE,UAAU,EACd,GAAG,EAAE,CAAC,EAAE,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GACrC,OAAO,CAAC,uBAAuB,CAAC,CAyBlC"}

package/dist/data/boundParameters.js

@@ -0,0 +1,162 @@
+import { InternalError } from "../error/pithyError.js";
+//#region src/data/boundParameters.ts
+/**
+* D1's bound-parameter ceiling, and the chunking every `in (...)` list needs to stay under it.
+*
+* D1 rejects a statement carrying more than 100 bound parameters. The failure mode is the nastiest kind:
+* every small test passes, and the query only breaks once real data arrives. Worse, the naive fix —
+* chunking the list at exactly 100 — is *also* wrong whenever the statement binds anything else. A
+* `where("indexName", "=", name).where("id", "in", <100 ids>)` binds 101, and an `update … set(a, b)`
+* ahead of the list binds two more before a single id is counted.
+*
+* So the unit here is not "the cap" but **the budget left after the statement's own fixed parameters**.
+* A call site names how many parameters its statement binds besides the list, and the chunk size is
+* derived. Adding a `where` to one of those queries is then a one-number edit next to it, not a silent
+* re-break of a limit nobody re-derived.
+*
+* Lives in core rather than in each capability because the arithmetic is the part that was got wrong,
+* and because `data/` is already where D1's quirks live (see `withD1Retry`).
+*/
+/** D1's hard cap on bound parameters in one statement. Cloudflare documents it; over it is an error, not a truncation. */
+const MAX_BOUND_PARAMETERS = 100;
+/**
+* How many list values one statement may still bind once its fixed parameters are paid for.
+*
+* `fixed` is everything the statement binds that is *not* part of the chunked list — each `where` value,
+* each `set` column, each limit. Throws when a statement leaves no room at all: that is a bug in the
+* query, not a runtime condition, and silently returning zero would spin the caller's loop forever.
+*/
+function boundParameterBudget(fixed) {
+	if (!Number.isInteger(fixed) || fixed < 0) throw new InternalError({
+		message: "Something unexpected happened.",
+		detail: `boundParameterBudget requires a non-negative integer count of fixed parameters; got ${fixed}.`
+	});
+	const budget = 100 - fixed;
+	if (budget < 1) throw new InternalError({
+		message: "Something unexpected happened.",
+		detail: `A statement binding ${fixed} fixed parameters leaves no room under D1's cap of 100.`
+	});
+	return budget;
+}
+/**
+* Split `values` into chunks, each small enough that one statement binding `fixed` other parameters
+* stays under D1's cap. An empty input yields no chunks, so a caller's loop simply does not run.
+*/
+function chunkByBoundParameters(values, fixed) {
+	const size = boundParameterBudget(fixed);
+	const chunks = [];
+	for (let start = 0; start < values.length; start += size) chunks.push(values.slice(start, start + size));
+	return chunks;
+}
+/**
+* Split `rows` into chunks small enough that one multi-row `insert` stays under D1's cap.
+*
+* The sibling of {@link chunkByBoundParameters}, and a separate function because the arithmetic is
+* genuinely different: an `in (…)` list binds **one** parameter per value, while an insert binds one
+* per *column* per row. Reusing the list chunker for an insert silently allows `columns` times too
+* many rows, which is a bug that passes every small test and only appears once real data arrives —
+* `@pithy-sh/support` shipped exactly that, capping attachments at 10 rows of 11 columns and losing
+* every one of them to `too many SQL variables`.
+*/
+function chunkRowsByBoundParameters(rows, columnsPerRow, fixed = 0) {
+	if (!Number.isInteger(columnsPerRow) || columnsPerRow < 1) throw new InternalError({
+		message: "Something unexpected happened.",
+		detail: `chunkRowsByBoundParameters requires a positive column count; got ${columnsPerRow}.`
+	});
+	const size = Math.floor(boundParameterBudget(fixed) / columnsPerRow);
+	if (size < 1) throw new InternalError({
+		message: "Something unexpected happened.",
+		detail: `A row of ${columnsPerRow} columns cannot fit under D1's cap of 100.`
+	});
+	const chunks = [];
+	for (let start = 0; start < rows.length; start += size) chunks.push(rows.slice(start, start + size));
+	return chunks;
+}
+/** Read a property off a platform object without losing its `this` — workerd's D1 objects need it. */
+function passThrough(target, property) {
+	const value = Reflect.get(target, property);
+	return typeof value === "function" ? value.bind(target) : value;
+}
+/** Enough of a statement to name it in a failure, without carrying a query of unbounded length. */
+function nameOf(query) {
+	const collapsed = query.replace(/\s+/g, " ").trim();
+	return collapsed.length > 160 ? `${collapsed.slice(0, 157)}…` : collapsed;
+}
+/**
+* D1, wrapped so a statement over the cap fails as **the rule** rather than as SQLite's complaint.
+*
+* `createDatabase` applies this to every database it builds, which is the whole point: the rule lives at
+* the thing being called, not at each of the query sites that call it. A capability written next month
+* that has never heard of the cap is covered by it, and so is one written last year — which matters,
+* because the list of sites that got this wrong has been wrong five times running. Four capabilities
+* bound past the cap while the arithmetic to avoid it sat in this file, unimported (#250).
+*
+* The check is at `bind`, because that is the only place the number is real: it is what the driver hands
+* the platform, after Kysely has compiled the statement and after any chunking a caller did. Anything
+* measured earlier measures intent.
+*
+* It does not chunk. It cannot — splitting an arbitrary statement is the caller's arithmetic, and
+* {@link chunkByBoundParameters} and {@link chunkRowsByBoundParameters} are where it belongs. What this
+* buys is that the failure names the rule that was broken, one statement before the platform says
+* `too many SQL variables` and leaves the author to work out which list was too long.
+*/
+function guardBoundParameters(d1) {
+	return new Proxy(d1, { get(target, property) {
+		if (property !== "prepare") return passThrough(target, property);
+		return (query) => {
+			const statement = target.prepare(query);
+			return new Proxy(statement, { get(inner, key) {
+				if (key !== "bind") return passThrough(inner, key);
+				return (...values) => {
+					if (values.length > 100) throw new InternalError({
+						message: "Something unexpected happened.",
+						action: "Retry. If it persists, the query needs chunking.",
+						detail: `A statement bound ${values.length} parameters; D1 accepts 100. Chunk the list through chunkByBoundParameters (one parameter per value) or chunkRowsByBoundParameters (one per column per row). Statement: ${nameOf(query)}`
+					});
+					return inner.bind(...values);
+				};
+			} });
+		};
+	} });
+}
+/**
+* Run `run` against a recording D1 and report every parameter count it bound.
+*
+* A gate wants to assert the ceiling *before* it rethrows, so the failure an author reads is the
+* invariant rather than whatever the platform said about it. Hence the throw comes back in the result
+* instead of propagating: the caller asserts the counts, then rethrows anything left.
+*
+* The counterpart to {@link guardBoundParameters} rather than a duplicate of it. The guard proves a
+* statement was *refused*; this proves what was *bound* — that chunks fill the budget rather than
+* creeping under it, and that chunking lost no rows on the way.
+*/
+async function recordBoundParameters(d1, run) {
+	const counts = [];
+	const recorder = new Proxy(d1, { get(target, property) {
+		if (property !== "prepare") return passThrough(target, property);
+		return (query) => {
+			const statement = target.prepare(query);
+			return new Proxy(statement, { get(inner, key) {
+				if (key !== "bind") return passThrough(inner, key);
+				return (...values) => {
+					counts.push(values.length);
+					return inner.bind(...values);
+				};
+			} });
+		};
+	} });
+	try {
+		await run(recorder);
+		return {
+			counts,
+			error: void 0
+		};
+	} catch (error) {
+		return {
+			counts,
+			error
+		};
+	}
+}
+//#endregion
+export { MAX_BOUND_PARAMETERS, boundParameterBudget, chunkByBoundParameters, chunkRowsByBoundParameters, guardBoundParameters, recordBoundParameters };

package/dist/data/codecs.d.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+/** SQLiteBoolean: boolean ↔ 0|1. Decode is lenient (number/boolean/string). */
+export declare const SQLiteBoolean: z.ZodCodec<z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodBoolean, z.ZodString]>, z.ZodBoolean>;
+/** SQLiteDate: Date ↔ ms-epoch number. Decode accepts number/string/Date. */
+export declare const SQLiteDate: z.ZodCodec<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodDate]>, z.ZodDate>;
+/** JsonDate: Date ↔ ISO string, for dates nested inside `sqliteJson` payloads. */
+export declare const JsonDate: z.ZodCodec<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodDate]>, z.ZodDate>;
+/**
+ * sqliteJson: T ↔ JSON string, validated by `schema` on both sides. Decode
+ * accepts a JSON string or an already-parsed value; the result is validated
+ * against `schema` before it reaches the app.
+ *
+ * **Both `JSON` functions throw**, and both were reachable. `JSON.parse` throws a
+ * `SyntaxError` on any string that is not a JSON document — which a column holding
+ * text an older writer put there, or a payload a customer's Worker returned, can be.
+ * `JSON.stringify` throws a `TypeError` on a `BigInt` and on a cycle, either of
+ * which a `schema` can legitimately admit. Both become an issue (#358).
+ */
+export declare function sqliteJson<T extends z.ZodType>(schema: T): z.ZodCodec<z.ZodUnion<readonly [z.ZodString, T]>, T>;
+export declare const MAX_TIMEZONE_LENGTH = 64;
+/**
+ * Trim, validate, and canonicalize an IANA timezone; anything invalid becomes
+ * `undefined`. Returns Intl's canonical casing (`america/new_york` →
+ * `America/New_York`) so a zone is stored and compared as one value.
+ */
+export declare function normalizeIanaTimezone(value: unknown): string | undefined;
+/** Whether `value` is a usable IANA timezone (bounded length, recognized by Intl). */
+export declare function isValidIanaTimezone(value: string): boolean;
+/**
+ * IanaTimezone: validated/bounded IANA timezone string. Coerces invalid input
+ * to `undefined` on both decode and encode rather than throwing.
+ */
+export declare const IanaTimezone: z.ZodCodec<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodOptional<z.ZodString>>;
+//# sourceMappingURL=codecs.d.ts.map

package/dist/data/codecs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codecs.d.ts","sourceRoot":"","sources":["../../src/data/codecs.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA+CxB,+EAA+E;AAC/E,eAAO,MAAM,aAAa,8GAGxB,CAAC;AAoBH,6EAA6E;AAC7E,eAAO,MAAM,UAAU,mFAGrB,CAAC;AAEH,kFAAkF;AAClF,eAAO,MAAM,QAAQ,mFAGnB,CAAC;AAEH;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,wDA8BxD;AAED,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CASxE;AAED,sFAAsF;AACtF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,mFAGvB,CAAC"}

package/dist/data/codecs.js

@@ -0,0 +1,135 @@
+import { z } from "zod";
+//#region src/data/codecs.ts
+const TRUTHY = [
+	true,
+	1,
+	"1",
+	"true",
+	"True",
+	"TRUE"
+];
+function isTruthy(value) {
+	return TRUTHY.includes(value);
+}
+/** SQLiteBoolean: boolean ↔ 0|1. Decode is lenient (number/boolean/string). */
+const SQLiteBoolean = z.codec(z.union([
+	z.literal(0),
+	z.literal(1),
+	z.boolean(),
+	z.string()
+]), z.boolean(), {
+	decode: (input) => typeof input === "boolean" ? input : isTruthy(input),
+	encode: (value) => value ? 1 : 0
+});
+/**
+* The shared decode for both date codecs. A string is parsed, a number is ms-epoch — what `encode`
+* writes, so a caller ingesting seconds-epoch from elsewhere converts explicitly — and a `Date` passes
+* through by identity.
+*
+* **Every branch can produce an unusable `Date`**, not only the string one: `new Date(8.64e15 + 1)` is
+* as invalid as `new Date("not-a-date")`. So the check is on the result, once, rather than on the input
+* shape — which is what stops the next accepted input type from arriving without it.
+*/
+function toDate(input, payload) {
+	const parsed = input instanceof Date ? input : new Date(input);
+	if (Number.isNaN(parsed.getTime())) {
+		payload.issues.push({
+			code: "invalid_format",
+			format: "datetime",
+			input: String(input),
+			message: "Not a date."
+		});
+		return z.NEVER;
+	}
+	return parsed;
+}
+/** SQLiteDate: Date ↔ ms-epoch number. Decode accepts number/string/Date. */
+const SQLiteDate = z.codec(z.union([
+	z.number(),
+	z.string(),
+	z.date()
+]), z.date(), {
+	decode: toDate,
+	encode: (value) => value.getTime()
+});
+/** JsonDate: Date ↔ ISO string, for dates nested inside `sqliteJson` payloads. */
+const JsonDate = z.codec(z.union([
+	z.string(),
+	z.number(),
+	z.date()
+]), z.date(), {
+	decode: toDate,
+	encode: (value) => value.toISOString()
+});
+/**
+* sqliteJson: T ↔ JSON string, validated by `schema` on both sides. Decode
+* accepts a JSON string or an already-parsed value; the result is validated
+* against `schema` before it reaches the app.
+*
+* **Both `JSON` functions throw**, and both were reachable. `JSON.parse` throws a
+* `SyntaxError` on any string that is not a JSON document — which a column holding
+* text an older writer put there, or a payload a customer's Worker returned, can be.
+* `JSON.stringify` throws a `TypeError` on a `BigInt` and on a cycle, either of
+* which a `schema` can legitimately admit. Both become an issue (#358).
+*/
+function sqliteJson(schema) {
+	return z.codec(z.union([z.string(), schema]), schema, {
+		decode: (value, payload) => {
+			if (typeof value !== "string") return value;
+			try {
+				return JSON.parse(value);
+			} catch {
+				payload.issues.push({
+					code: "invalid_format",
+					format: "json",
+					input: value,
+					message: "Not valid JSON."
+				});
+				return z.NEVER;
+			}
+		},
+		encode: (value, payload) => {
+			try {
+				const json = JSON.stringify(value);
+				if (typeof json === "string") return json;
+			} catch {}
+			payload.issues.push({
+				code: "invalid_format",
+				format: "json",
+				input: void 0,
+				message: "Not serializable as JSON."
+			});
+			return z.NEVER;
+		}
+	});
+}
+const MAX_TIMEZONE_LENGTH = 64;
+/**
+* Trim, validate, and canonicalize an IANA timezone; anything invalid becomes
+* `undefined`. Returns Intl's canonical casing (`america/new_york` →
+* `America/New_York`) so a zone is stored and compared as one value.
+*/
+function normalizeIanaTimezone(value) {
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim();
+	if (trimmed.length === 0 || trimmed.length > 64) return void 0;
+	try {
+		return Intl.DateTimeFormat(void 0, { timeZone: trimmed }).resolvedOptions().timeZone;
+	} catch {
+		return;
+	}
+}
+/** Whether `value` is a usable IANA timezone (bounded length, recognized by Intl). */
+function isValidIanaTimezone(value) {
+	return normalizeIanaTimezone(value) !== void 0;
+}
+/**
+* IanaTimezone: validated/bounded IANA timezone string. Coerces invalid input
+* to `undefined` on both decode and encode rather than throwing.
+*/
+const IanaTimezone = z.codec(z.string().nullish(), z.string().optional(), {
+	decode: (input) => normalizeIanaTimezone(input),
+	encode: (value) => normalizeIanaTimezone(value)
+});
+//#endregion
+export { IanaTimezone, JsonDate, MAX_TIMEZONE_LENGTH, SQLiteBoolean, SQLiteDate, isValidIanaTimezone, normalizeIanaTimezone, sqliteJson };

package/dist/data/cursor.d.ts

@@ -0,0 +1,81 @@
+import { z } from "zod";
+/**
+ * Keyset pagination, once, for every capability that lists an unbounded table.
+ *
+ * ## Why keyset and never offset
+ *
+ * `OFFSET` shifts under a client whenever a row is inserted, and every table these paginate — audit
+ * events, email jobs, users, ledger transactions — is written to constantly while somebody is reading
+ * it. With `OFFSET 25` a row inserted at the head pushes one row from page 1 onto page 2, so a client
+ * paging through sees it twice and misses nothing only by luck; a deletion drops a row entirely. A
+ * keyset cursor names the last row's sort position, so the next page starts exactly where the previous
+ * ended whatever happened in between.
+ *
+ * ## Why this is in core rather than copied
+ *
+ * `@pithy-sh/support` had the only implementation, and Part 3 of #89 needs the same thing in four more
+ * packages. Four copies of a security-adjacent decode — where the difference between "malformed cursor"
+ * and "500" is a caller's ability to probe — is four places for one of them to be wrong. Capabilities
+ * depend on core seams, which is exactly what this is.
+ *
+ * ## The shape of a page
+ *
+ * A caller asks for `limit`; the query fetches `limit + 1` and, when it gets them, drops the extra and
+ * returns a `nextCursor`. That is what makes "is there another page" answerable **without a count
+ * query**, which on an audit table is the difference between a page load and a table scan.
+ */
+/** A sensible page when a caller names none. Small enough to render, large enough to be one request. */
+export declare const DEFAULT_PAGE_SIZE = 25;
+/** The most a caller may ask for in one page, whatever they send. An unbounded page is a table scan. */
+export declare const MAX_PAGE_SIZE = 100;
+/**
+ * The `limit` a query should actually use, clamped into range.
+ *
+ * Clamped rather than rejected: a client asking for 1000 wants "as many as you'll give me", and failing
+ * the request teaches it nothing a capped page does not. A caller asking for 0 or a negative gets one
+ * row rather than an empty page that looks like the end of the list.
+ */
+export declare function pageLimit(requested: number | undefined): number;
+/**
+ * An opaque position in a descending `(sort, id)` ordering.
+ *
+ * `sort` is the primary column's value — a ms-epoch for a date, a number for a monotonic id. `id` is the
+ * tiebreak that makes the position exact: without it, two rows sharing a timestamp straddle a page
+ * boundary and one of them is skipped or repeated.
+ */
+export declare const PageCursor: z.ZodObject<{
+    sort: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+    id: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+}, z.core.$strip>;
+export type PageCursor = z.infer<typeof PageCursor>;
+/**
+ * Encode a cursor for the wire.
+ *
+ * Base64url over JSON, and **opaque by intent rather than by obscurity**: the point is that a client
+ * cannot construct one by hand and therefore cannot come to depend on its shape, so the ordering can
+ * change later without breaking every caller. It is not a secret — it holds a sort value and an id the
+ * caller was just given, both of which were in the page it came from.
+ */
+export declare function encodeCursor(cursor: PageCursor): string;
+/**
+ * Decode a cursor. Returns undefined for anything malformed.
+ *
+ * **A bad cursor is a first page, not a 500.** Cursors travel through URLs, get truncated by clients,
+ * and outlive deploys; treating a malformed one as an error turns an ordinary client bug into a page
+ * that never loads, and hands anyone probing the endpoint a way to tell a parse failure from a
+ * not-found. Every failure mode here — bad base64, bad JSON, wrong shape — collapses to the same
+ * undefined.
+ */
+export declare function decodeCursor(value: string | undefined): PageCursor | undefined;
+/**
+ * Split an over-fetched result into the page and the cursor that follows it.
+ *
+ * Pass the rows a query returned when asked for `limit + 1`. When there are more than `limit`, the extra
+ * is dropped and `nextCursor` names the last row of the page; otherwise `nextCursor` is null and the
+ * client knows it has reached the end without a second request.
+ */
+export declare function toPage<T>(rows: readonly T[], limit: number, position: (row: T) => PageCursor): {
+    items: T[];
+    nextCursor: string | null;
+};
+//# sourceMappingURL=cursor.d.ts.map

package/dist/data/cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../../src/data/cursor.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,wGAAwG;AACxG,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC,wGAAwG;AACxG,eAAO,MAAM,aAAa,MAAM,CAAC;AAEjC;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAE/D;AAED;;;;;;GAMG;AACH,eAAO,MAAM,UAAU;;;iBAa4E,CAAC;AACpG,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAQvD;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAU9E;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,CAAC,EACtB,IAAI,EAAE,SAAS,CAAC,EAAE,EAClB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,UAAU,GAC/B;IAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAK3C"}