metal-orm 1.0.89 → 1.0.91

package/src/core/dialect/abstract.ts

@@ -26,28 +26,25 @@ import {
   BetweenExpressionNode,
   ArithmeticExpressionNode,
   BitwiseExpressionNode,
-  CollateExpressionNode,
-  AliasRefNode,
-  isOperandNode,
-  ParamNode
-} from '../ast/expression.js';
+  CollateExpressionNode,
+  AliasRefNode,
+  isOperandNode
+} 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;
-  /** Whether Param operands are allowed (for schema generation) */
-  allowParams?: boolean;
-}
+/**
+ * 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;
+}
 
 /**
  * Result of SQL compilation
@@ -88,29 +85,18 @@ 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]
-    };
-  }
-
-  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 {
+  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 {
     const ctx = this.createCompilerContext();
     const rawSql = this.compileInsertAst(ast, ctx).trim();
     const sql = rawSql.endsWith(';') ? rawSql : `${rawSql};`;
@@ -211,24 +197,22 @@ export abstract class Dialect
     return `SELECT 1${tail}`;
   }
 
-  /**
-   * 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);
-      }
-    };
-  }
+  /**
+   * 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);
+      }
+    };
+  }
 
   /**
    * Formats a parameter placeholder
@@ -387,17 +371,13 @@ export abstract class Dialect
    * @param ctx - Compiler context
    * @returns Compiled SQL operand
    */
-  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);
-  }
+  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);
+  }
 
   /**
    * Compiles an ordering term (operand, expression, or alias reference).
@@ -472,19 +452,13 @@ export abstract class Dialect
     });
   }
 
-  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);
-    });
+  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);
+    });
 
     this.registerOperandCompiler('Column', (column: ColumnNode, _ctx) => {
       void _ctx;

package/src/core/execution/db-executor.ts

@@ -1,11 +1,10 @@
 // src/core/execution/db-executor.ts
 
 // low-level canonical shape
-export type QueryResult = {
-  columns: string[];
-  values: unknown[][];
-  insertId?: number;
-};
+export type QueryResult = {
+  columns: string[];
+  values: unknown[][];
+};
 
 export interface DbExecutor {
   /** Capability flags so the runtime can make correct decisions without relying on optional methods. */

package/src/core/execution/executors/mysql-executor.ts

