metal-orm 1.0.83 → 1.0.86

package/src/query-builder/select.ts

@@ -68,7 +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';
+import { findFirstParamOperandName } from '../core/ast/ast-validation.js';
 
 type ColumnSelectionValue =
   | ColumnDef
@@ -82,10 +82,14 @@ type SelectionValueType<TValue> =
   TValue extends ColumnDef ? ColumnToTs<TValue> :
   unknown;
 
-type SelectionResult<TSelection extends Record<string, ColumnSelectionValue>> = {
-  [K in keyof TSelection]: SelectionValueType<TSelection[K]>;
-};
-
+type SelectionResult<TSelection extends Record<string, ColumnSelectionValue>> = {
+  [K in keyof TSelection]: SelectionValueType<TSelection[K]>;
+};
+
+type ParamOperandOptions = {
+  allowParamOperands?: boolean;
+};
+
 type SelectionFromKeys<
   TTable extends TableDef,
   K extends keyof TTable['columns'] & string
@@ -730,11 +734,12 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
    * Validates that the query does not contain Param operands.
    * Param proxies are only for schema generation, not execution.
    */
-  private validateNoParamOperands(): void {
+  private validateNoParamOperands(options?: ParamOperandOptions): void {
+    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.`);
     }
   }
 
@@ -750,13 +755,13 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
    * // users is User[]
    * users[0] instanceof User; // true
    */
-  async execute(ctx: OrmSession): Promise<T[]> {
-    this.validateNoParamOperands();
+  async execute(ctx: OrmSession, options?: ParamOperandOptions): Promise<T[]> {
+    this.validateNoParamOperands(options);
     if (this.entityConstructor) {
-      return this.executeAs(this.entityConstructor, ctx) as unknown as T[];
+      return this.executeAs(this.entityConstructor, ctx, options) as unknown as T[];
     }
     const builder = this.ensureDefaultSelection();
-    return executeHydrated(ctx, builder) as unknown as T[];
+    return executeHydrated(ctx, builder, options) as unknown as T[];
   }
 
   /**
@@ -770,10 +775,10 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
    * // rows is EntityInstance<UserTable>[] (plain objects)
    * rows[0] instanceof User; // false
    */
-  async executePlain(ctx: OrmSession): Promise<EntityInstance<TTable>[]> {
-    this.validateNoParamOperands();
+  async executePlain(ctx: OrmSession, options?: ParamOperandOptions): Promise<EntityInstance<TTable>[]> {
+    this.validateNoParamOperands(options);
     const builder = this.ensureDefaultSelection();
-    const rows = await executeHydratedPlain(ctx, builder);
+    const rows = await executeHydratedPlain(ctx, builder, options);
     return rows as EntityInstance<TTable>[];
   }
 
@@ -793,11 +798,12 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
    */
   async executeAs<TEntity extends object>(
     entityClass: EntityConstructor<TEntity>,
-    ctx: OrmSession
+    ctx: OrmSession,
+    options?: ParamOperandOptions
   ): Promise<TEntity[]> {
-    this.validateNoParamOperands();
+    this.validateNoParamOperands(options);
     const builder = this.ensureDefaultSelection();
-    const results = await executeHydrated(ctx, builder);
+    const results = await executeHydrated(ctx, builder, options);
     return materializeAs(entityClass, results as unknown as Record<string, unknown>[]);
   }
 
@@ -807,9 +813,9 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
    * @example
    * const total = await qb.count(session);
    */
-  async count(session: OrmSession): Promise<number> {
-    this.validateNoParamOperands();
-    return executeCount(this.context, this.env, session);
+  async count(session: OrmSession, options?: ParamOperandOptions): Promise<number> {
+    this.validateNoParamOperands(options);
+    return executeCount(this.context, this.env, session, options);
   }
 
   /**
@@ -820,11 +826,11 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
    */
   async executePaged(
     session: OrmSession,
-    options: { page: number; pageSize: number }
+    options: { page: number; pageSize: number } & ParamOperandOptions
   ): Promise<PaginatedResult<T>> {
-    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);
   }
 
   /**
@@ -837,10 +843,10 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
    * const hydCtx = new HydrationContext();
    * const users = await qb.executeWithContexts(execCtx, hydCtx);
    */
-  async executeWithContexts(execCtx: ExecutionContext, hydCtx: HydrationContext): Promise<T[]> {
-    this.validateNoParamOperands();
+  async executeWithContexts(execCtx: ExecutionContext, hydCtx: HydrationContext, options?: ParamOperandOptions): Promise<T[]> {
+    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 as unknown as Record<string, unknown>[]) as unknown as T[];
     }
@@ -1109,10 +1115,18 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
    *   .compile('postgres');
    * console.log(compiled.sql); // SELECT "id", "name" FROM "users" WHERE "active" = true
    */
-  compile(dialect: SelectDialectInput): CompiledQuery {
-    const resolved = resolveDialectInput(dialect);
-    return resolved.compileSelect(this.getAST());
-  }
+  compile(dialect: SelectDialectInput, options?: ParamOperandOptions): CompiledQuery {
+    const resolved = resolveDialectInput(dialect);
+    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
@@ -1124,9 +1138,9 @@ export class SelectQueryBuilder<T = EntityInstance<TableDef>, TTable extends Tab
    *   .toSql('postgres');
    * console.log(sql); // SELECT "id", "name" FROM "users" WHERE "active" = true
    */
-  toSql(dialect: SelectDialectInput): string {
-    return this.compile(dialect).sql;
-  }
+  toSql(dialect: SelectDialectInput, options?: ParamOperandOptions): string {
+    return this.compile(dialect, options).sql;
+  }
 
   /**
    * Gets hydration plan for query