metal-orm 1.0.83 → 1.0.86

package/dist/index.cjs

@@ -175,8 +175,10 @@ __export(index_exports, {
   groupConcat: () => groupConcat,
   gt: () => gt,
   gte: () => gte,
+  hasExpressionDispatcher: () => hasExpressionDispatcher,
   hasMany: () => hasMany,
   hasOne: () => hasOne,
+  hasOperandDispatcher: () => hasOperandDispatcher,
   hour: () => hour,
   hydrateRows: () => hydrateRows,
   ifNull: () => ifNull,
@@ -655,16 +657,27 @@ var operandTypes = /* @__PURE__ */ new Set([
   "BitwiseExpression",
   "Collate"
 ]);
-var hasTypeProperty = (value) => typeof value === "object" && value !== null && "type" in value;
+var getNodeType = (value) => {
+  if (typeof value !== "object" || value === null) return void 0;
+  const descriptor = Object.getOwnPropertyDescriptor(value, "type");
+  if (descriptor && typeof descriptor.value === "string") {
+    return descriptor.value;
+  }
+  if ("type" in value) {
+    const type = value.type;
+    return typeof type === "string" ? type : void 0;
+  }
+  return void 0;
+};
 var isOperandNode = (node) => {
-  if (!hasTypeProperty(node)) return false;
-  return operandTypes.has(node.type);
-};
-var isFunctionNode = (node) => isOperandNode(node) && node.type === "Function";
-var isCaseExpressionNode = (node) => isOperandNode(node) && node.type === "CaseExpression";
-var isCastExpressionNode = (node) => isOperandNode(node) && node.type === "Cast";
-var isCollateExpressionNode = (node) => isOperandNode(node) && node.type === "Collate";
-var isWindowFunctionNode = (node) => isOperandNode(node) && node.type === "WindowFunction";
+  const type = getNodeType(node);
+  return type !== void 0 && operandTypes.has(type);
+};
+var isFunctionNode = (node) => isOperandNode(node) && getNodeType(node) === "Function";
+var isCaseExpressionNode = (node) => isOperandNode(node) && getNodeType(node) === "CaseExpression";
+var isCastExpressionNode = (node) => isOperandNode(node) && getNodeType(node) === "Cast";
+var isCollateExpressionNode = (node) => isOperandNode(node) && getNodeType(node) === "Collate";
+var isWindowFunctionNode = (node) => isOperandNode(node) && getNodeType(node) === "WindowFunction";
 var isExpressionSelectionNode = (node) => isFunctionNode(node) || isCaseExpressionNode(node) || isCastExpressionNode(node) || isWindowFunctionNode(node);
 
 // src/core/ast/expression-builders.ts
@@ -1043,23 +1056,34 @@ var registerExpressionDispatcher = (type, dispatcher) => {
 var registerOperandDispatcher = (type, dispatcher) => {
   operandRegistry = operandRegistry.register(type, dispatcher);
 };
+var hasExpressionDispatcher = (type) => expressionRegistry.get(type) !== void 0;
+var hasOperandDispatcher = (type) => operandRegistry.get(type) !== void 0;
 var clearExpressionDispatchers = () => {
   expressionRegistry = expressionRegistry.clear();
 };
 var clearOperandDispatchers = () => {
   operandRegistry = operandRegistry.clear();
 };
-var getNodeType = (node) => typeof node === "object" && node !== null && typeof node.type === "string" ? node.type : void 0;
+var getNodeType2 = (node) => {
+  if (typeof node !== "object" || node === null) return void 0;
+  const descriptor = Object.getOwnPropertyDescriptor(node, "type");
+  if (descriptor && typeof descriptor.value === "string") {
+    return descriptor.value;
+  }
+  const type = node.type;
+  return typeof type === "string" ? type : void 0;
+};
 var unsupportedExpression = (node) => {
-  throw new Error(`Unsupported expression type "${getNodeType(node) ?? "unknown"}"`);
+  throw new Error(`Unsupported expression type "${getNodeType2(node) ?? "unknown"}"`);
 };
 var unsupportedOperand = (node) => {
-  throw new Error(`Unsupported operand type "${getNodeType(node) ?? "unknown"}"`);
+  throw new Error(`Unsupported operand type "${getNodeType2(node) ?? "unknown"}"`);
 };
 var visitExpression = (node, visitor) => {
-  const dynamic = expressionRegistry.get(node.type);
+  const type = getNodeType2(node);
+  const dynamic = type ? expressionRegistry.get(type) : void 0;
   if (dynamic) return dynamic(node, visitor);
-  switch (node.type) {
+  switch (type) {
     case "BinaryExpression":
       if (visitor.visitBinaryExpression) return visitor.visitBinaryExpression(node);
       break;
@@ -1091,9 +1115,10 @@ var visitExpression = (node, visitor) => {
   return unsupportedExpression(node);
 };
 var visitOperand = (node, visitor) => {
-  const dynamic = operandRegistry.get(node.type);
+  const type = getNodeType2(node);
+  const dynamic = type ? operandRegistry.get(type) : void 0;
   if (dynamic) return dynamic(node, visitor);
-  switch (node.type) {
+  switch (type) {
     case "Column":
       if (visitor.visitColumn) return visitor.visitColumn(node);
       break;
@@ -1127,6 +1152,12 @@ var visitOperand = (node, visitor) => {
     case "Collate":
       if (visitor.visitCollate) return visitor.visitCollate(node);
       break;
+    case "ArithmeticExpression":
+      if (visitor.visitArithmeticExpression) return visitor.visitArithmeticExpression(node);
+      break;
+    case "BitwiseExpression":
+      if (visitor.visitBitwiseExpression) return visitor.visitBitwiseExpression(node);
+      break;
     default:
       break;
   }
@@ -1822,9 +1853,11 @@ var Dialect = class _Dialect {
    * @returns Compiled SQL operand
    */
   compileOperand(node, ctx) {
-    const compiler = this.operandCompilers.get(node.type);
+    const descriptor = Object.getOwnPropertyDescriptor(node, "type");
+    const nodeType = typeof descriptor?.value === "string" ? descriptor.value : typeof node.type === "string" ? node.type : void 0;
+    const compiler = nodeType ? this.operandCompilers.get(nodeType) : void 0;
     if (!compiler) {
-      throw new Error(`Unsupported operand node type "${node.type}" for ${this.constructor.name}`);
+      throw new Error(`Unsupported operand node type "${nodeType ?? "unknown"}" for ${this.constructor.name}`);
     }
     return compiler(node, ctx);
   }
@@ -4145,6 +4178,10 @@ var QueryAstService = class {
    * @returns Normalized ordering term
    */
   normalizeOrderingTerm(term) {
+    const paramNode = this.toParamNode(term);
+    if (paramNode) {
+      return paramNode;
+    }
     const from = this.state.ast.from;
     const tableRef2 = from.type === "Table" && from.alias ? { ...this.table, alias: from.alias } : this.table;
     const termType = term.type;
@@ -4162,6 +4199,14 @@ var QueryAstService = class {
     }
     return buildColumnNode(tableRef2, term);
   }
+  toParamNode(value) {
+    if (typeof value !== "object" || value === null) return void 0;
+    const type = Object.getOwnPropertyDescriptor(value, "type")?.value;
+    if (type !== "Param") return void 0;
+    const name = Object.getOwnPropertyDescriptor(value, "name")?.value;
+    if (typeof name !== "string") return void 0;
+    return { type: "Param", name };
+  }
 };
 
 // src/query-builder/relation-projection-helper.ts
@@ -6401,9 +6446,9 @@ var flattenResults = (results) => {
   }
   return rows;
 };
-var executeWithContexts = async (execCtx, entityCtx, qb) => {
+var executeWithContexts = async (execCtx, entityCtx, qb, options) => {
   const ast = qb.getAST();
-  const compiled = execCtx.dialect.compileSelect(ast);
+  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();
@@ -6421,9 +6466,9 @@ var executeWithContexts = async (execCtx, entityCtx, qb) => {
   await preloadRelationIncludes(entities, includeTree);
   return entities;
 };
-var executePlainWithContexts = async (execCtx, qb) => {
+var executePlainWithContexts = async (execCtx, qb, options) => {
   const ast = qb.getAST();
-  const compiled = execCtx.dialect.compileSelect(ast);
+  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) {
@@ -6431,21 +6476,21 @@ var executePlainWithContexts = async (execCtx, qb) => {
   }
   return hydrateRows(rows, qb.getHydrationPlan());
 };
-async function executeHydrated(session, qb) {
-  return executeWithContexts(session.getExecutionContext(), session, qb);
+async function executeHydrated(session, qb, options) {
+  return executeWithContexts(session.getExecutionContext(), session, qb, options);
 }
-async function executeHydratedPlain(session, qb) {
-  return executePlainWithContexts(session.getExecutionContext(), qb);
+async function executeHydratedPlain(session, qb, options) {
+  return executePlainWithContexts(session.getExecutionContext(), qb, options);
 }
-async function executeHydratedWithContexts(execCtx, hydCtx, qb) {
+async function executeHydratedWithContexts(execCtx, hydCtx, qb, options) {
   const entityCtx = hydCtx.entityContext;
   if (!entityCtx) {
     throw new Error("Hydration context is missing an EntityContext");
   }
-  return executeWithContexts(execCtx, entityCtx, qb);
+  return executeWithContexts(execCtx, entityCtx, qb, options);
 }
-async function executeHydratedPlainWithContexts(execCtx, qb) {
-  return executePlainWithContexts(execCtx, qb);
+async function executeHydratedPlainWithContexts(execCtx, qb, options) {
+  return executePlainWithContexts(execCtx, qb, options);
 }
 var loadLazyRelationsForTable = async (ctx, table, lazyRelations, lazyRelationOptions) => {
   if (!lazyRelations.length) return;
@@ -6646,7 +6691,7 @@ function applyOrderBy(context, predicateFacet, term, directionOrOptions) {
   const dir = options.direction ?? ORDER_DIRECTIONS.ASC;
   return predicateFacet.orderBy(context, term, dir, options.nulls, options.collation);
 }
-async function executeCount(context, env, session) {
+async function executeCount(context, env, session, options) {
   const unpagedAst = {
     ...context.state.ast,
     orderBy: void 0,
@@ -6666,7 +6711,7 @@ async function executeCount(context, env, session) {
     joins: []
   };
   const execCtx = session.getExecutionContext();
-  const compiled = execCtx.dialect.compileSelect(countQuery);
+  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;
@@ -6674,7 +6719,7 @@ async function executeCount(context, env, session) {
   if (typeof value === "string") return Number(value);
   return value === null || value === void 0 ? 0 : Number(value);
 }
-async function executePagedQuery(builder, session, options, countCallback) {
+async function executePagedQuery(builder, session, options, countCallback, paramOptions) {
   const { page, pageSize } = options;
   if (!Number.isInteger(page) || page < 1) {
     throw new Error("executePaged: page must be an integer >= 1");
@@ -6684,7 +6729,7 @@ async function executePagedQuery(builder, session, options, countCallback) {
   }
   const offset = (page - 1) * pageSize;
   const totalItems = await countCallback(session);
-  const items = await builder.limit(pageSize).offset(offset).execute(session);
+  const items = await builder.limit(pageSize).offset(offset).execute(session, paramOptions);
   return { items, totalItems, page, pageSize };
 }
 function buildWhereHasPredicate(env, context, relationFacet, createChildBuilder, relationName, callbackOrOptions, maybeOptions, negate = false) {
@@ -7767,225 +7812,235 @@ var buildFilterParameters = (table, where, from, options = {}) => {
   }];
 };
 
-// src/core/ast/ast-validation.ts
-var hasParamOperandsInExpression = (expr) => {
-  let hasParams = false;
-  visitExpression(expr, {
+// src/core/ast/query-visitor.ts
+var getNodeType3 = (value) => {
+  if (typeof value !== "object" || value === null) return void 0;
+  const descriptor = Object.getOwnPropertyDescriptor(value, "type");
+  if (descriptor && typeof descriptor.value === "string") {
+    return descriptor.value;
+  }
+  if ("type" in value) {
+    const type = value.type;
+    return typeof type === "string" ? type : void 0;
+  }
+  return void 0;
+};
+var visitSelectQuery = (ast, visitor) => {
+  const visitExpressionNode = (node) => {
+    visitExpression(node, expressionVisitor);
+  };
+  const visitOperandNode = (node) => {
+    visitOperand(node, operandVisitor);
+  };
+  const visitOrderingTerm = (term) => {
+    if (!term || typeof term !== "object") return;
+    if (isOperandNode(term)) {
+      visitOperandNode(term);
+      return;
+    }
+    const type = getNodeType3(term);
+    if (type && hasOperandDispatcher(type)) {
+      visitOperandNode(term);
+      return;
+    }
+    if (type) {
+      visitExpressionNode(term);
+    }
+  };
+  const visitOrderByNode = (node) => {
+    visitor.visitOrderBy?.(node);
+    visitOrderingTerm(node.term);
+  };
+  const visitTableSource = (source) => {
+    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 = {
     visitBinaryExpression: (node) => {
-      visitOperand(node.left, {
-        visitParam: () => {
-          hasParams = true;
-        },
-        otherwise: () => {
-        }
-      });
-      visitOperand(node.right, {
-        visitParam: () => {
-          hasParams = true;
-        },
-        otherwise: () => {
-        }
-      });
+      visitor.visitExpression?.(node);
+      visitOperandNode(node.left);
+      visitOperandNode(node.right);
       if (node.escape) {
-        visitOperand(node.escape, {
-          visitParam: () => {
-            hasParams = true;
-          },
-          otherwise: () => {
-          }
-        });
+        visitOperandNode(node.escape);
       }
     },
     visitLogicalExpression: (node) => {
-      node.operands.forEach((operand) => {
-        if (hasParamOperandsInExpression(operand)) {
-          hasParams = true;
-        }
-      });
+      visitor.visitExpression?.(node);
+      node.operands.forEach((operand) => visitExpressionNode(operand));
     },
-    visitNullExpression: () => {
+    visitNullExpression: (node) => {
+      visitor.visitExpression?.(node);
+      visitOperandNode(node.left);
     },
     visitInExpression: (node) => {
-      visitOperand(node.left, {
-        visitParam: () => {
-          hasParams = true;
-        },
-        otherwise: () => {
-        }
-      });
+      visitor.visitExpression?.(node);
+      visitOperandNode(node.left);
       if (Array.isArray(node.right)) {
-        node.right.forEach((operand) => visitOperand(operand, {
-          visitParam: () => {
-            hasParams = true;
-          },
-          otherwise: () => {
-          }
-        }));
+        node.right.forEach((operand) => visitOperandNode(operand));
+      } else {
+        visitOperandNode(node.right);
       }
     },
-    visitExistsExpression: () => {
+    visitExistsExpression: (node) => {
+      visitor.visitExpression?.(node);
+      visitSelectQuery(node.subquery, visitor);
     },
     visitBetweenExpression: (node) => {
-      visitOperand(node.left, {
-        visitParam: () => {
-          hasParams = true;
-        },
-        otherwise: () => {
-        }
-      });
-      visitOperand(node.lower, {
-        visitParam: () => {
-          hasParams = true;
-        },
-        otherwise: () => {
-        }
-      });
-      visitOperand(node.upper, {
-        visitParam: () => {
-          hasParams = true;
-        },
-        otherwise: () => {
-        }
-      });
+      visitor.visitExpression?.(node);
+      visitOperandNode(node.left);
+      visitOperandNode(node.lower);
+      visitOperandNode(node.upper);
     },
     visitArithmeticExpression: (node) => {
-      visitOperand(node.left, {
-        visitParam: () => {
-          hasParams = true;
-        },
-        otherwise: () => {
-        }
-      });
-      visitOperand(node.right, {
-        visitParam: () => {
-          hasParams = true;
-        },
-        otherwise: () => {
-        }
-      });
+      visitor.visitExpression?.(node);
+      visitOperandNode(node.left);
+      visitOperandNode(node.right);
     },
     visitBitwiseExpression: (node) => {
-      visitOperand(node.left, {
-        visitParam: () => {
-          hasParams = true;
-        },
-        otherwise: () => {
-        }
-      });
-      visitOperand(node.right, {
-        visitParam: () => {
-          hasParams = true;
-        },
-        otherwise: () => {
-        }
-      });
+      visitor.visitExpression?.(node);
+      visitOperandNode(node.left);
+      visitOperandNode(node.right);
     },
-    otherwise: () => {
+    visitOperand: (node) => {
+      visitOperandNode(node);
+    },
+    visitSelectQuery: (node) => {
+      visitSelectQuery(node, visitor);
+    },
+    otherwise: (node) => {
+      visitor.visitExpression?.(node);
     }
-  });
-  return hasParams;
-};
-var hasParamOperandsInOperand = (operand) => {
-  let hasParams = false;
-  visitOperand(operand, {
-    visitColumn: () => {
+  };
+  const operandVisitor = {
+    visitColumn: (node) => {
+      visitor.visitOperand?.(node);
     },
-    visitLiteral: () => {
+    visitLiteral: (node) => {
+      visitor.visitOperand?.(node);
     },
-    visitParam: () => {
-      hasParams = true;
+    visitParam: (node) => {
+      visitor.visitOperand?.(node);
+      visitor.visitParam?.(node);
     },
     visitFunction: (node) => {
-      node.args?.forEach((arg) => {
-        if (hasParamOperandsInOperand(arg)) {
-          hasParams = true;
-        }
-      });
+      visitor.visitOperand?.(node);
+      node.args?.forEach((arg) => visitOperandNode(arg));
+      node.orderBy?.forEach((order) => visitOrderByNode(order));
+      if (node.separator) {
+        visitOperandNode(node.separator);
+      }
     },
-    visitJsonPath: () => {
+    visitJsonPath: (node) => {
+      visitor.visitOperand?.(node);
+      visitOperandNode(node.column);
     },
-    visitScalarSubquery: () => {
+    visitScalarSubquery: (node) => {
+      visitor.visitOperand?.(node);
+      visitSelectQuery(node.query, visitor);
     },
     visitCaseExpression: (node) => {
+      visitor.visitOperand?.(node);
       node.conditions.forEach((cond) => {
-        if (hasParamOperandsInExpression(cond.when)) {
-          hasParams = true;
-        }
-        if (hasParamOperandsInOperand(cond.then)) {
-          hasParams = true;
-        }
+        visitExpressionNode(cond.when);
+        visitOperandNode(cond.then);
       });
-      if (node.else && hasParamOperandsInOperand(node.else)) {
-        hasParams = true;
+      if (node.else) {
+        visitOperandNode(node.else);
       }
     },
     visitCast: (node) => {
-      if (hasParamOperandsInOperand(node.expression)) {
-        hasParams = true;
-      }
+      visitor.visitOperand?.(node);
+      visitOperandNode(node.expression);
     },
     visitWindowFunction: (node) => {
-      node.args?.forEach((arg) => {
-        if (hasParamOperandsInOperand(arg)) {
-          hasParams = true;
-        }
-      });
-      node.orderBy?.forEach((ord) => {
-        if (ord.term) {
-          if (hasParamOperandsInOperand(ord.term)) {
-            hasParams = true;
-          }
-        }
-      });
+      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) => {
-      if (hasParamOperandsInOperand(node.expression)) {
-        hasParams = true;
-      }
+      visitor.visitOperand?.(node);
+      visitOperandNode(node.expression);
     },
-    visitAliasRef: () => {
+    visitAliasRef: (node) => {
+      visitor.visitOperand?.(node);
     },
-    otherwise: () => {
+    otherwise: (node) => {
+      visitor.visitOperand?.(node);
+    }
+  };
+  visitor.visitSelectQuery?.(ast);
+  if (ast.ctes) {
+    for (const cte of ast.ctes) {
+      visitor.visitCte?.(cte);
+      visitSelectQuery(cte.query, visitor);
     }
-  });
-  return hasParams;
-};
-var hasParamOperandsInQuery = (ast) => {
-  if (ast.where && hasParamOperandsInExpression(ast.where)) {
-    return true;
-  }
-  if (ast.having && hasParamOperandsInExpression(ast.having)) {
-    return true;
   }
+  visitTableSource(ast.from);
   ast.columns?.forEach((col2) => {
-    if (typeof col2 === "object" && col2 !== null && "type" in col2) {
-      if (hasParamOperandsInOperand(col2)) {
-        return true;
-      }
-    }
+    visitOperandNode(col2);
   });
-  ast.orderBy?.forEach((ord) => {
-    if (ord.term) {
-      if (hasParamOperandsInOperand(ord.term)) {
-        return true;
-      }
-    }
+  ast.joins?.forEach((join) => {
+    visitor.visitJoin?.(join);
+    visitTableSource(join.table);
+    visitExpressionNode(join.condition);
   });
-  if (ast.ctes) {
-    for (const cte of ast.ctes) {
-      if (cte.query.where && hasParamOperandsInExpression(cte.query.where)) {
-        return true;
-      }
-    }
+  if (ast.where) {
+    visitExpressionNode(ast.where);
   }
-  if (ast.setOps) {
-    for (const op of ast.setOps) {
-      if (hasParamOperandsInQuery(op.query)) {
-        return true;
+  ast.groupBy?.forEach((term) => {
+    visitOrderingTerm(term);
+  });
+  if (ast.having) {
+    visitExpressionNode(ast.having);
+  }
+  ast.orderBy?.forEach((order) => {
+    visitOrderByNode(order);
+  });
+  ast.distinct?.forEach((col2) => {
+    visitOperandNode(col2);
+  });
+  ast.setOps?.forEach((op) => {
+    visitor.visitSetOperation?.(op);
+    visitSelectQuery(op.query, visitor);
+  });
+};
+
+// src/core/ast/ast-validation.ts
+var findFirstParamOperandName = (ast) => {
+  let name;
+  visitSelectQuery(ast, {
+    visitParam: (node) => {
+      if (!name) {
+        name = node.name;
       }
     }
-  }
-  return false;
+  });
+  return name;
 };
 
 // src/query-builder/select.ts
@@ -8465,11 +8520,12 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * Validates that the query does not contain Param operands.
    * Param proxies are only for schema generation, not execution.
    */
-  validateNoParamOperands() {
+  validateNoParamOperands(options) {
+    if (options?.allowParamOperands) return;
     const ast = this.context.hydration.applyToAst(this.context.state.ast);
-    const hasParams = hasParamOperandsInQuery(ast);
-    if (hasParams) {
-      throw new Error("Cannot execute query containing Param operands. Param proxies are only for schema generation (getSchema()). If you need real parameters, use literal values.");
+    const paramName = findFirstParamOperandName(ast);
+    if (paramName) {
+      throw new Error(`Cannot execute query containing Param operand "${paramName}". Param proxies are only for schema generation (getSchema()). If you need real parameters, use literal values.`);
     }
   }
   /**
@@ -8484,13 +8540,13 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * // users is User[]
    * users[0] instanceof User; // true
    */
-  async execute(ctx) {
-    this.validateNoParamOperands();
+  async execute(ctx, options) {
+    this.validateNoParamOperands(options);
     if (this.entityConstructor) {
-      return this.executeAs(this.entityConstructor, ctx);
+      return this.executeAs(this.entityConstructor, ctx, options);
     }
     const builder = this.ensureDefaultSelection();
-    return executeHydrated(ctx, builder);
+    return executeHydrated(ctx, builder, options);
   }
   /**
    * Executes the query and returns plain row objects (POJOs), ignoring any entity materialization.
@@ -8503,10 +8559,10 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * // rows is EntityInstance<UserTable>[] (plain objects)
    * rows[0] instanceof User; // false
    */
-  async executePlain(ctx) {
-    this.validateNoParamOperands();
+  async executePlain(ctx, options) {
+    this.validateNoParamOperands(options);
     const builder = this.ensureDefaultSelection();
-    const rows = await executeHydratedPlain(ctx, builder);
+    const rows = await executeHydratedPlain(ctx, builder, options);
     return rows;
   }
   /**
@@ -8523,10 +8579,10 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * users[0] instanceof User; // true!
    * users[0].getFullName();   // works!
    */
-  async executeAs(entityClass, ctx) {
-    this.validateNoParamOperands();
+  async executeAs(entityClass, ctx, options) {
+    this.validateNoParamOperands(options);
     const builder = this.ensureDefaultSelection();
-    const results = await executeHydrated(ctx, builder);
+    const results = await executeHydrated(ctx, builder, options);
     return materializeAs(entityClass, results);
   }
   /**
@@ -8535,9 +8591,9 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * @example
    * const total = await qb.count(session);
    */
-  async count(session) {
-    this.validateNoParamOperands();
-    return executeCount(this.context, this.env, session);
+  async count(session, options) {
+    this.validateNoParamOperands(options);
+    return executeCount(this.context, this.env, session, options);
   }
   /**
    * Executes the query and returns both the paged items and the total.
@@ -8546,9 +8602,9 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * const { items, totalItems, page, pageSize } = await qb.executePaged(session, { page: 1, pageSize: 20 });
    */
   async executePaged(session, options) {
-    this.validateNoParamOperands();
+    this.validateNoParamOperands(options);
     const builder = this.ensureDefaultSelection();
-    return executePagedQuery(builder, session, options, (sess) => builder.count(sess));
+    return executePagedQuery(builder, session, options, (sess) => builder.count(sess, options), options);
   }
   /**
    * Executes the query with provided execution and hydration contexts
@@ -8560,10 +8616,10 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * const hydCtx = new HydrationContext();
    * const users = await qb.executeWithContexts(execCtx, hydCtx);
    */
-  async executeWithContexts(execCtx, hydCtx) {
-    this.validateNoParamOperands();
+  async executeWithContexts(execCtx, hydCtx, options) {
+    this.validateNoParamOperands(options);
     const builder = this.ensureDefaultSelection();
-    const results = await executeHydratedWithContexts(execCtx, hydCtx, builder);
+    const results = await executeHydratedWithContexts(execCtx, hydCtx, builder, options);
     if (this.entityConstructor) {
       return materializeAs(this.entityConstructor, results);
     }
@@ -8796,9 +8852,17 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    *   .compile('postgres');
    * console.log(compiled.sql); // SELECT "id", "name" FROM "users" WHERE "active" = true
    */
-  compile(dialect) {
+  compile(dialect, options) {
     const resolved = resolveDialectInput(dialect);
-    return resolved.compileSelect(this.getAST());
+    const ast = this.getAST();
+    if (!options?.allowParamOperands) {
+      const paramName = findFirstParamOperandName(ast);
+      if (paramName) {
+        throw new Error(`Cannot compile query containing Param operand "${paramName}". Param proxies are only for schema generation (getSchema()). If you need real parameters, use literal values.`);
+      }
+      return resolved.compileSelect(ast);
+    }
+    return resolved.compileSelectWithOptions(ast, { allowParams: true });
   }
   /**
    * Converts the query to SQL string for a specific dialect
@@ -8810,8 +8874,8 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    *   .toSql('postgres');
    * console.log(sql); // SELECT "id", "name" FROM "users" WHERE "active" = true
    */
-  toSql(dialect) {
-    return this.compile(dialect).sql;
+  toSql(dialect, options) {
+    return this.compile(dialect, options).sql;
   }
   /**
    * Gets hydration plan for query
@@ -14500,8 +14564,10 @@ function createPooledExecutorFactory(opts) {
   groupConcat,
   gt,
   gte,
+  hasExpressionDispatcher,
   hasMany,
   hasOne,
+  hasOperandDispatcher,
   hour,
   hydrateRows,
   ifNull,