@@ -31,15 +31,13 @@ export function createMysqlExecutor(
     capabilities: {
       transactions: supportsTransactions,
     },
-    async executeSql(sql, params) {
-      const [rows] = await client.query(sql, params);
-
-      if (!Array.isArray(rows)) {
-        const insertId = (rows as { insertId?: number } | null)?.insertId;
-        const normalized = typeof insertId === 'number' && insertId > 0 ? insertId : undefined;
-        // e.g. insert/update returning only headers, treat as no rows
-        return [{ columns: [], values: [], insertId: normalized }];
-      }
+    async executeSql(sql, params) {
+      const [rows] = await client.query(sql, params);
+
+      if (!Array.isArray(rows)) {
+        // e.g. insert/update returning only headers, treat as no rows
+        return [{ columns: [], values: [] }];
+      }
 
       const result = rowsToQueryResult(
         rows as Array<Record<string, unknown>>

package/src/decorators/bootstrap.ts

@@ -182,6 +182,9 @@ export const getTableDefFromEntity = <TTable extends TableDef = TableDef>(ctor:
   if (!meta.table) {
     bootstrapEntities();
   }
+  if (!meta.table) {
+    throw new Error(`Failed to build table definition for entity '${ctor.name}'`);
+  }
   return meta.table as TTable;
 };
 
@@ -245,29 +248,29 @@ export const selectFromEntity = <TEntity extends object>(
  * Lazily bootstraps entity metadata (via getTableDefFromEntity) and returns a
  * `tableRef(...)`-style proxy so users can write `u.id` instead of `u.columns.id`.
  */
-export const entityRef = <TEntity extends object>(
-  ctor: EntityConstructor<TEntity>
-): TableRef<EntityTable<TEntity>> => {
-  const table = getTableDefFromEntity(ctor);
-  if (!table) {
-    throw new Error(`Entity '${ctor.name}' is not registered with decorators or has not been bootstrapped`);
-  }
-  return tableRef(table as EntityTable<TEntity>);
-};
-
-type EntityRefsTuple<T extends readonly EntityConstructor<object>[]> = {
-  [K in keyof T]: T[K] extends EntityConstructor<infer TEntity>
-  ? TableRef<EntityTable<TEntity & object>>
-  : never;
-};
-
-/**
- * Public API: variadic entity references.
- * Usage:
- *   const [u, p] = entityRefs(User, Post);
- */
-export const entityRefs = <T extends readonly EntityConstructor<object>[]>(
-  ...ctors: T
-): EntityRefsTuple<T> => {
-  return ctors.map(ctor => entityRef(ctor)) as EntityRefsTuple<T>;
-};
+export const entityRef = <TEntity extends object>(
+  ctor: EntityConstructor<TEntity>
+): TableRef<EntityTable<TEntity>> => {
+  const table = getTableDefFromEntity(ctor);
+  if (!table) {
+    throw new Error(`Entity '${ctor.name}' is not registered with decorators or has not been bootstrapped`);
+  }
+  return tableRef(table as EntityTable<TEntity>);
+};
+
+type EntityRefsTuple<T extends readonly EntityConstructor<object>[]> = {
+  [K in keyof T]: T[K] extends EntityConstructor<infer TEntity>
+  ? TableRef<EntityTable<TEntity & object>>
+  : never;
+};
+
+/**
+ * Public API: variadic entity references.
+ * Usage:
+ *   const [u, p] = entityRefs(User, Post);
+ */
+export const entityRefs = <T extends readonly EntityConstructor<object>[]>(
+  ...ctors: T
+): EntityRefsTuple<T> => {
+  return ctors.map(ctor => entityRef(ctor)) as EntityRefsTuple<T>;
+};

package/src/dto/apply-filter.ts

@@ -0,0 +1,279 @@
+/**
+ * Runtime filter application - converts JSON filter objects to query builder conditions.
+ */
+
+import type { TableDef } from '../schema/table.js';
+import type { ColumnDef } from '../schema/column-types.js';
+import type { SelectQueryBuilder } from '../query-builder/select.js';
+import type { WhereInput, FilterValue, StringFilter } from './filter-types.js';
+import type { EntityConstructor } from '../orm/entity-metadata.js';
+import { getTableDefFromEntity } from '../decorators/bootstrap.js';
+import {
+  eq,
+  neq,
+  gt,
+  gte,
+  lt,
+  lte,
+  like,
+  inList,
+  notInList,
+  and,
+  type ExpressionNode
+} from '../core/ast/expression.js';
+
+/**
+ * Builds an expression node from a single field filter.
+ */
+function buildFieldExpression(
+  column: ColumnDef,
+  filter: FilterValue
+): ExpressionNode | null {
+  const expressions: ExpressionNode[] = [];
+
+  // String filters
+  if ('contains' in filter && filter.contains !== undefined) {
+    const pattern = `%${escapePattern(filter.contains)}%`;
+    const mode = (filter as StringFilter).mode;
+    if (mode === 'insensitive') {
+      expressions.push(caseInsensitiveLike(column, pattern));
+    } else {
+      expressions.push(like(column, pattern));
+    }
+  }
+
+  if ('startsWith' in filter && filter.startsWith !== undefined) {
+    const pattern = `${escapePattern(filter.startsWith)}%`;
+    const mode = (filter as StringFilter).mode;
+    if (mode === 'insensitive') {
+      expressions.push(caseInsensitiveLike(column, pattern));
+    } else {
+      expressions.push(like(column, pattern));
+    }
+  }
+
+  if ('endsWith' in filter && filter.endsWith !== undefined) {
+    const pattern = `%${escapePattern(filter.endsWith)}`;
+    const mode = (filter as StringFilter).mode;
+    if (mode === 'insensitive') {
+      expressions.push(caseInsensitiveLike(column, pattern));
+    } else {
+      expressions.push(like(column, pattern));
+    }
+  }
+
+  // Common filters (equals, not, in, notIn)
+  if ('equals' in filter && filter.equals !== undefined) {
+    expressions.push(eq(column, filter.equals as string | number | boolean));
+  }
+
+  if ('not' in filter && filter.not !== undefined) {
+    expressions.push(neq(column, filter.not as string | number | boolean));
+  }
+
+  if ('in' in filter && filter.in !== undefined) {
+    expressions.push(inList(column, filter.in as (string | number)[]));
+  }
+
+  if ('notIn' in filter && filter.notIn !== undefined) {
+    expressions.push(notInList(column, filter.notIn as (string | number)[]));
+  }
+
+  // Comparison filters (lt, lte, gt, gte)
+  if ('lt' in filter && filter.lt !== undefined) {
+    expressions.push(lt(column, filter.lt as string | number));
+  }
+
+  if ('lte' in filter && filter.lte !== undefined) {
+    expressions.push(lte(column, filter.lte as string | number));
+  }
+
+  if ('gt' in filter && filter.gt !== undefined) {
+    expressions.push(gt(column, filter.gt as string | number));
+  }
+
+  if ('gte' in filter && filter.gte !== undefined) {
+    expressions.push(gte(column, filter.gte as string | number));
+  }
+
+  if (expressions.length === 0) {
+    return null;
+  }
+
+  if (expressions.length === 1) {
+    return expressions[0];
+  }
+
+  return and(...expressions);
+}
+
+/**
+ * Escapes special LIKE pattern characters.
+ */
+function escapePattern(value: string): string {
+  return value.replace(/[%_\\]/g, '\\$&');
+}
+
+/**
+ * Creates a case-insensitive LIKE expression using LOWER().
+ * This is portable across all SQL dialects.
+ */
+function caseInsensitiveLike(column: ColumnDef, pattern: string): ExpressionNode {
+  return {
+    type: 'BinaryExpression',
+    left: {
+      type: 'Function',
+      name: 'LOWER',
+      args: [{ type: 'Column', table: column.table!, name: column.name }]
+    },
+    operator: 'LIKE',
+    right: { type: 'Literal', value: pattern.toLowerCase() }
+  } as unknown as ExpressionNode;
+}
+
+/**
+ * Applies a filter object to a SelectQueryBuilder.
+ * All conditions are AND-ed together.
+ *
+ * @param qb - The query builder to apply filters to
+ * @param tableOrEntity - The table definition or entity constructor (used to resolve column references)
+ * @param where - The filter object from: API request
+ * @returns The query builder with filters applied
+ *
+ * @example
+ * ```ts
+ * // In a controller - using Entity class
+ * @Get()
+ * async list(@Query() where?: UserFilter): Promise<UserResponse[]> {
+ *   let query = selectFromEntity(User);
+ *   query = applyFilter(query, User, where);
+ *   return query.execute(db);
+ * }
+ *
+ * // Using TableDef directly
+ * @Get()
+ * async list(@Query() where?: UserFilter): Promise<UserResponse[]> {
+ *   let query = selectFrom(usersTable);
+ *   query = applyFilter(query, usersTable, where);
+ *   return query.execute(db);
+ * }
+ *
+ * // Request: { "name": { "contains": "john" }, "email": { "endsWith": "@gmail.com" } }
+ * // SQL: WHERE name LIKE '%john%' AND email LIKE '%@gmail.com'
+ * ```
+ */
+export function applyFilter<T, TTable extends TableDef>(
+  qb: SelectQueryBuilder<T, TTable>,
+  tableOrEntity: TTable | EntityConstructor,
+  where?: WhereInput<TTable | EntityConstructor> | null
+): SelectQueryBuilder<T, TTable> {
+  if (!where) {
+    return qb;
+  }
+
+  const table = isEntityConstructor(tableOrEntity)
+    ? getTableDefFromEntity(tableOrEntity)
+    : tableOrEntity;
+
+  if (!table) {
+    return qb;
+  }
+
+  const expressions: ExpressionNode[] = [];
+
+  for (const [fieldName, fieldFilter] of Object.entries(where)) {
+    if (fieldFilter === undefined || fieldFilter === null) {
+      continue;
+    }
+
+    const column = table.columns[fieldName];
+    if (!column) {
+      continue;
+    }
+
+    const expr = buildFieldExpression(column, fieldFilter as FilterValue);
+    if (expr) {
+      expressions.push(expr);
+    }
+  }
+
+  if (expressions.length === 0) {
+    return qb;
+  }
+
+  if (expressions.length === 1) {
+    return qb.where(expressions[0]);
+  }
+
+  return qb.where(and(...expressions));
+}
+
+function isEntityConstructor(value: unknown): value is EntityConstructor {
+  return typeof value === 'function' && value.prototype?.constructor === value;
+}
+
+/**
+ * Builds an expression tree from a filter object without applying it.
+ * Useful for combining with other conditions.
+ *
+ * @param tableOrEntity - The table definition or entity constructor
+ * @param where - The filter object
+ * @returns An expression node or null if no filters
+ *
+ * @example
+ * ```ts
+ * // Using Entity class
+ * const filterExpr = buildFilterExpression(User, { name: { contains: "john" } });
+ *
+ * // Using TableDef directly
+ * const filterExpr = buildFilterExpression(usersTable, { name: { contains: "john" } });
+ *
+ * if (filterExpr) {
+ *   qb = qb.where(and(filterExpr, eq(users.columns.active, true)));
+ * }
+ * ```
+ */
+export function buildFilterExpression(
+  tableOrEntity: TableDef | EntityConstructor,
+  where?: WhereInput<TableDef | EntityConstructor> | null
+): ExpressionNode | null {
+  if (!where) {
+    return null;
+  }
+
+  const table = isEntityConstructor(tableOrEntity)
+    ? getTableDefFromEntity(tableOrEntity)
+    : tableOrEntity;
+
+  if (!table) {
+    return null;
+  }
+
+  const expressions: ExpressionNode[] = [];
+
+  for (const [fieldName, fieldFilter] of Object.entries(where)) {
+    if (fieldFilter === undefined || fieldFilter === null) {
+      continue;
+    }
+
+    const column = table.columns[fieldName];
+    if (!column) {
+      continue;
+    }
+
+    const expr = buildFieldExpression(column, fieldFilter as FilterValue);
+    if (expr) {
+      expressions.push(expr);
+    }
+  }
+
+  if (expressions.length === 0) {
+    return null;
+  }
+
+  if (expressions.length === 1) {
+    return expressions[0];
+  }
+
+  return and(...expressions);
+}