xantiagoma 0.1.2 → 0.2.1

package/README.md

@@ -22,19 +22,27 @@
 npm install xantiagoma
 ```
 
+Release process notes live in [docs/RELEASING.md](./docs/RELEASING.md).
+
 ## Entry Points
 
-| Import                  | Description                            | Dependencies                     |
-| ----------------------- | -------------------------------------- | -------------------------------- |
-| `xantiagoma`            | Core utilities (isomorphic, zero deps) | none                             |
-| `xantiagoma/web`        | Browser/FormData utilities             | none                             |
-| `xantiagoma/ulid`       | Prefixed ULID generation + helpers     | `ulid`                           |
-| `xantiagoma/temporal`   | Date/time/duration with Temporal API   | `temporal-polyfill`, `itty-time` |
-| `xantiagoma/dataloader` | DataLoader factory                     | `dataloader`                     |
-| `xantiagoma/unstorage`  | Cache helpers with unstorage           | `unstorage`, `ohash`             |
-| `xantiagoma/valibot`    | TimeZone validation schema             | `valibot`                        |
-| `xantiagoma/sonner`     | Toast streaming for iterables          | `sonner`, `react`                |
-| `xantiagoma/react`      | React hooks + components               | `react`, `@tanstack/react-query` |
+| Import                          | Description                            | Dependencies                     |
+| ------------------------------- | -------------------------------------- | -------------------------------- |
+| `xantiagoma`                    | Core utilities (isomorphic, zero deps) | none                             |
+| `xantiagoma/pagination`         | Pagination + keyset helpers            | none                             |
+| `xantiagoma/pagination/drizzle` | Drizzle adapter for pagination keysets | `drizzle-orm`                    |
+| `xantiagoma/pagination/kysely`  | Kysely adapter for pagination keysets  | `kysely`                         |
+| `xantiagoma/pagination/knex`    | Knex adapter for pagination keysets    | none                             |
+| `xantiagoma/pagination/mongo`   | Mongo/Mongoose adapter for keysets     | none                             |
+| `xantiagoma/pagination/prisma`  | Prisma adapter for pagination keysets  | none                             |
+| `xantiagoma/web`                | Browser/FormData utilities             | none                             |
+| `xantiagoma/ulid`               | Prefixed ULID generation + helpers     | `ulid`                           |
+| `xantiagoma/temporal`           | Date/time/duration with Temporal API   | `temporal-polyfill`, `itty-time` |
+| `xantiagoma/dataloader`         | DataLoader factory                     | `dataloader`                     |
+| `xantiagoma/unstorage`          | Cache helpers with unstorage           | `unstorage`, `ohash`             |
+| `xantiagoma/valibot`            | TimeZone validation schema             | `valibot`                        |
+| `xantiagoma/sonner`             | Toast streaming for iterables          | `sonner`, `react`                |
+| `xantiagoma/react`              | React hooks + components               | `react`, `@tanstack/react-query` |
 
 Sub-entry dependencies are **optional peer deps** — only install what you use.
 
@@ -42,12 +50,13 @@ Sub-entry dependencies are **optional peer deps** — only install what you use.
 
 ### Error Handling
 
-| Export                      | Description                            | Source                          | Tests                                   |
-| --------------------------- | -------------------------------------- | ------------------------------- | --------------------------------------- |
-| `tryCatch` / `tryCatchSync` | `[data, error]` tuples — no try/catch  | [src](./src/try-catch.ts)       | [tests](./test/try-catch.test.ts)       |
-| `assertNotNull`             | Throws if null/undefined, narrows type | [src](./src/assert-not-null.ts) | [tests](./test/assert-not-null.test.ts) |
-| `valueOrThrow`              | Returns value or throws                | [src](./src/error.ts)           | [tests](./test/error.test.ts)           |
-| `AssertError`               | Custom error class                     | [src](./src/errors.ts)          | [tests](./test/errors.test.ts)          |
+| Export                      | Description                                  | Source                          | Tests                                   |
+| --------------------------- | -------------------------------------------- | ------------------------------- | --------------------------------------- |
+| `tryCatch`                  | `[data, error]` tuples — sync/async adaptive | [src](./src/try-catch.ts)       | [tests](./test/try-catch.test.ts)       |
+| `tryCatchSync` (deprecated) | Use `tryCatch` — kept for backwards compat   | [src](./src/try-catch.ts)       | [tests](./test/try-catch.test.ts)       |
+| `assertNotNull`             | Throws if null/undefined, narrows type       | [src](./src/assert-not-null.ts) | [tests](./test/assert-not-null.test.ts) |
+| `valueOrThrow`              | Returns value or throws                      | [src](./src/error.ts)           | [tests](./test/error.test.ts)           |
+| `AssertError`               | Custom error class                           | [src](./src/errors.ts)          | [tests](./test/errors.test.ts)          |
 
 ### Async
 
@@ -55,19 +64,20 @@ Sub-entry dependencies are **optional peer deps** — only install what you use.
 | --------------------- | ---------------------------------------- | ------------------------------------- | --------------------------------------------- |
 | `wait`                | Typed setTimeout delay                   | [src](./src/wait.ts)                  | [tests](./test/wait.test.ts)                  |
 | `Completer`           | Externally resolvable Promise            | [src](./src/completer.ts)             | [tests](./test/completer.test.ts)             |
-| `collect`             | Drain `AsyncIterable<T>` into `T[]`      | [src](./src/collect.ts)               | [tests](./test/collect.test.ts)               |
+| `collect`             | Drain any iterable into `T[]` (adaptive) | [src](./src/collect.ts)               | [tests](./test/collect.test.ts)               |
 | `asyncOf`             | Create `AsyncGenerator` from values      | [src](./src/async-of.ts)              | [tests](./test/async-of.test.ts)              |
 | `AsyncChannel`        | Push-based `AsyncIterable` with modes    | [src](./src/async-channel.ts)         | [tests](./test/async-channel.test.ts)         |
 | `resolveMaybePromise` | Resolve `T \| Promise<T>` → `Promise<T>` | [src](./src/resolve-maybe-promise.ts) | [tests](./test/resolve-maybe-promise.test.ts) |
 
 ### Iterables & Generators
 
-| Export                         | Description                       | Source                            | Tests                                     |
-| ------------------------------ | --------------------------------- | --------------------------------- | ----------------------------------------- |
-| `range` / `rangeLazy`          | Numeric range (array / generator) | [src](./src/range.ts)             | [tests](./test/range.test.ts)             |
-| `enumerate` / `enumerateAsync` | `[index, value]` tuples           | [src](./src/enumerate.ts)         | [tests](./test/enumerate.test.ts)         |
-| `toIterator`                   | Normalize to `Iterator`           | [src](./src/to-iterator.ts)       | [tests](./test/to-iterator.test.ts)       |
-| `toAsyncIterable`              | Normalize to `AsyncGenerator`     | [src](./src/to-async-iterable.ts) | [tests](./test/to-async-iterable.test.ts) |
+| Export                | Description                                         | Source                            | Tests                                     |
+| --------------------- | --------------------------------------------------- | --------------------------------- | ----------------------------------------- |
+| `range` / `rangeLazy` | Numeric range (array / generator)                   | [src](./src/range.ts)             | [tests](./test/range.test.ts)             |
+| `enumerate`           | `[index, value]` tuples — sync/async adaptive       | [src](./src/enumerate.ts)         | [tests](./test/enumerate.test.ts)         |
+| `enumerateAsync`      | Always-async; awaits Promise values in sync sources | [src](./src/enumerate.ts)         | [tests](./test/enumerate.test.ts)         |
+| `toIterator`          | Normalize to `Iterator`                             | [src](./src/to-iterator.ts)       | [tests](./test/to-iterator.test.ts)       |
+| `toAsyncIterable`     | Normalize to `AsyncGenerator`                       | [src](./src/to-async-iterable.ts) | [tests](./test/to-async-iterable.test.ts) |
 
 ### Type Guards
 
@@ -104,6 +114,58 @@ Sub-entry dependencies are **optional peer deps** — only install what you use.
 | `resolveStreamSource`                       | Resolve `StreamSource<T>`               | [src](./src/stream-source.ts)         | [tests](./test/stream-source.test.ts)         |
 | `secondsToMs` / `minutesToMs` / `hoursToMs` | Time unit converters                    | [src](./src/time-convert.ts)          | [tests](./test/time-convert.test.ts)          |
 
+## Pagination Utilities (`xantiagoma/pagination`)
+
+Source-agnostic pagination: import from `xantiagoma/pagination`, provide fetchers for your data source (SQL, Drizzle, Prisma, Mongoose, HTTP...), and the paginator handles input styles (`page`/`pageSize`, `limit`/`offset`, cursor), `hasNextPage` lookahead, backward (scroll-up) pagination, and a uniform result envelope. **Full guide: [docs/PAGINATION.md](./docs/PAGINATION.md)** — backend recipes for SQL drivers, ORMs/query builders, Mongo, Firestore, DynamoDB, Redis sorted sets, Elasticsearch/OpenSearch, analytics warehouses, HTTP APIs, REST/GraphQL endpoints, cursor codecs, and frontend integration.
+
+Sync/async adaptive: pass all-sync fetchers and codec (e.g. an in-memory array) and `paginate()` returns plain values — no `await` needed; any async piece (even just an async cursor encoder) makes results Promises, reflected in the types. The pattern is documented in [docs/sync-async-adaptive.md](./docs/sync-async-adaptive.md).
+
+| Import                          | Export                      | Description                                                                | Source                             | Tests                                      |
+| ------------------------------- | --------------------------- | -------------------------------------------------------------------------- | ---------------------------------- | ------------------------------------------ |
+| `xantiagoma/pagination`         | `createPaginator`           | Paginator over user-provided fetchers; `pages()`/`items()` async iteration | [src](./src/pagination.ts)         | [tests](./test/pagination.test.ts)         |
+| `xantiagoma/pagination`         | `toOffsetWindow`            | Page/offset input → `{ limit, offset }`                                    | [src](./src/pagination.ts)         | [tests](./test/pagination.test.ts)         |
+| `xantiagoma/pagination`         | `createCursorCodec`         | Pluggable opaque-cursor codec (JSON + base64url)                           | [src](./src/cursor-codec.ts)       | [tests](./test/cursor-codec.test.ts)       |
+| `xantiagoma/pagination`         | `createKeysetSpec`          | Portable keyset `where()`/`orderBy()` AST                                  | [src](./src/keyset.ts)             | [tests](./test/keyset.test.ts)             |
+| `xantiagoma/pagination`         | `keysetSqlExpression`       | Mark server-owned computed SQL expressions for raw keyset helpers          | [src](./src/keyset.ts)             | [tests](./test/keyset.test.ts)             |
+| `xantiagoma/pagination`         | `toKeysetWhereSql`          | Keyset `WHERE` → parameterized SQL + params                                | [src](./src/keyset.ts)             | [tests](./test/keyset.test.ts)             |
+| `xantiagoma/pagination`         | `toKeysetOrderBySql`        | Keyset order → SQL `ORDER BY` fragment                                     | [src](./src/keyset.ts)             | [tests](./test/keyset.test.ts)             |
+| `xantiagoma/pagination/drizzle` | `toDrizzleKeyset`           | Keyset AST → Drizzle `where`/`orderBy` helpers                             | [src](./src/pagination-drizzle.ts) | [tests](./test/pagination-drizzle.test.ts) |
+| `xantiagoma/pagination/kysely`  | `toKyselyKeyset`            | Keyset AST → Kysely `where`/`orderBy` helpers                              | [src](./src/pagination-kysely.ts)  | [tests](./test/pagination-kysely.test.ts)  |
+| `xantiagoma/pagination/knex`    | `applyKeysetToKnex`         | Apply keyset AST to Knex `whereRaw`/`orderByRaw`                           | [src](./src/pagination-knex.ts)    | [tests](./test/pagination-knex.test.ts)    |
+| `xantiagoma/pagination/mongo`   | `toMongoKeyset`             | Keyset AST → Mongo/Mongoose `filter`/`sort` objects                        | [src](./src/pagination-mongo.ts)   | [tests](./test/pagination-mongo.test.ts)   |
+| `xantiagoma/pagination/prisma`  | `toPrismaKeyset`            | Keyset AST → Prisma `where`/`orderBy` objects                              | [src](./src/pagination-prisma.ts)  | [tests](./test/pagination-prisma.test.ts)  |
+| `xantiagoma/pagination`         | `parsePaginationParams`     | Query params → `PaginationInput` (with clamping)                           | [src](./src/pagination-params.ts)  | [tests](./test/pagination-params.test.ts)  |
+| `xantiagoma/pagination`         | `fromRelayArgs`             | Relay `first`/`after`/`last`/`before` → input                              | [src](./src/pagination-params.ts)  | [tests](./test/pagination-params.test.ts)  |
+| `xantiagoma/pagination`         | `toRelayConnection`         | Result → Relay connection (`edges`, `pageInfo`)                            | [src](./src/pagination-output.ts)  | [tests](./test/pagination-output.test.ts)  |
+| `xantiagoma/pagination`         | `toRestEnvelope`            | Result → `{ data, meta }` REST envelope                                    | [src](./src/pagination-output.ts)  | [tests](./test/pagination-output.test.ts)  |
+| `xantiagoma/pagination`         | `infinitePaginationOptions` | TanStack `useInfiniteQuery` config (dep-free)                              | [src](./src/pagination-output.ts)  | [tests](./test/pagination-output.test.ts)  |
+
+```ts
+import {
+  createPaginator,
+  fromRelayArgs,
+  parsePaginationParams,
+  toRestEnvelope,
+} from "xantiagoma/pagination";
+
+const paginator = createPaginator({
+  fetchOffset: ({ limit, offset }) => ({ items: db.query(/* LIMIT/OFFSET */) }),
+  fetchCursor: ({ limit, cursor, direction }) => ({ items: db.query(/* keyset */) }),
+  cursor: { fromItem: (u) => ({ id: u.id }) }, // codec optional — defaults to JSON + base64url
+  maxLimit: 100,
+});
+
+// REST route
+const result = await paginator.paginate(parsePaginationParams(url.searchParams));
+return Response.json(toRestEnvelope(result));
+
+// GraphQL/Relay resolver
+const result = await paginator.paginate(fromRelayArgs(args));
+return toRelayConnection(result, paginator.cursorFor);
+```
+
+Cursor tokens are produced by a two-stage codec (`serializer` + `encoder`, both replaceable) signature-compatible with [drizzle-cursor](https://github.com/xantiagoma/drizzle-cursor), so the same custom encoder/decoder (encryption, signing...) can be shared between both.
+
 ## Web Utilities (`xantiagoma/web`)
 
 | Export                  | Description                         | Source                                    | Tests                                       |
@@ -112,6 +174,37 @@ Sub-entry dependencies are **optional peer deps** — only install what you use.
 | `fetchWithProgress`     | Fetch with upload/download progress | [src](./src/fetch-with-progress.ts)       | [tests](./test/fetch-with-progress.test.ts) |
 | `createHttpInterceptor` | Intercept fetch + XHR with rules    | [src](./src/intercept-http.ts)            | [tests](./test/intercept-http.test.tsx)     |
 
+## Sonner Utilities (`xantiagoma/sonner`)
+
+Toast helpers for streaming iterables/generators through [Sonner](https://sonner.emilkowal.ski/).
+
+| Export             | Description                                                             | Source                       | Tests                                |
+| ------------------ | ----------------------------------------------------------------------- | ---------------------------- | ------------------------------------ |
+| `toastStream`      | Blocking/awaitable stream toast; resolves to `{ items, returnValue }`   | [src](./src/toast-stream.ts) | [tests](./test/toast-stream.test.ts) |
+| `toastStreamAsync` | Non-blocking stream toast; returns toast id immediately with `unwrap()` | [src](./src/toast-stream.ts) | [tests](./test/toast-stream.test.ts) |
+
+Use `toastStream` when the caller should wait for completion:
+
+```ts
+import { toastStream } from "xantiagoma/sonner";
+
+const { items, returnValue } = await toastStream(source, {
+  loading: "Loading...",
+  streaming: ({ count }) => `Received ${count}`,
+  success: ({ count }) => `Done: ${count} items`,
+});
+```
+
+Use `toastStreamAsync` when the caller should continue immediately, matching
+Sonner's `toast.promise(...).unwrap()` style:
+
+```ts
+import { toastStreamAsync } from "xantiagoma/sonner";
+
+const toastId = toastStreamAsync(source, { loading: "Loading..." });
+const { items, returnValue } = await toastId.unwrap();
+```
+
 ## React Utilities (`xantiagoma/react`)
 
 | Export                         | Description                         | Source                                 | Tests                                           |

package/dist/entry-pagination-drizzle.cjs

@@ -0,0 +1,61 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("./chunk-CKQMccvm.cjs");
+let drizzle_orm = require("drizzle-orm");
+//#region src/pagination-drizzle.ts
+const resolveColumn = (columns, key) => {
+	const col = columns[key];
+	if (col === void 0) throw new Error(`toDrizzleKeyset: missing column mapping for key "${key}"`);
+	return col;
+};
+/**
+* Create a Drizzle adapter for portable keyset predicates and ordering.
+*
+* The mapping values can be Drizzle columns or SQL expressions. Keys are the
+* logical cursor keys used by `createKeysetSpec`; they do not need to match
+* database column names.
+*
+* @example
+* ```ts
+* import { toDrizzleKeyset } from "xantiagoma/pagination/drizzle";
+*
+* const drizzleKeyset = toDrizzleKeyset({
+*   createdAt: posts.createdAt,
+*   id: posts.id,
+* });
+*
+* await db
+*   .select()
+*   .from(posts)
+*   .where(drizzleKeyset.where(keyset.where(cursor, direction)))
+*   .orderBy(...drizzleKeyset.orderBy(keyset.orderBy(direction)))
+*   .limit(limit);
+* ```
+*/
+function toDrizzleKeyset(columns) {
+	const where = (keysetWhere) => {
+		if (keysetWhere == null) return;
+		return (0, drizzle_orm.or)(...keysetWhere.or.flatMap((branch) => {
+			const combined = (0, drizzle_orm.and)(...branch.and.map((pred) => {
+				const col = resolveColumn(columns, pred.key);
+				switch (pred.op) {
+					case "eq": return (0, drizzle_orm.eq)(col, pred.value);
+					case "gt": return (0, drizzle_orm.gt)(col, pred.value);
+					case "lt": return (0, drizzle_orm.lt)(col, pred.value);
+				}
+			}));
+			return combined === void 0 ? [] : [combined];
+		}));
+	};
+	const orderBy = (order) => order.map((col) => {
+		const target = resolveColumn(columns, col.key);
+		return col.order === "asc" ? (0, drizzle_orm.asc)(target) : (0, drizzle_orm.desc)(target);
+	});
+	return {
+		where,
+		orderBy
+	};
+}
+//#endregion
+exports.toDrizzleKeyset = toDrizzleKeyset;
+
+//# sourceMappingURL=entry-pagination-drizzle.cjs.map

package/dist/entry-pagination-drizzle.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry-pagination-drizzle.cjs","names":[],"sources":["../src/pagination-drizzle.ts"],"sourcesContent":["import { and, asc, desc, eq, gt, lt, or, type SQL } from \"drizzle-orm\";\nimport type { KeysetSortKey, KeysetWhere } from \"./keyset.ts\";\n\nexport type DrizzleKeysetTarget = Parameters<typeof asc>[0];\n\nexport type DrizzleKeysetColumns = Record<string, DrizzleKeysetTarget>;\n\nexport type DrizzleKeyset = {\n  /** Render a portable keyset where AST to Drizzle SQL. `null` means first page. */\n  where(where: KeysetWhere | null): SQL | undefined;\n  /** Render portable keyset order keys to Drizzle `orderBy(...values)`. */\n  orderBy(order: KeysetSortKey[]): SQL[];\n};\n\nconst resolveColumn = (columns: DrizzleKeysetColumns, key: string): DrizzleKeysetTarget => {\n  const col = columns[key];\n  if (col === undefined) {\n    throw new Error(`toDrizzleKeyset: missing column mapping for key \"${key}\"`);\n  }\n  return col;\n};\n\n/**\n * Create a Drizzle adapter for portable keyset predicates and ordering.\n *\n * The mapping values can be Drizzle columns or SQL expressions. Keys are the\n * logical cursor keys used by `createKeysetSpec`; they do not need to match\n * database column names.\n *\n * @example\n * ```ts\n * import { toDrizzleKeyset } from \"xantiagoma/pagination/drizzle\";\n *\n * const drizzleKeyset = toDrizzleKeyset({\n *   createdAt: posts.createdAt,\n *   id: posts.id,\n * });\n *\n * await db\n *   .select()\n *   .from(posts)\n *   .where(drizzleKeyset.where(keyset.where(cursor, direction)))\n *   .orderBy(...drizzleKeyset.orderBy(keyset.orderBy(direction)))\n *   .limit(limit);\n * ```\n */\nexport function toDrizzleKeyset(columns: DrizzleKeysetColumns): DrizzleKeyset {\n  const where = (keysetWhere: KeysetWhere | null): SQL | undefined => {\n    if (keysetWhere == null) {\n      return undefined;\n    }\n\n    const branches = keysetWhere.or.flatMap((branch) => {\n      const predicates = branch.and.map((pred) => {\n        const col = resolveColumn(columns, pred.key);\n        switch (pred.op) {\n          case \"eq\":\n            return eq(col, pred.value);\n          case \"gt\":\n            return gt(col, pred.value);\n          case \"lt\":\n            return lt(col, pred.value);\n        }\n      });\n      const combined = and(...predicates);\n      return combined === undefined ? [] : [combined];\n    });\n\n    return or(...branches);\n  };\n\n  const orderBy = (order: KeysetSortKey[]): SQL[] =>\n    order.map((col) => {\n      const target = resolveColumn(columns, col.key);\n      return col.order === \"asc\" ? asc(target) : desc(target);\n    });\n\n  return { where, orderBy };\n}\n"],"mappings":";;;;AAcA,MAAM,iBAAiB,SAA+B,QAAqC;CACzF,MAAM,MAAM,QAAQ;CACpB,IAAI,QAAQ,KAAA,GACV,MAAM,IAAI,MAAM,oDAAoD,IAAI,GAAG;CAE7E,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BT,SAAgB,gBAAgB,SAA8C;CAC5E,MAAM,SAAS,gBAAqD;EAClE,IAAI,eAAe,MACjB;EAmBF,QAAA,GAAA,YAAA,IAAU,GAhBO,YAAY,GAAG,SAAS,WAAW;GAYlD,MAAM,YAAA,GAAA,YAAA,KAAe,GAXF,OAAO,IAAI,KAAK,SAAS;IAC1C,MAAM,MAAM,cAAc,SAAS,KAAK,IAAI;IAC5C,QAAQ,KAAK,IAAb;KACE,KAAK,MACH,QAAA,GAAA,YAAA,IAAU,KAAK,KAAK,MAAM;KAC5B,KAAK,MACH,QAAA,GAAA,YAAA,IAAU,KAAK,KAAK,MAAM;KAC5B,KAAK,MACH,QAAA,GAAA,YAAA,IAAU,KAAK,KAAK,MAAM;;KAGE,CAAC;GACnC,OAAO,aAAa,KAAA,IAAY,EAAE,GAAG,CAAC,SAAS;IAG5B,CAAC;;CAGxB,MAAM,WAAW,UACf,MAAM,KAAK,QAAQ;EACjB,MAAM,SAAS,cAAc,SAAS,IAAI,IAAI;EAC9C,OAAO,IAAI,UAAU,SAAA,GAAA,YAAA,KAAY,OAAO,IAAA,GAAA,YAAA,MAAQ,OAAO;GACvD;CAEJ,OAAO;EAAE;EAAO;EAAS"}

