metal-orm 1.0.11 → 1.0.13

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

@@ -0,0 +1,32 @@
+import { DialectName } from './schema-generator.js';
+import { DatabaseSchema } from './schema-types.js';
+import { DbExecutor } from '../../orm/db-executor.js';
+import type { IntrospectOptions, SchemaIntrospector } from './introspect/types.js';
+import { postgresIntrospector } from './introspect/postgres.js';
+import { mysqlIntrospector } from './introspect/mysql.js';
+import { sqliteIntrospector } from './introspect/sqlite.js';
+import { mssqlIntrospector } from './introspect/mssql.js';
+
+const INTROSPECTORS: Record<DialectName, SchemaIntrospector> = {
+  postgres: postgresIntrospector,
+  mysql: mysqlIntrospector,
+  sqlite: sqliteIntrospector,
+  mssql: mssqlIntrospector
+};
+
+/**
+ * Introspects an existing database schema using the dialect-specific strategy.
+ */
+export const introspectSchema = async (
+  executor: DbExecutor,
+  dialect: DialectName,
+  options: IntrospectOptions = {}
+): Promise<DatabaseSchema> => {
+  const handler = INTROSPECTORS[dialect];
+  if (!handler) {
+    throw new Error(`Unsupported dialect for introspection: ${dialect}`);
+  }
+  return handler.introspect(executor, options);
+};
+
+export type { IntrospectOptions, SchemaIntrospector };

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

@@ -0,0 +1,39 @@
+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[];
+}

package/src/core/dialect/abstract.ts

