@blamejs/core 0.7.18 → 0.7.19

package/lib/pagination.js

@@ -1,464 +1,464 @@
-"use strict";
-/**
- * pagination — cursor + offset helpers.
- *
- * Every CRUD list endpoint reinvents pagination, usually wrong.
- * The two failure modes:
- *
- *   - Offset pagination at depth: `LIMIT n OFFSET 50000` makes the DB
- *     scan-and-skip 50,000 rows. O(n). With concurrent writes, rows
- *     are also missed/duplicated as new inserts shift the offset.
- *   - Cursor pagination without a tie-breaker: `WHERE createdAt > ?`
- *     skips or duplicates rows when two records share createdAt.
- *
- * This module ships both, done correctly, plus the encode/decode
- * primitives operators reach for when their SQL doesn't fit the
- * Query-builder shape.
- *
- * Public API:
- *
- *   var p = b.pagination;
- *
- *   // Cursor: O(1) at any depth. Composite (orderBy, _id) ordering
- *   // so ties on the orderBy column are broken by _id and rows are
- *   // never skipped.
- *   var page = await p.cursor(b.db.from("users"), {
- *     cursor:    req.query.cursor,
- *     limit:     req.query.limit,
- *     max:       100,
- *     default:   25,
- *     orderBy:   "_id",         // default; use "createdAt" etc.
- *     direction: "asc",         // "asc" | "desc"
- *     secret:    pageSecret,    // Buffer or string; HMAC-tag the cursor
- *   });
- *   // → { items: [...], nextCursor, prevCursor, limit, hasMore }
- *
- *   // Offset: page-numbered. Ergonomic for legacy clients.
- *   var off = await p.offset(b.db.from("users"), {
- *     page:    req.query.page,
- *     perPage: req.query.perPage,
- *     max:     100,
- *     default: 25,
- *   });
- *   // → { items, total, page, perPage, totalPages, hasMore }
- *
- *   // Low-level — for raw SQL or custom row sources.
- *   var token = p.encodeCursor({ orderByVal: 12345, id: "abc" }, secret);
- *   var state = p.decodeCursor(token, secret);
- *
- * Cursor design:
- *   - Composite ordering: (orderBy column, _id). _id is the implicit
- *     tie-breaker, so two rows with identical orderByVal are still
- *     totally ordered. Forward navigation: WHERE
- *       (orderByVal > cur.orderByVal) OR
- *       (orderByVal = cur.orderByVal AND _id > cur.id)
- *     Backward: same with `<`, then reverse the result set.
- *   - Cursors are HMAC-tagged. A tampered cursor is detected at decode
- *     time and rejected with PaginationError. Operators MUST pass
- *     `secret` (Buffer or string) — there's no auto-derivation, since
- *     framework-derived secrets would produce surprises across deploys.
- *   - Cursor format: `<base64url state>.<base64url tag>`. State is
- *     canonical JSON of `{ v, dir, orderBy, orderByVal, id }`. Tag is
- *     SHA3-512(secret || stateJson).slice(0, 16).
- *   - direction is part of the cursor — operators don't need to round-
- *     trip it via query string. The cursor itself encodes whether it's
- *     a "next" or "prev" position so navigation stays consistent.
- *
- * Limit semantics:
- *   - Operator passes `default` and `max`. The effective limit is
- *     min(max, requestedLimit || default). Negative or non-integer
- *     limits are coerced to default.
- *   - The page query fetches limit+1 to detect hasMore without a
- *     second COUNT(*) trip.
- *
- * Offset is the legacy-client tool, not the recommended path. The
- * module's offset() returns a `total` (from COUNT(*)) and computes
- * `totalPages` so legacy clients can render numbered nav.
- *
- * Multi-column ordering:
- *   - orderBy accepts a string (single column), an array of strings
- *     (multiple columns, all using opts.direction), or an array of
- *     { column, direction } objects (mixed directions per column).
- *     The keyset WHERE expands to the standard OR cascade
- *       (col0 [op0] ? OR (col0 = ? AND col1 [op1] ?) OR ...)
- *     so successive pages can't repeat or skip rows when ties on the
- *     leading columns are broken by trailing ones. _id is appended as
- *     a tiebreaker if not already in the orderBy chain.
- *
- * Out of scope (with structural reasons documented):
- *   - Cursor TTL / expiry. Operators who want time-limited cursors
- *     embed a timestamp in their own state and check at decode-time
- *     before passing to .cursor(). The framework's HMAC tag carries
- *     no notion of time.
- *   - Search / filter integration. Operators chain .where() on the
- *     Query before handing to .cursor() — pagination composes with
- *     whatever filtering the operator's already applied.
- */
-
-var nodeCrypto = require("node:crypto");
-var C = require("./constants");
-var canonicalJson = require("./canonical-json");
-var crypto = require("./crypto");
-var nb = require("./numeric-bounds");
-var safeJson = require("./safe-json");
-var safeSql = require("./safe-sql");
-var { defineClass } = require("./framework-error");
-
-var PaginationError = defineClass("PaginationError", { alwaysPermanent: true });
-
-var CURSOR_VERSION = 1;
-var TAG_BYTES = C.BYTES.bytes(16);  // 128-bit HMAC tag truncated from SHA3-512
-var DEFAULT_LIMIT = 25;
-var DEFAULT_MAX_LIMIT = 100;
-var MAX_CURSOR_BYTES = C.BYTES.kib(8);
-
-// Canonical JSON via the shared lib/canonical-json walker with
-// bufferAs: "reject" — cursor state must contain only plain data, so
-// Buffer / Uint8Array reject loudly. Map / Set / RegExp / Symbol /
-// function / circular always reject; Date → ISO; BigInt → decimal
-// string. Wraps the walker's generic Error in a PaginationError so
-// callers can route on `pagination/bad-state`.
-function _canonicalize(value) {
-  try { return canonicalJson.stringify(value, { bufferAs: "reject" }); }
-  catch (e) {
-    throw new PaginationError("pagination/bad-state", e.message);
-  }
-}
-
-function _toBuf(secret) {
-  if (Buffer.isBuffer(secret)) return secret;
-  if (typeof secret === "string") return Buffer.from(secret, "utf8");
-  throw new PaginationError("pagination/bad-secret",
-    "secret must be a Buffer or non-empty string");
-}
-
-function _b64urlEncode(buf) {
-  var b = Buffer.isBuffer(buf) ? buf : Buffer.from(buf);
-  return b.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
-}
-
-function _b64urlDecode(s) {
-  if (typeof s !== "string") throw new PaginationError("pagination/bad-cursor", "cursor must be a string");
-  var pad = s.length % 4;
-  var padded = pad ? s + "=".repeat(4 - pad) : s;
-  return Buffer.from(padded.replace(/-/g, "+").replace(/_/g, "/"), "base64");
-}
-
-function _tag(secretBuf, stateJson) {
-  var h = nodeCrypto.createHash("sha3-512");
-  h.update(secretBuf);
-  h.update(Buffer.from(stateJson, "utf8"));
-  return h.digest().slice(0, TAG_BYTES);
-}
-
-function encodeCursor(state, secret) {
-  if (!state || typeof state !== "object") {
-    throw new PaginationError("pagination/bad-state",
-      "encodeCursor: state must be an object");
-  }
-  var sb = _toBuf(secret);
-  if (sb.length === 0) {
-    throw new PaginationError("pagination/bad-secret", "secret must be non-empty");
-  }
-  var withMeta = Object.assign({ v: CURSOR_VERSION }, state);
-  var json = _canonicalize(withMeta);
-  var tag  = _tag(sb, json);
-  return _b64urlEncode(json) + "." + _b64urlEncode(tag);
-}
-
-function decodeCursor(token, secret) {
-  if (typeof token !== "string" || token.length === 0) {
-    throw new PaginationError("pagination/bad-cursor", "cursor must be a non-empty string");
-  }
-  var dot = token.indexOf(".");
-  if (dot === -1) {
-    throw new PaginationError("pagination/bad-cursor", "cursor missing tag separator");
-  }
-  var sb = _toBuf(secret);
-  var jsonPart = token.slice(0, dot);
-  var tagPart  = token.slice(dot + 1);
-  var json, tag;
-  try {
-    json = _b64urlDecode(jsonPart).toString("utf8");
-    tag  = _b64urlDecode(tagPart);
-  } catch (_e) {
-    throw new PaginationError("pagination/bad-cursor", "cursor base64 decode failed");
-  }
-  var expected = _tag(sb, json);
-  if (!crypto.timingSafeEqual(tag, expected)) {
-    throw new PaginationError("pagination/cursor-tag-mismatch",
-      "cursor HMAC verification failed (tampered or wrong secret)");
-  }
-  var state;
-  try { state = safeJson.parse(json, { maxBytes: MAX_CURSOR_BYTES }); }
-  catch (_e) {
-    throw new PaginationError("pagination/bad-cursor", "cursor state JSON malformed");
-  }
-  if (!state || typeof state !== "object") {
-    throw new PaginationError("pagination/bad-cursor", "cursor state is not an object");
-  }
-  if (state.v !== CURSOR_VERSION) {
-    throw new PaginationError("pagination/cursor-version",
-      "cursor version " + state.v + " unsupported (current: " + CURSOR_VERSION + ")");
-  }
-  return state;
-}
-
-function _resolveLimit(opts) {
-  nb.requirePositiveFiniteIntIfPresent(opts.max,
-    "max", PaginationError, "pagination/bad-opt");
-  nb.requirePositiveFiniteIntIfPresent(opts.default,
-    "default", PaginationError, "pagination/bad-opt");
-  var max = opts.max || DEFAULT_MAX_LIMIT;
-  var def = opts.default || DEFAULT_LIMIT;
-  var requested = parseInt(opts.limit, 10);
-  if (isNaN(requested) || requested < 1) requested = def;
-  if (requested > max) requested = max;
-  return requested;
-}
-
-// ---- Cursor pagination ----
-
-// Normalize opts.orderBy into an array of { column, direction } entries.
-// Accepts:
-//   undefined / null            → [{ column: "_id", direction: opts.direction || "asc" }]
-//   "createdAt"                 → [{ column: "createdAt", direction: opts.direction || "asc" }]
-//   ["createdAt", "_id"]        → all entries default to opts.direction || "asc"
-//   [{column:"a",direction:"desc"}, {column:"b"}]
-//                               → mixed; missing direction defaults to opts.direction || "asc"
-// Always appends an _id tiebreaker if not present, so cursor uniqueness
-// is guaranteed regardless of the operator's spec.
-function _normalizeOrderBy(opts) {
-  var defaultDir = (opts && opts.direction === "desc") ? "desc" : "asc";
-  var raw = opts && opts.orderBy;
-  var entries;
-  if (raw == null) {
-    entries = [{ column: "_id", direction: defaultDir }];
-  } else if (typeof raw === "string") {
-    entries = [{ column: raw, direction: defaultDir }];
-  } else if (Array.isArray(raw)) {
-    entries = raw.map(function (e) {
-      if (typeof e === "string") return { column: e, direction: defaultDir };
-      if (!e || typeof e !== "object" || typeof e.column !== "string") {
-        throw new PaginationError("pagination/bad-orderby",
-          "orderBy[] entries must be strings or { column, direction } objects, got " +
-          JSON.stringify(e));
-      }
-      var d = (e.direction || defaultDir).toLowerCase();
-      if (d !== "asc" && d !== "desc") {
-        throw new PaginationError("pagination/bad-orderby",
-          "orderBy[].direction must be 'asc' | 'desc', got " + JSON.stringify(e.direction));
-      }
-      return { column: e.column, direction: d };
-    });
-  } else {
-    throw new PaginationError("pagination/bad-orderby",
-      "orderBy must be a string, array, or omitted; got " + typeof raw);
-  }
-  for (var i = 0; i < entries.length; i++) {
-    if (typeof entries[i].column !== "string" ||
-        entries[i].column.length === 0 ||
-        entries[i].column.length > safeSql.MAX_IDENTIFIER_LENGTH ||
-        !safeSql.DEFAULT_IDENTIFIER_RE.test(entries[i].column)) {
-      throw new PaginationError("pagination/bad-orderby",
-        "orderBy column must match " + safeSql.DEFAULT_IDENTIFIER_RE +
-        " and be 1.." + safeSql.MAX_IDENTIFIER_LENGTH + " chars, got " +
-        JSON.stringify(entries[i].column));
-    }
-  }
-  // Append _id tiebreaker if not already in the chain. Direction
-  // matches the chain's last entry by convention so the tiebreaker
-  // doesn't reverse the natural reading order.
-  var hasId = entries.some(function (e) { return e.column === "_id"; });
-  if (!hasId) {
-    entries.push({ column: "_id", direction: entries[entries.length - 1].direction });
-  }
-  return entries;
-}
-
-// Build the keyset WHERE clause for next-page navigation given the
-// cursor's column values. Each (col, dir) entry expands the OR cascade:
-//   col0 [op0] ? OR (col0 = ? AND col1 [op1] ?) OR ... OR (col0 = ? AND ... AND coln [opn] ?)
-// The compareOp per column flips by direction × forward (XNOR).
-function _buildKeysetWhere(orderEntries, cursorVals, forward) {
-  var clauses = [];
-  var params = [];
-  for (var i = 0; i < orderEntries.length; i++) {
-    var entry = orderEntries[i];
-    // Effective direction: asc + forward → ">", desc + forward → "<", and reversed for backward.
-    var effectiveAsc = (entry.direction === "asc") === forward;
-    var op = effectiveAsc ? ">" : "<";
-    var equalChain = [];
-    for (var j = 0; j < i; j++) {
-      equalChain.push('"' + orderEntries[j].column + '" = ?');
-      params.push(cursorVals[j]);
-    }
-    equalChain.push('"' + entry.column + '" ' + op + ' ?');
-    params.push(cursorVals[i]);
-    clauses.push("(" + equalChain.join(" AND ") + ")");
-  }
-  return { sql: clauses.join(" OR "), params: params };
-}
-
-async function cursor(query, opts) {
-  if (!query || typeof query.where !== "function" || typeof query.orderBy !== "function" ||
-      typeof query.limit !== "function" || typeof query.all !== "function") {
-    throw new PaginationError("pagination/bad-query",
-      "cursor: first arg must be a db Query (must support where, orderBy, limit, all)");
-  }
-  opts = opts || {};
-  if (opts.secret == null) {
-    throw new PaginationError("pagination/no-secret",
-      "cursor: opts.secret is required (Buffer or non-empty string for HMAC tagging)");
-  }
-  var limit = _resolveLimit(opts);
-  var orderEntries = _normalizeOrderBy(opts);
-  // Cursor compatibility key: array of `column:direction` pairs canonicalizes
-  // the orderBy spec so a stored cursor must match exactly to be replayed.
-  var orderKey = orderEntries.map(function (e) { return e.column + ":" + e.direction; });
-
-  var cursorState = null;
-  var forward = (opts.forward !== false);
-  if (opts.cursor) {
-    cursorState = decodeCursor(opts.cursor, opts.secret);
-    var cursorKey = Array.isArray(cursorState.orderKey) ? cursorState.orderKey :
-      // Back-compat with v0.6.20 single-column cursors: synthesize the
-      // key from the legacy orderBy/dir fields.
-      [cursorState.orderBy + ":" + cursorState.dir];
-    if (JSON.stringify(cursorKey) !== JSON.stringify(orderKey)) {
-      throw new PaginationError("pagination/cursor-mismatch",
-        "cursor orderKey [" + cursorKey.join(", ") + "] does not match call orderKey [" +
-        orderKey.join(", ") + "] — operator must use the same orderBy/direction spec");
-    }
-    if (typeof cursorState.forward === "boolean") forward = cursorState.forward;
-  }
-
-  // Apply the keyset WHERE if a cursor is present.
-  if (cursorState) {
-    var cursorVals;
-    if (Array.isArray(cursorState.vals)) {
-      cursorVals = cursorState.vals;
-    } else {
-      // v0.6.20 single-column shape — synthesize the vals array.
-      cursorVals = [cursorState.orderByVal, cursorState.id];
-      // Drop the synthetic _id append if the legacy cursor already had it
-      if (orderEntries.length === 1) cursorVals = [cursorState.orderByVal];
-    }
-    if (cursorVals.length !== orderEntries.length) {
-      throw new PaginationError("pagination/cursor-mismatch",
-        "cursor encoded " + cursorVals.length + " column value(s) but orderBy has " +
-        orderEntries.length + " — operator changed the orderBy spec mid-flight");
-    }
-    var where = _buildKeysetWhere(orderEntries, cursorVals, forward);
-    query.whereRaw(where.sql, where.params);
-  }
-
-  // Apply ORDER BY for each entry. When forward=false we reverse direction
-  // per entry so the SQL returns rows in the right reading order; we then
-  // reverse client-side at the end.
-  for (var oi = 0; oi < orderEntries.length; oi++) {
-    var entry = orderEntries[oi];
-    var effectiveDir = ((entry.direction === "asc") === forward) ? "asc" : "desc";
-    query.orderBy(entry.column, effectiveDir);
-  }
-  query.limit(limit + 1);
-
-  var rows = await Promise.resolve(query.all());
-
-  var hasMore = rows.length > limit;
-  var page = hasMore ? rows.slice(0, limit) : rows.slice();
-  if (!forward) page.reverse();
-
-  function _valsForRow(row) {
-    return orderEntries.map(function (e) {
-      return e.column === "_id" ? String(row._id) : row[e.column];
-    });
-  }
-
-  var nextCursor = null;
-  var prevCursor = null;
-  if (hasMore && page.length > 0) {
-    var last = page[page.length - 1];
-    nextCursor = encodeCursor({
-      orderKey: orderKey,
-      vals:     _valsForRow(last),
-      forward:  true,
-    }, opts.secret);
-  }
-  if (cursorState && page.length > 0) {
-    var first = page[0];
-    prevCursor = encodeCursor({
-      orderKey: orderKey,
-      vals:     _valsForRow(first),
-      forward:  false,
-    }, opts.secret);
-  }
-
-  return {
-    items:      page,
-    nextCursor: nextCursor,
-    prevCursor: prevCursor,
-    limit:      limit,
-    hasMore:    hasMore,
-  };
-}
-
-// ---- Offset pagination ----
-
-async function offset(query, opts) {
-  if (!query || typeof query.limit !== "function" || typeof query.offset !== "function" ||
-      typeof query.all !== "function" || typeof query.count !== "function") {
-    throw new PaginationError("pagination/bad-query",
-      "offset: first arg must be a db Query (must support limit, offset, all, count)");
-  }
-  opts = opts || {};
-  var perPage = _resolveLimit({ limit: opts.perPage, max: opts.max, default: opts.default });
-  var page = parseInt(opts.page, 10);
-  if (isNaN(page) || page < 1) page = 1;
-  var orderBy = typeof opts.orderBy === "string" && opts.orderBy.length > 0 ? opts.orderBy : "_id";
-  // Same identifier-only check on offset() as cursor() — orderBy passes
-  // through to the db Query; throw at call site to prevent SQL injection.
-  if (orderBy.length > safeSql.MAX_IDENTIFIER_LENGTH ||
-      !safeSql.DEFAULT_IDENTIFIER_RE.test(orderBy)) {
-    throw new PaginationError("pagination/bad-orderby",
-      "offset: orderBy must match " + safeSql.DEFAULT_IDENTIFIER_RE +
-      " and be 1.." + safeSql.MAX_IDENTIFIER_LENGTH + " chars, got " +
-      JSON.stringify(orderBy));
-  }
-  var direction = (opts.direction === "desc") ? "desc" : "asc";
-
-  // Count gives total — required for totalPages calculation. Cheap on
-  // an indexed column (which most app tables have via _id).
-  var total = await Promise.resolve(query.count());
-
-  // Build the page query — the operator's existing where() chain is
-  // already applied; we just add ordering + limit + offset.
-  query.orderBy(orderBy, direction);
-  query.limit(perPage);
-  query.offset((page - 1) * perPage);
-  var items = await Promise.resolve(query.all());
-
-  var totalPages = total === 0 ? 0 : Math.ceil(total / perPage);
-  var hasMore = page < totalPages;
-  return {
-    items:      items,
-    total:      total,
-    page:       page,
-    perPage:    perPage,
-    totalPages: totalPages,
-    hasMore:    hasMore,
-  };
-}
-
-module.exports = {
-  cursor:           cursor,
-  offset:           offset,
-  encodeCursor:     encodeCursor,
-  decodeCursor:     decodeCursor,
-  PaginationError:  PaginationError,
-  // Internal helpers exposed for tests
-  _resolveLimit:    _resolveLimit,
-  _b64urlEncode:    _b64urlEncode,
-  _b64urlDecode:    _b64urlDecode,
-  CURSOR_VERSION:   CURSOR_VERSION,
-};
+"use strict";
+/**
+ * pagination — cursor + offset helpers.
+ *
+ * Every CRUD list endpoint reinvents pagination, usually wrong.
+ * The two failure modes:
+ *
+ *   - Offset pagination at depth: `LIMIT n OFFSET 50000` makes the DB
+ *     scan-and-skip 50,000 rows. O(n). With concurrent writes, rows
+ *     are also missed/duplicated as new inserts shift the offset.
+ *   - Cursor pagination without a tie-breaker: `WHERE createdAt > ?`
+ *     skips or duplicates rows when two records share createdAt.
+ *
+ * This module ships both, done correctly, plus the encode/decode
+ * primitives operators reach for when their SQL doesn't fit the
+ * Query-builder shape.
+ *
+ * Public API:
+ *
+ *   var p = b.pagination;
+ *
+ *   // Cursor: O(1) at any depth. Composite (orderBy, _id) ordering
+ *   // so ties on the orderBy column are broken by _id and rows are
+ *   // never skipped.
+ *   var page = await p.cursor(b.db.from("users"), {
+ *     cursor:    req.query.cursor,
+ *     limit:     req.query.limit,
+ *     max:       100,
+ *     default:   25,
+ *     orderBy:   "_id",         // default; use "createdAt" etc.
+ *     direction: "asc",         // "asc" | "desc"
+ *     secret:    pageSecret,    // Buffer or string; HMAC-tag the cursor
+ *   });
+ *   // → { items: [...], nextCursor, prevCursor, limit, hasMore }
+ *
+ *   // Offset: page-numbered. Ergonomic for legacy clients.
+ *   var off = await p.offset(b.db.from("users"), {
+ *     page:    req.query.page,
+ *     perPage: req.query.perPage,
+ *     max:     100,
+ *     default: 25,
+ *   });
+ *   // → { items, total, page, perPage, totalPages, hasMore }
+ *
+ *   // Low-level — for raw SQL or custom row sources.
+ *   var token = p.encodeCursor({ orderByVal: 12345, id: "abc" }, secret);
+ *   var state = p.decodeCursor(token, secret);
+ *
+ * Cursor design:
+ *   - Composite ordering: (orderBy column, _id). _id is the implicit
+ *     tie-breaker, so two rows with identical orderByVal are still
+ *     totally ordered. Forward navigation: WHERE
+ *       (orderByVal > cur.orderByVal) OR
+ *       (orderByVal = cur.orderByVal AND _id > cur.id)
+ *     Backward: same with `<`, then reverse the result set.
+ *   - Cursors are HMAC-tagged. A tampered cursor is detected at decode
+ *     time and rejected with PaginationError. Operators MUST pass
+ *     `secret` (Buffer or string) — there's no auto-derivation, since
+ *     framework-derived secrets would produce surprises across deploys.
+ *   - Cursor format: `<base64url state>.<base64url tag>`. State is
+ *     canonical JSON of `{ v, dir, orderBy, orderByVal, id }`. Tag is
+ *     SHA3-512(secret || stateJson).slice(0, 16).
+ *   - direction is part of the cursor — operators don't need to round-
+ *     trip it via query string. The cursor itself encodes whether it's
+ *     a "next" or "prev" position so navigation stays consistent.
+ *
+ * Limit semantics:
+ *   - Operator passes `default` and `max`. The effective limit is
+ *     min(max, requestedLimit || default). Negative or non-integer
+ *     limits are coerced to default.
+ *   - The page query fetches limit+1 to detect hasMore without a
+ *     second COUNT(*) trip.
+ *
+ * Offset is the legacy-client tool, not the recommended path. The
+ * module's offset() returns a `total` (from COUNT(*)) and computes
+ * `totalPages` so legacy clients can render numbered nav.
+ *
+ * Multi-column ordering:
+ *   - orderBy accepts a string (single column), an array of strings
+ *     (multiple columns, all using opts.direction), or an array of
+ *     { column, direction } objects (mixed directions per column).
+ *     The keyset WHERE expands to the standard OR cascade
+ *       (col0 [op0] ? OR (col0 = ? AND col1 [op1] ?) OR ...)
+ *     so successive pages can't repeat or skip rows when ties on the
+ *     leading columns are broken by trailing ones. _id is appended as
+ *     a tiebreaker if not already in the orderBy chain.
+ *
+ * Out of scope (with structural reasons documented):
+ *   - Cursor TTL / expiry. Operators who want time-limited cursors
+ *     embed a timestamp in their own state and check at decode-time
+ *     before passing to .cursor(). The framework's HMAC tag carries
+ *     no notion of time.
+ *   - Search / filter integration. Operators chain .where() on the
+ *     Query before handing to .cursor() — pagination composes with
+ *     whatever filtering the operator's already applied.
+ */
+
+var nodeCrypto = require("node:crypto");
+var C = require("./constants");
+var canonicalJson = require("./canonical-json");
+var crypto = require("./crypto");
+var nb = require("./numeric-bounds");
+var safeJson = require("./safe-json");
+var safeSql = require("./safe-sql");
+var { defineClass } = require("./framework-error");
+
+var PaginationError = defineClass("PaginationError", { alwaysPermanent: true });
+
+var CURSOR_VERSION = 1;
+var TAG_BYTES = C.BYTES.bytes(16);  // 128-bit HMAC tag truncated from SHA3-512
+var DEFAULT_LIMIT = 25;
+var DEFAULT_MAX_LIMIT = 100;
+var MAX_CURSOR_BYTES = C.BYTES.kib(8);
+
+// Canonical JSON via the shared lib/canonical-json walker with
+// bufferAs: "reject" — cursor state must contain only plain data, so
+// Buffer / Uint8Array reject loudly. Map / Set / RegExp / Symbol /
+// function / circular always reject; Date → ISO; BigInt → decimal
+// string. Wraps the walker's generic Error in a PaginationError so
+// callers can route on `pagination/bad-state`.
+function _canonicalize(value) {
+  try { return canonicalJson.stringify(value, { bufferAs: "reject" }); }
+  catch (e) {
+    throw new PaginationError("pagination/bad-state", e.message);
+  }
+}
+
+function _toBuf(secret) {
+  if (Buffer.isBuffer(secret)) return secret;
+  if (typeof secret === "string") return Buffer.from(secret, "utf8");
+  throw new PaginationError("pagination/bad-secret",
+    "secret must be a Buffer or non-empty string");
+}
+
+function _b64urlEncode(buf) {
+  var b = Buffer.isBuffer(buf) ? buf : Buffer.from(buf);
+  return b.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function _b64urlDecode(s) {
+  if (typeof s !== "string") throw new PaginationError("pagination/bad-cursor", "cursor must be a string");
+  var pad = s.length % 4;
+  var padded = pad ? s + "=".repeat(4 - pad) : s;
+  return Buffer.from(padded.replace(/-/g, "+").replace(/_/g, "/"), "base64");
+}
+
+function _tag(secretBuf, stateJson) {
+  var h = nodeCrypto.createHash("sha3-512");
+  h.update(secretBuf);
+  h.update(Buffer.from(stateJson, "utf8"));
+  return h.digest().slice(0, TAG_BYTES);
+}
+
+function encodeCursor(state, secret) {
+  if (!state || typeof state !== "object") {
+    throw new PaginationError("pagination/bad-state",
+      "encodeCursor: state must be an object");
+  }
+  var sb = _toBuf(secret);
+  if (sb.length === 0) {
+    throw new PaginationError("pagination/bad-secret", "secret must be non-empty");
+  }
+  var withMeta = Object.assign({ v: CURSOR_VERSION }, state);
+  var json = _canonicalize(withMeta);
+  var tag  = _tag(sb, json);
+  return _b64urlEncode(json) + "." + _b64urlEncode(tag);
+}
+
+function decodeCursor(token, secret) {
+  if (typeof token !== "string" || token.length === 0) {
+    throw new PaginationError("pagination/bad-cursor", "cursor must be a non-empty string");
+  }
+  var dot = token.indexOf(".");
+  if (dot === -1) {
+    throw new PaginationError("pagination/bad-cursor", "cursor missing tag separator");
+  }
+  var sb = _toBuf(secret);
+  var jsonPart = token.slice(0, dot);
+  var tagPart  = token.slice(dot + 1);
+  var json, tag;
+  try {
+    json = _b64urlDecode(jsonPart).toString("utf8");
+    tag  = _b64urlDecode(tagPart);
+  } catch (_e) {
+    throw new PaginationError("pagination/bad-cursor", "cursor base64 decode failed");
+  }
+  var expected = _tag(sb, json);
+  if (!crypto.timingSafeEqual(tag, expected)) {
+    throw new PaginationError("pagination/cursor-tag-mismatch",
+      "cursor HMAC verification failed (tampered or wrong secret)");
+  }
+  var state;
+  try { state = safeJson.parse(json, { maxBytes: MAX_CURSOR_BYTES }); }
+  catch (_e) {
+    throw new PaginationError("pagination/bad-cursor", "cursor state JSON malformed");
+  }
+  if (!state || typeof state !== "object") {
+    throw new PaginationError("pagination/bad-cursor", "cursor state is not an object");
+  }
+  if (state.v !== CURSOR_VERSION) {
+    throw new PaginationError("pagination/cursor-version",
+      "cursor version " + state.v + " unsupported (current: " + CURSOR_VERSION + ")");
+  }
+  return state;
+}
+
+function _resolveLimit(opts) {
+  nb.requirePositiveFiniteIntIfPresent(opts.max,
+    "max", PaginationError, "pagination/bad-opt");
+  nb.requirePositiveFiniteIntIfPresent(opts.default,
+    "default", PaginationError, "pagination/bad-opt");
+  var max = opts.max || DEFAULT_MAX_LIMIT;
+  var def = opts.default || DEFAULT_LIMIT;
+  var requested = parseInt(opts.limit, 10);
+  if (isNaN(requested) || requested < 1) requested = def;
+  if (requested > max) requested = max;
+  return requested;
+}
+
+// ---- Cursor pagination ----
+
+// Normalize opts.orderBy into an array of { column, direction } entries.
+// Accepts:
+//   undefined / null            → [{ column: "_id", direction: opts.direction || "asc" }]
+//   "createdAt"                 → [{ column: "createdAt", direction: opts.direction || "asc" }]
+//   ["createdAt", "_id"]        → all entries default to opts.direction || "asc"
+//   [{column:"a",direction:"desc"}, {column:"b"}]
+//                               → mixed; missing direction defaults to opts.direction || "asc"
+// Always appends an _id tiebreaker if not present, so cursor uniqueness
+// is guaranteed regardless of the operator's spec.
+function _normalizeOrderBy(opts) {
+  var defaultDir = (opts && opts.direction === "desc") ? "desc" : "asc";
+  var raw = opts && opts.orderBy;
+  var entries;
+  if (raw == null) {
+    entries = [{ column: "_id", direction: defaultDir }];
+  } else if (typeof raw === "string") {
+    entries = [{ column: raw, direction: defaultDir }];
+  } else if (Array.isArray(raw)) {
+    entries = raw.map(function (e) {
+      if (typeof e === "string") return { column: e, direction: defaultDir };
+      if (!e || typeof e !== "object" || typeof e.column !== "string") {
+        throw new PaginationError("pagination/bad-orderby",
+          "orderBy[] entries must be strings or { column, direction } objects, got " +
+          JSON.stringify(e));
+      }
+      var d = (e.direction || defaultDir).toLowerCase();
+      if (d !== "asc" && d !== "desc") {
+        throw new PaginationError("pagination/bad-orderby",
+          "orderBy[].direction must be 'asc' | 'desc', got " + JSON.stringify(e.direction));
+      }
+      return { column: e.column, direction: d };
+    });
+  } else {
+    throw new PaginationError("pagination/bad-orderby",
+      "orderBy must be a string, array, or omitted; got " + typeof raw);
+  }
+  for (var i = 0; i < entries.length; i++) {
+    if (typeof entries[i].column !== "string" ||
+        entries[i].column.length === 0 ||
+        entries[i].column.length > safeSql.MAX_IDENTIFIER_LENGTH ||
+        !safeSql.DEFAULT_IDENTIFIER_RE.test(entries[i].column)) {
+      throw new PaginationError("pagination/bad-orderby",
+        "orderBy column must match " + safeSql.DEFAULT_IDENTIFIER_RE +
+        " and be 1.." + safeSql.MAX_IDENTIFIER_LENGTH + " chars, got " +
+        JSON.stringify(entries[i].column));
+    }
+  }
+  // Append _id tiebreaker if not already in the chain. Direction
+  // matches the chain's last entry by convention so the tiebreaker
+  // doesn't reverse the natural reading order.
+  var hasId = entries.some(function (e) { return e.column === "_id"; });
+  if (!hasId) {
+    entries.push({ column: "_id", direction: entries[entries.length - 1].direction });
+  }
+  return entries;
+}
+
+// Build the keyset WHERE clause for next-page navigation given the
+// cursor's column values. Each (col, dir) entry expands the OR cascade:
+//   col0 [op0] ? OR (col0 = ? AND col1 [op1] ?) OR ... OR (col0 = ? AND ... AND coln [opn] ?)
+// The compareOp per column flips by direction × forward (XNOR).
+function _buildKeysetWhere(orderEntries, cursorVals, forward) {
+  var clauses = [];
+  var params = [];
+  for (var i = 0; i < orderEntries.length; i++) {
+    var entry = orderEntries[i];
+    // Effective direction: asc + forward → ">", desc + forward → "<", and reversed for backward.
+    var effectiveAsc = (entry.direction === "asc") === forward;
+    var op = effectiveAsc ? ">" : "<";
+    var equalChain = [];
+    for (var j = 0; j < i; j++) {
+      equalChain.push('"' + orderEntries[j].column + '" = ?');
+      params.push(cursorVals[j]);
+    }
+    equalChain.push('"' + entry.column + '" ' + op + ' ?');
+    params.push(cursorVals[i]);
+    clauses.push("(" + equalChain.join(" AND ") + ")");
+  }
+  return { sql: clauses.join(" OR "), params: params };
+}
+
+async function cursor(query, opts) {
+  if (!query || typeof query.where !== "function" || typeof query.orderBy !== "function" ||
+      typeof query.limit !== "function" || typeof query.all !== "function") {
+    throw new PaginationError("pagination/bad-query",
+      "cursor: first arg must be a db Query (must support where, orderBy, limit, all)");
+  }
+  opts = opts || {};
+  if (opts.secret == null) {
+    throw new PaginationError("pagination/no-secret",
+      "cursor: opts.secret is required (Buffer or non-empty string for HMAC tagging)");
+  }
+  var limit = _resolveLimit(opts);
+  var orderEntries = _normalizeOrderBy(opts);
+  // Cursor compatibility key: array of `column:direction` pairs canonicalizes
+  // the orderBy spec so a stored cursor must match exactly to be replayed.
+  var orderKey = orderEntries.map(function (e) { return e.column + ":" + e.direction; });
+
+  var cursorState = null;
+  var forward = (opts.forward !== false);
+  if (opts.cursor) {
+    cursorState = decodeCursor(opts.cursor, opts.secret);
+    var cursorKey = Array.isArray(cursorState.orderKey) ? cursorState.orderKey :
+      // Back-compat with v0.6.20 single-column cursors: synthesize the
+      // key from the legacy orderBy/dir fields.
+      [cursorState.orderBy + ":" + cursorState.dir];
+    if (JSON.stringify(cursorKey) !== JSON.stringify(orderKey)) {
+      throw new PaginationError("pagination/cursor-mismatch",
+        "cursor orderKey [" + cursorKey.join(", ") + "] does not match call orderKey [" +
+        orderKey.join(", ") + "] — operator must use the same orderBy/direction spec");
+    }
+    if (typeof cursorState.forward === "boolean") forward = cursorState.forward;
+  }
+
+  // Apply the keyset WHERE if a cursor is present.
+  if (cursorState) {
+    var cursorVals;
+    if (Array.isArray(cursorState.vals)) {
+      cursorVals = cursorState.vals;
+    } else {
+      // v0.6.20 single-column shape — synthesize the vals array.
+      cursorVals = [cursorState.orderByVal, cursorState.id];
+      // Drop the synthetic _id append if the legacy cursor already had it
+      if (orderEntries.length === 1) cursorVals = [cursorState.orderByVal];
+    }
+    if (cursorVals.length !== orderEntries.length) {
+      throw new PaginationError("pagination/cursor-mismatch",
+        "cursor encoded " + cursorVals.length + " column value(s) but orderBy has " +
+        orderEntries.length + " — operator changed the orderBy spec mid-flight");
+    }
+    var where = _buildKeysetWhere(orderEntries, cursorVals, forward);
+    query.whereRaw(where.sql, where.params);
+  }
+
+  // Apply ORDER BY for each entry. When forward=false we reverse direction
+  // per entry so the SQL returns rows in the right reading order; we then
+  // reverse client-side at the end.
+  for (var oi = 0; oi < orderEntries.length; oi++) {
+    var entry = orderEntries[oi];
+    var effectiveDir = ((entry.direction === "asc") === forward) ? "asc" : "desc";
+    query.orderBy(entry.column, effectiveDir);
+  }
+  query.limit(limit + 1);
+
+  var rows = await Promise.resolve(query.all());
+
+  var hasMore = rows.length > limit;
+  var page = hasMore ? rows.slice(0, limit) : rows.slice();
+  if (!forward) page.reverse();
+
+  function _valsForRow(row) {
+    return orderEntries.map(function (e) {
+      return e.column === "_id" ? String(row._id) : row[e.column];
+    });
+  }
+
+  var nextCursor = null;
+  var prevCursor = null;
+  if (hasMore && page.length > 0) {
+    var last = page[page.length - 1];
+    nextCursor = encodeCursor({
+      orderKey: orderKey,
+      vals:     _valsForRow(last),
+      forward:  true,
+    }, opts.secret);
+  }
+  if (cursorState && page.length > 0) {
+    var first = page[0];
+    prevCursor = encodeCursor({
+      orderKey: orderKey,
+      vals:     _valsForRow(first),
+      forward:  false,
+    }, opts.secret);
+  }
+
+  return {
+    items:      page,
+    nextCursor: nextCursor,
+    prevCursor: prevCursor,
+    limit:      limit,
+    hasMore:    hasMore,
+  };
+}
+
+// ---- Offset pagination ----
+
+async function offset(query, opts) {
+  if (!query || typeof query.limit !== "function" || typeof query.offset !== "function" ||
+      typeof query.all !== "function" || typeof query.count !== "function") {
+    throw new PaginationError("pagination/bad-query",
+      "offset: first arg must be a db Query (must support limit, offset, all, count)");
+  }
+  opts = opts || {};
+  var perPage = _resolveLimit({ limit: opts.perPage, max: opts.max, default: opts.default });
+  var page = parseInt(opts.page, 10);
+  if (isNaN(page) || page < 1) page = 1;
+  var orderBy = typeof opts.orderBy === "string" && opts.orderBy.length > 0 ? opts.orderBy : "_id";
+  // Same identifier-only check on offset() as cursor() — orderBy passes
+  // through to the db Query; throw at call site to prevent SQL injection.
+  if (orderBy.length > safeSql.MAX_IDENTIFIER_LENGTH ||
+      !safeSql.DEFAULT_IDENTIFIER_RE.test(orderBy)) {
+    throw new PaginationError("pagination/bad-orderby",
+      "offset: orderBy must match " + safeSql.DEFAULT_IDENTIFIER_RE +
+      " and be 1.." + safeSql.MAX_IDENTIFIER_LENGTH + " chars, got " +
+      JSON.stringify(orderBy));
+  }
+  var direction = (opts.direction === "desc") ? "desc" : "asc";
+
+  // Count gives total — required for totalPages calculation. Cheap on
+  // an indexed column (which most app tables have via _id).
+  var total = await Promise.resolve(query.count());
+
+  // Build the page query — the operator's existing where() chain is
+  // already applied; we just add ordering + limit + offset.
+  query.orderBy(orderBy, direction);
+  query.limit(perPage);
+  query.offset((page - 1) * perPage);
+  var items = await Promise.resolve(query.all());
+
+  var totalPages = total === 0 ? 0 : Math.ceil(total / perPage);
+  var hasMore = page < totalPages;
+  return {
+    items:      items,
+    total:      total,
+    page:       page,
+    perPage:    perPage,
+    totalPages: totalPages,
+    hasMore:    hasMore,
+  };
+}
+
+module.exports = {
+  cursor:           cursor,
+  offset:           offset,
+  encodeCursor:     encodeCursor,
+  decodeCursor:     decodeCursor,
+  PaginationError:  PaginationError,
+  // Internal helpers exposed for tests
+  _resolveLimit:    _resolveLimit,
+  _b64urlEncode:    _b64urlEncode,
+  _b64urlDecode:    _b64urlDecode,
+  CURSOR_VERSION:   CURSOR_VERSION,
+};