package/dist/entry-pagination-drizzle.d.cts

@@ -0,0 +1,38 @@
+import { d as KeysetWhere, o as KeysetSortKey } from "./keyset-DqmiNJog.cjs";
+import { SQL, asc } from "drizzle-orm";
+
+//#region src/pagination-drizzle.d.ts
+type DrizzleKeysetTarget = Parameters<typeof asc>[0];
+type DrizzleKeysetColumns = Record<string, DrizzleKeysetTarget>;
+type DrizzleKeyset = {
+  /** Render a portable keyset where AST to Drizzle SQL. `null` means first page. */where(where: KeysetWhere | null): SQL | undefined; /** Render portable keyset order keys to Drizzle `orderBy(...values)`. */
+  orderBy(order: KeysetSortKey[]): SQL[];
+};
+/**
+ * Create a Drizzle adapter for portable keyset predicates and ordering.
+ *
+ * The mapping values can be Drizzle columns or SQL expressions. Keys are the
+ * logical cursor keys used by `createKeysetSpec`; they do not need to match
+ * database column names.
+ *
+ * @example
+ * ```ts
+ * import { toDrizzleKeyset } from "xantiagoma/pagination/drizzle";
+ *
+ * const drizzleKeyset = toDrizzleKeyset({
+ *   createdAt: posts.createdAt,
+ *   id: posts.id,
+ * });
+ *
+ * await db
+ *   .select()
+ *   .from(posts)
+ *   .where(drizzleKeyset.where(keyset.where(cursor, direction)))
+ *   .orderBy(...drizzleKeyset.orderBy(keyset.orderBy(direction)))
+ *   .limit(limit);
+ * ```
+ */
+declare function toDrizzleKeyset(columns: DrizzleKeysetColumns): DrizzleKeyset;
+//#endregion
+export { type DrizzleKeyset, type DrizzleKeysetColumns, type DrizzleKeysetTarget, toDrizzleKeyset };
+//# sourceMappingURL=entry-pagination-drizzle.d.cts.map

