metal-orm 1.0.82 → 1.0.85

package/dist/index.d.cts

@@ -1820,6 +1820,8 @@ interface CompilerContext {
     params: unknown[];
     /** Function to add a parameter and get its placeholder */
     addParameter(value: unknown): string;
+    /** Whether Param operands are allowed (for schema generation) */
+    allowParams?: boolean;
 }
 /**
  * Result of SQL compilation
@@ -1854,6 +1856,9 @@ declare abstract class Dialect implements SelectCompiler, InsertCompiler, Update
      * @returns Compiled query with SQL and parameters
      */
     compileSelect(ast: SelectQueryNode): CompiledQuery;
+    compileSelectWithOptions(ast: SelectQueryNode, options?: {
+        allowParams?: boolean;
+    }): CompiledQuery;
     compileInsert(ast: InsertQueryNode): CompiledQuery;
     compileUpdate(ast: UpdateQueryNode): CompiledQuery;
     compileDelete(ast: DeleteQueryNode): CompiledQuery;
@@ -1894,9 +1899,12 @@ declare abstract class Dialect implements SelectCompiler, InsertCompiler, Update
     protected compileSelectForExists(ast: SelectQueryNode, ctx: CompilerContext): string;
     /**
      * Creates a new compiler context
+     * @param options - Optional compiler context options
      * @returns Compiler context with parameter management
      */
-    protected createCompilerContext(): CompilerContext;
+    protected createCompilerContext(options?: {
+        allowParams?: boolean;
+    }): CompilerContext;
     /**
      * Formats a parameter placeholder
      * @param index - Parameter index
@@ -2384,6 +2392,7 @@ declare class QueryAstService {
      * @returns Normalized ordering term
      */
     private normalizeOrderingTerm;
+    private toParamNode;
 }
 
 /**
@@ -4312,6 +4321,11 @@ declare class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Ta
      * Ensures that if no columns are selected, all columns from the table are selected by default.
      */
     private ensureDefaultSelection;
+    /**
+     * Validates that the query does not contain Param operands.
+     * Param proxies are only for schema generation, not execution.
+     */
+    private validateNoParamOperands;
     /**
      * Executes the query and returns hydrated results.
      * If the builder was created with an entity constructor (e.g. via selectFromEntity),

package/dist/index.d.ts

@@ -1820,6 +1820,8 @@ interface CompilerContext {
     params: unknown[];
     /** Function to add a parameter and get its placeholder */
     addParameter(value: unknown): string;
+    /** Whether Param operands are allowed (for schema generation) */
+    allowParams?: boolean;
 }
 /**
  * Result of SQL compilation
@@ -1854,6 +1856,9 @@ declare abstract class Dialect implements SelectCompiler, InsertCompiler, Update
      * @returns Compiled query with SQL and parameters
      */
     compileSelect(ast: SelectQueryNode): CompiledQuery;
+    compileSelectWithOptions(ast: SelectQueryNode, options?: {
+        allowParams?: boolean;
+    }): CompiledQuery;
     compileInsert(ast: InsertQueryNode): CompiledQuery;
     compileUpdate(ast: UpdateQueryNode): CompiledQuery;
     compileDelete(ast: DeleteQueryNode): CompiledQuery;
@@ -1894,9 +1899,12 @@ declare abstract class Dialect implements SelectCompiler, InsertCompiler, Update
     protected compileSelectForExists(ast: SelectQueryNode, ctx: CompilerContext): string;
     /**
      * Creates a new compiler context
+     * @param options - Optional compiler context options
      * @returns Compiler context with parameter management
      */
-    protected createCompilerContext(): CompilerContext;
+    protected createCompilerContext(options?: {
+        allowParams?: boolean;
+    }): CompilerContext;
     /**
      * Formats a parameter placeholder
      * @param index - Parameter index
@@ -2384,6 +2392,7 @@ declare class QueryAstService {
      * @returns Normalized ordering term
      */
     private normalizeOrderingTerm;
+    private toParamNode;
 }
 
 /**
@@ -4312,6 +4321,11 @@ declare class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Ta
      * Ensures that if no columns are selected, all columns from the table are selected by default.
      */
     private ensureDefaultSelection;
