metal-orm 1.1.8 → 1.1.9

package/README.md

@@ -291,7 +291,7 @@ const listOpenTodos = selectFrom(todos).select(...defaultColumns);
 
 That's it: schema, query, SQL, done.
 
-If you are using the Level 2 runtime (`OrmSession`), `SelectQueryBuilder` also provides `count(session)` and `executePaged(session, { page, pageSize })` for common pagination patterns.
+If you are using the Level 2 runtime (`OrmSession`), `SelectQueryBuilder` also provides `count(session)`, `executePaged(session, { page, pageSize })`, and `executeCursor(session, { first/after | last/before })` for common pagination patterns. See [docs/pagination.md](./docs/pagination.md) for offset pagination, eager-include pagination guards, and bidirectional cursor pagination.
 
 #### Column pickers (preferred selection helpers)
 

package/dist/index.cjs

@@ -7714,6 +7714,193 @@ function buildWhereHasPredicate(env, context, relationFacet, createChildBuilder,
   return negate ? notExists(finalSubAst) : exists(finalSubAst);
 }
 
+// src/query-builder/select/cursor-pagination.ts
+function encodeCursor(payload) {
+  return Buffer.from(JSON.stringify(payload)).toString("base64url");
+}
+function decodeCursor(cursor) {
+  let parsed;
+  try {
+    parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+  } catch {
+    throw new Error("executeCursor: invalid cursor format");
+  }
+  if (typeof parsed !== "object" || parsed === null || parsed.v !== 2 || !Array.isArray(parsed.values) || typeof parsed.orderSig !== "string") {
+    throw new Error("executeCursor: invalid cursor payload");
+  }
+  return parsed;
+}
+function buildOrderSignature(specs) {
+  return specs.map((s) => `${s.table}.${s.column}:${s.direction}`).join(",");
+}
+function extractOrderSpecs(ast) {
+  if (!ast.orderBy || ast.orderBy.length === 0) {
+    throw new Error("executeCursor: ORDER BY is required for cursor pagination");
+  }
+  return ast.orderBy.map((ob) => {
+    if (ob.nulls) {
+      throw new Error("executeCursor: NULLS FIRST/LAST is not supported for cursor pagination");
+    }
+    const term = ob.term;
+    if (!term || term.type !== "Column") {
+      throw new Error(
+        "executeCursor: only column references are supported in ORDER BY for cursor pagination"
+      );
+    }
+    const col2 = term;
+    return {
+      table: col2.table,
+      column: col2.name,
+      valueKey: resolveOrderValueKey(ast, col2),
+      direction: ob.direction
+    };
+  });
+}
+function resolveOrderValueKey(ast, col2) {
+  const projectedColumn = ast.columns.find(
+    (candidate) => candidate.type === "Column" && candidate.table === col2.table && candidate.name === col2.name
+  );
+  return projectedColumn?.alias ?? projectedColumn?.name ?? col2.alias ?? col2.name;
+}
+function buildKeysetPredicate(specs, values, mode) {
+  if (values.length !== specs.length) {
+    throw new Error("executeCursor: invalid cursor payload");
+  }
+  const branches = [];
+  for (let i = 0; i < specs.length; i++) {
+    const spec = specs[i];
+    const colNode = { type: "Column", table: spec.table, name: spec.column };
+    const value = values[i];
+    if (value === null || value === void 0) {
+      throw new Error("executeCursor: invalid cursor payload");
+    }
+    const literal = { type: "Literal", value };
+    let operator;
+    if (mode === "after") {
+      operator = spec.direction === "ASC" ? ">" : "<";
+    } else {
+      operator = spec.direction === "ASC" ? "<" : ">";
+    }
+    const eqParts = [];
+    for (let j = 0; j < i; j++) {
+      const prevSpec = specs[j];
+      const prevCol = { type: "Column", table: prevSpec.table, name: prevSpec.column };
+      const prevValue = values[j];
+      if (prevValue === null || prevValue === void 0) {
+        throw new Error("executeCursor: invalid cursor payload");
+      }
+      const prevVal = { type: "Literal", value: prevValue };
+      eqParts.push({
+        type: "BinaryExpression",
+        left: prevCol,
+        operator: "=",
+        right: prevVal
+      });
+    }
+    const breakExpr = {
+      type: "BinaryExpression",
+      left: colNode,
+      operator,
+      right: literal
+    };
+    if (eqParts.length === 0) {
+      branches.push(breakExpr);
+    } else {
+      branches.push(and(...eqParts, breakExpr));
+    }
+  }
+  return branches.length === 1 ? branches[0] : or(...branches);
+}
+function buildCursorFromRow(row, specs) {
+  const values = specs.map((spec) => {
+    const value = row[spec.valueKey];
+    if (value === null || value === void 0) {
+      throw new Error("executeCursor: cursor pagination requires non-null ORDER BY values");
+    }
+    return value;
+  });
+  return encodeCursor({ v: 2, values, orderSig: buildOrderSignature(specs) });
+}
+function reverseDirection(direction) {
+  return direction === "ASC" ? "DESC" : "ASC";
+}
+function createExecutionBuilder(builder, options) {
+  const internals = builder.getInternals();
+  const baseAst = internals.context.state.ast;
+  const orderBy = options.reverseOrder && baseAst.orderBy ? baseAst.orderBy.map((order) => ({
+    ...order,
+    direction: reverseDirection(order.direction)
+  })) : baseAst.orderBy;
+  const nextAst = {
+    ...baseAst,
+    where: options.predicate ? baseAst.where ? and(baseAst.where, options.predicate) : options.predicate : baseAst.where,
+    orderBy,
+    limit: options.limit
+  };
+  const nextContext = {
+    ...internals.context,
+    state: new SelectQueryState(builder.getTable(), nextAst)
+  };
+  return internals.clone(nextContext, internals.includeTree);
+}
+async function executeCursorQuery(builder, session, options) {
+  const { first, after, last, before } = options;
+  if (first != null && last != null) {
+    throw new Error('executeCursor: "first" and "last" cannot be used together');
+  }
+  if (after != null && before != null) {
+    throw new Error('executeCursor: "after" and "before" cannot be used together');
+  }
+  if (first == null && last == null) {
+    throw new Error('executeCursor: either "first" or "last" must be provided');
+  }
+  const limit = first ?? last;
+  if (!Number.isInteger(limit) || limit < 1) {
+    throw new Error(`executeCursor: "${first != null ? "first" : "last"}" must be an integer >= 1`);
+  }
+  const isBackward = last != null;
+  const cursor = after ?? before;
+  const ast = builder.getInternals().context.state.ast;
+  const specs = extractOrderSpecs(ast);
+  let predicate;
+  if (cursor) {
+    const decoded = decodeCursor(cursor);
+    const expectedSig = buildOrderSignature(specs);
+    if (decoded.orderSig !== expectedSig) {
+      throw new Error(
+        "executeCursor: cursor ORDER BY signature does not match the current query. The ORDER BY clause must remain the same between paginated requests."
+      );
+    }
+    predicate = buildKeysetPredicate(specs, decoded.values, isBackward ? "before" : "after");
+  }
+  const executionBuilder = createExecutionBuilder(builder, {
+    predicate,
+    limit: limit + 1,
+    reverseOrder: isBackward
+  });
+  const rows = await executionBuilder.execute(session);
+  const hasExtraItem = rows.length > limit;
+  if (hasExtraItem) {
+    rows.pop();
+  }
+  const orderedRows = isBackward ? rows.reverse() : rows;
+  const items = orderedRows;
+  const hasItems = items.length > 0;
+  const hasNextPage2 = hasItems ? isBackward ? before != null : hasExtraItem : false;
+  const hasPreviousPage = hasItems ? isBackward ? hasExtraItem : after != null : false;
+  const startCursor = hasItems ? buildCursorFromRow(items[0], specs) : null;
+  const endCursor = hasItems ? buildCursorFromRow(items[items.length - 1], specs) : null;
+  return {
+    items,
+    pageInfo: {
+      hasNextPage: hasNextPage2,
+      hasPreviousPage,
+      startCursor,
+      endCursor
+    }
+  };
+}
+
 // src/query-builder/select/from-facet.ts
 var SelectFromFacet = class {
   /**
@@ -8740,7 +8927,38 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
     return executePagedQuery(builder, session, options, (sess) => builder.count(sess));
   }
   /**
-   * Executes the query and returns an array of values for a single column.
+   * Executes the query using cursor-based (keyset) pagination.
+   * Requires a stable ORDER BY on selected, non-null columns.
+   * Cursor pagination currently supports simple column references only and
+   * the cursor token is opaque: it must be reused with the same ORDER BY signature.
+   *
+   * @param session - ORM session context
+   * @param options - Cursor pagination options (`first`/`after` or `last`/`before`)
+   * @returns Promise of cursor-paginated result with items and pageInfo
+   * @example
+   * const page1 = await selectFrom(users)
+   *   .orderBy(users.columns.createdAt, 'DESC')
+   *   .orderBy(users.columns.id, 'DESC')
+   *   .executeCursor(session, { first: 20 });
+   *
+   * // Next page
+   * const page2 = await selectFrom(users)
+   *   .orderBy(users.columns.createdAt, 'DESC')
+   *   .orderBy(users.columns.id, 'DESC')
+   *   .executeCursor(session, { first: 20, after: page1.pageInfo.endCursor });
+   *
+   * // Previous page from a known cursor
+   * const prevPage = await selectFrom(users)
+   *   .orderBy(users.columns.createdAt, 'DESC')
+   *   .orderBy(users.columns.id, 'DESC')
+   *   .executeCursor(session, { last: 20, before: page2.pageInfo.startCursor });
+   */
+  async executeCursor(session, options) {
+    const builder = this.ensureDefaultSelection();
+    return executeCursorQuery(builder, session, options);
+  }
+  /**
+    * Executes the query and returns an array of values for a single column.
    * This is a convenience method to avoid manual `.map(r => r.column)`.
    *
    * @param column - The column name to extract