metal-orm 1.1.7 → 1.1.9

package/src/orm/unit-of-work.ts

@@ -6,8 +6,8 @@ import { UpdateQueryBuilder } from '../query-builder/update.js';
 import { DeleteQueryBuilder } from '../query-builder/delete.js';
 import { findPrimaryKey } from '../query-builder/hydration-planner.js';
 import type { TableDef, TableHooks } from '../schema/table.js';
-import { payloadResultSets } from '../core/execution/db-executor.js';
-import type { DbExecutor, QueryResult } from '../core/execution/db-executor.js';
+import { payloadResultSets } from '../core/execution/db-executor.js';
+import type { DbExecutor, QueryResult } from '../core/execution/db-executor.js';
 import { IdentityMap } from './identity-map.js';
 import { EntityStatus } from './runtime-types.js';
 import type { TrackedEntity } from './runtime-types.js';
@@ -323,10 +323,10 @@ export class UnitOfWork {
    * @param compiled - The compiled query
    * @returns Query results
    */
-  private async executeCompiled(compiled: CompiledQuery): Promise<QueryResult[]> {
-    const payload = await this.executor.executeSql(compiled.sql, compiled.params);
-    return payloadResultSets(payload);
-  }
+  private async executeCompiled(compiled: CompiledQuery): Promise<QueryResult[]> {
+    const payload = await this.executor.executeSql(compiled.sql, compiled.params);
+    return payloadResultSets(payload);
+  }
 
   /**
    * Gets columns for RETURNING clause.

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.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/tree/tree-decorator.ts

@@ -5,8 +5,16 @@
  * Integrates with MetalORM's decorator entity system.
  */
 
-import type { TreeConfig } from './tree-types.js';
-import { resolveTreeConfig } from './tree-types.js';
+import type { TreeConfig } from './tree-types.js';
+import { resolveTreeConfig } from './tree-types.js';
+import { RelationKinds, belongsTo, hasMany } from '../schema/relation.js';
+import { addRelationMetadata, getEntityMetadata, type EntityConstructor } from '../orm/entity-metadata.js';
+import {
+  type DecoratorTreeMetadata,
+  getOrCreateMetadataBag,
+  readMetadataBag,
+  readMetadataBagFromConstructor
+} from '../decorators/decorator-metadata.js';
 
 /**
  * Symbol key for storing tree metadata on entity classes.
@@ -73,18 +81,25 @@ export interface TreeDecoratorOptions {
  * }
  * ```
  */
-export function Tree(options: TreeDecoratorOptions = {}) {
-  return function <T extends abstract new (...args: unknown[]) => object>(
-    target: T
-  ): T {
-    const config = resolveTreeConfig(options);
-    const metadata: TreeMetadata = { config };
-    
-    setTreeMetadataOnClass(target, metadata);
-    
-    return target;
-  };
-}
+export function Tree(options: TreeDecoratorOptions = {}) {
+  return function <T extends abstract new (...args: unknown[]) => object>(
+    target: T,
+    context: ClassDecoratorContext<T>
+  ): T {
+    const config = resolveTreeConfig(options);
+    const metadataBag = readMetadataBag(context) ?? readMetadataBagFromConstructor(target);
+    const metadata: TreeMetadata = {
+      config,
+      parentProperty: metadataBag?.tree?.parentProperty,
+      childrenProperty: metadataBag?.tree?.childrenProperty
+    };
+    
+    setTreeMetadataOnClass(target, metadata);
+    registerTreeRelations(target as unknown as EntityConstructor, metadata);
+    
+    return target;
+  };
+}
 
 /**
  * Decorator to mark a property as the parent relation in a tree entity.
@@ -95,23 +110,22 @@ export function Tree(options: TreeDecoratorOptions = {}) {
  * parent?: Category;
  * ```
  */
-export function TreeParent() {
-  return function <T, V>(
-    _value: undefined,
-    context: ClassFieldDecoratorContext<T, V>
-  ): void {
-    const propertyName = String(context.name);
-    
-    context.addInitializer(function (this: T) {
-      const constructor = (this as object).constructor as new (...args: unknown[]) => object;
-      const metadata = getTreeMetadata(constructor);
-      if (metadata) {
-        metadata.parentProperty = propertyName;
-        setTreeMetadata(constructor, metadata);
-      }
-    });
-  };
-}
+export function TreeParent() {
+  return function <T, V>(
+    _value: undefined,
+    context: ClassFieldDecoratorContext<T, V>
+  ): void {
+    if (!context.name) {
+      throw new Error('TreeParent decorator requires a property name');
+    }
+    if (context.private) {
+      throw new Error('TreeParent decorator does not support private fields');
+    }
+    const propertyName = String(context.name);
+    const bag = getOrCreateMetadataBag(context);
+    bag.tree = { ...bag.tree, parentProperty: propertyName };
+  };
+}
 
 /**
  * Decorator to mark a property as the children relation in a tree entity.
@@ -122,23 +136,54 @@ export function TreeParent() {
  * children?: Category[];
  * ```
  */
-export function TreeChildren() {
-  return function <T, V>(
-    _value: undefined,
-    context: ClassFieldDecoratorContext<T, V>
-  ): void {
-    const propertyName = String(context.name);
-    
-    context.addInitializer(function (this: T) {
-      const constructor = (this as object).constructor as new (...args: unknown[]) => object;
-      const metadata = getTreeMetadata(constructor);
-      if (metadata) {
-        metadata.childrenProperty = propertyName;
-        setTreeMetadata(constructor, metadata);
-      }
-    });
-  };
-}
+export function TreeChildren() {
+  return function <T, V>(
+    _value: undefined,
+    context: ClassFieldDecoratorContext<T, V>
+  ): void {
+    if (!context.name) {
+      throw new Error('TreeChildren decorator requires a property name');
+    }
+    if (context.private) {
+      throw new Error('TreeChildren decorator does not support private fields');
+    }
+    const propertyName = String(context.name);
+    const bag = getOrCreateMetadataBag(context);
+    bag.tree = { ...bag.tree, childrenProperty: propertyName };
+  };
+}
+
+/**
+ * Synchronizes tree metadata + self-relations for entities using @Tree decorators.
+ * Safe to call multiple times (idempotent).
+ */
+export function syncTreeEntityMetadata(
+  ctor: EntityConstructor,
+  treeMetadata?: DecoratorTreeMetadata
+): void {
+  const current = getTreeMetadata(ctor);
+  if (!current) return;
+  const metadataBag = readMetadataBagFromConstructor(ctor);
+
+  const nextParentProperty =
+    treeMetadata?.parentProperty ?? metadataBag?.tree?.parentProperty ?? current.parentProperty;
+  const nextChildrenProperty =
+    treeMetadata?.childrenProperty ?? metadataBag?.tree?.childrenProperty ?? current.childrenProperty;
+
+  if (nextParentProperty !== current.parentProperty || nextChildrenProperty !== current.childrenProperty) {
+    setTreeMetadata(ctor, {
+      ...current,
+      parentProperty: nextParentProperty,
+      childrenProperty: nextChildrenProperty
+    });
+  }
+
+  registerTreeRelations(ctor, {
+    ...current,
+    parentProperty: nextParentProperty,
+    childrenProperty: nextChildrenProperty
+  });
+}
 
 /**
  * Gets tree metadata from an entity class.
@@ -152,12 +197,50 @@ export function getTreeMetadata(
 /**
  * Sets tree metadata on an entity class.
  */
-export function setTreeMetadata(
-  target: new (...args: unknown[]) => object,
-  metadata: TreeMetadata
-): void {
-  (target as unknown as Record<symbol, TreeMetadata>)[TREE_METADATA_KEY] = metadata;
-}
+export function setTreeMetadata(
+  target: new (...args: unknown[]) => object,
+  metadata: TreeMetadata
+): void {
+  (target as unknown as Record<symbol, TreeMetadata>)[TREE_METADATA_KEY] = metadata;
+}
+
+const registerTreeRelations = (
+  target: EntityConstructor,
+  metadata: TreeMetadata
+): void => {
+  const entityMeta = getEntityMetadata(target);
+  if (!entityMeta) return;
+
+  if (metadata.parentProperty && !entityMeta.relations[metadata.parentProperty]) {
+    addRelationMetadata(target, metadata.parentProperty, {
+      kind: RelationKinds.BelongsTo,
+      propertyKey: metadata.parentProperty,
+      target: () => target,
+      foreignKey: metadata.config.parentKey
+    });
+    if (entityMeta.table && !entityMeta.table.relations[metadata.parentProperty]) {
+      entityMeta.table.relations[metadata.parentProperty] = belongsTo(
+        entityMeta.table,
+        metadata.config.parentKey
+      );
+    }
+  }
+
+  if (metadata.childrenProperty && !entityMeta.relations[metadata.childrenProperty]) {
+    addRelationMetadata(target, metadata.childrenProperty, {
+      kind: RelationKinds.HasMany,
+      propertyKey: metadata.childrenProperty,
+      target: () => target,
+      foreignKey: metadata.config.parentKey
+    });
+    if (entityMeta.table && !entityMeta.table.relations[metadata.childrenProperty]) {
+      entityMeta.table.relations[metadata.childrenProperty] = hasMany(
+        entityMeta.table,
+        metadata.config.parentKey
+      );
+    }
+  }
+};
 
 /**
  * Sets tree metadata on an entity class (internal, handles abstract classes).