@classytic/repo-core 0.1.0

package/dist/lookup/types.d.mts

@@ -0,0 +1,170 @@
+import { Filter } from "../filter/types.mjs";
+import { KeysetPaginationResultCore, OffsetPaginationResultCore } from "../pagination/types.mjs";
+
+//#region src/lookup/types.d.ts
+/**
+ * Single lookup join. Reads like a `LEFT JOIN from ON from.foreignField
+ * = this.localField`, with the joined payload landing on `as`.
+ *
+ * Kit semantics (identical output shape across all three):
+ *
+ *   - **mongokit** → `{ $lookup: { from, localField, foreignField, as,
+ *     pipeline?: [{ $project: select }] } }`, optionally followed by
+ *     `$unwind` when `single` is true.
+ *   - **sqlitekit** → `LEFT JOIN "${from}" ON "${from}"."${foreignField}"
+ *     = base."${localField}"` with a projected `json_object(...)` or
+ *     `json_group_array(json_object(...))` column aliased to `as`.
+ *   - **pgkit** (future) → `LEFT JOIN LATERAL (SELECT ... WHERE ...)`
+ *     with `row_to_json` / `json_agg`.
+ *
+ * The `from` value is a string table/collection name — kits resolve it
+ * via their registry (Drizzle schema for SQL, mongoose connection for
+ * mongokit). Typos fail at query-time with a clear error, not silently.
+ */
+interface LookupSpec {
+  /**
+   * Foreign table / collection name to join against. Must exist in the
+   * kit's schema — sqlitekit looks it up in the Drizzle schema map;
+   * mongokit resolves to a Model by collection name.
+   */
+  from: string;
+  /** Field on the base row that holds the foreign key. */
+  localField: string;
+  /** Field on the joined row that matches `localField`. */
+  foreignField: string;
+  /**
+   * Output key where joined data lands. Defaults to `from` when
+   * omitted. Keep it explicit in application code — implicit
+   * defaults lead to name collisions when the foreign table name
+   * isn't a valid JavaScript identifier.
+   */
+  as?: string;
+  /**
+   * When true, unwrap the join to a single object (or `null` when no
+   * row matches). Use for one-to-one and many-to-one relationships
+   * (e.g. a user's single department). Default is `false` — the join
+   * produces an array (empty when no rows match), matching
+   * one-to-many semantics.
+   *
+   * Kits implement this via `$unwind: { preserveNullAndEmptyArrays:
+   * true }` (mongokit) or a `json_object()` projection that skips the
+   * GROUP BY required for array aggregation (sqlitekit).
+   */
+  single?: boolean;
+  /**
+   * Project only these fields from the joined row. Accepts either a
+   * column-name array (`['id', 'name']`) or a MongoDB-style
+   * inclusion/exclusion map (`{ id: 1, name: 1 }`). Kits translate to
+   * their native projection primitive.
+   *
+   * Omitting `select` returns every column from the joined table.
+   * Prefer to narrow — it reduces network bytes and prevents
+   * accidental leaks of sensitive fields on the joined row.
+   */
+  select?: readonly string[] | Record<string, 0 | 1>;
+  /**
+   * Optional pre-join filter on the joined rows. Compiled by the same
+   * Filter IR compiler each kit already uses for WHERE / `$match`.
+   * Narrows which foreign rows participate in the join — useful for
+   * soft-delete (`isNull('deletedAt')`) or status filters
+   * (`eq('status', 'active')`) applied to the joined side.
+   *
+   * NOTE: Applies to the foreign side only; filter the base side via
+   * the top-level `filters` on `lookupPopulate`.
+   */
+  where?: Filter | Record<string, unknown>;
+}
+/**
+ * Full options bag for `StandardRepo.lookupPopulate`. Same shape as the
+ * paginated read surface (`filters`, `sort`, `page`/`after`, `limit`)
+ * plus the `lookups` array. Drops straight into arc controllers that
+ * already build `PaginationParams` — just add the `lookups` field.
+ *
+ * Mixing offset vs keyset follows the same auto-detection rule as
+ * `getAll`: presence of `page` → offset, presence of `after` → keyset,
+ * neither → offset with `page: 1`.
+ */
+interface LookupPopulateOptions<TBase = unknown> {
+  /**
+   * Pre-join filter on the BASE table. Applied as `WHERE` / `$match`
+   * before joins run, so tenant scoping + soft-delete plugins compose
+   * correctly. Accepts Filter IR nodes or plain literal records; every
+   * kit's compiler handles both.
+   */
+  filters?: Filter | (Partial<TBase> & Record<string, unknown>);
+  /** One or more joins. Processed in array order. */
+  lookups: readonly LookupSpec[];
+  /**
+   * Sort spec applied to the base table. Fields from joined rows are
+   * NOT sortable through this contract — they require the kit-native
+   * path (mongokit's `aggregatePipeline`, sqlitekit's raw query) because
+   * cross-kit semantics for sorting on denormalized joined payloads
+   * diverge significantly.
+   */
+  sort?: string | Record<string, 1 | -1>;
+  /** 1-indexed page number for offset pagination. Defaults to `1`. */
+  page?: number;
+  /** Keyset cursor from a prior `next` field. */
+  after?: string;
+  /** Rows per page. Kit-dependent default (usually 20); capped at 1000. */
+  limit?: number;
+  /**
+   * Base-table column projection. Applied before joins so kits can
+   * narrow the SELECT list early. Joined-row projections live on the
+   * individual `LookupSpec.select`.
+   */
+  select?: readonly string[] | Record<string, 0 | 1>;
+  /**
+   * `'exact'` (default) runs a parallel count query for `total`;
+   * `'none'` skips the count entirely — the envelope reports
+   * `total: 0`, `pages: 0`, and derives `hasNext` from a `LIMIT N+1`
+   * peek on the data query. Use `'none'` for infinite-scroll UI where
+   * the total is never rendered.
+   */
+  countStrategy?: 'exact' | 'none';
+  /**
+   * Transaction session, same semantics as every other read. Mongokit
+   * threads this into the aggregation; SQL kits ignore it when the
+   * repo is already bound to a tx via `withTransaction`.
+   */
+  session?: unknown;
+}
+/**
+ * Row shape returned by `lookupPopulate`. Each row carries the base
+ * document plus one key per `LookupSpec.as` (defaulting to `from`).
+ * The joined value is:
+ *
+ *   - an array of rows for `single: false` / default (one-to-many)
+ *   - an object or `null` for `single: true` (one-to-one)
+ *
+ * `TBase` is the base row type; `TExtra` (defaults to `Record<string,
+ * unknown>`) is the aggregate shape of all joined payloads. Apps that
+ * want tight typing can supply `TExtra = { department: Department |
+ * null }` at the call site; callers that don't care just see
+ * `Record<string, unknown>`.
+ */
+type LookupRow<TBase = Record<string, unknown>, TExtra extends Record<string, unknown> = Record<string, unknown>> = TBase & TExtra;
+/**
+ * Paginated result envelope for `lookupPopulate`. Mirrors `getAll`'s
+ * discriminated union — same `docs` / `page` / `limit` / `total` /
+ * `pages` / `hasNext` / `hasPrev` (offset) or `docs` / `limit` /
+ * `hasMore` / `next` (keyset) — so UI code paginates join results
+ * with the same primitives whether it's looking at plain documents
+ * or joined ones. Narrow on the `method` discriminator:
+ *
+ * ```ts
+ * const result = await repo.lookupPopulate({ ... });
+ * if (result.method === 'keyset') {
+ *   // result.next, result.hasMore
+ * } else {
+ *   // result.page, result.total, result.pages
+ * }
+ * ```
+ *
+ * Kits that don't implement keyset joins simply never return the
+ * keyset variant — TypeScript's narrowing handles either case
+ * uniformly so callers don't branch on the kit.
+ */
+type LookupPopulateResult<TBase = Record<string, unknown>, TExtra extends Record<string, unknown> = Record<string, unknown>> = OffsetPaginationResultCore<LookupRow<TBase, TExtra>> | KeysetPaginationResultCore<LookupRow<TBase, TExtra>>;
+//#endregion
+export { LookupPopulateOptions, LookupPopulateResult, LookupRow, LookupSpec };