package/dist/entry-pagination-drizzle.d.mts

@@ -0,0 +1,38 @@
+import { d as KeysetWhere, o as KeysetSortKey } from "./keyset-Cd8leiME.mjs";
+import { SQL, asc } from "drizzle-orm";
+
+//#region src/pagination-drizzle.d.ts
+type DrizzleKeysetTarget = Parameters<typeof asc>[0];
+type DrizzleKeysetColumns = Record<string, DrizzleKeysetTarget>;
+type DrizzleKeyset = {
+  /** Render a portable keyset where AST to Drizzle SQL. `null` means first page. */where(where: KeysetWhere | null): SQL | undefined; /** Render portable keyset order keys to Drizzle `orderBy(...values)`. */
+  orderBy(order: KeysetSortKey[]): SQL[];
+};
+/**
+ * Create a Drizzle adapter for portable keyset predicates and ordering.
+ *
+ * The mapping values can be Drizzle columns or SQL expressions. Keys are the
+ * logical cursor keys used by `createKeysetSpec`; they do not need to match
+ * database column names.
+ *
+ * @example
+ * ```ts
+ * import { toDrizzleKeyset } from "xantiagoma/pagination/drizzle";
+ *
+ * const drizzleKeyset = toDrizzleKeyset({
+ *   createdAt: posts.createdAt,
+ *   id: posts.id,
+ * });
+ *
+ * await db
+ *   .select()
+ *   .from(posts)
+ *   .where(drizzleKeyset.where(keyset.where(cursor, direction)))
+ *   .orderBy(...drizzleKeyset.orderBy(keyset.orderBy(direction)))
+ *   .limit(limit);
+ * ```
+ */
+declare function toDrizzleKeyset(columns: DrizzleKeysetColumns): DrizzleKeyset;
+//#endregion
+export { type DrizzleKeyset, type DrizzleKeysetColumns, type DrizzleKeysetTarget, toDrizzleKeyset };
+//# sourceMappingURL=entry-pagination-drizzle.d.mts.map

