metal-orm 1.1.25 → 1.1.27

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

@@ -1,12 +1,11 @@
-import { TableDef } from '../../schema/table.js';
-import { ColumnDef } from '../../schema/column-types.js';
+import type { TableDef } from '../../schema/table.js';
+import type { ColumnDef } from '../../schema/column-types.js';
 import type { DbExecutor } from '../execution/db-executor.js';
-import { SchemaDialect } from './schema-dialect.js';
+import type { SchemaDialect } from './schema-dialect.js';
 import { deriveIndexName } from './naming-strategy.js';
 import { generateCreateTableSql, renderColumnDefinition } from './schema-generator.js';
-import { ColumnDiff, DatabaseColumn, DatabaseSchema, DatabaseTable } from './schema-types.js';
+import type { ColumnDiff, DatabaseColumn, DatabaseSchema, DatabaseTable } from './schema-types.js';
 
-/** The kind of schema change. */
 export type SchemaChangeKind =
   | 'createTable'
   | 'dropTable'
@@ -16,7 +15,6 @@ export type SchemaChangeKind =
   | 'addIndex'
   | 'dropIndex';
 
-/** Represents a single schema change. */
 export interface SchemaChange {
   kind: SchemaChangeKind;
   table: string;
@@ -25,45 +23,47 @@ export interface SchemaChange {
   safe: boolean;
 }
 
-/** Represents a plan of schema changes. */
 export interface SchemaPlan {
   changes: SchemaChange[];
   warnings: string[];
 }
 
-/** Options for schema diffing. */
 export interface SchemaDiffOptions {
-  /** Allow destructive operations (drops) */
   allowDestructive?: boolean;
 }
 
-const tableKey = (name: string, schema?: string) => (schema ? `${schema}.${name}` : name);
+const tableKey = (name: string, schema?: string): string => schema ? `${schema}.${name}` : name;
 
-const mapTables = (schema: DatabaseSchema) => {
+const mapTables = (schema: DatabaseSchema): Map<string, DatabaseTable> => {
   const map = new Map<string, DatabaseTable>();
-  for (const table of schema.tables) {
-    map.set(tableKey(table.name, table.schema), table);
-  }
+  for (const table of schema.tables) map.set(tableKey(table.name, table.schema), table);
   return map;
 };
 
-const buildAddColumnSql = (table: TableDef, colName: string, dialect: SchemaDialect): string => {
-  const column = table.columns[colName];
+const buildAddColumnSql = (table: TableDef, columnName: string, dialect: SchemaDialect): string => {
+  const column = table.columns[columnName];
   const rendered = renderColumnDefinition(table, column, dialect);
   return `ALTER TABLE ${dialect.formatTableName(table)} ADD ${rendered.sql};`;
 };
 
-const normalizeType = (value: string | undefined): string => (value || '').toLowerCase().replace(/\s+/g, ' ').trim();
+const normalizeType = (value: string | undefined): string =>
+  (value || '').toLowerCase().replace(/\s+/g, ' ').trim();
+
 const normalizeDefault = (value: unknown): string | undefined => {
   if (value === undefined || value === null) return undefined;
   return String(value).trim();
 };
 
-const diffColumn = (expected: ColumnDef, actual: DatabaseColumn, dialect: SchemaDialect): ColumnDiff => {
+const diffColumn = (
+  expected: ColumnDef,
+  actual: DatabaseColumn,
+  dialect: SchemaDialect
+): ColumnDiff => {
   const expectedType = normalizeType(dialect.renderColumnType(expected));
   const actualType = normalizeType(actual.type);
-  const expectedDefault =
-    expected.default !== undefined ? normalizeDefault(dialect.renderDefault(expected.default, expected)) : undefined;
+  const expectedDefault = expected.default !== undefined
+    ? normalizeDefault(dialect.renderDefault(expected.default, expected))
+    : undefined;
   const actualDefault = normalizeDefault(actual.default);
   return {
     typeChanged: expectedType !== actualType,
@@ -73,14 +73,13 @@ const diffColumn = (expected: ColumnDef, actual: DatabaseColumn, dialect: Schema
   };
 };
 
-/**
- * Computes the differences between expected and actual database schemas.
- * @param expectedTables - The expected table definitions.
- * @param actualSchema - The actual database schema.
- * @param dialect - The schema dialect.
- * @param options - Options for the diff.
- * @returns The schema plan with changes and warnings.
- */
+const unsupportedMutationWarning = (
+  dialect: SchemaDialect,
+  operation: string,
+  target: string
+): string =>
+  `Dialect "${dialect.name}" does not provide the ${operation} capability for ${target}; manual migration is required.`;
+
 export const diffSchema = (
   expectedTables: TableDef[],
   actualSchema: DatabaseSchema,
@@ -89,10 +88,8 @@ export const diffSchema = (
 ): SchemaPlan => {
   const allowDestructive = options.allowDestructive ?? false;
   const plan: SchemaPlan = { changes: [], warnings: [] };
-
   const actualMap = mapTables(actualSchema);
 
-  // Create missing tables and indexes
   for (const table of expectedTables) {
     const key = tableKey(table.name, table.schema);
     const actual = actualMap.get(key);
@@ -108,115 +105,148 @@ export const diffSchema = (
       continue;
     }
 
-    // Columns
-    const actualCols = new Map(actual.columns.map(c => [c.name, c]));
-    for (const colName of Object.keys(table.columns)) {
-      if (!actualCols.has(colName)) {
+    const actualColumns = new Map(actual.columns.map(column => [column.name, column]));
+    for (const columnName of Object.keys(table.columns)) {
+      if (!actualColumns.has(columnName)) {
         plan.changes.push({
           kind: 'addColumn',
           table: key,
-          description: `Add column ${colName} to ${key}`,
-          statements: [buildAddColumnSql(table, colName, dialect)],
+          description: `Add column ${columnName} to ${key}`,
+          statements: [buildAddColumnSql(table, columnName, dialect)],
           safe: true
         });
-      } else {
-        const expectedCol = table.columns[colName];
-        const actualCol = actualCols.get(colName)!;
-        const colDiff = diffColumn(expectedCol, actualCol, dialect);
-        const shouldAlter =
-          colDiff.typeChanged || colDiff.nullabilityChanged || colDiff.defaultChanged || colDiff.autoIncrementChanged;
-        if (shouldAlter) {
-          const statements = dialect.alterColumnSql?.(table, expectedCol, actualCol, colDiff) ?? [];
+        continue;
+      }
+
+      const expectedColumn = table.columns[columnName];
+      const actualColumn = actualColumns.get(columnName)!;
+      const columnDiff = diffColumn(expectedColumn, actualColumn, dialect);
+      const shouldAlter =
+        columnDiff.typeChanged
+        || columnDiff.nullabilityChanged
+        || columnDiff.defaultChanged
+        || columnDiff.autoIncrementChanged;
+
+      if (shouldAlter) {
+        const capability = dialect.mutations.alterColumn;
+        if (capability) {
+          const statements = capability.compile(table, expectedColumn, actualColumn, columnDiff);
           if (statements.length > 0) {
             plan.changes.push({
               kind: 'alterColumn',
               table: key,
-              description: `Alter column ${colName} on ${key}`,
+              description: `Alter column ${columnName} on ${key}`,
               statements,
               safe: true
             });
           }
-          const warning = dialect.warnAlterColumn?.(table, expectedCol, actualCol, colDiff);
+          const warning = capability.warning?.(table, expectedColumn, actualColumn, columnDiff);
           if (warning) plan.warnings.push(warning);
+        } else {
+          plan.warnings.push(
+            unsupportedMutationWarning(dialect, 'ALTER COLUMN', `${key}.${columnName}`)
+          );
         }
       }
     }
-    for (const colName of actualCols.keys()) {
-      if (!table.columns[colName]) {
-        plan.changes.push({
-          kind: 'dropColumn',
-          table: key,
-          description: `Drop column ${colName} from ${key}`,
-          statements: allowDestructive ? dialect.dropColumnSql(actual, colName) : [],
-          safe: false
-        });
-        const warning = dialect.warnDropColumn?.(actual, colName);
+
+    for (const columnName of actualColumns.keys()) {
+      if (table.columns[columnName]) continue;
+      const capability = dialect.mutations.dropColumn;
+      const statements = allowDestructive && capability
+        ? capability.compile(actual, columnName)
+        : [];
+      plan.changes.push({
+        kind: 'dropColumn',
+        table: key,
+        description: `Drop column ${columnName} from ${key}`,
+        statements,
+        safe: false
+      });
+      if (!capability) {
+        plan.warnings.push(
+          unsupportedMutationWarning(dialect, 'DROP COLUMN', `${key}.${columnName}`)
+        );
+      } else {
+        const warning = capability.warning?.(actual, columnName);
         if (warning) plan.warnings.push(warning);
       }
     }
 
-    // Indexes (naive: based on name or derived name)
     const expectedIndexes = table.indexes ?? [];
     const actualIndexes = actual.indexes ?? [];
-    const actualIndexMap = new Map(actualIndexes.map(idx => [idx.name, idx]));
+    const actualIndexMap = new Map(actualIndexes.map(index => [index.name, index]));
 
-    for (const idx of expectedIndexes) {
-      const name = idx.name || deriveIndexName(table, idx);
+    for (const index of expectedIndexes) {
+      const name = index.name || deriveIndexName(table, index);
       if (!actualIndexMap.has(name)) {
         plan.changes.push({
           kind: 'addIndex',
           table: key,
           description: `Create index ${name} on ${key}`,
-          statements: [dialect.renderIndex(table, { ...idx, name })],
+          statements: [dialect.renderIndex(table, { ...index, name })],
           safe: true
         });
       }
     }
 
-    for (const idx of actualIndexes) {
-      if (idx.name && !expectedIndexes.find(expected => (expected.name || deriveIndexName(table, expected)) === idx.name)) {
-        plan.changes.push({
-          kind: 'dropIndex',
-          table: key,
-          description: `Drop index ${idx.name} on ${key}`,
-          statements: allowDestructive ? dialect.dropIndexSql(actual, idx.name) : [],
-          safe: false
-        });
+    for (const index of actualIndexes) {
+      if (!index.name) continue;
+      const expected = expectedIndexes.find(
+        candidate => (candidate.name || deriveIndexName(table, candidate)) === index.name
+      );
+      if (expected) continue;
+
+      const capability = dialect.mutations.dropIndex;
+      const statements = allowDestructive && capability
+        ? capability.compile(actual, index.name)
+        : [];
+      plan.changes.push({
+        kind: 'dropIndex',
+        table: key,
+        description: `Drop index ${index.name} on ${key}`,
+        statements,
+        safe: false
+      });
+      if (!capability) {
+        plan.warnings.push(
+          unsupportedMutationWarning(dialect, 'DROP INDEX', `${key}.${index.name}`)
+        );
+      } else {
+        const warning = capability.warning?.(actual, index.name);
+        if (warning) plan.warnings.push(warning);
       }
     }
   }
 
-  // Extra tables
   for (const actual of actualSchema.tables) {
     const key = tableKey(actual.name, actual.schema);
-    if (!expectedTables.find(t => tableKey(t.name, t.schema) === key)) {
-      plan.changes.push({
-        kind: 'dropTable',
-        table: key,
-        description: `Drop table ${key}`,
-        statements: allowDestructive ? dialect.dropTableSql(actual) : [],
-        safe: false
-      });
+    if (expectedTables.find(table => tableKey(table.name, table.schema) === key)) continue;
+
+    const capability = dialect.mutations.dropTable;
+    const statements = allowDestructive && capability ? capability.compile(actual) : [];
+    plan.changes.push({
+      kind: 'dropTable',
+      table: key,
+      description: `Drop table ${key}`,
+      statements,
+      safe: false
+    });
+    if (!capability) {
+      plan.warnings.push(unsupportedMutationWarning(dialect, 'DROP TABLE', key));
+    } else {
+      const warning = capability.warning?.(actual);
+      if (warning) plan.warnings.push(warning);
     }
   }
 
   return plan;
 };
 
-/** Options for schema synchronization. */
 export interface SynchronizeOptions extends SchemaDiffOptions {
   dryRun?: boolean;
 }
 
-/**
- * Synchronizes the database schema with the expected tables.
- * @param expectedTables - The expected table definitions.
- * @param actualSchema - The actual database schema.
- * @param dialect - The schema dialect.
- * @param executor - The database executor.
- * @param options - Options for synchronization.
- * @returns The schema plan with changes and warnings.
- */
 export const synchronizeSchema = async (
   expectedTables: TableDef[],
   actualSchema: DatabaseSchema,
@@ -231,4 +261,3 @@ export const synchronizeSchema = async (
   }
   return plan;
 };
-

package/src/core/dialect/abstract.ts

@@ -1,25 +1,9 @@
 import type {
-  SelectQueryNode,
-  InsertQueryNode,
-  UpdateQueryNode,
   DeleteQueryNode,
-  SetOperationKind,
-  OrderingTerm
+  InsertQueryNode,
+  SelectQueryNode,
+  UpdateQueryNode
 } from '../ast/query.js';
-import type {
-  ExpressionNode,
-  ColumnNode,
-  OperandNode,
-  FunctionNode,
-  JsonPathNode
-} from '../ast/expression.js';
-import type { 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';
-import { ExpressionCompilerRegistry } from './base/expression-compiler-registry.js';
-import { SelectAstNormalizer } from './base/select-ast-normalizer.js';
 
 /** Context for SQL compilation with parameter management. */
 export interface CompilerContext {
@@ -50,219 +34,13 @@ export interface DeleteCompiler {
 }
 
 /**
- * Public dialect contract consumed by builders and the ORM runtime.
- * Optional backend features such as stored procedures live in dedicated
- * capability interfaces; mutation-wide behavior shared by the runtime stays
- * in this small core contract.
+ * Structural contract consumed by query builders and the ORM runtime.
+ *
+ * A dialect is assembled from compiler components. There is intentionally no
+ * base class: inheritance is not part of the extension model.
  */
 export interface Dialect
   extends SelectCompiler, InsertCompiler, UpdateCompiler, DeleteCompiler {
   quoteIdentifier(id: string): string;
   supportsDmlReturningClause(): boolean;
 }
-
-/**
- * Shared implementation infrastructure for SQL dialects.
- *
- * This is deliberately separate from the public Dialect contract: custom
- * dialects may extend this class, extend SqlDialectBase, or use composition.
- */
-export abstract class DialectBase implements Dialect {
-  protected abstract readonly dialect: DialectName;
-
-  private readonly expressionCompilerRegistry: ExpressionCompilerRegistry;
-  private readonly selectAstNormalizer: SelectAstNormalizer;
-  protected readonly functionStrategy: FunctionStrategy;
-  protected readonly tableFunctionStrategy: TableFunctionStrategy;
-
-  protected constructor(
-    functionStrategy?: FunctionStrategy,
-    tableFunctionStrategy?: TableFunctionStrategy
-  ) {
-    this.functionStrategy = functionStrategy ?? new StandardFunctionStrategy();
-    this.tableFunctionStrategy = tableFunctionStrategy ?? new StandardTableFunctionStrategy();
-    this.selectAstNormalizer = new SelectAstNormalizer(kind => this.supportsSetOperation(kind));
-    this.expressionCompilerRegistry = new ExpressionCompilerRegistry({
-      quoteIdentifier: id => this.quoteIdentifier(id),
-      compileSelectAst: (ast, ctx) => this.compileSelectAst(ast, ctx),
-      compileSelectForExists: (ast, ctx) => this.compileSelectForExists(ast, ctx),
-      compileJsonPath: node => this.compileJsonPath(node),
-      compileFunctionOperand: (node, ctx) => this.compileFunctionOperand(node, ctx),
-      describe: () => this.constructor.name
-    });
-  }
-
-  compileSelect(ast: SelectQueryNode): CompiledQuery {
-    const ctx = this.createCompilerContext();
-    const normalized = this.normalizeSelectAst(ast);
-    const rawSql = this.compileSelectAst(normalized, ctx).trim();
-    return {
-      sql: rawSql.endsWith(';') ? rawSql : `${rawSql};`,
-      params: [...ctx.params]
-    };
-  }
-
-  compileInsert(ast: InsertQueryNode): CompiledQuery {
-    const ctx = this.createCompilerContext();
-    const rawSql = this.compileInsertAst(ast, ctx).trim();
-    return {
-      sql: rawSql.endsWith(';') ? rawSql : `${rawSql};`,
-      params: [...ctx.params]
-    };
-  }
-
-  compileUpdate(ast: UpdateQueryNode): CompiledQuery {
-    const ctx = this.createCompilerContext();
-    const rawSql = this.compileUpdateAst(ast, ctx).trim();
-    return {
-      sql: rawSql.endsWith(';') ? rawSql : `${rawSql};`,
-      params: [...ctx.params]
-    };
-  }
-
-  compileDelete(ast: DeleteQueryNode): CompiledQuery {
-    const ctx = this.createCompilerContext();
-    const rawSql = this.compileDeleteAst(ast, ctx).trim();
-    return {
-      sql: rawSql.endsWith(';') ? rawSql : `${rawSql};`,
-      params: [...ctx.params]
-    };
-  }
-
-  supportsDmlReturningClause(): boolean {
-    return false;
-  }
-
-  protected abstract compileSelectAst(ast: SelectQueryNode, ctx: CompilerContext): string;
-  protected abstract compileInsertAst(ast: InsertQueryNode, ctx: CompilerContext): string;
-  protected abstract compileUpdateAst(ast: UpdateQueryNode, ctx: CompilerContext): string;
-  protected abstract compileDeleteAst(ast: DeleteQueryNode, ctx: CompilerContext): string;
-
-  abstract quoteIdentifier(id: string): string;
-
-  protected compileWhere(where: ExpressionNode | undefined, ctx: CompilerContext): string {
-    if (!where) return '';
-    return ` WHERE ${this.compileExpression(where, ctx)}`;
-  }
-
-  protected compileReturning(
-    returning: ColumnNode[] | undefined,
-    _ctx: CompilerContext
-  ): string {
-    void _ctx;
-    if (!returning || returning.length === 0) return '';
-    throw new Error('RETURNING is not supported by this dialect.');
-  }
-
-  protected compileSelectForExists(ast: SelectQueryNode, ctx: CompilerContext): string {
-    const normalized = this.normalizeSelectAst(ast);
-    const full = this.compileSelectAst(normalized, ctx).trim().replace(/;$/, '');
-
-    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;
-
-    return `SELECT 1${full.slice(fromIndex)}`;
-  }
-
-  protected createCompilerContext(): CompilerContext {
-    const params: unknown[] = [];
-    let counter = 0;
-    return {
-      params,
-      addParameter: (value: unknown) => {
-        counter += 1;
-        params.push(value);
-        return this.formatPlaceholder(counter);
-      }
-    };
-  }
-
-  protected formatPlaceholder(_index: number): string {
-    void _index;
-    return '?';
-  }
-
-  protected supportsSetOperation(_kind: SetOperationKind): boolean {
-    void _kind;
-    return true;
-  }
-
-  protected normalizeSelectAst(ast: SelectQueryNode): SelectQueryNode {
-    return this.selectAstNormalizer.normalize(ast);
-  }
-
-  protected registerExpressionCompiler<T extends ExpressionNode>(
-    type: T['type'],
-    compiler: (node: T, ctx: CompilerContext) => string
-  ): void {
-    this.expressionCompilerRegistry.registerExpressionCompiler(type, compiler);
-  }
-
-  protected registerOperandCompiler<T extends OperandNode>(
-    type: T['type'],
-    compiler: (node: T, ctx: CompilerContext) => string
-  ): void {
-    this.expressionCompilerRegistry.registerOperandCompiler(type, compiler);
-  }
-
-  protected compileExpression(node: ExpressionNode, ctx: CompilerContext): string {
-    return this.expressionCompilerRegistry.compileExpression(node, ctx);
-  }
-
-  protected compileOperand(node: OperandNode, ctx: CompilerContext): string {
-    return this.expressionCompilerRegistry.compileOperand(node, ctx);
-  }
-
-  protected compileOrderingTerm(term: OrderingTerm, ctx: CompilerContext): string {
-    return this.expressionCompilerRegistry.compileOrderingTerm(term, ctx);
-  }
-
-  protected compileJsonPath(_node: JsonPathNode): string {
-    void _node;
-    throw new Error('JSON Path not supported by this dialect');
-  }
-
-  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,
-        compileOperand: operand => this.compileOperand(operand, ctx)
-      });
-    }
-    return `${fnNode.name}(${compiledArgs.join(', ')})`;
-  }
-
-  /** Creates a minimal dialect implementation for isolated compiler tests. */
-  static create(
-    functionStrategy?: FunctionStrategy,
-    tableFunctionStrategy?: TableFunctionStrategy
-  ): Dialect {
-    class TestDialect extends DialectBase {
-      protected readonly dialect: DialectName = 'sqlite';
-      quoteIdentifier(id: string): string {
-        return `"${id}"`;
-      }
-      protected compileSelectAst(): never {
-        throw new Error('Not implemented');
-      }
-      protected compileInsertAst(): never {
-        throw new Error('Not implemented');
-      }
-      protected compileUpdateAst(): never {
-        throw new Error('Not implemented');
-      }
-      protected compileDeleteAst(): never {
-        throw new Error('Not implemented');
-      }
-    }
-    return new TestDialect(functionStrategy, tableFunctionStrategy);
-  }
-}