package/dist/operations/index.d.mts

@@ -0,0 +1,3 @@
+import { CoreRepositoryOperation, OperationDescriptor, OperationRegistry, PolicyKey, RepositoryOperation } from "./types.mjs";
+import { CORE_OP_REGISTRY, describe, extendRegistry, listOperations, mutatingOperations, operationsByPolicyKey, readOperations } from "./registry.mjs";
+export { CORE_OP_REGISTRY, type CoreRepositoryOperation, type OperationDescriptor, type OperationRegistry, type PolicyKey, type RepositoryOperation, describe, extendRegistry, listOperations, mutatingOperations, operationsByPolicyKey, readOperations };

package/dist/operations/index.mjs

@@ -0,0 +1,2 @@
+import { CORE_OP_REGISTRY, describe, extendRegistry, listOperations, mutatingOperations, operationsByPolicyKey, readOperations } from "./registry.mjs";
+export { CORE_OP_REGISTRY, describe, extendRegistry, listOperations, mutatingOperations, operationsByPolicyKey, readOperations };

package/dist/operations/registry.d.mts

@@ -0,0 +1,41 @@
+import { CoreRepositoryOperation, OperationDescriptor, OperationRegistry, PolicyKey, RepositoryOperation } from "./types.mjs";
+
+//#region src/operations/registry.d.ts
+/**
+ * The core registry. Driver kits merge their own descriptors on top of this
+ * via `extendRegistry`.
+ */
+declare const CORE_OP_REGISTRY: OperationRegistry<CoreRepositoryOperation>;
+/**
+ * Merge additional operations into a base registry. Returns a frozen object.
+ *
+ * Kits call this at module load:
+ * ```ts
+ * export const MONGOKIT_OP_REGISTRY = extendRegistry(CORE_OP_REGISTRY, {
+ *   aggregate: { policyKey: 'query', mutates: false, hasIdContext: false },
+ *   aggregatePaginate: { policyKey: 'filters', mutates: false, hasIdContext: false },
+ *   lookupPopulate: { policyKey: 'filters', mutates: false, hasIdContext: false },
+ *   bulkWrite: { policyKey: 'operations', mutates: true, hasIdContext: false },
+ * });
+ * ```
+ *
+ * The return type preserves both the base union and the extension keys, so
+ * plugins can still narrow on specific op names when they need to.
+ */
+declare function extendRegistry<Base extends string, Extra extends Record<string, OperationDescriptor>>(base: OperationRegistry<Base>, extra: Extra): OperationRegistry<Base | (keyof Extra & string)>;
+/** All known operation names in the registry, in insertion order. */
+declare function listOperations<Op extends string>(registry: OperationRegistry<Op>): Op[];
+/** Operations that mutate the database — drives audit + cache invalidation. */
+declare function mutatingOperations<Op extends string>(registry: OperationRegistry<Op>): Op[];
+/** Operations that don't mutate — drives default cacheable-op lists. */
+declare function readOperations<Op extends string>(registry: OperationRegistry<Op>): Op[];
+/** Filter ops by their policy-injection key. */
+declare function operationsByPolicyKey<Op extends string>(registry: OperationRegistry<Op>, key: PolicyKey): Op[];
+/**
+ * Look up a descriptor. Returns `undefined` when the op isn't registered —
+ * plugins should treat an unknown op as "ignore" rather than crash, so new
+ * kits can introduce operations without every plugin needing an update.
+ */
+declare function describe<Op extends string>(registry: OperationRegistry<Op>, op: RepositoryOperation): OperationDescriptor | undefined;
+//#endregion
+export { CORE_OP_REGISTRY, describe, extendRegistry, listOperations, mutatingOperations, operationsByPolicyKey, readOperations };

