metal-orm 1.0.14 → 1.0.15

package/src/core/dialect/base/function-table-formatter.ts

@@ -0,0 +1,132 @@
+import { CompilerContext } from '../abstract.js';
+import { SqlDialectBase } from './sql-dialect.js';
+
+export interface FunctionTableNode {
+  type: 'FunctionTable';
+  schema?: string;
+  name: string;
+  args?: unknown[];
+  lateral?: boolean;
+  withOrdinality?: boolean;
+  alias?: string;
+  columnAliases?: string[];
+}
+
+/**
+ * Formatter for function table expressions (e.g., LATERAL unnest(...) WITH ORDINALITY).
+ * Encapsulates logic for generating SQL function table syntax including LATERAL, aliases, and column lists.
+ */
+export class FunctionTableFormatter {
+  /**
+   * Formats a function table node into SQL syntax.
+   * @param fn - The function table node containing schema, name, args, and aliases.
+   * @param ctx - Optional compiler context for operand compilation.
+   * @param dialect - The dialect instance for compiling operands.
+   * @returns SQL function table expression (e.g., "LATERAL schema.func(args) WITH ORDINALITY AS alias(col1, col2)").
+   */
+  static format(fn: FunctionTableNode, ctx?: CompilerContext, dialect?: SqlDialectBase): string {
+    const schemaPart = this.formatSchema(fn, dialect);
+    const args = this.formatArgs(fn, ctx, dialect);
+    const base = this.formatBase(fn, schemaPart, args, dialect);
+    const lateral = this.formatLateral(fn);
+    const alias = this.formatAlias(fn, dialect);
+    const colAliases = this.formatColumnAliases(fn, dialect);
+    return `${lateral}${base}${alias}${colAliases}`;
+  }
+
+  /**
+   * Formats the schema prefix for the function name.
+   * @param fn - The function table node.
+   * @param dialect - The dialect instance for quoting identifiers.
+   * @returns Schema prefix (e.g., "schema.") or empty string.
+   * @internal
+   */
+  private static formatSchema(fn: FunctionTableNode, dialect?: SqlDialectBase): string {
+    if (!fn.schema) return '';
+    const quoted = dialect ? dialect.quoteIdentifier(fn.schema) : fn.schema;
+    return `${quoted}.`;
+  }
+
+  /**
+   * Formats function arguments into SQL syntax.
+   * @param fn - The function table node containing arguments.
+   * @param ctx - Optional compiler context for operand compilation.
+   * @param dialect - The dialect instance for compiling operands.
+   * @returns Comma-separated function arguments.
+   * @internal
+   */
+  private static formatArgs(fn: FunctionTableNode, ctx?: CompilerContext, dialect?: SqlDialectBase): string {
+    return (fn.args || [])
+      .map((a: any) => {
+        if (ctx && dialect) {
+          return (dialect as any).compileOperand(a, ctx);
+        }
+        return String(a);
+      })
+      .join(', ');
+  }
+
+  /**
+   * Formats the base function call with WITH ORDINALITY if present.
+   * @param fn - The function table node.
+   * @param schemaPart - Formatted schema prefix.
+   * @param args - Formatted function arguments.
+   * @param dialect - The dialect instance for quoting identifiers.
+   * @returns Base function call expression (e.g., "schema.func(args) WITH ORDINALITY").
+   * @internal
+   */
+  private static formatBase(fn: FunctionTableNode, schemaPart: string, args: string, dialect?: SqlDialectBase): string {
+    const ordinality = fn.withOrdinality ? ' WITH ORDINALITY' : '';
+    const quoted = dialect ? dialect.quoteIdentifier(fn.name) : fn.name;
+    return `${schemaPart}${quoted}(${args})${ordinality}`;
+  }
+
+  /**
+   * Formats the LATERAL keyword if present.
+   * @param fn - The function table node.
+   * @returns "LATERAL " or empty string.
+   * @internal
+   */
+  private static formatLateral(fn: FunctionTableNode): string {
+    return fn.lateral ? 'LATERAL ' : '';
+  }
+
+  /**
+   * Formats the table alias for the function table.
+   * @param fn - The function table node.
+   * @param dialect - The dialect instance for quoting identifiers.
+   * @returns " AS alias" or empty string.
+   * @internal
+   */
+  private static formatAlias(fn: FunctionTableNode, dialect?: SqlDialectBase): string {
+    if (!fn.alias) return '';
+    const quoted = dialect ? dialect.quoteIdentifier(fn.alias) : fn.alias;
+    return ` AS ${quoted}`;
+  }
+
+  /**
+   * Formats column aliases for the function table result columns.
+   * @param fn - The function table node containing column aliases.
+   * @param dialect - The dialect instance for quoting identifiers.
+   * @returns "(col1, col2, ...)" or empty string.
+   * @internal
+   */
+  private static formatColumnAliases(fn: FunctionTableNode, dialect?: SqlDialectBase): string {
+    if (!fn.columnAliases || !fn.columnAliases.length) return '';
+    const aliases = fn.columnAliases
+      .map(col => dialect ? dialect.quoteIdentifier(col) : col)
+      .join(', ');
+    return `(${aliases})`;
+  }
+}
+
+export interface FunctionTableNode {
+  type: 'FunctionTable';
+  schema?: string;
+  name: string;
+  args?: unknown[];
+  lateral?: boolean;
+  withOrdinality?: boolean;
+  alias?: string;
+  columnAliases?: string[];
+}

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