+    /**
+     * Validates that the query does not contain Param operands.
+     * Param proxies are only for schema generation, not execution.
+     */
+    private validateNoParamOperands;
     /**
      * Executes the query and returns hydrated results.
      * If the builder was created with an entity constructor (e.g. via selectFromEntity),

package/dist/index.js

@@ -371,16 +371,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
@@ -389,6 +400,14 @@ var toLiteralNode = (value) => ({
   type: "Literal",
   value: value instanceof Date ? value.toISOString() : value
 });
+var 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 };
+};
 var columnRefToNode = (col2) => {
   if (!col2.table) {
     throw new Error(
@@ -398,6 +417,10 @@ var columnRefToNode = (col2) => {
   return { type: "Column", table: col2.table, name: col2.name };
 };
 var toOperandNode = (value) => {
+  const paramNode = toParamNode(value);
+  if (paramNode) {
+    return paramNode;
+  }
   if (isOperandNode(value)) {
     return value;
   }
@@ -407,6 +430,10 @@ var toOperandNode = (value) => {
   return columnRefToNode(value);
 };
 var valueToOperand = (value) => {
+  const paramNode = toParamNode(value);
+  if (paramNode) {
+    return paramNode;
+  }
   if (isOperandNode(value)) {
     return value;
   }
@@ -749,17 +776,26 @@ var clearExpressionDispatchers = () => {
 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;
@@ -791,9 +827,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;
@@ -848,7 +885,7 @@ var buildParamProxy = (name) => {
         const nextName2 = name ? `${name}.${trimmed}` : trimmed;
         return buildParamProxy(nextName2);
       }
-      if (prop in t) {
+      if (prop in t && name === "") {
         return t[prop];
       }
       const nextName = name ? `${name}.${prop}` : prop;
@@ -867,9 +904,6 @@ var createParamProxy = () => {
       if (typeof prop === "string" && prop.startsWith("$")) {
         return buildParamProxy(prop.slice(1));
       }
-      if (prop in t) {
-        return t[prop];
-      }
       return buildParamProxy(String(prop));
     }
   });
@@ -1286,6 +1320,16 @@ var Dialect = class _Dialect {
       params: [...ctx.params]
     };
   }
+  compileSelectWithOptions(ast, options = {}) {
+    const ctx = this.createCompilerContext(options);
+    const normalized = this.normalizeSelectAst(ast);
+    const rawSql = this.compileSelectAst(normalized, ctx).trim();
+    const sql = rawSql.endsWith(";") ? rawSql : `${rawSql};`;
+    return {
+      sql,
+      params: [...ctx.params]
+    };
+  }
   compileInsert(ast) {
     const ctx = this.createCompilerContext();
     const rawSql = this.compileInsertAst(ast, ctx).trim();
@@ -1356,13 +1400,15 @@ var Dialect = class _Dialect {
   }
   /**
    * Creates a new compiler context
+   * @param options - Optional compiler context options
    * @returns Compiler context with parameter management
    */
-  createCompilerContext() {
+  createCompilerContext(options = {}) {
     const params = [];
     let counter = 0;
     return {
       params,
+      allowParams: options.allowParams ?? false,
       addParameter: (value) => {
         counter += 1;
         params.push(value);
@@ -1513,9 +1559,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);
   }
@@ -1584,7 +1632,12 @@ var Dialect = class _Dialect {
   }
   registerDefaultOperandCompilers() {
     this.registerOperandCompiler("Literal", (literal, ctx) => ctx.addParameter(literal.value));
-    this.registerOperandCompiler("Param", (_param, ctx) => ctx.addParameter(null));
+    this.registerOperandCompiler("Param", (_param, ctx) => {
+      if (!ctx.allowParams) {
+        throw new Error("Cannot compile query with Param operands. Param proxies are only for schema generation (getSchema()). If you need real parameters, use literal values.");
+      }
+      return ctx.addParameter(null);
+    });
     this.registerOperandCompiler("AliasRef", (alias, _ctx) => {
       void _ctx;
       return this.quoteIdentifier(alias.name);
@@ -3831,6 +3884,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;
@@ -3848,6 +3905,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
@@ -7302,7 +7367,7 @@ var collectFilterColumns = (expr, table, rootTables) => {
       columns.add(node.name);
     }
   };
-  const visitOrderingTerm = (term) => {
+  const visitOrderingTerm2 = (term) => {
     if (!term || typeof term !== "object") return;
     if (isOperandNode(term)) {
       visitOperand2(term);
@@ -7314,7 +7379,7 @@ var collectFilterColumns = (expr, table, rootTables) => {
   };
   const visitOrderBy = (orderBy) => {
     if (!orderBy) return;
-    orderBy.forEach((node) => visitOrderingTerm(node.term));
+    orderBy.forEach((node) => visitOrderingTerm2(node.term));
   };
   const visitOperand2 = (node) => {
     switch (node.type) {
@@ -7453,6 +7518,198 @@ var buildFilterParameters = (table, where, from, options = {}) => {
   }];
 };
 
+// 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 visitOrderingTerm = (term, visitor) => {
+  if (isOperandNode(term)) {
+    visitOperandNode(term, visitor);
+    return;
+  }
+  visitExpressionNode(term, visitor);
+};
+var visitOrderByNode = (node, visitor) => {
+  visitor.visitOrderBy?.(node);
+  visitOrderingTerm(node.term, visitor);
+};
+var visitTableSource = (source, visitor) => {
+  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));
+  }
+};
+var visitExpressionNode = (node, visitor) => {
+  visitor.visitExpression?.(node);
+  const type = getNodeType3(node);
+  if (!type) return;
+  switch (type) {
+    case "BinaryExpression":
+      visitOperandNode(node.left, visitor);
+      visitOperandNode(node.right, visitor);
+      if (node.escape) {
+        visitOperandNode(node.escape, visitor);
+      }
+      return;
+    case "LogicalExpression":
+      node.operands.forEach((operand) => visitExpressionNode(operand, visitor));
+      return;
+    case "NullExpression":
+      visitOperandNode(node.left, visitor);
+      return;
+    case "InExpression":
+      visitOperandNode(node.left, visitor);
+      if (Array.isArray(node.right)) {
+        node.right.forEach((operand) => visitOperandNode(operand, visitor));
+      } else {
+        visitOperandNode(node.right, visitor);
+      }
+      return;
+    case "ExistsExpression":
+      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;
+    }
+  }
+};
+var visitOperandNode = (node, visitor) => {
+  visitor.visitOperand?.(node);
+  const type = getNodeType3(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));
+      if (node.separator) {
+        visitOperandNode(node.separator, visitor);
+      }
+      return;
+    case "JsonPath":
+      visitOperandNode(node.column, visitor);
+      return;
+    case "ScalarSubquery":
+      visitSelectQuery(node.query, visitor);
+      return;
+    case "CaseExpression":
+      node.conditions.forEach((cond) => {
+        visitExpressionNode(cond.when, visitor);
+        visitOperandNode(cond.then, visitor);
+      });
+      if (node.else) {
+        visitOperandNode(node.else, visitor);
+      }
+      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 = node;
+      return _exhaustive;
+    }
+  }
+};
+var visitSelectQuery = (ast, visitor) => {
+  visitor.visitSelectQuery?.(ast);
+  if (ast.ctes) {
+    for (const cte of ast.ctes) {
+      visitor.visitCte?.(cte);
+      visitSelectQuery(cte.query, visitor);
+    }
+  }
+  visitTableSource(ast.from, visitor);
+  ast.columns?.forEach((col2) => {
+    visitOperandNode(col2, visitor);
+  });
+  ast.joins?.forEach((join) => {
+    visitor.visitJoin?.(join);
+    visitTableSource(join.table, visitor);
+    visitExpressionNode(join.condition, visitor);
+  });
+  if (ast.where) {
+    visitExpressionNode(ast.where, visitor);
+  }
+  ast.groupBy?.forEach((term) => {
+    visitOrderingTerm(term, visitor);
+  });
+  if (ast.having) {
+    visitExpressionNode(ast.having, visitor);
+  }
+  ast.orderBy?.forEach((order) => {
+    visitOrderByNode(order, visitor);
+  });
+  ast.distinct?.forEach((col2) => {
+    visitOperandNode(col2, visitor);
+  });
+  ast.setOps?.forEach((op) => {
+    visitor.visitSetOperation?.(op);
+    visitSelectQuery(op.query, visitor);
+  });
+};
+
+// src/core/ast/ast-validation.ts
+var hasParamOperandsInQuery = (ast) => {
+  let hasParams = false;
+  visitSelectQuery(ast, {
+    visitParam: () => {
+      hasParams = true;
+    }
+  });
+  return hasParams;
+};
+
 // src/query-builder/select.ts
 var SelectQueryBuilder = class _SelectQueryBuilder {
   env;
@@ -7926,6 +8183,17 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
     }
     return this;
   }