package/dist/entry-pagination-drizzle.mjs

@@ -0,0 +1,59 @@
+import { and, asc, desc, eq, gt, lt, or } from "drizzle-orm";
+//#region src/pagination-drizzle.ts
+const resolveColumn = (columns, key) => {
+	const col = columns[key];
+	if (col === void 0) throw new Error(`toDrizzleKeyset: missing column mapping for key "${key}"`);
+	return col;
+};
+/**
+* Create a Drizzle adapter for portable keyset predicates and ordering.
+*
+* The mapping values can be Drizzle columns or SQL expressions. Keys are the
+* logical cursor keys used by `createKeysetSpec`; they do not need to match
+* database column names.
+*
+* @example
+* ```ts
+* import { toDrizzleKeyset } from "xantiagoma/pagination/drizzle";
+*
+* const drizzleKeyset = toDrizzleKeyset({
+*   createdAt: posts.createdAt,
+*   id: posts.id,
+* });
+*
+* await db
+*   .select()
+*   .from(posts)
+*   .where(drizzleKeyset.where(keyset.where(cursor, direction)))
+*   .orderBy(...drizzleKeyset.orderBy(keyset.orderBy(direction)))
+*   .limit(limit);
+* ```
+*/
+function toDrizzleKeyset(columns) {
+	const where = (keysetWhere) => {
+		if (keysetWhere == null) return;
+		return or(...keysetWhere.or.flatMap((branch) => {
+			const combined = and(...branch.and.map((pred) => {
+				const col = resolveColumn(columns, pred.key);
+				switch (pred.op) {
+					case "eq": return eq(col, pred.value);
+					case "gt": return gt(col, pred.value);
+					case "lt": return lt(col, pred.value);
+				}
+			}));
+			return combined === void 0 ? [] : [combined];
+		}));
+	};
+	const orderBy = (order) => order.map((col) => {
+		const target = resolveColumn(columns, col.key);
+		return col.order === "asc" ? asc(target) : desc(target);
+	});
+	return {
+		where,
+		orderBy
+	};
+}
+//#endregion
+export { toDrizzleKeyset };
+
+//# sourceMappingURL=entry-pagination-drizzle.mjs.map