package/dist/operations/registry.mjs

@@ -0,0 +1,140 @@
+//#region src/operations/registry.ts
+/**
+* The core registry. Driver kits merge their own descriptors on top of this
+* via `extendRegistry`.
+*/
+const CORE_OP_REGISTRY = Object.freeze({
+	create: {
+		policyKey: "data",
+		mutates: true,
+		hasIdContext: false
+	},
+	update: {
+		policyKey: "query",
+		mutates: true,
+		hasIdContext: true
+	},
+	findOneAndUpdate: {
+		policyKey: "query",
+		mutates: true,
+		hasIdContext: false
+	},
+	delete: {
+		policyKey: "query",
+		mutates: true,
+		hasIdContext: true
+	},
+	restore: {
+		policyKey: "query",
+		mutates: true,
+		hasIdContext: true
+	},
+	createMany: {
+		policyKey: "dataArray",
+		mutates: true,
+		hasIdContext: false
+	},
+	updateMany: {
+		policyKey: "query",
+		mutates: true,
+		hasIdContext: false
+	},
+	deleteMany: {
+		policyKey: "query",
+		mutates: true,
+		hasIdContext: false
+	},
+	getById: {
+		policyKey: "query",
+		mutates: false,
+		hasIdContext: true
+	},
+	getByQuery: {
+		policyKey: "query",
+		mutates: false,
+		hasIdContext: false
+	},
+	getOne: {
+		policyKey: "query",
+		mutates: false,
+		hasIdContext: false
+	},
+	findAll: {
+		policyKey: "query",
+		mutates: false,
+		hasIdContext: false
+	},
+	getOrCreate: {
+		policyKey: "query",
+		mutates: false,
+		hasIdContext: false
+	},
+	count: {
+		policyKey: "query",
+		mutates: false,
+		hasIdContext: false
+	},
+	exists: {
+		policyKey: "query",
+		mutates: false,
+		hasIdContext: false
+	},
+	distinct: {
+		policyKey: "query",
+		mutates: false,
+		hasIdContext: false
+	},
+	getAll: {
+		policyKey: "filters",
+		mutates: false,
+		hasIdContext: false
+	}
+});
+/**
+* Merge additional operations into a base registry. Returns a frozen object.
+*
+* Kits call this at module load:
+* ```ts
+* export const MONGOKIT_OP_REGISTRY = extendRegistry(CORE_OP_REGISTRY, {
+*   aggregate: { policyKey: 'query', mutates: false, hasIdContext: false },
+*   aggregatePaginate: { policyKey: 'filters', mutates: false, hasIdContext: false },
+*   lookupPopulate: { policyKey: 'filters', mutates: false, hasIdContext: false },
+*   bulkWrite: { policyKey: 'operations', mutates: true, hasIdContext: false },
+* });
+* ```
+*
+* The return type preserves both the base union and the extension keys, so
+* plugins can still narrow on specific op names when they need to.
+*/
+function extendRegistry(base, extra) {
+	return Object.freeze({
+		...base,
+		...extra
+	});
+}
+/** All known operation names in the registry, in insertion order. */
+function listOperations(registry) {
+	return Object.keys(registry);
+}
+/** Operations that mutate the database — drives audit + cache invalidation. */
+function mutatingOperations(registry) {
+	return listOperations(registry).filter((op) => registry[op].mutates);
+}
+/** Operations that don't mutate — drives default cacheable-op lists. */
+function readOperations(registry) {
+	return listOperations(registry).filter((op) => !registry[op].mutates);
+}
+/** Filter ops by their policy-injection key. */
+function operationsByPolicyKey(registry, key) {
+	return listOperations(registry).filter((op) => registry[op].policyKey === key);
+}
+/**
+* Look up a descriptor. Returns `undefined` when the op isn't registered —
+* plugins should treat an unknown op as "ignore" rather than crash, so new
+* kits can introduce operations without every plugin needing an update.
+*/
+function describe(registry, op) {
+	return Object.hasOwn(registry, op) ? registry[op] : void 0;
+}
+//#endregion
+export { CORE_OP_REGISTRY, describe, extendRegistry, listOperations, mutatingOperations, operationsByPolicyKey, readOperations };