@@ -1,4 +1,11 @@
-import { SelectQueryNode, InsertQueryNode, UpdateQueryNode, DeleteQueryNode } from '../ast/query.js';
+import {
+  SelectQueryNode,
+  InsertQueryNode,
+  UpdateQueryNode,
+  DeleteQueryNode,
+  SetOperationKind,
+  CommonTableExpressionNode
+} from '../ast/query.js';
 import {
   ExpressionNode,
   BinaryExpressionNode,
@@ -56,22 +63,23 @@ 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
+{
   /**
    * 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 rawSql = this.compileSelectAst(ast, 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 {
@@ -94,15 +102,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;
+  }
 
   /**
    * Compiles SELECT query AST to SQL (to be implemented by concrete dialects)
@@ -110,7 +122,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;
@@ -149,16 +161,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 full = this.compileSelectAst(ast, ctx).trim().replace(/;$/, '');
-    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}`;
   }
@@ -185,15 +204,81 @@ export abstract class Dialect
    * @param index - Parameter index
    * @returns Formatted placeholder string
    */
-  protected formatPlaceholder(index: number): string {
-    return '?';
-  }
-
-  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 constructor() {
+    this.expressionCompilers = new Map();
     this.operandCompilers = new Map();
     this.registerDefaultOperandCompilers();
     this.registerDefaultExpressionCompilers();

package/src/core/dialect/base/sql-dialect.ts

@@ -0,0 +1,204 @@
+import { CompilerContext, Dialect } from '../abstract.js';
+import { SelectQueryNode, InsertQueryNode, UpdateQueryNode, DeleteQueryNode } from '../../ast/query.js';
+import { ColumnNode } from '../../ast/expression.js';
+
+/**
+ * Shared SQL compiler for dialects with standard LIMIT/OFFSET pagination.
+ * Concrete dialects override only the minimal hooks (identifier quoting,
+ * JSON path, placeholders, RETURNING support) instead of re-implementing
+ * the entire compile pipeline.
+ */
+export abstract class SqlDialectBase extends Dialect {
+  /**
+   * Quotes an identifier (dialect-specific).
+   */
+  abstract quoteIdentifier(id: string): string;
+
+  /**
+   * Compiles SELECT query AST to SQL using common rules.
+   */
+  protected compileSelectAst(ast: SelectQueryNode, ctx: CompilerContext): string {
+    const hasSetOps = !!(ast.setOps && ast.setOps.length);
+    const ctes = this.compileCtes(ast, ctx);
+
+    // When set operations exist, omit ORDER BY/OFFSET/LIMIT from the operands and apply at the end.
+    const baseAst: SelectQueryNode = hasSetOps
+      ? { ...ast, setOps: undefined, orderBy: undefined, limit: undefined, offset: undefined }
+      : ast;
+
+    const baseSelect = this.compileSelectCore(baseAst, ctx);
+
+    if (!hasSetOps) {
+      return `${ctes}${baseSelect}`;
+    }
+
+    const compound = ast.setOps!
+      .map(op => `${op.operator} ${this.wrapSetOperand(this.compileSelectAst(op.query, ctx))}`)
+      .join(' ');
+
+    const orderBy = this.compileOrderBy(ast);
+    const pagination = this.compilePagination(ast, orderBy);
+
+    const combined = `${this.wrapSetOperand(baseSelect)} ${compound}`;
+    return `${ctes}${combined}${orderBy}${pagination}`;
+  }
+
+  protected compileInsertAst(ast: InsertQueryNode, ctx: CompilerContext): string {
+    const table = this.compileTableName(ast.into);
+    const columnList = ast.columns
+      .map(column => `${this.quoteIdentifier(column.table)}.${this.quoteIdentifier(column.name)}`)
+      .join(', ');
+    const values = ast.values.map(row => `(${row.map(value => this.compileOperand(value, ctx)).join(', ')})`).join(', ');
+    const returning = this.compileReturning(ast.returning, ctx);
+    return `INSERT INTO ${table} (${columnList}) VALUES ${values}${returning}`;
+  }
+
+  /**
+   * Compiles a single SELECT (no set operations, no CTE prefix).
+   */
+  private compileSelectCore(ast: SelectQueryNode, ctx: CompilerContext): string {
+    const columns = this.compileSelectColumns(ast, ctx);
+    const from = this.compileFrom(ast.from);
+    const joins = this.compileJoins(ast, ctx);
+    const whereClause = this.compileWhere(ast.where, ctx);
+    const groupBy = this.compileGroupBy(ast);
+    const having = this.compileHaving(ast, ctx);
+    const orderBy = this.compileOrderBy(ast);
+    const pagination = this.compilePagination(ast, orderBy);
+
+    return `SELECT ${this.compileDistinct(ast)}${columns} FROM ${from}${joins}${whereClause}${groupBy}${having}${orderBy}${pagination}`;
+  }
+
+  protected compileUpdateAst(ast: UpdateQueryNode, ctx: CompilerContext): string {
+    const table = this.compileTableName(ast.table);
+    const assignments = ast.set.map(assignment => {
+      const col = assignment.column;
+      const target = `${this.quoteIdentifier(col.table)}.${this.quoteIdentifier(col.name)}`;
+      const value = this.compileOperand(assignment.value, ctx);
+      return `${target} = ${value}`;
+    }).join(', ');
+    const whereClause = this.compileWhere(ast.where, ctx);
+    const returning = this.compileReturning(ast.returning, ctx);
+    return `UPDATE ${table} SET ${assignments}${whereClause}${returning}`;
+  }
+
+  protected compileDeleteAst(ast: DeleteQueryNode, ctx: CompilerContext): string {
+    const table = this.compileTableName(ast.from);
+    const whereClause = this.compileWhere(ast.where, ctx);
+    const returning = this.compileReturning(ast.returning, ctx);
+    return `DELETE FROM ${table}${whereClause}${returning}`;
+  }
+
+  /**
+   * Default RETURNING compilation: no support.
+   */
+  protected compileReturning(returning: ColumnNode[] | undefined, _ctx: CompilerContext): string {
+    if (!returning || returning.length === 0) return '';
+    throw new Error('RETURNING is not supported by this dialect.');
+  }
+
+  protected formatReturningColumns(returning: ColumnNode[]): string {
+    return returning
+      .map(column => {
+        const tablePart = column.table ? `${this.quoteIdentifier(column.table)}.` : '';
+        const aliasPart = column.alias ? ` AS ${this.quoteIdentifier(column.alias)}` : '';
+        return `${tablePart}${this.quoteIdentifier(column.name)}${aliasPart}`;
+      })
+      .join(', ');
+  }
+
+  /**
+   * DISTINCT clause. Override for DISTINCT ON support.
+   */
+  protected compileDistinct(ast: SelectQueryNode): string {
+    return ast.distinct ? 'DISTINCT ' : '';
+  }
+
+  protected compileSelectColumns(ast: SelectQueryNode, ctx: CompilerContext): string {
+    return ast.columns.map(c => {
+      const expr = this.compileOperand(c, ctx);
+      if (c.alias) {
+        if (c.alias.includes('(')) return c.alias;
+        return `${expr} AS ${this.quoteIdentifier(c.alias)}`;
+      }
+      return expr;
+    }).join(', ');
+  }
+
+  protected compileFrom(ast: SelectQueryNode['from']): string {
+    const base = this.compileTableName(ast);
+    return ast.alias ? `${base} AS ${this.quoteIdentifier(ast.alias)}` : base;
+  }
+
+  protected compileTableName(table: { name: string; schema?: string }): string {
+    if (table.schema) {
+      return `${this.quoteIdentifier(table.schema)}.${this.quoteIdentifier(table.name)}`;
+    }
+    return this.quoteIdentifier(table.name);
+  }
+
+  protected compileJoins(ast: SelectQueryNode, ctx: CompilerContext): string {
+    if (!ast.joins || ast.joins.length === 0) return '';
+    const parts = ast.joins.map(j => {
+      const table = this.compileFrom(j.table);
+      const cond = this.compileExpression(j.condition, ctx);
+      return `${j.kind} JOIN ${table} ON ${cond}`;
+    });
+    return ` ${parts.join(' ')}`;
+  }
+
+  protected compileGroupBy(ast: SelectQueryNode): string {
+    if (!ast.groupBy || ast.groupBy.length === 0) return '';
+    const cols = ast.groupBy
+      .map(c => `${this.quoteIdentifier(c.table)}.${this.quoteIdentifier(c.name)}`)
+      .join(', ');
+    return ` GROUP BY ${cols}`;
+  }
+
+  protected compileHaving(ast: SelectQueryNode, ctx: CompilerContext): string {
+    if (!ast.having) return '';
+    return ` HAVING ${this.compileExpression(ast.having, ctx)}`;
+  }
+
+  protected compileOrderBy(ast: SelectQueryNode): string {
+    if (!ast.orderBy || ast.orderBy.length === 0) return '';
+    const parts = ast.orderBy
+      .map(o => `${this.quoteIdentifier(o.column.table)}.${this.quoteIdentifier(o.column.name)} ${o.direction}`)
+      .join(', ');
+    return ` ORDER BY ${parts}`;
+  }
+
+  /**
+   * Default LIMIT/OFFSET pagination clause.
+   */
+  protected compilePagination(ast: SelectQueryNode, _orderByClause: string): string {
+    const parts: string[] = [];
+    if (ast.limit !== undefined) parts.push(`LIMIT ${ast.limit}`);
+    if (ast.offset !== undefined) parts.push(`OFFSET ${ast.offset}`);
+    return parts.length ? ` ${parts.join(' ')}` : '';
+  }
+
+  protected compileCtes(ast: SelectQueryNode, ctx: CompilerContext): 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 = this.quoteIdentifier(cte.name);
+      const cols = cte.columns && cte.columns.length
+        ? `(${cte.columns.map(c => this.quoteIdentifier(c)).join(', ')})`
+        : '';
+      const query = this.stripTrailingSemicolon(this.compileSelectAst(this.normalizeSelectAst(cte.query), ctx));
+      return `${name}${cols} AS (${query})`;
+    }).join(', ');
+    return `${prefix}${cteDefs} `;
+  }
+
+  protected stripTrailingSemicolon(sql: string): string {
+    return sql.trim().replace(/;$/, '');
+  }
+
+  protected wrapSetOperand(sql: string): string {
+    const trimmed = this.stripTrailingSemicolon(sql);
+    return `(${trimmed})`;
+  }
+}