package/dist/entry-pagination-drizzle.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry-pagination-drizzle.mjs","names":[],"sources":["../src/pagination-drizzle.ts"],"sourcesContent":["import { and, asc, desc, eq, gt, lt, or, type SQL } from \"drizzle-orm\";\nimport type { KeysetSortKey, KeysetWhere } from \"./keyset.ts\";\n\nexport type DrizzleKeysetTarget = Parameters<typeof asc>[0];\n\nexport type DrizzleKeysetColumns = Record<string, DrizzleKeysetTarget>;\n\nexport type DrizzleKeyset = {\n  /** Render a portable keyset where AST to Drizzle SQL. `null` means first page. */\n  where(where: KeysetWhere | null): SQL | undefined;\n  /** Render portable keyset order keys to Drizzle `orderBy(...values)`. */\n  orderBy(order: KeysetSortKey[]): SQL[];\n};\n\nconst resolveColumn = (columns: DrizzleKeysetColumns, key: string): DrizzleKeysetTarget => {\n  const col = columns[key];\n  if (col === undefined) {\n    throw new Error(`toDrizzleKeyset: missing column mapping for key \"${key}\"`);\n  }\n  return col;\n};\n\n/**\n * Create a Drizzle adapter for portable keyset predicates and ordering.\n *\n * The mapping values can be Drizzle columns or SQL expressions. Keys are the\n * logical cursor keys used by `createKeysetSpec`; they do not need to match\n * database column names.\n *\n * @example\n * ```ts\n * import { toDrizzleKeyset } from \"xantiagoma/pagination/drizzle\";\n *\n * const drizzleKeyset = toDrizzleKeyset({\n *   createdAt: posts.createdAt,\n *   id: posts.id,\n * });\n *\n * await db\n *   .select()\n *   .from(posts)\n *   .where(drizzleKeyset.where(keyset.where(cursor, direction)))\n *   .orderBy(...drizzleKeyset.orderBy(keyset.orderBy(direction)))\n *   .limit(limit);\n * ```\n */\nexport function toDrizzleKeyset(columns: DrizzleKeysetColumns): DrizzleKeyset {\n  const where = (keysetWhere: KeysetWhere | null): SQL | undefined => {\n    if (keysetWhere == null) {\n      return undefined;\n    }\n\n    const branches = keysetWhere.or.flatMap((branch) => {\n      const predicates = branch.and.map((pred) => {\n        const col = resolveColumn(columns, pred.key);\n        switch (pred.op) {\n          case \"eq\":\n            return eq(col, pred.value);\n          case \"gt\":\n            return gt(col, pred.value);\n          case \"lt\":\n            return lt(col, pred.value);\n        }\n      });\n      const combined = and(...predicates);\n      return combined === undefined ? [] : [combined];\n    });\n\n    return or(...branches);\n  };\n\n  const orderBy = (order: KeysetSortKey[]): SQL[] =>\n    order.map((col) => {\n      const target = resolveColumn(columns, col.key);\n      return col.order === \"asc\" ? asc(target) : desc(target);\n    });\n\n  return { where, orderBy };\n}\n"],"mappings":";;AAcA,MAAM,iBAAiB,SAA+B,QAAqC;CACzF,MAAM,MAAM,QAAQ;CACpB,IAAI,QAAQ,KAAA,GACV,MAAM,IAAI,MAAM,oDAAoD,IAAI,GAAG;CAE7E,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BT,SAAgB,gBAAgB,SAA8C;CAC5E,MAAM,SAAS,gBAAqD;EAClE,IAAI,eAAe,MACjB;EAmBF,OAAO,GAAG,GAhBO,YAAY,GAAG,SAAS,WAAW;GAYlD,MAAM,WAAW,IAAI,GAXF,OAAO,IAAI,KAAK,SAAS;IAC1C,MAAM,MAAM,cAAc,SAAS,KAAK,IAAI;IAC5C,QAAQ,KAAK,IAAb;KACE,KAAK,MACH,OAAO,GAAG,KAAK,KAAK,MAAM;KAC5B,KAAK,MACH,OAAO,GAAG,KAAK,KAAK,MAAM;KAC5B,KAAK,MACH,OAAO,GAAG,KAAK,KAAK,MAAM;;KAGE,CAAC;GACnC,OAAO,aAAa,KAAA,IAAY,EAAE,GAAG,CAAC,SAAS;IAG5B,CAAC;;CAGxB,MAAM,WAAW,UACf,MAAM,KAAK,QAAQ;EACjB,MAAM,SAAS,cAAc,SAAS,IAAI,IAAI;EAC9C,OAAO,IAAI,UAAU,QAAQ,IAAI,OAAO,GAAG,KAAK,OAAO;GACvD;CAEJ,OAAO;EAAE;EAAO;EAAS"}