package/dist/operations/types.d.mts

@@ -0,0 +1,49 @@
+//#region src/operations/types.d.ts
+/**
+ * Operation-registry type definitions.
+ *
+ * These types are the driver-agnostic classification of every repository
+ * operation — where a plugin should inject its scoping filter (for
+ * multi-tenant, soft-delete, etc.), whether the operation mutates, and
+ * whether it carries a primary-key id on the context. Every driver kit
+ * (mongokit, pgkit, prismakit) ships a registry with the same shape so
+ * cross-driver plugins work identically.
+ */
+/** Operations declared by `@classytic/repo-core`. Kits extend this union. */
+type CoreRepositoryOperation = 'create' | 'update' | 'findOneAndUpdate' | 'delete' | 'restore' | 'createMany' | 'updateMany' | 'deleteMany' | 'getById' | 'getByQuery' | 'getOne' | 'findAll' | 'getOrCreate' | 'count' | 'exists' | 'distinct' | 'getAll';
+/**
+ * Open repository-operation name. Kits extend the core union with their
+ * own native operations (e.g. mongokit's `aggregate`, `bulkWrite`). Plugins
+ * that walk a registry use this string type so they don't need to know the
+ * full union.
+ */
+type RepositoryOperation = CoreRepositoryOperation | (string & {});
+/**
+ * Where a plugin should inject its scoping filter (multi-tenant scope,
+ * soft-delete filter, etc.) on the repository context.
+ *
+ * - `data`        — single-doc create payload (`context.data`)
+ * - `dataArray`   — multi-doc create payload (`context.dataArray`)
+ * - `query`       — raw filter (`context.query`); the dominant convention
+ * - `filters`     — paginated list options' filter sub-bag (`context.filters`)
+ * - `operations`  — bulk-write per-sub-op (plugins walk each entry)
+ * - `none`        — no scoping target (op accepts no filter input)
+ */
+type PolicyKey = 'data' | 'dataArray' | 'query' | 'filters' | 'operations' | 'none';
+/** Classification of a single repository operation. */
+interface OperationDescriptor {
+  /** Where multi-tenant / soft-delete plugins inject their scoping filter. */
+  readonly policyKey: PolicyKey;
+  /** Whether this op writes to the database. Drives audit + cache invalidation. */
+  readonly mutates: boolean;
+  /** True when `context.id` is populated by the time before/after hooks fire. */
+  readonly hasIdContext: boolean;
+}
+/**
+ * Registry shape. Indexed by operation name; values are operation descriptors.
+ * Kits compose their registry from `CORE_OP_REGISTRY` plus driver-specific
+ * additions (see `extendRegistry`).
+ */
+type OperationRegistry<Op extends string = RepositoryOperation> = Readonly<Record<Op, OperationDescriptor>>;
+//#endregion
+export { CoreRepositoryOperation, OperationDescriptor, OperationRegistry, PolicyKey, RepositoryOperation };