@@ -0,0 +1,21 @@
+import { SelectQueryNode } from '../../ast/query.js';
+
+/**
+ * Compiler for GROUP BY clauses in SELECT statements.
+ * Handles compilation of column grouping expressions.
+ */
+export class GroupByCompiler {
+  /**
+   * Compiles GROUP BY clause from a SELECT query AST.
+   * @param ast - The SELECT query AST containing grouping columns.
+   * @param quoteIdentifier - Function to quote identifiers according to dialect rules.
+   * @returns SQL GROUP BY clause (e.g., " GROUP BY table.col1, table.col2") or empty string if no grouping.
+   */
+  static compileGroupBy(ast: SelectQueryNode, quoteIdentifier: (id: string) => string): string {
+    if (!ast.groupBy || ast.groupBy.length === 0) return '';
+    const cols = ast.groupBy
+      .map(c => `${quoteIdentifier(c.table)}.${quoteIdentifier(c.name)}`)
+      .join(', ');
+    return ` GROUP BY ${cols}`;
+  }
+}

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

@@ -0,0 +1,26 @@
+import { SelectQueryNode } from '../../ast/query.js';
+import { CompilerContext } from '../abstract.js';
+
+/**
+ * Compiler for JOIN clauses in SELECT statements.
+ * Handles compilation of all join types (INNER, LEFT, RIGHT, FULL, CROSS).
+ */
+export class JoinCompiler {
+  /**
+   * Compiles all JOIN clauses from a SELECT query AST.
+   * @param ast - The SELECT query AST containing join definitions.
+   * @param ctx - The compiler context for expression compilation.
+   * @param compileFrom - Function to compile table sources (tables or subqueries).
+   * @param compileExpression - Function to compile join condition expressions.
+   * @returns SQL JOIN clauses (e.g., " LEFT JOIN table ON condition") or empty string if no joins.
+   */
+  static compileJoins(ast: SelectQueryNode, ctx: CompilerContext, compileFrom: (from: any, ctx: CompilerContext) => string, compileExpression: (expr: any, ctx: CompilerContext) => string): string {
+    if (!ast.joins || ast.joins.length === 0) return '';
+    const parts = ast.joins.map(j => {
+      const table = compileFrom(j.table as any, ctx);
+      const cond = compileExpression(j.condition, ctx);
+      return `${j.kind} JOIN ${table} ON ${cond}`;
+    });
+    return ` ${parts.join(' ')}`;
+  }
+}

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

@@ -0,0 +1,21 @@
+import { SelectQueryNode } from '../../ast/query.js';
+
+/**
+ * Compiler for ORDER BY clauses in SELECT statements.
+ * Handles compilation of sorting expressions with direction (ASC/DESC).
+ */
+export class OrderByCompiler {
+  /**
+   * Compiles ORDER BY clause from a SELECT query AST.
+   * @param ast - The SELECT query AST containing sort specifications.
+   * @param quoteIdentifier - Function to quote identifiers according to dialect rules.
+   * @returns SQL ORDER BY clause (e.g., " ORDER BY table.col1 ASC, table.col2 DESC") or empty string if no ordering.
+   */
+  static compileOrderBy(ast: SelectQueryNode, quoteIdentifier: (id: string) => string): string {
+    if (!ast.orderBy || ast.orderBy.length === 0) return '';
+    const parts = ast.orderBy
+      .map(o => `${quoteIdentifier(o.column.table)}.${quoteIdentifier(o.column.name)} ${o.direction}`)
+      .join(', ');
+    return ` ORDER BY ${parts}`;
+  }
+}

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

@@ -0,0 +1,32 @@
+/**
+ * Strategy interface for compiling pagination clauses.
+ * Allows dialects to customize how pagination (LIMIT/OFFSET, ROWS FETCH, etc.) is generated.
+ */
+export interface PaginationStrategy {
+  /**
+   * Compiles pagination logic into SQL clause.
+   * @param limit - The limit value, if present.
+   * @param offset - The offset value, if present.
+   * @returns SQL pagination clause (e.g., " LIMIT 10 OFFSET 0") or empty string if no pagination.
+   */
+  compilePagination(limit?: number, offset?: number): string;
+}
+
+/**
+ * Standard SQL pagination using LIMIT and OFFSET.
+ * Implements the ANSI SQL-style pagination with LIMIT/OFFSET syntax.
+ */
+export class StandardLimitOffsetPagination implements PaginationStrategy {
+  /**
+   * Compiles LIMIT/OFFSET pagination clause.
+   * @param limit - The maximum number of rows to return.
+   * @param offset - The number of rows to skip.
+   * @returns SQL pagination clause with LIMIT and/or OFFSET.
+   */
+  compilePagination(limit?: number, offset?: number): string {
+    const parts: string[] = [];
+    if (limit !== undefined) parts.push(`LIMIT ${limit}`);
+    if (offset !== undefined) parts.push(`OFFSET ${offset}`);
+    return parts.length ? ` ${parts.join(' ')}` : '';
+  }
+}

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

@@ -0,0 +1,56 @@
+import { ColumnNode } from '../../ast/expression.js';
+import { 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 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;
+}
+
+/**
+ * Default RETURNING strategy that throws an error when RETURNING is used.
+ * Use this for dialects that don't support RETURNING clauses.
+ */
+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 {
+    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 {
+    return returning
+      .map(column => {
+        const tablePart = column.table ? `${quoteIdentifier(column.table)}.` : '';
+        const aliasPart = column.alias ? ` AS ${quoteIdentifier(column.alias)}` : '';
+        return `${tablePart}${quoteIdentifier(column.name)}${aliasPart}`;
+      })
+      .join(', ');
+  }
+}