metal-orm 1.1.8 → 1.1.10

package/src/query-builder/select/cursor-pagination.ts

@@ -0,0 +1,323 @@
+import { TableDef } from '../../schema/table.js';
+import { SelectQueryNode, OrderByNode } from '../../core/ast/query.js';
+import {
+  ColumnNode,
+  LiteralNode,
+  ExpressionNode,
+  and,
+  or
+} from '../../core/ast/expression.js';
+import { OrmSession } from '../../orm/orm-session.js';
+import { SelectQueryState } from '../select-query-state.js';
+import type { SelectQueryBuilder } from '../select.js';
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export type CursorPageOptions = {
+  first?: number;
+  after?: string;
+  last?: number;
+  before?: string;
+};
+
+export type CursorPageInfo = {
+  hasNextPage: boolean;
+  hasPreviousPage: boolean;
+  startCursor: string | null;
+  endCursor: string | null;
+};
+
+export type CursorPageResult<T> = {
+  items: T[];
+  pageInfo: CursorPageInfo;
+};
+
+// ---------------------------------------------------------------------------
+// Internal types
+// ---------------------------------------------------------------------------
+
+interface CursorOrderSpec {
+  table: string;
+  column: string;
+  valueKey: string;
+  direction: 'ASC' | 'DESC';
+}
+
+interface EncodedCursor {
+  v: 2;
+  values: unknown[];
+  orderSig: string;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+export function encodeCursor(payload: EncodedCursor): string {
+  return Buffer.from(JSON.stringify(payload)).toString('base64url');
+}
+
+export function decodeCursor(cursor: string): EncodedCursor {
+  let parsed: unknown;
+  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 as EncodedCursor).v !== 2 ||
+    !Array.isArray((parsed as EncodedCursor).values) ||
+    typeof (parsed as EncodedCursor).orderSig !== 'string'
+  ) {
+    throw new Error('executeCursor: invalid cursor payload');
+  }
+  return parsed as EncodedCursor;
+}
+
+export function buildOrderSignature(specs: CursorOrderSpec[]): string {
+  return specs.map(s => `${s.table}.${s.column}:${s.direction}`).join(',');
+}
+
+function extractOrderSpecs(ast: SelectQueryNode): CursorOrderSpec[] {
+  if (!ast.orderBy || ast.orderBy.length === 0) {
+    throw new Error('executeCursor: ORDER BY is required for cursor pagination');
+  }
+
+  return ast.orderBy.map((ob: OrderByNode) => {
+    if (ob.nulls) {
+      throw new Error('executeCursor: NULLS FIRST/LAST is not supported for cursor pagination');
+    }
+    const term = ob.term;
+    if (!term || (term as ColumnNode).type !== 'Column') {
+      throw new Error(
+        'executeCursor: only column references are supported in ORDER BY for cursor pagination'
+      );
+    }
+    const col = term as ColumnNode;
+    return {
+      table: col.table,
+      column: col.name,
+      valueKey: resolveOrderValueKey(ast, col),
+      direction: ob.direction
+    };
+  });
+}
+
+function resolveOrderValueKey(ast: SelectQueryNode, col: ColumnNode): string {
+  const projectedColumn = ast.columns.find((candidate): candidate is ColumnNode =>
+    candidate.type === 'Column' &&
+    candidate.table === col.table &&
+    candidate.name === col.name
+  );
+
+  return projectedColumn?.alias ?? projectedColumn?.name ?? col.alias ?? col.name;
+}
+
+export function buildKeysetPredicate(
+  specs: CursorOrderSpec[],
+  values: unknown[],
+  mode: 'after' | 'before'
+): ExpressionNode {
+  if (values.length !== specs.length) {
+    throw new Error('executeCursor: invalid cursor payload');
+  }
+
+  // For a multi-column keyset (c1 DESC, c2 DESC) with mode='after':
+  //   (c1 < v1) OR (c1 = v1 AND c2 < v2)
+  // 'after' on DESC → use '<'; 'after' on ASC → use '>'
+  // 'before' inverts the operators.
+
+  const branches: ExpressionNode[] = [];
+
+  for (let i = 0; i < specs.length; i++) {
+    const spec = specs[i];
+    const colNode: ColumnNode = { type: 'Column', table: spec.table, name: spec.column };
+    const value = values[i];
+    if (value === null || value === undefined) {
+      throw new Error('executeCursor: invalid cursor payload');
+    }
+    const literal: LiteralNode = { type: 'Literal', value: value as LiteralNode['value'] };
+
+    // Determine the comparison operator for the "breaking" column
+    let operator: '>' | '<';
+    if (mode === 'after') {
+      operator = spec.direction === 'ASC' ? '>' : '<';
+    } else {
+      operator = spec.direction === 'ASC' ? '<' : '>';
+    }
+
+    // Build equality prefix: c0 = v0 AND c1 = v1 AND ... AND c(i-1) = v(i-1)
+    const eqParts: ExpressionNode[] = [];
+    for (let j = 0; j < i; j++) {
+      const prevSpec = specs[j];
+      const prevCol: ColumnNode = { type: 'Column', table: prevSpec.table, name: prevSpec.column };
+      const prevValue = values[j];
+      if (prevValue === null || prevValue === undefined) {
+        throw new Error('executeCursor: invalid cursor payload');
+      }
+      const prevVal: LiteralNode = { type: 'Literal', value: prevValue as LiteralNode['value'] };
+      eqParts.push({
+        type: 'BinaryExpression',
+        left: prevCol,
+        operator: '=',
+        right: prevVal
+      });
+    }
+
+    // The "breaking" comparison: ci <op> vi
+    const breakExpr: ExpressionNode = {
+      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: Record<string, unknown>, specs: CursorOrderSpec[]): string {
+  const values = specs.map(spec => {
+    const value = row[spec.valueKey];
+    if (value === null || value === undefined) {
+      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: 'ASC' | 'DESC'): 'ASC' | 'DESC' {
+  return direction === 'ASC' ? 'DESC' : 'ASC';
+}
+
+function createExecutionBuilder<T, TTable extends TableDef>(
+  builder: SelectQueryBuilder<T, TTable>,
+  options: {
+    predicate?: ExpressionNode;
+    limit: number;
+    reverseOrder: boolean;
+  }
+): SelectQueryBuilder<T, TTable> {
+  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: SelectQueryNode = {
+    ...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);
+}
+
+// ---------------------------------------------------------------------------
+// Main executor
+// ---------------------------------------------------------------------------
+
+export async function executeCursorQuery<T, TTable extends TableDef>(
+  builder: SelectQueryBuilder<T, TTable>,
+  session: OrmSession,
+  options: CursorPageOptions
+): Promise<CursorPageResult<T>> {
+  const { first, after, last, before } = options;
+
+  // --- Validation ---
+  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;
+
+  // --- Extract order specs from builder AST ---
+  const ast = builder.getInternals().context.state.ast;
+  const specs = extractOrderSpecs(ast);
+
+  // --- Apply cursor predicate if present ---
+  let predicate: ExpressionNode | undefined;
+  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');
+  }
+
+  // --- Fetch limit + 1 to detect hasNextPage ---
+  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 as (T & Record<string, unknown>)[];
+  const hasItems = items.length > 0;
+  const hasNextPage = hasItems
+    ? (isBackward ? before != null : hasExtraItem)
+    : false;
+  const hasPreviousPage = hasItems
+    ? (isBackward ? hasExtraItem : after != null)
+    : false;
+
+  const startCursor = hasItems
+    ? buildCursorFromRow(items[0] as Record<string, unknown>, specs)
+    : null;
+  const endCursor = hasItems
+    ? buildCursorFromRow(items[items.length - 1] as Record<string, unknown>, specs)
+    : null;
+
+  return {
+    items,
+    pageInfo: {
+      hasNextPage,
+      hasPreviousPage,
+      startCursor,
+      endCursor
+    }
+  };
+}

package/src/query-builder/select/select-operations.ts

@@ -1,4 +1,5 @@
 import { TableDef } from '../../schema/table.js';
+import { isSingleTargetRelation } from '../../schema/relation.js';
 import { ColumnDef } from '../../schema/column-types.js';
 import { OrderingTerm, SelectQueryNode } from '../../core/ast/query.js';
 import { ColumnNode, FunctionNode, ExpressionNode, exists, notExists } from '../../core/ast/expression.js';
@@ -12,35 +13,35 @@ import { OrmSession } from '../../orm/orm-session.js';
 import type { SelectQueryBuilder } from '../select.js';
 import { findPrimaryKey } from '../hydration-planner.js';
 import { payloadResultSets } from '../../core/execution/db-executor.js';
-
-export type WhereHasOptions = {
-  correlate?: ExpressionNode;
-};
-
-export type RelationCallback = <TChildTable extends TableDef>(
-  qb: SelectQueryBuilder<unknown, TChildTable>
-) => SelectQueryBuilder<unknown, TChildTable>;
-
-type ChildBuilderFactory = <R, TChild extends TableDef>(table: TChild) => SelectQueryBuilder<R, TChild>;
-
-/**
- * Builds a new query context with an ORDER BY clause applied.
- */
-export function applyOrderBy(
-  context: SelectQueryBuilderContext,
-  predicateFacet: SelectPredicateFacet,
-  term: ColumnDef | OrderingTerm,
-  directionOrOptions: OrderDirection | { direction?: OrderDirection; nulls?: 'FIRST' | 'LAST'; collation?: string }
-): SelectQueryBuilderContext {
-  const options =
-    typeof directionOrOptions === 'string' ? { direction: directionOrOptions } : directionOrOptions;
-  const dir = options.direction ?? ORDER_DIRECTIONS.ASC;
-  return predicateFacet.orderBy(context, term, dir, options.nulls, options.collation);
-}
-
-/**
- * Runs the count query for the provided context and session.
- */
+
+export type WhereHasOptions = {
+  correlate?: ExpressionNode;
+};
+
+export type RelationCallback = <TChildTable extends TableDef>(
+  qb: SelectQueryBuilder<unknown, TChildTable>
+) => SelectQueryBuilder<unknown, TChildTable>;
+
+type ChildBuilderFactory = <R, TChild extends TableDef>(table: TChild) => SelectQueryBuilder<R, TChild>;
+
+/**
+ * Builds a new query context with an ORDER BY clause applied.
+ */
+export function applyOrderBy(
+  context: SelectQueryBuilderContext,
+  predicateFacet: SelectPredicateFacet,
+  term: ColumnDef | OrderingTerm,
+  directionOrOptions: OrderDirection | { direction?: OrderDirection; nulls?: 'FIRST' | 'LAST'; collation?: string }
+): SelectQueryBuilderContext {
+  const options =
+    typeof directionOrOptions === 'string' ? { direction: directionOrOptions } : directionOrOptions;
+  const dir = options.direction ?? ORDER_DIRECTIONS.ASC;
+  return predicateFacet.orderBy(context, term, dir, options.nulls, options.collation);
+}
+
+/**
+ * Runs the count query for the provided context and session.
+ */
 export async function executeCount(
   context: SelectQueryBuilderContext,
   env: SelectQueryBuilderEnvironment,
@@ -103,10 +104,10 @@ export async function executeCount(
   const payload = await execCtx.interceptors.run({ sql: compiled.sql, params: compiled.params }, execCtx.executor);
   const results = payloadResultSets(payload);
   const value = results[0]?.values?.[0]?.[0];
-
-  if (typeof value === 'number') return value;
-  if (typeof value === 'bigint') return Number(value);
-  if (typeof value === 'string') return Number(value);
+
+  if (typeof value === 'number') return value;
+  if (typeof value === 'bigint') return Number(value);
+  if (typeof value === 'string') return Number(value);
   return value === null || value === undefined ? 0 : Number(value);
 }
 
@@ -156,75 +157,79 @@ export async function executeCountRows(
   if (typeof value === 'string') return Number(value);
   return value === null || value === undefined ? 0 : Number(value);
 }
-
-export interface PaginatedResult<T> {
-  items: T[];
-  totalItems: number;
-  page: number;
-  pageSize: number;
-}
-
-/**
- * Executes paged queries using the provided builder helpers.
- */
-export async function executePagedQuery<T, TTable extends TableDef>(
-  builder: SelectQueryBuilder<T, TTable>,
-  session: OrmSession,
-  options: { page: number; pageSize: number },
-  countCallback: (session: OrmSession) => Promise<number>
-): Promise<PaginatedResult<T>> {
-  const { page, pageSize } = options;
-
-  if (!Number.isInteger(page) || page < 1) {
-    throw new Error('executePaged: page must be an integer >= 1');
-  }
-  if (!Number.isInteger(pageSize) || pageSize < 1) {
-    throw new Error('executePaged: pageSize must be an integer >= 1');
-  }
-
-  const offset = (page - 1) * pageSize;
-
-  const totalItems = await countCallback(session);
-  const items = await builder.limit(pageSize).offset(offset).execute(session);
-
-  return { items, totalItems, page, pageSize };
-}
-
-/**
- * Builds an EXISTS or NOT EXISTS predicate for a related table.
- */
-export function buildWhereHasPredicate<TTable extends TableDef>(
-  env: SelectQueryBuilderEnvironment,
-  context: SelectQueryBuilderContext,
-  relationFacet: SelectRelationFacet,
-  createChildBuilder: ChildBuilderFactory,
-  relationName: keyof TTable['relations'] & string,
-  callbackOrOptions?: RelationCallback | WhereHasOptions,
-  maybeOptions?: WhereHasOptions,
-  negate = false
-): ExpressionNode {
-  const relation = env.table.relations[relationName as string];
-  if (!relation) {
-    throw new Error(`Relation '${relationName}' not found on table '${env.table.name}'`);
-  }
-
-  const callback = typeof callbackOrOptions === 'function' ? callbackOrOptions : undefined;
-  const options = (typeof callbackOrOptions === 'function' ? maybeOptions : callbackOrOptions) as
-    | WhereHasOptions
-    | undefined;
-
-  let subQb = createChildBuilder<unknown, TableDef>(relation.target);
-  if (callback) {
-    subQb = callback(subQb);
-  }
-
-  const subAst = subQb.getAST();
-  const finalSubAst = relationFacet.applyRelationCorrelation(
-    context,
-    relationName,
-    subAst,
-    options?.correlate
-  );
-
-  return negate ? notExists(finalSubAst) : exists(finalSubAst);
-}
+
+export interface PaginatedResult<T> {
+  items: T[];
+  totalItems: number;
+  page: number;
+  pageSize: number;
+}
+
+/**
+ * Executes paged queries using the provided builder helpers.
+ */
+export async function executePagedQuery<T, TTable extends TableDef>(
+  builder: SelectQueryBuilder<T, TTable>,
+  session: OrmSession,
+  options: { page: number; pageSize: number },
+  countCallback: (session: OrmSession) => Promise<number>
+): Promise<PaginatedResult<T>> {
+  const { page, pageSize } = options;
+
+  if (!Number.isInteger(page) || page < 1) {
+    throw new Error('executePaged: page must be an integer >= 1');
+  }
+  if (!Number.isInteger(pageSize) || pageSize < 1) {
+    throw new Error('executePaged: pageSize must be an integer >= 1');
+  }
+
+  const offset = (page - 1) * pageSize;
+
+  const totalItems = await countCallback(session);
+  const items = await builder.limit(pageSize).offset(offset).execute(session);
+
+  return { items, totalItems, page, pageSize };
+}
+
+/**
+ * Builds an EXISTS or NOT EXISTS predicate for a related table.
+ */
+export function buildWhereHasPredicate<TTable extends TableDef>(
+  env: SelectQueryBuilderEnvironment,
+  context: SelectQueryBuilderContext,
+  relationFacet: SelectRelationFacet,
+  createChildBuilder: ChildBuilderFactory,
+  relationName: keyof TTable['relations'] & string,
+  callbackOrOptions?: RelationCallback | WhereHasOptions,
+  maybeOptions?: WhereHasOptions,
+  negate = false
+): ExpressionNode {
+  const relation = env.table.relations[relationName as string];
+  if (!relation) {
+    throw new Error(`Relation '${relationName}' not found on table '${env.table.name}'`);
+  }
+
+  const callback = typeof callbackOrOptions === 'function' ? callbackOrOptions : undefined;
+  const options = (typeof callbackOrOptions === 'function' ? maybeOptions : callbackOrOptions) as
+    | WhereHasOptions
+    | undefined;
+
+  if (!isSingleTargetRelation(relation)) {
+    throw new Error(`Polymorphic relation '${relationName}' does not support whereHas/whereHasNot`);
+  }
+
+  let subQb = createChildBuilder<unknown, TableDef>(relation.target);
+  if (callback) {
+    subQb = callback(subQb);
+  }
+
+  const subAst = subQb.getAST();
+  const finalSubAst = relationFacet.applyRelationCorrelation(
+    context,
+    relationName,
+    subAst,
+    options?.correlate
+  );
+
+  return negate ? notExists(finalSubAst) : exists(finalSubAst);
+}

package/src/query-builder/select.ts

@@ -61,6 +61,12 @@ import {
   WhereHasOptions
 } from './select/select-operations.js';
 export type { PaginatedResult };
+import {
+  executeCursorQuery,
+  CursorPageOptions,
+  CursorPageResult
+} from './select/cursor-pagination.js';
+export type { CursorPageOptions, CursorPageResult, CursorPageInfo } from './select/cursor-pagination.js';
 import { SelectFromFacet } from './select/from-facet.js';
 import { SelectJoinFacet } from './select/join-facet.js';
 import { SelectProjectionFacet } from './select/projection-facet.js';
@@ -946,7 +952,42 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
   }
 
   /**
-   * 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: OrmSession,
+    options: CursorPageOptions
+  ): Promise<CursorPageResult<T>> {
+    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

package/src/query-builder/update-include.ts

@@ -1,5 +1,6 @@
 import { JOIN_KINDS } from '../core/sql/sql.js';
 import type { TableDef } from '../schema/table.js';
+import { isSingleTargetRelation } from '../schema/relation.js';
 import { findJoinByRelationKey, findJoinIndexByRelationKey } from './join-utils.js';
 import { addRelationJoin, updateRelationJoin } from './relation-join-strategies.js';
 import { getExposedName } from './table-alias-utils.js';
@@ -92,6 +93,9 @@ export const updateInclude = <T, TTable extends TableDef>(
       });
     }
 
+    if (!isSingleTargetRelation(relation)) {
+      continue;
+    }
     const joinForSegment = findJoinByRelationKey(state.ast.joins, relationKey);
     currentAlias = joinForSegment ? (getExposedName(joinForSegment.table) ?? relation.target.name) : relation.target.name;
     currentTable = relation.target;