package/dist/pagination/cursor.d.mts

@@ -0,0 +1,44 @@
+import { DecodedCursor, SortSpec } from "./types.mjs";
+
+//#region src/pagination/cursor.d.ts
+/**
+ * Encode a document's sort values and id into a base64url cursor token.
+ *
+ * The encoder accepts arbitrary string type tags beyond the core set; a kit
+ * that wants to tag an id as `'objectid'` can stamp that in the payload and
+ * decode it back on its side. Repo-core doesn't narrow unknown tags; they
+ * round-trip as `string` values.
+ *
+ * @param doc           — document to extract cursor values from
+ * @param primaryField  — primary sort field name (non-_id preferred, `_id` fallback)
+ * @param sort          — normalized sort specification the cursor describes
+ * @param version       — cursor format version; bump on breaking format changes
+ * @param tagValue      — optional override for type tagging (kit extension point).
+ *                        When omitted, repo-core uses a minimal tagger that emits
+ *                        `date | boolean | number | string | null | unknown`.
+ */
+declare function encodeCursor(doc: Record<string, unknown>, primaryField: string, sort: SortSpec, version?: number, tagValue?: (value: unknown) => string): string;
+/**
+ * Decode a cursor token back into a structured payload.
+ *
+ * Accepts both URL-safe (`-`/`_`) and standard (`+`/`/`) base64 alphabets,
+ * so cursors emitted by mongokit ≤3.x (which used Node `Buffer` standard
+ * base64) remain decodable after a kit upgrade.
+ *
+ * Unknown type tags round-trip as strings — kits that need typed
+ * rehydration (`'objectid'` → `ObjectId` instance) can post-process the
+ * decoded cursor on their side.
+ */
+declare function decodeCursor(token: string): DecodedCursor;
+/** Throw when the cursor's sort doesn't match the current query sort. */
+declare function validateCursorSort(cursorSort: SortSpec, currentSort: SortSpec): void;
+/**
+ * Validate cursor version against the server's accepted range.
+ *
+ * - Cursors newer than `expectedVersion` → client is ahead of server; reject.
+ * - Cursors older than `minVersion` → client cached a cursor from a
+ *   pre-breaking-change deploy; reject so pagination restarts cleanly.
+ */
+declare function validateCursorVersion(cursorVersion: number, expectedVersion: number, minVersion?: number): void;
+//#endregion
+export { decodeCursor, encodeCursor, validateCursorSort, validateCursorVersion };

