metal-orm 1.0.85 → 1.0.86

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metal-orm",
-  "version": "1.0.85",
+  "version": "1.0.86",
   "type": "module",
   "types": "./dist/index.d.ts",
   "engines": {

package/src/core/ast/ast-validation.ts

@@ -1,14 +1,19 @@
 import type { SelectQueryNode } from './query.js';
 import { visitSelectQuery } from './query-visitor.js';
 
-export const hasParamOperandsInQuery = (ast: SelectQueryNode): boolean => {
-  let hasParams = false;
+export const findFirstParamOperandName = (ast: SelectQueryNode): string | undefined => {
+  let name: string | undefined;
 
   visitSelectQuery(ast, {
-    visitParam: () => {
-      hasParams = true;
+    visitParam: (node) => {
+      if (!name) {
+        name = node.name;
+      }
     }
   });
 
-  return hasParams;
+  return name;
 };
+
+export const hasParamOperandsInQuery = (ast: SelectQueryNode): boolean =>
+  !!findFirstParamOperandName(ast);

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

@@ -21,6 +21,7 @@ import {
   BitwiseExpressionNode,
   ParamNode
 } from './expression-nodes.js';
+import type { SelectQueryNode } from './query.js';
 
 /**
  * Visitor for expression nodes
@@ -34,6 +35,8 @@ export interface ExpressionVisitor<R> {
   visitBetweenExpression?(node: BetweenExpressionNode): R;
   visitArithmeticExpression?(node: ArithmeticExpressionNode): R;
   visitBitwiseExpression?(node: BitwiseExpressionNode): R;
+  visitOperand?(node: OperandNode): R;
+  visitSelectQuery?(node: SelectQueryNode): R;
   otherwise?(node: ExpressionNode): R;
 }
 
@@ -50,6 +53,10 @@ export interface OperandVisitor<R> {
   visitCaseExpression?(node: CaseExpressionNode): R;
   visitCast?(node: CastExpressionNode): R;
   visitWindowFunction?(node: WindowFunctionNode): R;
+  visitArithmeticExpression?(node: ArithmeticExpressionNode): R;
+  visitBitwiseExpression?(node: BitwiseExpressionNode): R;
+  visitExpression?(node: ExpressionNode): R;
+  visitSelectQuery?(node: SelectQueryNode): R;
   visitCollate?(node: CollateExpressionNode): R;
   visitAliasRef?(node: AliasRefNode): R;
   otherwise?(node: OperandNode): R;
@@ -111,6 +118,12 @@ export const registerOperandDispatcher = (type: string, dispatcher: OperandDispa
   operandRegistry = operandRegistry.register(type, dispatcher);
 };
 
+export const hasExpressionDispatcher = (type: string): boolean =>
+  expressionRegistry.get(type) !== undefined;
+
+export const hasOperandDispatcher = (type: string): boolean =>
+  operandRegistry.get(type) !== undefined;
+
 /**
  * Clears all registered dispatchers. Primarily for tests.
  */
@@ -225,6 +238,12 @@ export const visitOperand = <R>(node: OperandNode, visitor: OperandVisitor<R>):
     case 'Collate':
       if (visitor.visitCollate) return visitor.visitCollate(node as CollateExpressionNode);
       break;
+    case 'ArithmeticExpression':
+      if (visitor.visitArithmeticExpression) return visitor.visitArithmeticExpression(node as ArithmeticExpressionNode);
+      break;
+    case 'BitwiseExpression':
+      if (visitor.visitBitwiseExpression) return visitor.visitBitwiseExpression(node as BitwiseExpressionNode);
+      break;
     default:
       break;
   }

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

@@ -15,6 +15,13 @@ import type {
   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;
@@ -43,142 +50,181 @@ const getNodeType = (value: unknown): string | undefined => {
   return undefined;
 };
 
-const visitOrderingTerm = (term: OrderingTerm, visitor: SelectQueryVisitor): void => {
-  if (isOperandNode(term)) {
-    visitOperandNode(term, visitor);
-    return;
-  }
-  visitExpressionNode(term as ExpressionNode, visitor);
-};
+export const visitSelectQuery = (ast: SelectQueryNode, visitor: SelectQueryVisitor): void => {
+  const visitExpressionNode = (node: ExpressionNode): void => {
+    visitExpression(node, expressionVisitor);
+  };
 
-const visitOrderByNode = (node: OrderByNode, visitor: SelectQueryVisitor): void => {
-  visitor.visitOrderBy?.(node);
-  visitOrderingTerm(node.term, visitor);
-};
+  const visitOperandNode = (node: OperandNode): void => {
+    visitOperand(node, operandVisitor);
+  };
 
-const visitTableSource = (source: TableSourceNode, visitor: SelectQueryVisitor): 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, visitor));
-  }
-};
-
-const visitExpressionNode = (node: ExpressionNode, visitor: SelectQueryVisitor): void => {
-  visitor.visitExpression?.(node);
-  const type = getNodeType(node);
-  if (!type) return;
-  switch (type) {
-    case 'BinaryExpression':
-      visitOperandNode(node.left, visitor);
-      visitOperandNode(node.right, visitor);
-      if (node.escape) {
-        visitOperandNode(node.escape, visitor);
-      }
+  const visitOrderingTerm = (term: OrderingTerm): void => {
+    if (!term || typeof term !== 'object') return;
+    if (isOperandNode(term)) {
+      visitOperandNode(term);
       return;
-    case 'LogicalExpression':
-      node.operands.forEach(operand => visitExpressionNode(operand, visitor));
+    }
+    const type = getNodeType(term);
+    if (type && hasOperandDispatcher(type)) {
+      visitOperandNode(term as unknown as OperandNode);
       return;
-    case 'NullExpression':
-      visitOperandNode(node.left, visitor);
+    }
+    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;
-    case 'InExpression':
-      visitOperandNode(node.left, visitor);
+    }
+    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, visitor));
+        node.right.forEach(operand => visitOperandNode(operand));
       } else {
-        visitOperandNode(node.right, visitor);
+        visitOperandNode(node.right);
       }