+  /**
+   * Validates that the query does not contain Param operands.
+   * Param proxies are only for schema generation, not execution.
+   */
+  validateNoParamOperands() {
+    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.");
+    }
+  }
   /**
    * Executes the query and returns hydrated results.
    * If the builder was created with an entity constructor (e.g. via selectFromEntity),
@@ -7939,6 +8207,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * users[0] instanceof User; // true
    */
   async execute(ctx) {
+    this.validateNoParamOperands();
     if (this.entityConstructor) {
       return this.executeAs(this.entityConstructor, ctx);
     }
@@ -7957,6 +8226,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * rows[0] instanceof User; // false
    */
   async executePlain(ctx) {
+    this.validateNoParamOperands();
     const builder = this.ensureDefaultSelection();
     const rows = await executeHydratedPlain(ctx, builder);
     return rows;
@@ -7976,6 +8246,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * users[0].getFullName();   // works!
    */
   async executeAs(entityClass, ctx) {
+    this.validateNoParamOperands();
     const builder = this.ensureDefaultSelection();
     const results = await executeHydrated(ctx, builder);
     return materializeAs(entityClass, results);
@@ -7987,6 +8258,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * const total = await qb.count(session);
    */
   async count(session) {
+    this.validateNoParamOperands();
     return executeCount(this.context, this.env, session);
   }
   /**
@@ -7996,6 +8268,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * const { items, totalItems, page, pageSize } = await qb.executePaged(session, { page: 1, pageSize: 20 });
    */
   async executePaged(session, options) {
+    this.validateNoParamOperands();
     const builder = this.ensureDefaultSelection();
     return executePagedQuery(builder, session, options, (sess) => builder.count(sess));
   }
@@ -8010,6 +8283,7 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
    * const users = await qb.executeWithContexts(execCtx, hydCtx);
    */
   async executeWithContexts(execCtx, hydCtx) {
+    this.validateNoParamOperands();
     const builder = this.ensureDefaultSelection();
     const results = await executeHydratedWithContexts(execCtx, hydCtx, builder);
     if (this.entityConstructor) {