package/dist/pagination/cursor.mjs

@@ -0,0 +1,150 @@
+//#region src/pagination/cursor.ts
+/** Core value types repo-core knows how to round-trip natively. */
+const CORE_TYPES = [
+	"date",
+	"boolean",
+	"number",
+	"string",
+	"null",
+	"unknown"
+];
+/**
+* Encode a document's sort values and id into a base64url cursor token.
+*
+* The encoder accepts arbitrary string type tags beyond the core set; a kit
+* that wants to tag an id as `'objectid'` can stamp that in the payload and
+* decode it back on its side. Repo-core doesn't narrow unknown tags; they
+* round-trip as `string` values.
+*
+* @param doc           — document to extract cursor values from
+* @param primaryField  — primary sort field name (non-_id preferred, `_id` fallback)
+* @param sort          — normalized sort specification the cursor describes
+* @param version       — cursor format version; bump on breaking format changes
+* @param tagValue      — optional override for type tagging (kit extension point).
+*                        When omitted, repo-core uses a minimal tagger that emits
+*                        `date | boolean | number | string | null | unknown`.
+*/
+function encodeCursor(doc, primaryField, sort, version = 1, tagValue = defaultTagValue) {
+	const primaryValue = doc[primaryField];
+	const idValue = doc["_id"] ?? doc["id"];
+	const sortFields = Object.keys(sort).filter((k) => k !== "_id");
+	const vals = {};
+	const types = {};
+	for (const field of sortFields) {
+		vals[field] = serializeValue(doc[field]);
+		types[field] = tagValue(doc[field]);
+	}
+	const payload = {
+		v: serializeValue(primaryValue),
+		t: tagValue(primaryValue),
+		id: String(serializeValue(idValue) ?? ""),
+		idType: tagValue(idValue),
+		sort,
+		ver: version,
+		...sortFields.length > 1 && {
+			vals,
+			types
+		}
+	};
+	return base64urlEncode(JSON.stringify(payload));
+}
+/**
+* Decode a cursor token back into a structured payload.
+*
+* Accepts both URL-safe (`-`/`_`) and standard (`+`/`/`) base64 alphabets,
+* so cursors emitted by mongokit ≤3.x (which used Node `Buffer` standard
+* base64) remain decodable after a kit upgrade.
+*
+* Unknown type tags round-trip as strings — kits that need typed
+* rehydration (`'objectid'` → `ObjectId` instance) can post-process the
+* decoded cursor on their side.
+*/
+function decodeCursor(token) {
+	let json;
+	try {
+		json = base64urlDecode(token);
+	} catch {
+		throw new Error("Invalid cursor token: not valid base64");
+	}
+	let payload;
+	try {
+		payload = JSON.parse(json);
+	} catch {
+		throw new Error("Invalid cursor token: not valid JSON");
+	}
+	if (!isValidPayload(payload)) throw new Error("Invalid cursor token: malformed payload structure");
+	let values;
+	if (payload.vals && payload.types) {
+		values = {};
+		for (const [field, serialized] of Object.entries(payload.vals)) values[field] = rehydrateValue(serialized, payload.types[field] ?? "unknown");
+	}
+	return {
+		value: rehydrateValue(payload.v, payload.t),
+		id: rehydrateValue(payload.id, payload.idType),
+		sort: payload.sort,
+		version: payload.ver,
+		...values && { values }
+	};
+}
+/** Throw when the cursor's sort doesn't match the current query sort. */
+function validateCursorSort(cursorSort, currentSort) {
+	if (JSON.stringify(cursorSort) !== JSON.stringify(currentSort)) throw new Error("Cursor sort does not match current query sort");
+}
+/**
+* Validate cursor version against the server's accepted range.
+*
+* - Cursors newer than `expectedVersion` → client is ahead of server; reject.
+* - Cursors older than `minVersion` → client cached a cursor from a
+*   pre-breaking-change deploy; reject so pagination restarts cleanly.
+*/
+function validateCursorVersion(cursorVersion, expectedVersion, minVersion = 1) {
+	if (cursorVersion > expectedVersion) throw new Error(`Cursor version ${String(cursorVersion)} is newer than expected version ${String(expectedVersion)}. Please upgrade.`);
+	if (cursorVersion < minVersion) throw new Error(`Cursor version ${String(cursorVersion)} is older than minimum supported ${String(minVersion)}. Pagination must restart.`);
+}
+function isValidPayload(payload) {
+	if (!payload || typeof payload !== "object") return false;
+	const p = payload;
+	return "v" in p && typeof p["t"] === "string" && typeof p["id"] === "string" && typeof p["idType"] === "string" && typeof p["sort"] === "object" && p["sort"] !== null && typeof p["ver"] === "number";
+}
+function serializeValue(value) {
+	if (value === null || value === void 0) return null;
+	if (value instanceof Date) return value.toISOString();
+	if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
+	return String(value);
+}
+function defaultTagValue(value) {
+	if (value === null || value === void 0) return "null";
+	if (value instanceof Date) return "date";
+	if (typeof value === "boolean") return "boolean";
+	if (typeof value === "number") return "number";
+	if (typeof value === "string") return "string";
+	return "unknown";
+}
+function rehydrateValue(serialized, tag) {
+	if (tag === "null" || serialized === null) return null;
+	if (!CORE_TYPES.includes(tag)) return serialized;
+	switch (tag) {
+		case "date": return new Date(serialized);
+		case "boolean": return serialized === true || serialized === "true";
+		case "number": return Number(serialized);
+		case "string": return String(serialized);
+		default: return serialized;
+	}
+}
+function base64urlEncode(input) {
+	const bytes = new TextEncoder().encode(input);
+	let binary = "";
+	for (const b of bytes) binary += String.fromCharCode(b);
+	return globalThis.btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64urlDecode(token) {
+	const base64 = token.replace(/-/g, "+").replace(/_/g, "/");
+	const padLen = (4 - base64.length % 4) % 4;
+	const padded = base64 + "=".repeat(padLen);
+	const binary = globalThis.atob(padded);
+	const bytes = new Uint8Array(binary.length);
+	for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+	return new TextDecoder().decode(bytes);
+}
+//#endregion
+export { decodeCursor, encodeCursor, validateCursorSort, validateCursorVersion };

package/dist/pagination/index.d.mts

@@ -0,0 +1,5 @@
+import { CursorPayload, DecodedCursor, KeysetPaginationResult, KeysetPaginationResultCore, OffsetPaginationResult, OffsetPaginationResultCore, PaginationConfig, SortDirection, SortSpec, ValueType } from "./types.mjs";
+import { decodeCursor, encodeCursor, validateCursorSort, validateCursorVersion } from "./cursor.mjs";
+import { getPrimaryField, invertSort, normalizeSort, validateKeysetSort } from "./keyset.mjs";
+import { calculateSkip, calculateTotalPages, shouldWarnDeepPagination, validateLimit, validatePage } from "./offset.mjs";
+export { type CursorPayload, type DecodedCursor, type KeysetPaginationResult, type KeysetPaginationResultCore, type OffsetPaginationResult, type OffsetPaginationResultCore, type PaginationConfig, type SortDirection, type SortSpec, type ValueType, calculateSkip, calculateTotalPages, decodeCursor, encodeCursor, getPrimaryField, invertSort, normalizeSort, shouldWarnDeepPagination, validateCursorSort, validateCursorVersion, validateKeysetSort, validateLimit, validatePage };

package/dist/pagination/index.mjs

@@ -0,0 +1,4 @@
+import { decodeCursor, encodeCursor, validateCursorSort, validateCursorVersion } from "./cursor.mjs";
+import { getPrimaryField, invertSort, normalizeSort, validateKeysetSort } from "./keyset.mjs";
+import { calculateSkip, calculateTotalPages, shouldWarnDeepPagination, validateLimit, validatePage } from "./offset.mjs";
+export { calculateSkip, calculateTotalPages, decodeCursor, encodeCursor, getPrimaryField, invertSort, normalizeSort, shouldWarnDeepPagination, validateCursorSort, validateCursorVersion, validateKeysetSort, validateLimit, validatePage };

package/dist/pagination/keyset.d.mts

@@ -0,0 +1,25 @@
+import { SortSpec } from "./types.mjs";
+
+//#region src/pagination/keyset.d.ts
+/**
+ * Normalize a sort object so non-`_id` fields come first, `_id` last.
+ * Stable ordering is required for cursor comparability across requests.
+ */
+declare function normalizeSort(sort: SortSpec): SortSpec;
+/**
+ * Validate a sort spec for keyset pagination and return the normalized form.
+ *
+ * - Rejects empty sorts (keyset needs at least one field).
+ * - Rejects non-`±1` directions.
+ * - Rejects mixed directions across fields (keyset can't straddle directions).
+ * - Auto-adds `_id` as tie-breaker (matching the primary direction) when absent.
+ * - When `allowedPrimaryFields` is non-empty, rejects primary fields outside
+ *   the allowlist (protects against lossy null-boundary keyset).
+ */
+declare function validateKeysetSort(sort: SortSpec, allowedPrimaryFields?: readonly string[]): SortSpec;
+/** Invert every direction in a sort (ascending ↔ descending). */
+declare function invertSort(sort: SortSpec): SortSpec;
+/** Primary (first non-`_id`) sort field; falls back to `_id`. */
+declare function getPrimaryField(sort: SortSpec): string;
+//#endregion
+export { getPrimaryField, invertSort, normalizeSort, validateKeysetSort };