package/dist/entry-pagination-knex.cjs

@@ -0,0 +1,50 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_keyset = require("./keyset-BiguUVI7.cjs");
+//#region src/pagination-knex.ts
+/**
+* Apply a portable keyset `WHERE` + `ORDER BY` to a Knex query builder.
+* Values are passed as bindings; column identifiers are validated by the raw
+* SQL helpers before being rendered.
+*
+* This mutates and returns the provided Knex query builder, matching Knex's
+* chaining style. For first-page cursor requests (`where === null`), it skips
+* `whereRaw` and only applies `orderByRaw`.
+*
+* @example
+* ```ts
+* import { createKeysetSpec } from "xantiagoma/pagination";
+* import { applyKeysetToKnex } from "xantiagoma/pagination/knex";
+*
+* const keyset = createKeysetSpec({
+*   sort: [
+*     { key: "createdAt", order: "asc" },
+*     { key: "id", order: "asc" },
+*   ],
+* });
+*
+* const q = applyKeysetToKnex(
+*   knex("posts").select("*"),
+*   keyset.where(cursor, direction),
+*   keyset.orderBy(direction),
+*   { columns: { createdAt: "created_at", id: "id" } },
+* );
+*
+* const rows = await q.limit(limit);
+* ```
+*
+* @throws If `options.columns` is missing a key or contains an unsafe SQL
+* identifier.
+*/
+function applyKeysetToKnex(query, where, order, options) {
+	const whereSql = require_keyset.toKeysetWhereSql(where, options.columns, {
+		paramStart: options.paramStart,
+		placeholder: options.placeholder ?? (() => "?")
+	});
+	if (whereSql.sql) query.whereRaw(whereSql.sql, whereSql.params);
+	query.orderByRaw(require_keyset.toKeysetOrderBySql(order, options.columns));
+	return query;
+}
+//#endregion
+exports.applyKeysetToKnex = applyKeysetToKnex;
+
+//# sourceMappingURL=entry-pagination-knex.cjs.map

