metal-orm 1.0.13 → 1.0.15

package/src/core/ddl/schema-types.ts

@@ -1,39 +1,46 @@
-import { ForeignKeyReference } from '../../schema/column.js';
-import { IndexColumn } from '../../schema/table.js';
-
-export interface DatabaseColumn {
-  name: string;
-  type: string;
-  notNull?: boolean;
-  default?: unknown;
-  autoIncrement?: boolean;
-  generated?: 'always' | 'byDefault';
-  unique?: boolean | string;
-  references?: ForeignKeyReference;
-  check?: string;
-}
-
-export interface DatabaseIndex {
-  name: string;
-  columns: IndexColumn[];
-  unique?: boolean;
-  where?: string;
-}
-
-export interface DatabaseCheck {
-  name?: string;
-  expression: string;
-}
-
-export interface DatabaseTable {
-  name: string;
-  schema?: string;
-  columns: DatabaseColumn[];
-  primaryKey?: string[];
-  indexes?: DatabaseIndex[];
-  checks?: DatabaseCheck[];
-}
-
-export interface DatabaseSchema {
-  tables: DatabaseTable[];
-}
+import { ForeignKeyReference } from '../../schema/column.js';
+import { IndexColumn } from '../../schema/table.js';
+
+export interface ColumnDiff {
+  typeChanged?: boolean;
+  nullabilityChanged?: boolean;
+  defaultChanged?: boolean;
+  autoIncrementChanged?: boolean;
+}
+
+export interface DatabaseColumn {
+  name: string;
+  type: string;
+  notNull?: boolean;
+  default?: unknown;
+  autoIncrement?: boolean;
+  generated?: 'always' | 'byDefault';
+  unique?: boolean | string;
+  references?: ForeignKeyReference;
+  check?: string;
+}
+
+export interface DatabaseIndex {
+  name: string;
+  columns: IndexColumn[];
+  unique?: boolean;
+  where?: string;
+}
+
+export interface DatabaseCheck {
+  name?: string;
+  expression: string;
+}
+
+export interface DatabaseTable {
+  name: string;
+  schema?: string;
+  columns: DatabaseColumn[];
+  primaryKey?: string[];
+  indexes?: DatabaseIndex[];
+  checks?: DatabaseCheck[];
+}
+
+export interface DatabaseSchema {
+  tables: DatabaseTable[];
+}

package/src/core/ddl/sql-writing.ts

