metal-orm 1.0.82 → 1.0.85

package/src/core/dialect/abstract.ts

@@ -37,15 +37,17 @@ import { StandardFunctionStrategy } from '../functions/standard-strategy.js';
 import type { TableFunctionStrategy } from '../functions/table-types.js';
 import { StandardTableFunctionStrategy } from '../functions/standard-table-strategy.js';
 
-/**
- * Context for SQL compilation with parameter management
- */
-export interface CompilerContext {
-  /** Array of parameters */
-  params: unknown[];
-  /** Function to add a parameter and get its placeholder */
-  addParameter(value: unknown): string;
-}
+/**
+ * Context for SQL compilation with parameter management
+ */
+export interface CompilerContext {
+  /** Array of parameters */
+  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
@@ -86,18 +88,29 @@ export abstract class Dialect
    * @param ast - Query AST to compile
    * @returns Compiled query with SQL and parameters
    */
-  compileSelect(ast: SelectQueryNode): CompiledQuery {
-    const ctx = this.createCompilerContext();
-    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: InsertQueryNode): CompiledQuery {
+  compileSelect(ast: SelectQueryNode): CompiledQuery {
+    const ctx = this.createCompilerContext();
+    const normalized = this.normalizeSelectAst(ast);
+    const rawSql = this.compileSelectAst(normalized, ctx).trim();
+    const sql = rawSql.endsWith(';') ? rawSql : `${rawSql};`;
+    return {
+      sql,
+      params: [...ctx.params]
+    };
+  }
+
+  compileSelectWithOptions(ast: SelectQueryNode, options: { allowParams?: boolean } = {}): CompiledQuery {
+    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: InsertQueryNode): CompiledQuery {
     const ctx = this.createCompilerContext();
     const rawSql = this.compileInsertAst(ast, ctx).trim();
     const sql = rawSql.endsWith(';') ? rawSql : `${rawSql};`;
@@ -198,22 +211,24 @@ export abstract class Dialect
     return `SELECT 1${tail}`;
   }
 
-  /**
-   * Creates a new compiler context
-   * @returns Compiler context with parameter management
-   */
-  protected createCompilerContext(): CompilerContext {
-    const params: unknown[] = [];
-    let counter = 0;
-    return {
-      params,
-      addParameter: (value: unknown) => {
-        counter += 1;
-        params.push(value);
-        return this.formatPlaceholder(counter);
-      }
-    };
-  }
+  /**
+   * Creates a new compiler context
+   * @param options - Optional compiler context options
+   * @returns Compiler context with parameter management
+   */
+  protected createCompilerContext(options: { allowParams?: boolean } = {}): CompilerContext {
+    const params: unknown[] = [];
+    let counter = 0;
+    return {
+      params,
+      allowParams: options.allowParams ?? false,
+      addParameter: (value: unknown) => {
+        counter += 1;
+        params.push(value);
+        return this.formatPlaceholder(counter);
+      }
+    };
+  }
 
   /**
    * Formats a parameter placeholder
@@ -372,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).
@@ -453,9 +472,14 @@ export abstract class Dialect
     });
   }
 
-  private registerDefaultOperandCompilers(): void {
+  private registerDefaultOperandCompilers(): void {
     this.registerOperandCompiler('Literal', (literal: LiteralNode, ctx) => ctx.addParameter(literal.value));
-    this.registerOperandCompiler('Param', (_param: ParamNode, ctx) => ctx.addParameter(null));
+    this.registerOperandCompiler('Param', (_param: ParamNode, 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: AliasRefNode, _ctx) => {
       void _ctx;

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.ts

@@ -68,6 +68,7 @@ import { SelectCTEFacet } from './select/cte-facet.js';
 import { SelectSetOpFacet } from './select/setop-facet.js';
 import { SelectRelationFacet } from './select/relation-facet.js';
 import { buildFilterParameters, extractSchema, SchemaOptions, OpenApiSchemaBundle } from '../openapi/index.js';
+import { hasParamOperandsInQuery } from '../core/ast/ast-validation.js';
 
 type ColumnSelectionValue =
   | ColumnDef
@@ -713,120 +714,138 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
     return this.env.table as TTable;
   }
 
-  /**
-   * Ensures that if no columns are selected, all columns from the table are selected by default.
-   */
-  private ensureDefaultSelection(): SelectQueryBuilder<T, TTable> {
-    const columns = this.context.state.ast.columns;
-    if (!columns || columns.length === 0) {
-      const columnKeys = Object.keys(this.env.table.columns) as (keyof TTable['columns'] & string)[];
-      return this.select(...columnKeys);
-    }
-    return this;
-  }
-
-  /**
-   * Executes the query and returns hydrated results.
-   * If the builder was created with an entity constructor (e.g. via selectFromEntity),
-   * this will automatically return fully materialized entity instances.
-   *
-   * @param ctx - ORM session context
-   * @returns Promise of entity instances (or objects if generic T is not an entity)
-   * @example
-   * const users = await selectFromEntity(User).execute(session);
-   * // users is User[]
-   * users[0] instanceof User; // true
-   */
-  async execute(ctx: OrmSession): Promise<T[]> {
-    if (this.entityConstructor) {
-      return this.executeAs(this.entityConstructor, ctx) as unknown as T[];
-    }
-    const builder = this.ensureDefaultSelection();
-    return executeHydrated(ctx, builder) as unknown as T[];
-  }
+  /**
+   * Ensures that if no columns are selected, all columns from the table are selected by default.
+   */
+  private ensureDefaultSelection(): SelectQueryBuilder<T, TTable> {
+    const columns = this.context.state.ast.columns;
+    if (!columns || columns.length === 0) {
+      const columnKeys = Object.keys(this.env.table.columns) as (keyof TTable['columns'] & string)[];
+      return this.select(...columnKeys);
+    }
+    return this;
+  }
+
+  /**
+   * Validates that the query does not contain Param operands.
+   * Param proxies are only for schema generation, not execution.
+   */
+  private validateNoParamOperands(): void {
+    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 plain row objects (POJOs), ignoring any entity materialization.
-   * Use this if you want raw data even when using selectFromEntity.
-   *
-   * @param ctx - ORM session context
-   * @returns Promise of plain entity instances
-   * @example
-   * const rows = await selectFromEntity(User).executePlain(session);
-   * // rows is EntityInstance<UserTable>[] (plain objects)
-   * rows[0] instanceof User; // false
-   */
-  async executePlain(ctx: OrmSession): Promise<EntityInstance<TTable>[]> {
-    const builder = this.ensureDefaultSelection();
-    const rows = await executeHydratedPlain(ctx, builder);
-    return rows as EntityInstance<TTable>[];
-  }
+  /**
+   * Executes the query and returns hydrated results.
+   * If the builder was created with an entity constructor (e.g. via selectFromEntity),
+   * this will automatically return fully materialized entity instances.
+   *
+   * @param ctx - ORM session context
+   * @returns Promise of entity instances (or objects if generic T is not an entity)
+   * @example
+   * const users = await selectFromEntity(User).execute(session);
+   * // users is User[]
+   * users[0] instanceof User; // true
+   */
+  async execute(ctx: OrmSession): Promise<T[]> {
+    this.validateNoParamOperands();
+    if (this.entityConstructor) {
+      return this.executeAs(this.entityConstructor, ctx) as unknown as T[];
+    }
+    const builder = this.ensureDefaultSelection();
+    return executeHydrated(ctx, builder) as unknown as T[];
+  }
 
-  /**
-   * Executes the query and returns results as real class instances.
-   * Unlike execute(), this returns actual instances of the decorated entity class
-   * with working methods and proper instanceof checks.
-   * @param entityClass - The entity class constructor
-   * @param ctx - ORM session context
-   * @returns Promise of entity class instances
-   * @example
-   * const users = await selectFromEntity(User)
-   *   .include('posts')
-   *   .executeAs(User, session);
-   * users[0] instanceof User; // true!
-   * users[0].getFullName();   // works!
-   */
-  async executeAs<TEntity extends object>(
-    entityClass: EntityConstructor<TEntity>,
-    ctx: OrmSession
-  ): Promise<TEntity[]> {
-    const builder = this.ensureDefaultSelection();
-    const results = await executeHydrated(ctx, builder);
-    return materializeAs(entityClass, results as unknown as Record<string, unknown>[]);
-  }
+  /**
+   * Executes the query and returns plain row objects (POJOs), ignoring any entity materialization.
+   * Use this if you want raw data even when using selectFromEntity.
+   *
+   * @param ctx - ORM session context
+   * @returns Promise of plain entity instances
+   * @example
+   * const rows = await selectFromEntity(User).executePlain(session);
+   * // rows is EntityInstance<UserTable>[] (plain objects)
+   * rows[0] instanceof User; // false
+   */
+  async executePlain(ctx: OrmSession): Promise<EntityInstance<TTable>[]> {
+    this.validateNoParamOperands();
+    const builder = this.ensureDefaultSelection();
+    const rows = await executeHydratedPlain(ctx, builder);
+    return rows as EntityInstance<TTable>[];
+  }
 
-  /**
-   * Executes a count query for the current builder without LIMIT/OFFSET clauses.
-   *
-   * @example
-   * const total = await qb.count(session);
-   */
-  async count(session: OrmSession): Promise<number> {
-    return executeCount(this.context, this.env, session);
-  }
+  /**
+   * Executes the query and returns results as real class instances.
+   * Unlike execute(), this returns actual instances of the decorated entity class
+   * with working methods and proper instanceof checks.
+   * @param entityClass - The entity class constructor
+   * @param ctx - ORM session context
+   * @returns Promise of entity class instances
+   * @example
+   * const users = await selectFromEntity(User)
+   *   .include('posts')
+   *   .executeAs(User, session);
+   * users[0] instanceof User; // true!
+   * users[0].getFullName();   // works!
+   */
+  async executeAs<TEntity extends object>(
+    entityClass: EntityConstructor<TEntity>,
+    ctx: OrmSession
+  ): Promise<TEntity[]> {
+    this.validateNoParamOperands();
+    const builder = this.ensureDefaultSelection();
+    const results = await executeHydrated(ctx, builder);
+    return materializeAs(entityClass, results as unknown as Record<string, unknown>[]);
+  }
 
-  /**
-   * Executes the query and returns both the paged items and the total.
-   *
-   * @example
-   * const { items, totalItems, page, pageSize } = await qb.executePaged(session, { page: 1, pageSize: 20 });
-   */
-  async executePaged(
-    session: OrmSession,
-    options: { page: number; pageSize: number }
-  ): Promise<PaginatedResult<T>> {
-    const builder = this.ensureDefaultSelection();
-    return executePagedQuery(builder, session, options, sess => builder.count(sess));
-  }
+  /**
+   * Executes a count query for the current builder without LIMIT/OFFSET clauses.
+   *
+   * @example
+   * const total = await qb.count(session);
+   */
+  async count(session: OrmSession): Promise<number> {
+    this.validateNoParamOperands();
+    return executeCount(this.context, this.env, session);
+  }
+
+  /**
+   * Executes the query and returns both the paged items and the total.
+   *
+   * @example
+   * const { items, totalItems, page, pageSize } = await qb.executePaged(session, { page: 1, pageSize: 20 });
+   */
+  async executePaged(
+    session: OrmSession,
+    options: { page: number; pageSize: number }
+  ): Promise<PaginatedResult<T>> {
+    this.validateNoParamOperands();
+    const builder = this.ensureDefaultSelection();
+    return executePagedQuery(builder, session, options, sess => builder.count(sess));
+  }
 
-  /**
-   * Executes the query with provided execution and hydration contexts
-   * @param execCtx - Execution context
-   * @param hydCtx - Hydration context
-   * @returns Promise of entity instances
-   * @example
-   * const execCtx = new ExecutionContext(session);
-   * const hydCtx = new HydrationContext();
-   * const users = await qb.executeWithContexts(execCtx, hydCtx);
-   */
-  async executeWithContexts(execCtx: ExecutionContext, hydCtx: HydrationContext): Promise<T[]> {
-    const builder = this.ensureDefaultSelection();
-    const results = await executeHydratedWithContexts(execCtx, hydCtx, builder);
-    if (this.entityConstructor) {
-      return materializeAs(this.entityConstructor, results as unknown as Record<string, unknown>[]) as unknown as T[];
-    }
-    return results as unknown as T[];
-  }
+  /**
+   * Executes the query with provided execution and hydration contexts
+   * @param execCtx - Execution context
+   * @param hydCtx - Hydration context
+   * @returns Promise of entity instances
+   * @example
+   * const execCtx = new ExecutionContext(session);
+   * const hydCtx = new HydrationContext();
+   * const users = await qb.executeWithContexts(execCtx, hydCtx);
+   */
+  async executeWithContexts(execCtx: ExecutionContext, hydCtx: HydrationContext): Promise<T[]> {
+    this.validateNoParamOperands();
+    const builder = this.ensureDefaultSelection();
+    const results = await executeHydratedWithContexts(execCtx, hydCtx, builder);
+    if (this.entityConstructor) {
+      return materializeAs(this.entityConstructor, results as unknown as Record<string, unknown>[]) as unknown as T[];
+    }
+    return results as unknown as T[];
+  }
 
   /**
    * Adds a WHERE condition to the query