metal-orm 1.1.24 → 1.1.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metal-orm",
-  "version": "1.1.24",
+  "version": "1.1.25",
   "type": "module",
   "repository": {
     "type": "git",

package/src/core/dialect/base/returning-strategy.ts

@@ -1,51 +1,39 @@
-import { ColumnNode } from '../../ast/expression.js';
-import { CompilerContext } from '../abstract.js';
+import type { ColumnNode } from '../../ast/expression.js';
+import type { CompilerContext } from '../abstract.js';
 
-/**
- * Strategy interface for handling RETURNING clauses in DML statements (INSERT, UPDATE, DELETE).
- * Different SQL dialects have varying levels of support for RETURNING clauses.
- */
+export type QuoteIdentifier = (id: string) => string;
+
+/** Backend-specific RETURNING/OUTPUT rendering strategy. */
 export interface ReturningStrategy {
-  /**
-   * Compiles a RETURNING clause for DML statements.
-   * @param returning - Array of columns to return, or undefined if none.
-   * @param ctx - The compiler context for expression compilation.
-   * @returns SQL RETURNING clause or empty string if not supported.
-   * @throws Error if RETURNING is not supported by this dialect.
-   */
-  compileReturning(returning: ColumnNode[] | undefined, ctx: CompilerContext): string;
-  /**
-   * Formats column list for RETURNING clause.
-   * @param returning - Array of columns to format.
-   * @param quoteIdentifier - Function to quote identifiers according to dialect rules.
-   * @returns Formatted column list (e.g., "table.col1, table.col2").
-   */
-  formatReturningColumns(returning: ColumnNode[], quoteIdentifier: (id: string) => string): string;
+  compileReturning(
+    returning: ColumnNode[] | undefined,
+    ctx: CompilerContext,
+    quoteIdentifier: QuoteIdentifier
+  ): string;
+
+  formatReturningColumns(
+    returning: ColumnNode[],
+    quoteIdentifier: QuoteIdentifier
+  ): string;
 }
 
-/**
- * Default RETURNING strategy that throws an error when RETURNING is used.
- * Use this for dialects that don't support RETURNING clauses.
- */
+/** Default RETURNING strategy for dialects without support. */
 export class NoReturningStrategy implements ReturningStrategy {
-  /**
-   * Throws an error as RETURNING is not supported.
-   * @param returning - Columns to return (causes error if non-empty).
-   * @param _ctx - Compiler context (unused).
-   * @throws Error indicating RETURNING is not supported.
-   */
-  compileReturning(returning: ColumnNode[] | undefined, _ctx: CompilerContext): string {
+  compileReturning(
+    returning: ColumnNode[] | undefined,
+    _ctx: CompilerContext,
+    _quoteIdentifier: QuoteIdentifier
+  ): string {
     void _ctx;
+    void _quoteIdentifier;
     if (!returning || returning.length === 0) return '';
     throw new Error('RETURNING is not supported by this dialect.');
   }
-  /**
-   * Formats column names for RETURNING clause.
-   * @param returning - Columns to format.
-   * @param quoteIdentifier - Function to quote identifiers according to dialect rules.
-   * @returns Simple comma-separated column names.
-   */
-  formatReturningColumns(returning: ColumnNode[], quoteIdentifier: (id: string) => string): string {
+
+  formatReturningColumns(
+    returning: ColumnNode[],
+    quoteIdentifier: QuoteIdentifier
+  ): string {
     return returning
       .map(column => {
         const tablePart = column.table ? `${quoteIdentifier(column.table)}.` : '';
@@ -55,3 +43,16 @@ export class NoReturningStrategy implements ReturningStrategy {
       .join(', ');
   }
 }
+
+/** Standard SQL RETURNING implementation with qualified column support. */
+export class StandardReturningStrategy extends NoReturningStrategy {
+  override compileReturning(
+    returning: ColumnNode[] | undefined,
+    _ctx: CompilerContext,
+    quoteIdentifier: QuoteIdentifier
+  ): string {
+    void _ctx;
+    if (!returning || returning.length === 0) return '';
+    return ` RETURNING ${this.formatReturningColumns(returning, quoteIdentifier)}`;
+  }
+}

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

@@ -0,0 +1,33 @@
+import type { CompilerContext } from '../abstract.js';
+import type {
+  DeleteQueryNode,
+  InsertQueryNode,
+  SelectQueryNode,
+  UpdateQueryNode
+} from '../../ast/query.js';
+import type { StandardSqlCompilerServices } from './standard-sql-services.js';
+import type { StandardSqlSourceCompiler } from './standard-sql-source-compiler.js';
+
+export interface SqlAstCompiler<TAst> {
+  compile(ast: TAst, ctx: CompilerContext): string;
+}
+
+export interface SqlCompilerSet {
+  select: SqlAstCompiler<SelectQueryNode>;
+  insert: SqlAstCompiler<InsertQueryNode>;
+  update: SqlAstCompiler<UpdateQueryNode>;
+  delete: SqlAstCompiler<DeleteQueryNode>;
+}
+
+export interface SqlCompilerAssemblyContext {
+  services: StandardSqlCompilerServices;
+  sources: StandardSqlSourceCompiler;
+}
+
+/**
+ * Allows a backend to replace only the standard query compilers whose SQL
+ * grammar genuinely differs from the common implementation.
+ */
+export type SqlCompilerFactory = (
+  context: SqlCompilerAssemblyContext
+) => Partial<SqlCompilerSet>;

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

@@ -1,55 +1,71 @@
 import { DialectBase } from '../abstract.js';
 import type { CompilerContext } from '../abstract.js';
 import type {
-  SelectQueryNode,
-  InsertQueryNode,
-  UpdateQueryNode,
   DeleteQueryNode,
-  UpsertClause,
-  TableSourceNode,
   DerivedTableNode,
   FunctionTableNode,
+  InsertQueryNode,
   OrderByNode,
-  TableNode
+  SelectQueryNode,
+  TableNode,
+  TableSourceNode,
+  UpdateAssignmentNode,
+  UpdateQueryNode,
+  UpsertClause
 } from '../../ast/query.js';
-import type { ColumnNode, OperandNode } from '../../ast/expression.js';
+import type { ColumnNode } from '../../ast/expression.js';
 import type { FunctionStrategy } from '../../functions/types.js';
 import type { TableFunctionStrategy } from '../../functions/table-types.js';
 import { StandardLimitOffsetPagination } from './pagination-strategy.js';
 import type { PaginationStrategy } from './pagination-strategy.js';
 import { NoReturningStrategy } from './returning-strategy.js';
 import type { ReturningStrategy } from './returning-strategy.js';
+import { NoUpsertStrategy } from './upsert-strategy.js';
+import type { UpsertStrategy } from './upsert-strategy.js';
 import { StandardSqlSourceCompiler } from './standard-sql-source-compiler.js';
 import { StandardSelectCompiler } from './standard-select-compiler.js';
 import { StandardInsertCompiler } from './standard-insert-compiler.js';
 import { StandardUpdateCompiler } from './standard-update-compiler.js';
 import { StandardDeleteCompiler } from './standard-delete-compiler.js';
 import type { StandardSqlCompilerServices } from './standard-sql-services.js';
+import type { SqlCompilerFactory, SqlCompilerSet } from './sql-compiler-set.js';
+
+export interface SqlDialectBaseOptions {
+  functionStrategy?: FunctionStrategy;
+  tableFunctionStrategy?: TableFunctionStrategy;
+  paginationStrategy?: PaginationStrategy;
+  returningStrategy?: ReturningStrategy;
+  upsertStrategy?: UpsertStrategy;
+  compilerFactory?: SqlCompilerFactory;
+  supportsDmlReturning?: boolean;
+}
 
 /**
- * Thin assembly base for dialects that use MetalORM's standard SQL compilers.
+ * Thin assembly base for dialects that use MetalORM's reusable SQL compiler pieces.
  *
- * SELECT/INSERT/UPDATE/DELETE orchestration lives in independent compiler
- * objects. This class only wires dialect-specific syntax hooks and strategies
- * into those components.
+ * Query orchestration, source rendering, upsert behavior and returning behavior are
+ * injected components. Concrete dialects keep only syntax hooks that are genuinely
+ * intrinsic to that backend.
  */
 export abstract class SqlDialectBase extends DialectBase {
   abstract quoteIdentifier(id: string): string;
 
-  protected paginationStrategy: PaginationStrategy = new StandardLimitOffsetPagination();
-  protected returningStrategy: ReturningStrategy = new NoReturningStrategy();
+  protected readonly paginationStrategy: PaginationStrategy;
+  protected readonly returningStrategy: ReturningStrategy;
+  protected readonly upsertStrategy: UpsertStrategy;
 
+  private readonly dmlReturningSupported: boolean;
   private readonly sourceCompiler: StandardSqlSourceCompiler;
-  private readonly selectCompiler: StandardSelectCompiler;
-  private readonly insertCompiler: StandardInsertCompiler;
-  private readonly updateCompiler: StandardUpdateCompiler;
-  private readonly deleteCompiler: StandardDeleteCompiler;
+  private readonly standardUpdateCompiler: StandardUpdateCompiler;
+  private readonly compilerSet: SqlCompilerSet;
 
-  protected constructor(
-    functionStrategy?: FunctionStrategy,
-    tableFunctionStrategy?: TableFunctionStrategy
-  ) {
-    super(functionStrategy, tableFunctionStrategy);
+  protected constructor(options: SqlDialectBaseOptions = {}) {
+    super(options.functionStrategy, options.tableFunctionStrategy);
+
+    this.paginationStrategy = options.paginationStrategy ?? new StandardLimitOffsetPagination();
+    this.returningStrategy = options.returningStrategy ?? new NoReturningStrategy();
+    this.upsertStrategy = options.upsertStrategy ?? new NoUpsertStrategy();
+    this.dmlReturningSupported = options.supportsDmlReturning ?? false;
 
     const services: StandardSqlCompilerServices = {
       getDialectName: () => this.dialect,
@@ -69,48 +85,73 @@ export abstract class SqlDialectBase extends DialectBase {
     };
 
     this.sourceCompiler = new StandardSqlSourceCompiler(services);
-    this.selectCompiler = new StandardSelectCompiler(services, this.sourceCompiler);
-    this.insertCompiler = new StandardInsertCompiler(services, this.sourceCompiler);
-    this.updateCompiler = new StandardUpdateCompiler(services, this.sourceCompiler);
-    this.deleteCompiler = new StandardDeleteCompiler(services, this.sourceCompiler);
+    const standardSelect = new StandardSelectCompiler(services, this.sourceCompiler);
+    const standardInsert = new StandardInsertCompiler(services, this.sourceCompiler);
+    this.standardUpdateCompiler = new StandardUpdateCompiler(services, this.sourceCompiler);
+    const standardDelete = new StandardDeleteCompiler(services, this.sourceCompiler);
+
+    const overrides = options.compilerFactory?.({
+      services,
+      sources: this.sourceCompiler
+    }) ?? {};
+
+    this.compilerSet = {
+      select: overrides.select ?? standardSelect,
+      insert: overrides.insert ?? standardInsert,
+      update: overrides.update ?? this.standardUpdateCompiler,
+      delete: overrides.delete ?? standardDelete
+    };
+  }
+
+  override supportsDmlReturningClause(): boolean {
+    return this.dmlReturningSupported;
   }
 
   protected compileSelectAst(ast: SelectQueryNode, ctx: CompilerContext): string {
-    return this.selectCompiler.compile(ast, ctx);
+    return this.compilerSet.select.compile(ast, ctx);
   }
 
   protected compileInsertAst(ast: InsertQueryNode, ctx: CompilerContext): string {
-    return this.insertCompiler.compile(ast, ctx);
+    return this.compilerSet.insert.compile(ast, ctx);
   }
 
   protected compileUpdateAst(ast: UpdateQueryNode, ctx: CompilerContext): string {
-    return this.updateCompiler.compile(ast, ctx);
+    return this.compilerSet.update.compile(ast, ctx);
   }
 
   protected compileDeleteAst(ast: DeleteQueryNode, ctx: CompilerContext): string {
-    return this.deleteCompiler.compile(ast, ctx);
+    return this.compilerSet.delete.compile(ast, ctx);
   }
 
-  protected compileUpsertClause(ast: InsertQueryNode, _ctx: CompilerContext): string {
-    void _ctx;
-    if (!ast.onConflict) return '';
-    throw new Error(`UPSERT/ON CONFLICT is not supported by dialect "${this.dialect}".`);
+  protected compileUpsertClause(ast: InsertQueryNode, ctx: CompilerContext): string {
+    return this.upsertStrategy.compile(ast, ctx, {
+      getDialectName: () => this.dialect,
+      quoteIdentifier: id => this.quoteIdentifier(id),
+      compileOperand: (node, compilerContext) => this.compileOperand(node, compilerContext),
+      compileExpression: (node, compilerContext) => this.compileExpression(node, compilerContext),
+      compileUpdateAssignments: (assignments, table, compilerContext) =>
+        this.standardUpdateCompiler.compileAssignments(assignments, table, compilerContext)
+    });
   }
 
   protected compileReturning(returning: ColumnNode[] | undefined, ctx: CompilerContext): string {
-    return this.returningStrategy.compileReturning(returning, ctx);
+    return this.returningStrategy.compileReturning(
+      returning,
+      ctx,
+      id => this.quoteIdentifier(id)
+    );
   }
 
   protected ensureConflictColumns(clause: UpsertClause, message: string): void {
-    this.insertCompiler.ensureConflictColumns(clause, message);
+    if (!clause.target.columns.length) throw new Error(message);
   }
 
   protected compileUpdateAssignments(
-    assignments: { column: ColumnNode; value: OperandNode }[],
+    assignments: UpdateAssignmentNode[],
     table: TableNode,
     ctx: CompilerContext
   ): string {
-    return this.updateCompiler.compileAssignments(assignments, table, ctx);
+    return this.standardUpdateCompiler.compileAssignments(assignments, table, ctx);
   }
 
   protected compileSetTarget(column: ColumnNode, table: TableNode): string {

package/src/core/dialect/base/upsert-strategy.ts

@@ -0,0 +1,45 @@
+import type { CompilerContext } from '../abstract.js';
+import type {
+  InsertQueryNode,
+  TableNode,
+  UpdateAssignmentNode
+} from '../../ast/query.js';
+import type { ExpressionNode, OperandNode } from '../../ast/expression.js';
+import type { DialectName } from '../../sql/sql.js';
+
+/** Narrow services needed by backend-specific UPSERT implementations. */
+export interface UpsertCompilationServices {
+  getDialectName(): DialectName;
+  quoteIdentifier(id: string): string;
+  compileOperand(node: OperandNode, ctx: CompilerContext): string;
+  compileExpression(node: ExpressionNode, ctx: CompilerContext): string;
+  compileUpdateAssignments(
+    assignments: UpdateAssignmentNode[],
+    table: TableNode,
+    ctx: CompilerContext
+  ): string;
+}
+
+/** Backend-specific INSERT conflict/upsert rendering strategy. */
+export interface UpsertStrategy {
+  compile(
+    ast: InsertQueryNode,
+    ctx: CompilerContext,
+    services: UpsertCompilationServices
+  ): string;
+}
+
+/** Default strategy for dialects without UPSERT support. */
+export class NoUpsertStrategy implements UpsertStrategy {
+  compile(
+    ast: InsertQueryNode,
+    _ctx: CompilerContext,
+    services: UpsertCompilationServices
+  ): string {
+    void _ctx;
+    if (!ast.onConflict) return '';
+    throw new Error(
+      `UPSERT/ON CONFLICT is not supported by dialect "${services.getDialectName()}".`
+    );
+  }
+}

package/src/core/dialect/capabilities/procedure-compiler.ts

@@ -1,5 +1,6 @@
 import type { ProcedureCallNode } from '../../ast/procedure.js';
-import type { CompiledQuery } from '../abstract.js';
+import type { OperandNode } from '../../ast/expression.js';
+import type { CompiledQuery, CompilerContext } from '../abstract.js';
 
 export interface CompiledProcedureCall extends CompiledQuery {
   outParams: {
@@ -8,13 +9,14 @@ export interface CompiledProcedureCall extends CompiledQuery {
   };
 }
 
-/**
- * Optional dialect capability for stored-procedure compilation.
- *
- * Dialects that do not support procedures simply do not implement this
- * interface; unsupported behavior is resolved at the capability boundary
- * rather than through mandatory methods that only throw.
- */
+/** Narrow SQL services consumed by reusable procedure compiler components. */
+export interface ProcedureCompilerServices {
+  quoteIdentifier(id: string): string;
+  createCompilerContext(): CompilerContext;
+  compileOperand(node: OperandNode, ctx: CompilerContext): string;
+}
+
+/** Optional dialect capability for stored-procedure compilation. */
 export interface ProcedureCompiler {
   compileProcedureCall(ast: ProcedureCallNode): CompiledProcedureCall;
 }

package/src/core/dialect/mssql/compiler-factory.ts

@@ -0,0 +1,12 @@
+import type { SqlCompilerFactory } from '../base/sql-compiler-set.js';
+import { MssqlDeleteCompiler } from './delete-compiler.js';
+import { MssqlInsertCompiler } from './insert-compiler.js';
+import { MssqlSelectCompiler } from './select-compiler.js';
+import { MssqlUpdateCompiler } from './update-compiler.js';
+
+export const createMssqlCompilerSet: SqlCompilerFactory = ({ services, sources }) => ({
+  select: new MssqlSelectCompiler(services, sources),
+  insert: new MssqlInsertCompiler(services, sources),
+  update: new MssqlUpdateCompiler(services, sources),
+  delete: new MssqlDeleteCompiler(services, sources)
+});

package/src/core/dialect/mssql/delete-compiler.ts

@@ -0,0 +1,40 @@
+import type { DeleteQueryNode } from '../../ast/query.js';
+import type { CompilerContext } from '../abstract.js';
+import { JoinCompiler } from '../base/join-compiler.js';
+import type { SqlAstCompiler } from '../base/sql-compiler-set.js';
+import type { StandardSqlCompilerServices } from '../base/standard-sql-services.js';
+import type { StandardSqlSourceCompiler } from '../base/standard-sql-source-compiler.js';
+import { MssqlOutputStrategy } from './output.js';
+
+export class MssqlDeleteCompiler implements SqlAstCompiler<DeleteQueryNode> {
+  private readonly output = new MssqlOutputStrategy();
+
+  constructor(
+    private readonly services: StandardSqlCompilerServices,
+    private readonly sources: StandardSqlSourceCompiler
+  ) {}
+
+  compile(ast: DeleteQueryNode, ctx: CompilerContext): string {
+    if (ast.using) {
+      throw new Error('DELETE ... USING is not supported in the MSSQL dialect; use join() instead.');
+    }
+
+    const alias = ast.from.alias ?? ast.from.name;
+    const target = this.sources.compileTableReference(ast.from);
+    const joins = JoinCompiler.compileJoins(
+      ast.joins,
+      ctx,
+      (source, compilerContext) => this.sources.compileFrom(source, compilerContext),
+      (expression, compilerContext) => this.services.compileExpression(expression, compilerContext)
+    );
+    const where = ast.where
+      ? ` WHERE ${this.services.compileExpression(ast.where, ctx)}`
+      : '';
+    const returning = this.output.compileOutput(
+      ast.returning,
+      'deleted',
+      id => this.services.quoteIdentifier(id)
+    );
+    return `DELETE ${this.services.quoteIdentifier(alias)}${returning} FROM ${target}${joins}${where}`;
+  }
+}