metal-orm 1.0.83 → 1.0.86

package/src/core/ast/query-visitor.ts

@@ -0,0 +1,273 @@
+import type {
+  CommonTableExpressionNode,
+  DerivedTableNode,
+  FunctionTableNode,
+  OrderByNode,
+  OrderingTerm,
+  SelectQueryNode,
+  SetOperationNode,
+  TableSourceNode
+} from './query.js';
+import type { JoinNode } from './join.js';
+import type {
+  ExpressionNode,
+  OperandNode,
+  ParamNode
+} from './expression-nodes.js';
+import { isOperandNode } from './expression-nodes.js';
+import {
+  hasOperandDispatcher,
+  type ExpressionVisitor,
+  type OperandVisitor,
+  visitExpression,
+  visitOperand
+} from './expression-visitor.js';
+
+export interface SelectQueryVisitor {
+  visitSelectQuery?(node: SelectQueryNode): void;
+  visitTableSource?(node: TableSourceNode): void;
+  visitDerivedTable?(node: DerivedTableNode): void;
+  visitFunctionTable?(node: FunctionTableNode): void;
+  visitJoin?(node: JoinNode): void;
+  visitCte?(node: CommonTableExpressionNode): void;
+  visitSetOperation?(node: SetOperationNode): void;
+  visitOrderBy?(node: OrderByNode): void;
+  visitExpression?(node: ExpressionNode): void;
+  visitOperand?(node: OperandNode): void;
+  visitParam?(node: ParamNode): void;
+}
+
+const getNodeType = (value: unknown): string | undefined => {
+  if (typeof value !== 'object' || value === null) return undefined;
+  const descriptor = Object.getOwnPropertyDescriptor(value, 'type');
+  if (descriptor && typeof descriptor.value === 'string') {
+    return descriptor.value;
+  }
+  if ('type' in value) {
+    const type = (value as { type?: unknown }).type;
+    return typeof type === 'string' ? type : undefined;
+  }
+  return undefined;
+};
+
+export const visitSelectQuery = (ast: SelectQueryNode, visitor: SelectQueryVisitor): void => {
+  const visitExpressionNode = (node: ExpressionNode): void => {
+    visitExpression(node, expressionVisitor);
+  };
+
+  const visitOperandNode = (node: OperandNode): void => {
+    visitOperand(node, operandVisitor);
+  };
+
+  const visitOrderingTerm = (term: OrderingTerm): void => {
+    if (!term || typeof term !== 'object') return;
+    if (isOperandNode(term)) {
+      visitOperandNode(term);
+      return;
+    }
+    const type = getNodeType(term);
+    if (type && hasOperandDispatcher(type)) {
+      visitOperandNode(term as unknown as OperandNode);
+      return;
+    }
+    if (type) {
+      visitExpressionNode(term as ExpressionNode);
+    }
+  };
+
+  const visitOrderByNode = (node: OrderByNode): void => {
+    visitor.visitOrderBy?.(node);
+    visitOrderingTerm(node.term);
+  };
+
+  const visitTableSource = (source: TableSourceNode): void => {
+    visitor.visitTableSource?.(source);
+    if (source.type === 'DerivedTable') {
+      visitor.visitDerivedTable?.(source);
+      visitSelectQuery(source.query, visitor);
+      return;
+    }
+    if (source.type === 'FunctionTable') {
+      visitor.visitFunctionTable?.(source);
+      source.args?.forEach(arg => visitOperandNode(arg));
+    }
+  };
+
+  const expressionVisitor: ExpressionVisitor<void> = {
+    visitBinaryExpression: (node) => {
+      visitor.visitExpression?.(node);
+      visitOperandNode(node.left);
+      visitOperandNode(node.right);
+      if (node.escape) {
+        visitOperandNode(node.escape);
+      }
+    },
+    visitLogicalExpression: (node) => {
+      visitor.visitExpression?.(node);
+      node.operands.forEach(operand => visitExpressionNode(operand));
+    },
+    visitNullExpression: (node) => {
+      visitor.visitExpression?.(node);
+      visitOperandNode(node.left);
+    },
+    visitInExpression: (node) => {
+      visitor.visitExpression?.(node);
+      visitOperandNode(node.left);
+      if (Array.isArray(node.right)) {
+        node.right.forEach(operand => visitOperandNode(operand));
+      } else {
+        visitOperandNode(node.right);
+      }
+    },
+    visitExistsExpression: (node) => {
+      visitor.visitExpression?.(node);
+      visitSelectQuery(node.subquery, visitor);
+    },
+    visitBetweenExpression: (node) => {
+      visitor.visitExpression?.(node);
+      visitOperandNode(node.left);
+      visitOperandNode(node.lower);
+      visitOperandNode(node.upper);
+    },
+    visitArithmeticExpression: (node) => {
+      visitor.visitExpression?.(node);
+      visitOperandNode(node.left);
+      visitOperandNode(node.right);
+    },
+    visitBitwiseExpression: (node) => {
+      visitor.visitExpression?.(node);
+      visitOperandNode(node.left);
+      visitOperandNode(node.right);
+    },
+    visitOperand: (node) => {
+      visitOperandNode(node);
+    },
+    visitSelectQuery: (node) => {
+      visitSelectQuery(node, visitor);
+    },
+    otherwise: (node) => {
+      visitor.visitExpression?.(node);
+    }
+  };
+
+  const operandVisitor: OperandVisitor<void> = {
+    visitColumn: (node) => {
+      visitor.visitOperand?.(node);
+    },
+    visitLiteral: (node) => {
+      visitor.visitOperand?.(node);
+    },
+    visitParam: (node) => {
+      visitor.visitOperand?.(node);
+      visitor.visitParam?.(node);
+    },
+    visitFunction: (node) => {
+      visitor.visitOperand?.(node);
+      node.args?.forEach(arg => visitOperandNode(arg));
+      node.orderBy?.forEach(order => visitOrderByNode(order));
+      if (node.separator) {
+        visitOperandNode(node.separator);
+      }
+    },
+    visitJsonPath: (node) => {
+      visitor.visitOperand?.(node);
+      visitOperandNode(node.column);
+    },
+    visitScalarSubquery: (node) => {
+      visitor.visitOperand?.(node);
+      visitSelectQuery(node.query, visitor);
+    },
+    visitCaseExpression: (node) => {
+      visitor.visitOperand?.(node);
+      node.conditions.forEach(cond => {
+        visitExpressionNode(cond.when);
+        visitOperandNode(cond.then);
+      });
+      if (node.else) {
+        visitOperandNode(node.else);
+      }
+    },
+    visitCast: (node) => {
+      visitor.visitOperand?.(node);
+      visitOperandNode(node.expression);
+    },
+    visitWindowFunction: (node) => {
+      visitor.visitOperand?.(node);
+      node.args?.forEach(arg => visitOperandNode(arg));
+      node.partitionBy?.forEach(term => visitOperandNode(term));
+      node.orderBy?.forEach(order => visitOrderByNode(order));
+    },
+    visitArithmeticExpression: (node) => {
+      visitor.visitOperand?.(node);
+      visitOperandNode(node.left);
+      visitOperandNode(node.right);
+    },
+    visitBitwiseExpression: (node) => {
+      visitor.visitOperand?.(node);
+      visitOperandNode(node.left);
+      visitOperandNode(node.right);
+    },
+    visitExpression: (node) => {
+      visitExpressionNode(node);
+    },
+    visitSelectQuery: (node) => {
+      visitSelectQuery(node, visitor);
+    },
+    visitCollate: (node) => {
+      visitor.visitOperand?.(node);
+      visitOperandNode(node.expression);
+    },
+    visitAliasRef: (node) => {
+      visitor.visitOperand?.(node);
+    },
+    otherwise: (node) => {
+      visitor.visitOperand?.(node);
+    }
+  };
+
+  visitor.visitSelectQuery?.(ast);
+
+  if (ast.ctes) {
+    for (const cte of ast.ctes) {
+      visitor.visitCte?.(cte);
+      visitSelectQuery(cte.query, visitor);
+    }
+  }
+
+  visitTableSource(ast.from);
+
+  ast.columns?.forEach(col => {
+    visitOperandNode(col as OperandNode);
+  });
+
+  ast.joins?.forEach(join => {
+    visitor.visitJoin?.(join);
+    visitTableSource(join.table);
+    visitExpressionNode(join.condition);
+  });
+
+  if (ast.where) {
+    visitExpressionNode(ast.where);
+  }
+
+  ast.groupBy?.forEach(term => {
+    visitOrderingTerm(term);
+  });
+
+  if (ast.having) {
+    visitExpressionNode(ast.having);
+  }
+
+  ast.orderBy?.forEach(order => {
+    visitOrderByNode(order);
+  });
+
+  ast.distinct?.forEach(col => {
+    visitOperandNode(col);
+  });
+
+  ast.setOps?.forEach(op => {
+    visitor.visitSetOperation?.(op);
+    visitSelectQuery(op.query, visitor);
+  });
+};