@@ -0,0 +1,170 @@
+import type { TableDef, IndexColumn } from '../../schema/table.js';
+import type { RawDefaultValue } from '../../schema/column.js';
+
+/**
+ * Minimal surface for anything that can quote identifiers.
+ * Implemented by SchemaDialect, runtime Dialect, etc.
+ */
+export interface Quoter {
+  quoteIdentifier(id: string): string;
+}
+
+/**
+ * Escape a value to be safe inside a single-quoted SQL literal.
+ * Purely mechanical; no dialect knowledge.
+ */
+export const escapeSqlString = (value: string): string =>
+  value.replace(/'/g, "''");
+
+/**
+ * Narrow a value to the RawDefaultValue shape.
+ * This is domain-specific but dialect-agnostic.
+ */
+export const isRawDefault = (value: unknown): value is RawDefaultValue =>
+  typeof value === 'object' &&
+  value !== null &&
+  'raw' in value &&
+  typeof (value as RawDefaultValue).raw === 'string';
+
+/**
+ * Abstraction for "how do I turn values into SQL literals".
+ * Implemented or configured by each dialect.
+ */
+export interface LiteralFormatter {
+  formatLiteral(value: unknown): string;
+}
+
+/**
+ * Declarative options for building a LiteralFormatter.
+ * Dialects configure behavior by data, not by being hard-coded here.
+ */
+export interface LiteralFormatOptions {
+  nullLiteral?: string; // default: 'NULL'
+  booleanTrue?: string; // default: 'TRUE'
+  booleanFalse?: string; // default: 'FALSE'
+
+  numberFormatter?: (value: number) => string;
+  dateFormatter?: (value: Date) => string;
+  stringWrapper?: (escaped: string) => string; // how to wrap an escaped string
+  jsonWrapper?: (escaped: string) => string;   // how to wrap escaped JSON
+}
+
+/**
+ * Factory for a value-based LiteralFormatter that:
+ * - Handles type dispatch (null/number/boolean/date/string/object/raw)
+ * - Delegates representation choices to options
+ * - Knows nothing about concrete dialects
+ */
+export const createLiteralFormatter = (
+  options: LiteralFormatOptions = {}
+): LiteralFormatter => {
+  const {
+    nullLiteral = 'NULL',
+    booleanTrue = 'TRUE',
+    booleanFalse = 'FALSE',
+
+    numberFormatter = (value: number): string =>
+      Number.isFinite(value) ? String(value) : nullLiteral,
+
+    dateFormatter = (value: Date): string =>
+      `'${escapeSqlString(value.toISOString())}'`,
+
+    stringWrapper = (escaped: string): string => `'${escaped}'`,
+    jsonWrapper = (escaped: string): string => `'${escaped}'`,
+  } = options;
+
+  const wrapString = stringWrapper;
+  const wrapJson = jsonWrapper;
+
+  const format = (value: unknown): string => {
+    // Domain rule: raw defaults bypass all formatting.
+    if (isRawDefault(value)) return value.raw;
+
+    if (value === null) return nullLiteral;
+
+    if (typeof value === 'number') {
+      return numberFormatter(value);
+    }
+
+    if (typeof value === 'boolean') {
+      return value ? booleanTrue : booleanFalse;
+    }
+
+    if (value instanceof Date) {
+      return dateFormatter(value);
+    }
+
+    if (typeof value === 'string') {
+      return wrapString(escapeSqlString(value));
+    }
+
+    // Fallback: serialize to JSON then treat as string.
+    return wrapJson(escapeSqlString(JSON.stringify(value)));
+  };
+
+  return {
+    formatLiteral: format,
+  };
+};
+
+/**
+ * Convenience wrapper if you prefer a functional style at call-sites.
+ */
+export const formatLiteral = (
+  formatter: LiteralFormatter,
+  value: unknown
+): string => formatter.formatLiteral(value);
+
+/**
+ * Quotes a possibly qualified identifier like "schema.table" or "db.schema.table"
+ * using a Quoter that knows how to quote a single segment.
+ */
+export const quoteQualified = (quoter: Quoter, identifier: string): string => {
+  const parts = identifier.split('.');
+  return parts.map(part => quoter.quoteIdentifier(part)).join('.');
+};
+
+/**
+ * Renders index column list, including optional order / nulls, using the
+ * provided Quoter for identifier quoting.
+ */
+export const renderIndexColumns = (
+  quoter: Quoter,
+  columns: (string | IndexColumn)[]
+): string =>
+  columns
+    .map(col => {
+      if (typeof col === 'string') {
+        return quoter.quoteIdentifier(col);
+      }
+
+      const parts: string[] = [quoter.quoteIdentifier(col.column)];
+
+      if (col.order) {
+        parts.push(col.order);
+      }
+
+      if (col.nulls) {
+        parts.push(`NULLS ${col.nulls}`);
+      }
+
+      return parts.join(' ');
+    })
+    .join(', ');
+
+/**
+ * Resolves the primary key column names for a table, based purely on schema
+ * metadata. This is domain logic, but independent from any dialect.
+ */
+export const resolvePrimaryKey = (table: TableDef): string[] => {
+  if (Array.isArray(table.primaryKey) && table.primaryKey.length > 0) {
+    return table.primaryKey;
+  }
+
+  const columns = Object.values(table.columns ?? {});
+
+  // `primary` / `name` are domain-level properties of ColumnDef.
+  return columns
+    .filter((col: any) => col.primary)
+    .map((col: any) => col.name);
+};

package/src/core/dialect/abstract.ts

@@ -1,11 +1,11 @@
-import {
-  SelectQueryNode,
-  InsertQueryNode,
-  UpdateQueryNode,
-  DeleteQueryNode,
-  SetOperationKind,
-  CommonTableExpressionNode
-} from '../ast/query.js';
+import {
+  SelectQueryNode,
+  InsertQueryNode,
+  UpdateQueryNode,
+  DeleteQueryNode,
+  SetOperationKind,
+  CommonTableExpressionNode
+} from '../ast/query.js';
 import {
   ExpressionNode,
   BinaryExpressionNode,
@@ -23,6 +23,9 @@ import {
   WindowFunctionNode,
   BetweenExpressionNode
 } from '../ast/expression.js';
+import { DialectName } from '../sql/sql.js';
+import type { FunctionStrategy } from '../functions/types.js';
+import { StandardFunctionStrategy } from '../functions/standard-strategy.js';
 
 /**
  * Context for SQL compilation with parameter management
@@ -63,23 +66,25 @@ export interface DeleteCompiler {
 /**
  * Abstract base class for SQL dialect implementations
  */
-export abstract class Dialect
-  implements SelectCompiler, InsertCompiler, UpdateCompiler, DeleteCompiler
-{
+export abstract class Dialect
+  implements SelectCompiler, InsertCompiler, UpdateCompiler, DeleteCompiler {
+  /** Dialect identifier used for function rendering and formatting */
+  protected abstract readonly dialect: DialectName;
+
   /**
    * Compiles a SELECT query AST to SQL
    * @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]
-    };
+  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 {
@@ -102,19 +107,19 @@ export abstract class Dialect
     };
   }
 
-  compileDelete(ast: DeleteQueryNode): CompiledQuery {
-    const ctx = this.createCompilerContext();
-    const rawSql = this.compileDeleteAst(ast, ctx).trim();
+  compileDelete(ast: DeleteQueryNode): CompiledQuery {
+    const ctx = this.createCompilerContext();
+    const rawSql = this.compileDeleteAst(ast, ctx).trim();
     const sql = rawSql.endsWith(';') ? rawSql : `${rawSql};`;
     return {
       sql,
       params: [...ctx.params]
-    };
-  }
-
-  supportsReturning(): boolean {
-    return false;
-  }
+    };
+  }
+
+  supportsReturning(): boolean {
+    return false;
+  }
 
   /**
    * Compiles SELECT query AST to SQL (to be implemented by concrete dialects)
@@ -122,7 +127,7 @@ export abstract class Dialect
    * @param ctx - Compiler context
    * @returns SQL string
    */
-  protected abstract compileSelectAst(ast: SelectQueryNode, ctx: CompilerContext): string;
+  protected abstract compileSelectAst(ast: SelectQueryNode, ctx: CompilerContext): string;
 
   protected abstract compileInsertAst(ast: InsertQueryNode, ctx: CompilerContext): string;
   protected abstract compileUpdateAst(ast: UpdateQueryNode, ctx: CompilerContext): string;
@@ -161,23 +166,23 @@ export abstract class Dialect
    * Does not add ';' at the end
    * @param ast - Query AST
    * @param ctx - Compiler context
-   * @returns SQL for EXISTS subquery
-   */
-  protected compileSelectForExists(ast: SelectQueryNode, ctx: CompilerContext): string {
-    const normalized = this.normalizeSelectAst(ast);
-    const full = this.compileSelectAst(normalized, ctx).trim().replace(/;$/, '');
-
-    // When the subquery is a set operation, wrap it as a derived table to keep valid syntax.
-    if (normalized.setOps && normalized.setOps.length > 0) {
-      return `SELECT 1 FROM (${full}) AS _exists`;
-    }
-
-    const upper = full.toUpperCase();
-    const fromIndex = upper.indexOf(' FROM ');
-    if (fromIndex === -1) {
-      return full;
-    }
-
+   * @returns SQL for EXISTS subquery
+   */
+  protected compileSelectForExists(ast: SelectQueryNode, ctx: CompilerContext): string {
+    const normalized = this.normalizeSelectAst(ast);
+    const full = this.compileSelectAst(normalized, ctx).trim().replace(/;$/, '');
+
+    // When the subquery is a set operation, wrap it as a derived table to keep valid syntax.
+    if (normalized.setOps && normalized.setOps.length > 0) {
+      return `SELECT 1 FROM (${full}) AS _exists`;
+    }
+
+    const upper = full.toUpperCase();
+    const fromIndex = upper.indexOf(' FROM ');
+    if (fromIndex === -1) {
+      return full;
+    }
+
     const tail = full.slice(fromIndex);
     return `SELECT 1${tail}`;
   }
@@ -204,82 +209,84 @@ export abstract class Dialect
    * @param index - Parameter index
    * @returns Formatted placeholder string
    */
-  protected formatPlaceholder(index: number): string {
-    return '?';
-  }
-
-  /**
-   * Whether the current dialect supports a given set operation.
-   * Override in concrete dialects to restrict support.
-   */
-  protected supportsSetOperation(kind: SetOperationKind): boolean {
-    return true;
-  }
-
-  /**
-   * Validates set-operation semantics:
-   * - Ensures the dialect supports requested operators.
-   * - Enforces that only the outermost compound query may have ORDER/LIMIT/OFFSET.
-   * @param ast - Query to validate
-   * @param isOutermost - Whether this node is the outermost compound query
-   */
-  protected validateSetOperations(ast: SelectQueryNode, isOutermost = true): void {
-    const hasSetOps = !!(ast.setOps && ast.setOps.length);
-    if (!isOutermost && (ast.orderBy || ast.limit !== undefined || ast.offset !== undefined)) {
-      throw new Error('ORDER BY / LIMIT / OFFSET are only allowed on the outermost compound query.');
-    }
-
-    if (hasSetOps) {
-      for (const op of ast.setOps!) {
-        if (!this.supportsSetOperation(op.operator)) {
-          throw new Error(`Set operation ${op.operator} is not supported by this dialect.`);
-        }
-        this.validateSetOperations(op.query, false);
-      }
-    }
-  }
-
-  /**
-   * Hoists CTEs from set-operation operands to the outermost query so WITH appears once.
-   * @param ast - Query AST
-   * @returns Normalized AST without inner CTEs and a list of hoisted CTEs
-   */
-  private hoistCtes(ast: SelectQueryNode): { normalized: SelectQueryNode; hoistedCtes: CommonTableExpressionNode[] } {
-    let hoisted: CommonTableExpressionNode[] = [];
-
-    const normalizedSetOps = ast.setOps?.map(op => {
-      const { normalized: child, hoistedCtes: childHoisted } = this.hoistCtes(op.query);
-      const childCtes = child.ctes ?? [];
-      if (childCtes.length) {
-        hoisted = hoisted.concat(childCtes);
-      }
-      hoisted = hoisted.concat(childHoisted);
-      const queryWithoutCtes = childCtes.length ? { ...child, ctes: undefined } : child;
-      return { ...op, query: queryWithoutCtes };
-    });
-
-    const normalized: SelectQueryNode = normalizedSetOps ? { ...ast, setOps: normalizedSetOps } : ast;
-    return { normalized, hoistedCtes: hoisted };
-  }
-
-  /**
-   * Normalizes a SELECT AST before compilation (validation + CTE hoisting).
-   * @param ast - Query AST
-   * @returns Normalized query AST
-   */
-  protected normalizeSelectAst(ast: SelectQueryNode): SelectQueryNode {
-    this.validateSetOperations(ast, true);
-    const { normalized, hoistedCtes } = this.hoistCtes(ast);
-    const combinedCtes = [...(normalized.ctes ?? []), ...hoistedCtes];
-    return combinedCtes.length ? { ...normalized, ctes: combinedCtes } : normalized;
-  }
-
-  private readonly expressionCompilers: Map<string, (node: ExpressionNode, ctx: CompilerContext) => string>;
-  private readonly operandCompilers: Map<string, (node: OperandNode, ctx: CompilerContext) => string>;
-
-  protected constructor() {
-    this.expressionCompilers = new Map();
+  protected formatPlaceholder(index: number): string {
+    return '?';
+  }
+
+  /**
+   * Whether the current dialect supports a given set operation.
+   * Override in concrete dialects to restrict support.
+   */
+  protected supportsSetOperation(kind: SetOperationKind): boolean {
+    return true;
+  }
+
+  /**
+   * Validates set-operation semantics:
+   * - Ensures the dialect supports requested operators.
+   * - Enforces that only the outermost compound query may have ORDER/LIMIT/OFFSET.
+   * @param ast - Query to validate
+   * @param isOutermost - Whether this node is the outermost compound query
+   */
+  protected validateSetOperations(ast: SelectQueryNode, isOutermost = true): void {
+    const hasSetOps = !!(ast.setOps && ast.setOps.length);
+    if (!isOutermost && (ast.orderBy || ast.limit !== undefined || ast.offset !== undefined)) {
+      throw new Error('ORDER BY / LIMIT / OFFSET are only allowed on the outermost compound query.');
+    }
+
+    if (hasSetOps) {
+      for (const op of ast.setOps!) {
+        if (!this.supportsSetOperation(op.operator)) {
+          throw new Error(`Set operation ${op.operator} is not supported by this dialect.`);
+        }
+        this.validateSetOperations(op.query, false);
+      }
+    }
+  }
+
+  /**
+   * Hoists CTEs from set-operation operands to the outermost query so WITH appears once.
+   * @param ast - Query AST
+   * @returns Normalized AST without inner CTEs and a list of hoisted CTEs
+   */
+  private hoistCtes(ast: SelectQueryNode): { normalized: SelectQueryNode; hoistedCtes: CommonTableExpressionNode[] } {
+    let hoisted: CommonTableExpressionNode[] = [];
+
+    const normalizedSetOps = ast.setOps?.map(op => {
+      const { normalized: child, hoistedCtes: childHoisted } = this.hoistCtes(op.query);
+      const childCtes = child.ctes ?? [];
+      if (childCtes.length) {
+        hoisted = hoisted.concat(childCtes);
+      }
+      hoisted = hoisted.concat(childHoisted);
+      const queryWithoutCtes = childCtes.length ? { ...child, ctes: undefined } : child;
+      return { ...op, query: queryWithoutCtes };
+    });
+
+    const normalized: SelectQueryNode = normalizedSetOps ? { ...ast, setOps: normalizedSetOps } : ast;
+    return { normalized, hoistedCtes: hoisted };
+  }
+
+  /**
+   * Normalizes a SELECT AST before compilation (validation + CTE hoisting).
+   * @param ast - Query AST
+   * @returns Normalized query AST
+   */
+  protected normalizeSelectAst(ast: SelectQueryNode): SelectQueryNode {
+    this.validateSetOperations(ast, true);
+    const { normalized, hoistedCtes } = this.hoistCtes(ast);
+    const combinedCtes = [...(normalized.ctes ?? []), ...hoistedCtes];
+    return combinedCtes.length ? { ...normalized, ctes: combinedCtes } : normalized;
+  }
+
+  private readonly expressionCompilers: Map<string, (node: ExpressionNode, ctx: CompilerContext) => string>;
+  private readonly operandCompilers: Map<string, (node: OperandNode, ctx: CompilerContext) => string>;
+  protected readonly functionStrategy: FunctionStrategy;
+
+  protected constructor(functionStrategy?: FunctionStrategy) {
+    this.expressionCompilers = new Map();
     this.operandCompilers = new Map();
+    this.functionStrategy = functionStrategy || new StandardFunctionStrategy();
     this.registerDefaultOperandCompilers();
     this.registerDefaultExpressionCompilers();
   }
@@ -381,10 +388,9 @@ export abstract class Dialect
     this.registerOperandCompiler('Column', (column: ColumnNode, _ctx) => {
       return `${this.quoteIdentifier(column.table)}.${this.quoteIdentifier(column.name)}`;
     });
-    this.registerOperandCompiler('Function', (fnNode: FunctionNode, ctx) => {
-      const args = fnNode.args.map(arg => this.compileOperand(arg, ctx)).join(', ');
-      return `${fnNode.name}(${args})`;
-    });
+    this.registerOperandCompiler('Function', (fnNode: FunctionNode, ctx) =>
+      this.compileFunctionOperand(fnNode, ctx)
+    );
     this.registerOperandCompiler('JsonPath', (path: JsonPathNode, _ctx) => this.compileJsonPath(path));
 
     this.registerOperandCompiler('ScalarSubquery', (node: ScalarSubqueryNode, ctx) => {
@@ -438,4 +444,16 @@ export abstract class Dialect
   protected compileJsonPath(node: JsonPathNode): string {
     throw new Error("JSON Path not supported by this dialect");
   }
+
+  /**
+   * Compiles a function operand, using the dialect's function strategy.
+   */
+  protected compileFunctionOperand(fnNode: FunctionNode, ctx: CompilerContext): string {
+    const compiledArgs = fnNode.args.map(arg => this.compileOperand(arg, ctx));
+    const renderer = this.functionStrategy.getRenderer(fnNode.name);
+    if (renderer) {
+      return renderer({ node: fnNode, compiledArgs });
+    }
+    return `${fnNode.name}(${compiledArgs.join(', ')})`;
+  }
 }

package/src/core/dialect/base/cte-compiler.ts

@@ -0,0 +1,33 @@
+import { SelectQueryNode } from '../../ast/query.js';
+import { CompilerContext } from '../abstract.js';
+
+/**
+ * Compiler for Common Table Expressions (CTEs).
+ * Handles compilation of WITH and WITH RECURSIVE clauses.
+ */
+export class CteCompiler {
+  /**
+   * Compiles CTEs (WITH clauses) including recursive CTEs.
+   * @param ast - The SELECT query AST containing CTE definitions.
+   * @param ctx - The compiler context for expression compilation.
+   * @param quoteIdentifier - Function to quote identifiers according to dialect rules.
+   * @param compileSelectAst - Function to recursively compile SELECT query ASTs.
+   * @param normalizeSelectAst - Function to normalize SELECT query ASTs before compilation.
+   * @param stripTrailingSemicolon - Function to remove trailing semicolons from SQL.
+   * @returns SQL WITH clause string (e.g., "WITH cte_name AS (...) ") or empty string if no CTEs.
+   */
+  static compileCtes(ast: SelectQueryNode, ctx: CompilerContext, quoteIdentifier: (id: string) => string, compileSelectAst: (ast: SelectQueryNode, ctx: CompilerContext) => string, normalizeSelectAst: (ast: SelectQueryNode) => SelectQueryNode, stripTrailingSemicolon: (sql: string) => string): string {
+    if (!ast.ctes || ast.ctes.length === 0) return '';
+    const hasRecursive = ast.ctes.some(cte => cte.recursive);
+    const prefix = hasRecursive ? 'WITH RECURSIVE ' : 'WITH ';
+    const cteDefs = ast.ctes.map(cte => {
+      const name = quoteIdentifier(cte.name);
+      const cols = cte.columns && cte.columns.length
+        ? `(${cte.columns.map(c => quoteIdentifier(c)).join(', ')})`
+        : '';
+      const query = stripTrailingSemicolon(compileSelectAst(normalizeSelectAst(cte.query), ctx));
+      return `${name}${cols} AS (${query})`;
+    }).join(', ');
+    return `${prefix}${cteDefs} `;
+  }
+}