-      return;
-    case 'ExistsExpression':
+    },
+    visitExistsExpression: (node) => {
+      visitor.visitExpression?.(node);
       visitSelectQuery(node.subquery, visitor);
-      return;
-    case 'BetweenExpression':
-      visitOperandNode(node.left, visitor);
-      visitOperandNode(node.lower, visitor);
-      visitOperandNode(node.upper, visitor);
-      return;
-    case 'ArithmeticExpression':
-      visitOperandNode(node.left, visitor);
-      visitOperandNode(node.right, visitor);
-      return;
-    case 'BitwiseExpression':
-      visitOperandNode(node.left, visitor);
-      visitOperandNode(node.right, visitor);
-      return;
-    default: {
-      return;
+    },
+    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 visitOperandNode = (node: OperandNode, visitor: SelectQueryVisitor): void => {
-  visitor.visitOperand?.(node);
-  const type = getNodeType(node);
-  if (type === 'Param') {
-    visitor.visitParam?.(node);
-  }
-  if (!type) return;
-  switch (type) {
-    case 'Column':
-    case 'Literal':
-    case 'Param':
-    case 'AliasRef':
-      return;
-    case 'Function':
-      node.args?.forEach(arg => visitOperandNode(arg, visitor));
-      node.orderBy?.forEach(order => visitOrderByNode(order, visitor));
+  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, visitor);
+        visitOperandNode(node.separator);
       }
-      return;
-    case 'JsonPath':
-      visitOperandNode(node.column, visitor);
-      return;
-    case 'ScalarSubquery':
+    },
+    visitJsonPath: (node) => {
+      visitor.visitOperand?.(node);
+      visitOperandNode(node.column);
+    },
+    visitScalarSubquery: (node) => {
+      visitor.visitOperand?.(node);
       visitSelectQuery(node.query, visitor);
-      return;
-    case 'CaseExpression':
+    },
+    visitCaseExpression: (node) => {
+      visitor.visitOperand?.(node);
       node.conditions.forEach(cond => {
-        visitExpressionNode(cond.when, visitor);
-        visitOperandNode(cond.then, visitor);
+        visitExpressionNode(cond.when);
+        visitOperandNode(cond.then);
       });
       if (node.else) {
-        visitOperandNode(node.else, visitor);
+        visitOperandNode(node.else);
       }
-      return;
-    case 'Cast':
-      visitOperandNode(node.expression, visitor);
-      return;
-    case 'WindowFunction':
-      node.args?.forEach(arg => visitOperandNode(arg, visitor));
-      node.partitionBy?.forEach(term => visitOperandNode(term, visitor));
-      node.orderBy?.forEach(order => visitOrderByNode(order, visitor));
-      return;
-    case 'ArithmeticExpression':
-      visitOperandNode(node.left, visitor);
-      visitOperandNode(node.right, visitor);
-      return;
-    case 'BitwiseExpression':
-      visitOperandNode(node.left, visitor);
-      visitOperandNode(node.right, visitor);
-      return;
-    case 'Collate':
-      visitOperandNode(node.expression, visitor);
-      return;
-    default: {
-      const _exhaustive: never = node;
-      return _exhaustive;
+    },
+    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);
     }
-  }
-};
+  };
 
-export const visitSelectQuery = (ast: SelectQueryNode, visitor: SelectQueryVisitor): void => {
   visitor.visitSelectQuery?.(ast);
 
   if (ast.ctes) {
@@ -188,36 +234,36 @@ export const visitSelectQuery = (ast: SelectQueryNode, visitor: SelectQueryVisit
     }
   }
 
-  visitTableSource(ast.from, visitor);
+  visitTableSource(ast.from);
 
   ast.columns?.forEach(col => {
-    visitOperandNode(col as OperandNode, visitor);
+    visitOperandNode(col as OperandNode);
   });
 
   ast.joins?.forEach(join => {
     visitor.visitJoin?.(join);
-    visitTableSource(join.table, visitor);
-    visitExpressionNode(join.condition, visitor);
+    visitTableSource(join.table);
+    visitExpressionNode(join.condition);
   });
 
   if (ast.where) {
-    visitExpressionNode(ast.where, visitor);
+    visitExpressionNode(ast.where);
   }
 
   ast.groupBy?.forEach(term => {
-    visitOrderingTerm(term, visitor);
+    visitOrderingTerm(term);
   });
 
   if (ast.having) {
-    visitExpressionNode(ast.having, visitor);
+    visitExpressionNode(ast.having);
   }
 
   ast.orderBy?.forEach(order => {
-    visitOrderByNode(order, visitor);
+    visitOrderByNode(order);
   });
 
   ast.distinct?.forEach(col => {
-    visitOperandNode(col, visitor);
+    visitOperandNode(col);
   });
 
   ast.setOps?.forEach(op => {

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,