package/src/core/dialect/abstract.ts

@@ -387,13 +387,17 @@ export abstract class Dialect
    * @param ctx - Compiler context
    * @returns Compiled SQL operand
    */
-  protected compileOperand(node: OperandNode, ctx: CompilerContext): string {
-    const compiler = this.operandCompilers.get(node.type);
-    if (!compiler) {
-      throw new Error(`Unsupported operand node type "${node.type}" for ${this.constructor.name}`);
-    }
-    return compiler(node, ctx);
-  }
+  protected compileOperand(node: OperandNode, ctx: CompilerContext): string {
+    const descriptor = Object.getOwnPropertyDescriptor(node, 'type');
+    const nodeType = typeof descriptor?.value === 'string'
+      ? descriptor.value
+      : (typeof node.type === 'string' ? node.type : undefined);
+    const compiler = nodeType ? this.operandCompilers.get(nodeType) : undefined;
+    if (!compiler) {
+      throw new Error(`Unsupported operand node type "${nodeType ?? 'unknown'}" for ${this.constructor.name}`);
+    }
+    return compiler(node, ctx);
+  }
 
   /**
    * Compiles an ordering term (operand, expression, or alias reference).

package/src/orm/execute.ts

@@ -22,9 +22,13 @@ import {
   loadBelongsToManyRelation
 } from './lazy-batch.js';
 
-type Row = Record<string, unknown>;
-
-const flattenResults = (results: { columns: string[]; values: unknown[][] }[]): Row[] => {
+type Row = Record<string, unknown>;
+
+type ParamOperandOptions = {
+  allowParamOperands?: boolean;
+};
+
+const flattenResults = (results: { columns: string[]; values: unknown[][] }[]): Row[] => {
   const rows: Row[] = [];
   for (const result of results) {
     const { columns, values } = result;
@@ -39,13 +43,16 @@ const flattenResults = (results: { columns: string[]; values: unknown[][] }[]):
   return rows;
 };
 
-const executeWithContexts = async <TTable extends TableDef>(
-  execCtx: ExecutionContext,
-  entityCtx: EntityContext,
-  qb: SelectQueryBuilder<unknown, TTable>
-): Promise<EntityInstance<TTable>[]> => {
-  const ast = qb.getAST();
-  const compiled = execCtx.dialect.compileSelect(ast);
+const executeWithContexts = async <TTable extends TableDef>(
+  execCtx: ExecutionContext,
+  entityCtx: EntityContext,
+  qb: SelectQueryBuilder<unknown, TTable>,
+  options?: ParamOperandOptions
+): Promise<EntityInstance<TTable>[]> => {
+  const ast = qb.getAST();
+  const compiled = options?.allowParamOperands
+    ? execCtx.dialect.compileSelectWithOptions(ast, { allowParams: true })
+    : execCtx.dialect.compileSelect(ast);
   const executed = await execCtx.interceptors.run({ sql: compiled.sql, params: compiled.params }, execCtx.executor);
   const rows = flattenResults(executed);
   const lazyRelations = qb.getLazyRelations() as RelationKey<TTable>[];
@@ -66,13 +73,16 @@ const executeWithContexts = async <TTable extends TableDef>(
   return entities;
 };
 
-const executePlainWithContexts = async <TTable extends TableDef>(
-  execCtx: ExecutionContext,
-  qb: SelectQueryBuilder<unknown, TTable>
-): Promise<Record<string, unknown>[]> => {
-  const ast = qb.getAST();
-  const compiled = execCtx.dialect.compileSelect(ast);
-  const executed = await execCtx.interceptors.run({ sql: compiled.sql, params: compiled.params }, execCtx.executor);
+const executePlainWithContexts = async <TTable extends TableDef>(
+  execCtx: ExecutionContext,
+  qb: SelectQueryBuilder<unknown, TTable>,
+  options?: ParamOperandOptions
+): Promise<Record<string, unknown>[]> => {
+  const ast = qb.getAST();
+  const compiled = options?.allowParamOperands
+    ? execCtx.dialect.compileSelectWithOptions(ast, { allowParams: true })
+    : execCtx.dialect.compileSelect(ast);
+  const executed = await execCtx.interceptors.run({ sql: compiled.sql, params: compiled.params }, execCtx.executor);
   const rows = flattenResults(executed);
 
   if (ast.setOps && ast.setOps.length > 0) {
@@ -89,12 +99,13 @@ const executePlainWithContexts = async <TTable extends TableDef>(
  * @param qb - The select query builder
  * @returns Promise resolving to array of entity instances
  */