package/dist/entry-pagination-knex.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry-pagination-knex.cjs","names":["toKeysetWhereSql","toKeysetOrderBySql"],"sources":["../src/pagination-knex.ts"],"sourcesContent":["import type { KeysetSortKey, KeysetSqlColumns, KeysetWhere, ToKeysetSqlOptions } from \"./keyset.ts\";\nimport { toKeysetOrderBySql, toKeysetWhereSql } from \"./keyset.ts\";\n\n/**\n * Minimal structural subset of a Knex query builder used by\n * {@link applyKeysetToKnex}.\n *\n * `xantiagoma/pagination/knex` does not import `knex`; any object with these\n * methods works, which keeps Knex as your application's dependency rather than\n * a peer dependency of this package.\n */\nexport type KnexKeysetQuery = {\n  /** Apply a raw `WHERE` clause with bind parameters. */\n  whereRaw(sql: string, bindings?: unknown[]): unknown;\n  /** Apply a raw `ORDER BY` clause. */\n  orderByRaw(sql: string): unknown;\n};\n\n/** Options for {@link applyKeysetToKnex}. */\nexport type ApplyKeysetToKnexOptions = ToKeysetSqlOptions & {\n  /** Logical key → SQL identifier/expression. Must be server-owned, not request data. */\n  columns: KeysetSqlColumns;\n};\n\n/**\n * Apply a portable keyset `WHERE` + `ORDER BY` to a Knex query builder.\n * Values are passed as bindings; column identifiers are validated by the raw\n * SQL helpers before being rendered.\n *\n * This mutates and returns the provided Knex query builder, matching Knex's\n * chaining style. For first-page cursor requests (`where === null`), it skips\n * `whereRaw` and only applies `orderByRaw`.\n *\n * @example\n * ```ts\n * import { createKeysetSpec } from \"xantiagoma/pagination\";\n * import { applyKeysetToKnex } from \"xantiagoma/pagination/knex\";\n *\n * const keyset = createKeysetSpec({\n *   sort: [\n *     { key: \"createdAt\", order: \"asc\" },\n *     { key: \"id\", order: \"asc\" },\n *   ],\n * });\n *\n * const q = applyKeysetToKnex(\n *   knex(\"posts\").select(\"*\"),\n *   keyset.where(cursor, direction),\n *   keyset.orderBy(direction),\n *   { columns: { createdAt: \"created_at\", id: \"id\" } },\n * );\n *\n * const rows = await q.limit(limit);\n * ```\n *\n * @throws If `options.columns` is missing a key or contains an unsafe SQL\n * identifier.\n */\nexport function applyKeysetToKnex<TQuery extends KnexKeysetQuery>(\n  query: TQuery,\n  where: KeysetWhere | null,\n  order: KeysetSortKey[],\n  options: ApplyKeysetToKnexOptions,\n): TQuery {\n  const whereSql = toKeysetWhereSql(where, options.columns, {\n    paramStart: options.paramStart,\n    placeholder: options.placeholder ?? (() => \"?\"),\n  });\n  if (whereSql.sql) {\n    query.whereRaw(whereSql.sql, whereSql.params);\n  }\n  query.orderByRaw(toKeysetOrderBySql(order, options.columns));\n  return query;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0DA,SAAgB,kBACd,OACA,OACA,OACA,SACQ;CACR,MAAM,WAAWA,eAAAA,iBAAiB,OAAO,QAAQ,SAAS;EACxD,YAAY,QAAQ;EACpB,aAAa,QAAQ,sBAAsB;EAC5C,CAAC;CACF,IAAI,SAAS,KACX,MAAM,SAAS,SAAS,KAAK,SAAS,OAAO;CAE/C,MAAM,WAAWC,eAAAA,mBAAmB,OAAO,QAAQ,QAAQ,CAAC;CAC5D,OAAO"}

package/dist/entry-pagination-knex.d.cts

@@ -0,0 +1,57 @@
+import { c as KeysetSqlColumns, d as KeysetWhere, o as KeysetSortKey, p as ToKeysetSqlOptions } from "./keyset-DqmiNJog.cjs";
+
+//#region src/pagination-knex.d.ts
+/**
+ * Minimal structural subset of a Knex query builder used by
+ * {@link applyKeysetToKnex}.
+ *
+ * `xantiagoma/pagination/knex` does not import `knex`; any object with these
+ * methods works, which keeps Knex as your application's dependency rather than
+ * a peer dependency of this package.
+ */
+type KnexKeysetQuery = {
+  /** Apply a raw `WHERE` clause with bind parameters. */whereRaw(sql: string, bindings?: unknown[]): unknown; /** Apply a raw `ORDER BY` clause. */
+  orderByRaw(sql: string): unknown;
+};
+/** Options for {@link applyKeysetToKnex}. */
+type ApplyKeysetToKnexOptions = ToKeysetSqlOptions & {
+  /** Logical key → SQL identifier/expression. Must be server-owned, not request data. */columns: KeysetSqlColumns;
+};
+/**
+ * Apply a portable keyset `WHERE` + `ORDER BY` to a Knex query builder.
+ * Values are passed as bindings; column identifiers are validated by the raw
+ * SQL helpers before being rendered.
+ *
+ * This mutates and returns the provided Knex query builder, matching Knex's
+ * chaining style. For first-page cursor requests (`where === null`), it skips
+ * `whereRaw` and only applies `orderByRaw`.
+ *
+ * @example
+ * ```ts
+ * import { createKeysetSpec } from "xantiagoma/pagination";
+ * import { applyKeysetToKnex } from "xantiagoma/pagination/knex";
+ *
+ * const keyset = createKeysetSpec({
+ *   sort: [
+ *     { key: "createdAt", order: "asc" },
+ *     { key: "id", order: "asc" },
+ *   ],
+ * });
+ *
+ * const q = applyKeysetToKnex(
+ *   knex("posts").select("*"),
+ *   keyset.where(cursor, direction),
+ *   keyset.orderBy(direction),
+ *   { columns: { createdAt: "created_at", id: "id" } },
+ * );
+ *
+ * const rows = await q.limit(limit);
+ * ```
+ *
+ * @throws If `options.columns` is missing a key or contains an unsafe SQL
+ * identifier.
+ */
+declare function applyKeysetToKnex<TQuery extends KnexKeysetQuery>(query: TQuery, where: KeysetWhere | null, order: KeysetSortKey[], options: ApplyKeysetToKnexOptions): TQuery;
+//#endregion
+export { type ApplyKeysetToKnexOptions, type KnexKeysetQuery, applyKeysetToKnex };
+//# sourceMappingURL=entry-pagination-knex.d.cts.map

