metal-orm 1.0.81 → 1.0.83

package/src/core/dialect/abstract.ts

@@ -26,25 +26,28 @@ import {
   BetweenExpressionNode,
   ArithmeticExpressionNode,
   BitwiseExpressionNode,
-  CollateExpressionNode,
-  AliasRefNode,
-  isOperandNode
-} from '../ast/expression.js';
+  CollateExpressionNode,
+  AliasRefNode,
+  isOperandNode,
+  ParamNode
+} from '../ast/expression.js';
 import { DialectName } from '../sql/sql.js';
 import type { FunctionStrategy } from '../functions/types.js';
 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
@@ -85,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};`;
@@ -197,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
@@ -452,13 +468,19 @@ export abstract class Dialect
     });
   }
 
-  private registerDefaultOperandCompilers(): void {
-    this.registerOperandCompiler('Literal', (literal: LiteralNode, ctx) => ctx.addParameter(literal.value));
-
-    this.registerOperandCompiler('AliasRef', (alias: AliasRefNode, _ctx) => {
-      void _ctx;
-      return this.quoteIdentifier(alias.name);
-    });
+  private registerDefaultOperandCompilers(): void {
+    this.registerOperandCompiler('Literal', (literal: LiteralNode, ctx) => ctx.addParameter(literal.value));
+    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;
+      return this.quoteIdentifier(alias.name);
+    });
 
     this.registerOperandCompiler('Column', (column: ColumnNode, _ctx) => {
       void _ctx;

package/src/openapi/query-parameters.ts

@@ -117,6 +117,7 @@ const collectFilterColumns = (
       }
       case 'AliasRef':
       case 'Literal':
+      case 'Param':
         return;
       default:
         return;

package/src/query-builder/relation-filter-utils.ts

@@ -144,6 +144,7 @@ const collectFromOperand = (node: OperandNode, collector: FilterTableCollector):
       break;
     case 'Literal':
     case 'AliasRef':
+    case 'Param':
       break;
     default:
       break;

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