-export async function executeHydrated<TTable extends TableDef>(
-  session: OrmSession,
-  qb: SelectQueryBuilder<unknown, TTable>
-): Promise<EntityInstance<TTable>[]> {
-  return executeWithContexts(session.getExecutionContext(), session, qb);
-}
+export async function executeHydrated<TTable extends TableDef>(
+  session: OrmSession,
+  qb: SelectQueryBuilder<unknown, TTable>,
+  options?: ParamOperandOptions
+): Promise<EntityInstance<TTable>[]> {
+  return executeWithContexts(session.getExecutionContext(), session, qb, options);
+}
 
 /**
  * Executes a hydrated query and returns plain row objects (no entity proxies).
@@ -103,12 +114,13 @@ export async function executeHydrated<TTable extends TableDef>(
  * @param qb - The select query builder
  * @returns Promise resolving to array of plain row objects
  */
-export async function executeHydratedPlain<TTable extends TableDef>(
-  session: OrmSession,
-  qb: SelectQueryBuilder<unknown, TTable>
-): Promise<Record<string, unknown>[]> {
-  return executePlainWithContexts(session.getExecutionContext(), qb);
-}
+export async function executeHydratedPlain<TTable extends TableDef>(
+  session: OrmSession,
+  qb: SelectQueryBuilder<unknown, TTable>,
+  options?: ParamOperandOptions
+): Promise<Record<string, unknown>[]> {
+  return executePlainWithContexts(session.getExecutionContext(), qb, options);
+}
 
 /**
  * Executes a hydrated query using execution and hydration contexts.
@@ -118,17 +130,18 @@ export async function executeHydratedPlain<TTable extends TableDef>(
  * @param qb - The select query builder
  * @returns Promise resolving to array of entity instances
  */