package/dist/entry-pagination-knex.d.mts

@@ -0,0 +1,57 @@
+import { c as KeysetSqlColumns, d as KeysetWhere, o as KeysetSortKey, p as ToKeysetSqlOptions } from "./keyset-Cd8leiME.mjs";
+
+//#region src/pagination-knex.d.ts
+/**
+ * Minimal structural subset of a Knex query builder used by
+ * {@link applyKeysetToKnex}.
+ *
+ * `xantiagoma/pagination/knex` does not import `knex`; any object with these
+ * methods works, which keeps Knex as your application's dependency rather than
+ * a peer dependency of this package.
+ */
+type KnexKeysetQuery = {
+  /** Apply a raw `WHERE` clause with bind parameters. */whereRaw(sql: string, bindings?: unknown[]): unknown; /** Apply a raw `ORDER BY` clause. */
+  orderByRaw(sql: string): unknown;
+};
+/** Options for {@link applyKeysetToKnex}. */
+type ApplyKeysetToKnexOptions = ToKeysetSqlOptions & {
+  /** Logical key → SQL identifier/expression. Must be server-owned, not request data. */columns: KeysetSqlColumns;
+};
+/**
+ * Apply a portable keyset `WHERE` + `ORDER BY` to a Knex query builder.
+ * Values are passed as bindings; column identifiers are validated by the raw
+ * SQL helpers before being rendered.
+ *
+ * This mutates and returns the provided Knex query builder, matching Knex's
+ * chaining style. For first-page cursor requests (`where === null`), it skips
+ * `whereRaw` and only applies `orderByRaw`.
+ *
+ * @example
+ * ```ts
+ * import { createKeysetSpec } from "xantiagoma/pagination";
+ * import { applyKeysetToKnex } from "xantiagoma/pagination/knex";
+ *
+ * const keyset = createKeysetSpec({
+ *   sort: [
+ *     { key: "createdAt", order: "asc" },
+ *     { key: "id", order: "asc" },
+ *   ],
+ * });
+ *
+ * const q = applyKeysetToKnex(
+ *   knex("posts").select("*"),
+ *   keyset.where(cursor, direction),
+ *   keyset.orderBy(direction),
+ *   { columns: { createdAt: "created_at", id: "id" } },
+ * );
+ *
+ * const rows = await q.limit(limit);
+ * ```
+ *
+ * @throws If `options.columns` is missing a key or contains an unsafe SQL
+ * identifier.
+ */
+declare function applyKeysetToKnex<TQuery extends KnexKeysetQuery>(query: TQuery, where: KeysetWhere | null, order: KeysetSortKey[], options: ApplyKeysetToKnexOptions): TQuery;
+//#endregion
+export { type ApplyKeysetToKnexOptions, type KnexKeysetQuery, applyKeysetToKnex };
+//# sourceMappingURL=entry-pagination-knex.d.mts.map

package/dist/entry-pagination-knex.mjs

@@ -0,0 +1,49 @@
+import { a as toKeysetOrderBySql, o as toKeysetWhereSql } from "./keyset-ChU9XDqc.mjs";
+//#region src/pagination-knex.ts
+/**
+* Apply a portable keyset `WHERE` + `ORDER BY` to a Knex query builder.
+* Values are passed as bindings; column identifiers are validated by the raw
+* SQL helpers before being rendered.
+*
+* This mutates and returns the provided Knex query builder, matching Knex's
+* chaining style. For first-page cursor requests (`where === null`), it skips
+* `whereRaw` and only applies `orderByRaw`.
+*
+* @example
+* ```ts
+* import { createKeysetSpec } from "xantiagoma/pagination";
+* import { applyKeysetToKnex } from "xantiagoma/pagination/knex";
+*
+* const keyset = createKeysetSpec({
+*   sort: [
+*     { key: "createdAt", order: "asc" },
+*     { key: "id", order: "asc" },
+*   ],
+* });
+*
+* const q = applyKeysetToKnex(
+*   knex("posts").select("*"),
+*   keyset.where(cursor, direction),
+*   keyset.orderBy(direction),
+*   { columns: { createdAt: "created_at", id: "id" } },
+* );
+*
+* const rows = await q.limit(limit);
+* ```
+*
+* @throws If `options.columns` is missing a key or contains an unsafe SQL
+* identifier.
+*/
+function applyKeysetToKnex(query, where, order, options) {
+	const whereSql = toKeysetWhereSql(where, options.columns, {
+		paramStart: options.paramStart,
+		placeholder: options.placeholder ?? (() => "?")
+	});
+	if (whereSql.sql) query.whereRaw(whereSql.sql, whereSql.params);
+	query.orderByRaw(toKeysetOrderBySql(order, options.columns));
+	return query;
+}
+//#endregion
+export { applyKeysetToKnex };
+
+//# sourceMappingURL=entry-pagination-knex.mjs.map