-export async function executeHydratedWithContexts<TTable extends TableDef>(
-  execCtx: ExecutionContext,
-  hydCtx: HydrationContext,
-  qb: SelectQueryBuilder<unknown, TTable>
-): Promise<EntityInstance<TTable>[]> {
-  const entityCtx = hydCtx.entityContext;
-  if (!entityCtx) {
-    throw new Error('Hydration context is missing an EntityContext');
-  }
-  return executeWithContexts(execCtx, entityCtx, qb);
-}
+export async function executeHydratedWithContexts<TTable extends TableDef>(
+  execCtx: ExecutionContext,
+  hydCtx: HydrationContext,
+  qb: SelectQueryBuilder<unknown, TTable>,
+  options?: ParamOperandOptions
+): Promise<EntityInstance<TTable>[]> {
+  const entityCtx = hydCtx.entityContext;
+  if (!entityCtx) {
+    throw new Error('Hydration context is missing an EntityContext');
+  }
+  return executeWithContexts(execCtx, entityCtx, qb, options);
+}
 
 /**
  * Executes a hydrated query using execution context and returns plain row objects.
@@ -137,12 +150,13 @@ export async function executeHydratedWithContexts<TTable extends TableDef>(
  * @param qb - The select query builder
  * @returns Promise resolving to array of plain row objects
  */
-export async function executeHydratedPlainWithContexts<TTable extends TableDef>(
-  execCtx: ExecutionContext,
-  qb: SelectQueryBuilder<unknown, TTable>
-): Promise<Record<string, unknown>[]> {
-  return executePlainWithContexts(execCtx, qb);
-}
+export async function executeHydratedPlainWithContexts<TTable extends TableDef>(
+  execCtx: ExecutionContext,
+  qb: SelectQueryBuilder<unknown, TTable>,
+  options?: ParamOperandOptions
+): Promise<Record<string, unknown>[]> {
+  return executePlainWithContexts(execCtx, qb, options);
+}
 
 const loadLazyRelationsForTable = async <TTable extends TableDef>(
   ctx: EntityContext,

package/src/query-builder/query-ast-service.ts

@@ -18,6 +18,7 @@ import {
   CastExpressionNode,
   WindowFunctionNode,
   ScalarSubqueryNode,
+  ParamNode,
   and,
   isExpressionSelectionNode,
   isOperandNode
@@ -258,6 +259,10 @@ export class QueryAstService {
    * @returns Normalized ordering term
    */
   private normalizeOrderingTerm(term: ColumnDef | OrderingTerm): OrderingTerm {
+    const paramNode = this.toParamNode(term);
+    if (paramNode) {
+      return paramNode;
+    }
     const from = this.state.ast.from;
     const tableRef = from.type === 'Table' && from.alias ? { ...this.table, alias: from.alias } : this.table;
     const termType = (term as { type?: string }).type;
@@ -284,4 +289,12 @@ export class QueryAstService {
     return buildColumnNode(tableRef, term as ColumnDef);
   }
 
+  private toParamNode(value: unknown): ParamNode | undefined {
+    if (typeof value !== 'object' || value === null) return undefined;
+    const type = Object.getOwnPropertyDescriptor(value, 'type')?.value;
+    if (type !== 'Param') return undefined;
+    const name = Object.getOwnPropertyDescriptor(value, 'name')?.value;
+    if (typeof name !== 'string') return undefined;
+    return { type: 'Param', name };
+  }
 }

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

@@ -11,10 +11,14 @@ import { ORDER_DIRECTIONS, OrderDirection } from '../../core/sql/sql.js';
 import { OrmSession } from '../../orm/orm-session.js';
 import type { SelectQueryBuilder } from '../select.js';
 
-export type WhereHasOptions = {
-  correlate?: ExpressionNode;
-};
-
+export type WhereHasOptions = {
+  correlate?: ExpressionNode;
+};
+
+type ParamOperandOptions = {
+  allowParamOperands?: boolean;
+};
+
 export type RelationCallback = <TChildTable extends TableDef>(
   qb: SelectQueryBuilder<unknown, TChildTable>
 ) => SelectQueryBuilder<unknown, TChildTable>;
@@ -39,11 +43,12 @@ export function applyOrderBy(
 /**
  * Runs the count query for the provided context and session.
  */
-export async function executeCount(
-  context: SelectQueryBuilderContext,
-  env: SelectQueryBuilderEnvironment,
-  session: OrmSession
-): Promise<number> {
+export async function executeCount(
+  context: SelectQueryBuilderContext,
+  env: SelectQueryBuilderEnvironment,
+  session: OrmSession,
+  options?: ParamOperandOptions
+): Promise<number> {
   const unpagedAst: SelectQueryNode = {
     ...context.state.ast,
     orderBy: undefined,
@@ -65,10 +70,12 @@ export async function executeCount(
     joins: []
   };
 
-  const execCtx = session.getExecutionContext();
-  const compiled = execCtx.dialect.compileSelect(countQuery);
-  const results = await execCtx.interceptors.run({ sql: compiled.sql, params: compiled.params }, execCtx.executor);
-  const value = results[0]?.values?.[0]?.[0];
+  const execCtx = session.getExecutionContext();
+  const compiled = options?.allowParamOperands
+    ? execCtx.dialect.compileSelectWithOptions(countQuery, { allowParams: true })
+    : execCtx.dialect.compileSelect(countQuery);
+  const results = await execCtx.interceptors.run({ sql: compiled.sql, params: compiled.params }, execCtx.executor);
+  const value = results[0]?.values?.[0]?.[0];
 
   if (typeof value === 'number') return value;
   if (typeof value === 'bigint') return Number(value);
@@ -86,12 +93,13 @@ export interface PaginatedResult<T> {
 /**
  * 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>> {
+export async function executePagedQuery<T, TTable extends TableDef>(
+  builder: SelectQueryBuilder<T, TTable>,
+  session: OrmSession,
+  options: { page: number; pageSize: number },
+  countCallback: (session: OrmSession) => Promise<number>,
+  paramOptions?: ParamOperandOptions
+): Promise<PaginatedResult<T>> {
   const { page, pageSize } = options;
 
   if (!Number.isInteger(page) || page < 1) {
@@ -103,11 +111,11 @@ export async function executePagedQuery<T, TTable extends TableDef>(
 
   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 };
-}
+  const totalItems = await countCallback(session);
+  const items = await builder.limit(pageSize).offset(offset).execute(session, paramOptions);
+
+  return { items, totalItems, page, pageSize };
+}
 
 /**
  * Builds an EXISTS or NOT EXISTS predicate for a related table.