metal-orm 1.0.17 → 1.0.19

package/src/codegen/naming-strategy.ts

@@ -1,4 +1,4 @@
-import type { TableNode, FunctionTableNode } from '../core/ast/query.js';
+import type { TableNode, FunctionTableNode, DerivedTableNode, TableSourceNode } from '../core/ast/query.js';
 import type { ColumnNode } from '../core/ast/expression.js';
 
 /**
@@ -7,10 +7,10 @@ import type { ColumnNode } from '../core/ast/expression.js';
 export interface NamingStrategy {
   /**
    * Converts a table name to a TypeScript symbol name
-   * @param table - Table node, function table node, or name
-   * @returns Valid TypeScript identifier
-   */
-  tableToSymbol(table: TableNode | FunctionTableNode | string): string;
+   * @param table - Table node, function table node, or name
+   * @returns Valid TypeScript identifier
+   */
+  tableToSymbol(table: TableSourceNode | string): string;
 
   /**
    * Converts a column reference to a property name
@@ -27,11 +27,16 @@ export interface NamingStrategy {
 export class DefaultNamingStrategy implements NamingStrategy {
   /**
    * Converts table names to TypeScript symbols
-   * @param table - Table node, function table node, or string name
-   * @returns Capitalized table name (handles schema-qualified names)
-   */
-  tableToSymbol(table: TableNode | FunctionTableNode | string): string {
-    const tableName = typeof table === 'string' ? table : table.name;
+   * @param table - Table node, function table node, or string name
+   * @returns Capitalized table name (handles schema-qualified names)
+   */
+  tableToSymbol(table: TableNode | FunctionTableNode | DerivedTableNode | string): string {
+    const tableName =
+      typeof table === 'string'
+        ? table
+        : table.type === 'DerivedTable'
+          ? table.alias
+          : table.name;
 
     // Handle schema-qualified names (e.g., "auth.user" → "AuthUser")
     if (tableName.includes('.')) {

package/src/core/ast/builders.ts

@@ -1,5 +1,5 @@
 import { ColumnNode } from './expression-nodes.js';
-import { TableNode, FunctionTableNode } from './query.js';
+import { TableNode, FunctionTableNode, DerivedTableNode } from './query.js';
 import { ColumnRef, TableRef } from './types.js';
 
 /**
@@ -13,9 +13,15 @@ export const buildColumnNode = (table: TableRef, column: ColumnRef | ColumnNode)
   }
 
   const def = column as ColumnRef;
+  const baseTable = def.table
+    ? table.alias && def.table === table.name
+      ? table.alias
+      : def.table
+    : table.alias || table.name;
+
   return {
     type: 'Column',
-    table: def.table || table.name,
+    table: baseTable,
     name: def.name
   };
 };
@@ -28,7 +34,7 @@ export const buildColumnNode = (table: TableRef, column: ColumnRef | ColumnNode)
 export const buildColumnNodes = (table: TableRef, names: string[]): ColumnNode[] =>
   names.map(name => ({
     type: 'Column',
-    table: table.name,
+    table: table.alias || table.name,
     name
   }));
 
@@ -54,3 +60,17 @@ export const fnTable = (name: string, args: any[] = [], alias?: string, opts?: {
   columnAliases: opts?.columnAliases,
   schema: opts?.schema
 });
+
+/**
+ * Creates a derived table node wrapping a subquery.
+ */
+export const derivedTable = (
+  query: import('./query.js').SelectQueryNode,
+  alias: string,
+  columnAliases?: string[]
+): DerivedTableNode => ({
+  type: 'DerivedTable',
+  query,
+  alias,
+  columnAliases
+});

package/src/core/ast/expression-builders.ts

@@ -63,7 +63,20 @@ const toOperand = (val: OperandNode | ColumnRef | LiteralValue): OperandNode =>
   return toNode(val);
 };
 
-export const columnOperand = (col: ColumnRef | ColumnNode): ColumnNode => toNode(col) as ColumnNode;
+export const columnOperand = (col: ColumnRef | ColumnNode): ColumnNode => toNode(col) as ColumnNode;
+/**
+ * Marks a column reference as an outer-scope reference for correlated subqueries.
+ * Primarily semantic; SQL rendering still uses the provided table/alias name.
+ */
+export const outerRef = (col: ColumnRef | ColumnNode): ColumnNode => ({
+  ...columnOperand(col),
+  scope: 'outer'
+});
+
+/**
+ * Creates an outer-scoped column reference using a specific table or alias name.
+ */
+export const correlateBy = (table: string, column: string): ColumnNode => outerRef({ name: column, table });
 
 const createBinaryExpression = (
   operator: SqlOperator,

package/src/core/ast/expression-nodes.ts

@@ -14,15 +14,17 @@ export interface LiteralNode {
 /**
  * AST node representing a column reference
  */
-export interface ColumnNode {
-  type: 'Column';
-  /** Table name the column belongs to */
-  table: string;
-  /** Column name */
-  name: string;
-  /** Optional alias for the column */
-  alias?: string;
-}
+export interface ColumnNode {
+  type: 'Column';
+  /** Table name the column belongs to */
+  table: string;
+  /** Column name */
+  name: string;
+  /** Optional alias for the column */
+  alias?: string;
+  /** Optional scope marker (e.g., 'outer' for correlated references) */
+  scope?: 'outer' | 'default';
+}
 
 /**
  * AST node representing a function call

package/src/core/ast/join-node.ts

@@ -2,7 +2,7 @@ import { JoinNode } from './join.js';
 import { ExpressionNode } from './expression.js';
 import { JoinKind } from '../sql/sql.js';
 import { JoinMetadata } from './join-metadata.js';
-import { TableNode, FunctionTableNode } from './query.js';
+import { TableSourceNode, TableNode, FunctionTableNode } from './query.js';
 
 /**
  * Creates a JoinNode ready for AST insertion.
@@ -10,13 +10,15 @@ import { TableNode, FunctionTableNode } from './query.js';
  */
 export const createJoinNode = (
   kind: JoinKind,
-  tableName: string | TableNode | FunctionTableNode,
+  tableName: string | TableSourceNode,
   condition: ExpressionNode,
   relationName?: string
 ): JoinNode => ({
   type: 'Join',
   kind,
-  table: typeof tableName === 'string' ? { type: 'Table', name: tableName } as TableNode : (tableName as TableNode | FunctionTableNode),
+  table: typeof tableName === 'string'
+    ? ({ type: 'Table', name: tableName } as TableNode)
+    : (tableName as TableSourceNode),
   condition,
   meta: relationName ? ({ relationName } as JoinMetadata) : undefined
 });

package/src/core/ast/join.ts

@@ -1,18 +1,18 @@
-import { TableNode, FunctionTableNode } from './query.js';
-import { ExpressionNode } from './expression.js';
-import { JoinKind } from '../sql/sql.js';
-
-/**
- * AST node representing a JOIN clause
+import { TableSourceNode } from './query.js';
+import { ExpressionNode } from './expression.js';
+import { JoinKind } from '../sql/sql.js';
+
+/**
+ * AST node representing a JOIN clause
  */
 export interface JoinNode {
-  type: 'Join';
-  /** Type of join (INNER, LEFT, RIGHT, etc.) */
-  kind: JoinKind;
-  /** Table to join */
-  table: TableNode | FunctionTableNode;
- /** Join condition expression */
-  condition: ExpressionNode;
-  /** Optional metadata for non-SQL concerns (e.g., relation name) */
-  meta?: Record<string, unknown>;
-}
+  type: 'Join';
+  /** Type of join (INNER, LEFT, RIGHT, etc.) */
+  kind: JoinKind;
+  /** Table to join */
+  table: TableSourceNode;
+ /** Join condition expression */
+  condition: ExpressionNode;
+  /** Optional metadata for non-SQL concerns (e.g., relation name) */
+  meta?: Record<string, unknown>;
+}

package/src/core/ast/query.ts

@@ -13,18 +13,18 @@ import { OrderDirection } from '../sql/sql.js';
 /**
  * AST node representing a table reference in a query
  */
-export interface TableNode {
-  type: 'Table';
-  /** Table name */
-  name: string;
-  /** Optional schema name */
-  schema?: string;
-  /** Optional table alias */
-  alias?: string;
-}
-
-/**
- * AST node representing a function used as a table source (table-valued function)
+export interface TableNode {
+  type: 'Table';
+  /** Table name */
+  name: string;
+  /** Optional schema name */
+  schema?: string;
+  /** Optional table alias */
+  alias?: string;
+}
+
+/**
+ * AST node representing a function used as a table source (table-valued function)
  */
 export interface FunctionTableNode {
   type: 'FunctionTable';
@@ -37,17 +37,32 @@ export interface FunctionTableNode {
   /** Optional alias for the function table */
   alias?: string;
   /** LATERAL flag */
-  lateral?: boolean;
-  /** WITH ORDINALITY flag */
-  withOrdinality?: boolean;
-  /** Optional column aliases */
-  columnAliases?: string[];
-}
-
-/**
- * AST node representing an ORDER BY clause
- */
-export interface OrderByNode {
+  lateral?: boolean;
+  /** WITH ORDINALITY flag */
+  withOrdinality?: boolean;
+  /** Optional column aliases */
+  columnAliases?: string[];
+}
+
+/**
+ * AST node representing a derived table (subquery with an alias)
+ */
+export interface DerivedTableNode {
+  type: 'DerivedTable';
+  /** Subquery providing the rows */
+  query: SelectQueryNode;
+  /** Required alias for the derived table */
+  alias: string;
+  /** Optional column aliases */
+  columnAliases?: string[];
+}
+
+export type TableSourceNode = TableNode | FunctionTableNode | DerivedTableNode;
+
+/**
+ * AST node representing an ORDER BY clause
+ */
+export interface OrderByNode {
   type: 'OrderBy';
   /** Column to order by */
   column: ColumnNode;
@@ -89,12 +104,12 @@ export interface SetOperationNode {
 /**
  * AST node representing a complete SELECT query
  */
-export interface SelectQueryNode {
-  type: 'SelectQuery';
-  /** Optional CTEs (WITH clauses) */
-  ctes?: CommonTableExpressionNode[];
-  /** FROM clause table (either a Table or a FunctionTable) */
-  from: TableNode | FunctionTableNode;
+export interface SelectQueryNode {
+  type: 'SelectQuery';
+  /** Optional CTEs (WITH clauses) */
+  ctes?: CommonTableExpressionNode[];
+  /** FROM clause table (either a Table or a FunctionTable) */
+  from: TableSourceNode;
   /** SELECT clause columns */
   columns: (ColumnNode | FunctionNode | ScalarSubqueryNode | CaseExpressionNode | WindowFunctionNode)[];
   /** JOIN clauses */

package/src/core/ddl/dialects/mssql-schema-dialect.ts

@@ -65,6 +65,24 @@ export class MSSqlSchemaDialect extends BaseSchemaDialect {
       case 'TEXT':
       case 'text':
         return 'NVARCHAR(MAX)';
+      case 'BINARY':
+      case 'binary': {
+        const length = column.args?.[0];
+        return length !== undefined ? `BINARY(${length})` : 'BINARY(255)';
+      }
+      case 'VARBINARY':
+      case 'varbinary': {
+        const length = column.args?.[0];
+        if (typeof length === 'string' && length.toLowerCase() === 'max') {
+          return 'VARBINARY(MAX)';
+        }
+        return length !== undefined ? `VARBINARY(${length})` : 'VARBINARY(255)';
+      }
+      case 'BLOB':
+      case 'blob':
+      case 'BYTEA':
+      case 'bytea':
+        return 'VARBINARY(MAX)';
       case 'ENUM':
       case 'enum':
         return 'NVARCHAR(255)';

package/src/core/ddl/dialects/mysql-schema-dialect.ts

@@ -69,6 +69,17 @@ export class MySqlSchemaDialect extends BaseSchemaDialect {
       case 'TEXT':
       case 'text':
         return 'TEXT';
+      case 'BINARY':
+      case 'binary':
+        return column.args?.length ? `BINARY(${column.args[0]})` : 'BINARY(255)';
+      case 'VARBINARY':
+      case 'varbinary':
+        return column.args?.length ? `VARBINARY(${column.args[0]})` : 'VARBINARY(255)';
+      case 'BLOB':
+      case 'blob':
+      case 'BYTEA':
+      case 'bytea':
+        return 'BLOB';
       case 'ENUM':
       case 'enum':
         return column.args && Array.isArray(column.args) && column.args.length

package/src/core/ddl/dialects/postgres-schema-dialect.ts

@@ -70,6 +70,15 @@ export class PostgresSchemaDialect extends BaseSchemaDialect {
       case 'ENUM':
       case 'enum':
         return 'text';
+      case 'BINARY':
+      case 'binary':
+      case 'VARBINARY':
+      case 'varbinary':
+      case 'BLOB':
+      case 'blob':
+      case 'BYTEA':
+      case 'bytea':
+        return 'bytea';
       default:
         return String(column.type).toLowerCase();
     }

package/src/core/ddl/dialects/sqlite-schema-dialect.ts

@@ -62,6 +62,15 @@ export class SQLiteSchemaDialect extends BaseSchemaDialect {
       case 'ENUM':
       case 'enum':
         return 'TEXT';
+      case 'BINARY':
+      case 'binary':
+      case 'VARBINARY':
+      case 'varbinary':
+      case 'BLOB':
+      case 'blob':
+      case 'BYTEA':
+      case 'bytea':
+        return 'BLOB';
       default:
         return 'TEXT';
     }

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

@@ -1,7 +1,7 @@
 import { CompilerContext, Dialect } from '../abstract.js';
-import { SelectQueryNode, InsertQueryNode, UpdateQueryNode, DeleteQueryNode } from '../../ast/query.js';
+import { SelectQueryNode, InsertQueryNode, UpdateQueryNode, DeleteQueryNode, TableSourceNode, DerivedTableNode, FunctionTableNode } from '../../ast/query.js';
 import { ColumnNode } from '../../ast/expression.js';
-import { FunctionTableFormatter, FunctionTableNode } from './function-table-formatter.js';
+import { FunctionTableFormatter } from './function-table-formatter.js';
 import { PaginationStrategy, StandardLimitOffsetPagination } from './pagination-strategy.js';
 import { CteCompiler } from './cte-compiler.js';
 import { ReturningStrategy, NoReturningStrategy } from './returning-strategy.js';
@@ -63,11 +63,9 @@ export abstract class SqlDialectBase extends Dialect {
     return this.returningStrategy.compileReturning(returning, ctx);
   }
 
-  private compileInsertColumnList(columns: ColumnNode[]): string {
-    return columns
-      .map(column => `${this.quoteIdentifier(column.table)}.${this.quoteIdentifier(column.name)}`)
-      .join(', ');
-  }
+  private compileInsertColumnList(columns: ColumnNode[]): string {
+    return columns.map(column => this.quoteIdentifier(column.name)).join(', ');
+  }
 
   private compileInsertValues(values: any[][], ctx: CompilerContext): string {
     return values
@@ -99,15 +97,15 @@ export abstract class SqlDialectBase extends Dialect {
     assignments: { column: ColumnNode; value: any }[],
     ctx: CompilerContext
   ): string {
-    return assignments
-      .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(', ');
-  }
+    return assignments
+      .map(assignment => {
+        const col = assignment.column;
+        const target = this.quoteIdentifier(col.name);
+        const value = this.compileOperand(assignment.value, ctx);
+        return `${target} = ${value}`;
+      })
+      .join(', ');
+  }
 
   protected compileDeleteAst(ast: DeleteQueryNode, ctx: CompilerContext): string {
     const table = this.compileTableName(ast.from);
@@ -135,29 +133,49 @@ export abstract class SqlDialectBase extends Dialect {
     }).join(', ');
   }
 
-  protected compileFrom(ast: SelectQueryNode['from'], ctx?: CompilerContext): string {
-    const tableSource = ast as any;
-    if (tableSource.type === 'FunctionTable') {
-      return this.compileFunctionTable(tableSource, ctx);
-    }
-    return this.compileTableSource(tableSource);
-  }
-
-  protected compileFunctionTable(fn: FunctionTableNode, ctx?: CompilerContext): string {
-    return FunctionTableFormatter.format(fn, ctx, this);
-  }
-
-  protected compileTableSource(table: TableSourceNode): string {
-    const base = this.compileTableName(table);
-    return table.alias ? `${base} AS ${this.quoteIdentifier(table.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 compileFrom(ast: SelectQueryNode['from'], ctx?: CompilerContext): string {
+    const tableSource = ast as any;
+    if (tableSource.type === 'FunctionTable') {
+      return this.compileFunctionTable(tableSource, ctx);
+    }
+    if (tableSource.type === 'DerivedTable') {
+      return this.compileDerivedTable(tableSource, ctx);
+    }
+    return this.compileTableSource(tableSource);
+  }
+
+  protected compileFunctionTable(fn: FunctionTableNode, ctx?: CompilerContext): string {
+    return FunctionTableFormatter.format(fn, ctx, this);
+  }
+
+  protected compileDerivedTable(table: DerivedTableNode, ctx?: CompilerContext): string {
+    if (!table.alias) {
+      throw new Error('Derived tables must have an alias.');
+    }
+    const subquery = this.compileSelectAst(this.normalizeSelectAst(table.query), ctx!).trim().replace(/;$/, '');
+    const columns = table.columnAliases?.length
+      ? ` (${table.columnAliases.map(c => this.quoteIdentifier(c)).join(', ')})`
+      : '';
+    return `(${subquery}) AS ${this.quoteIdentifier(table.alias)}${columns}`;
+  }
+
+  protected compileTableSource(table: TableSourceNode): string {
+    if (table.type === 'FunctionTable') {
+      return this.compileFunctionTable(table as FunctionTableNode);
+    }
+    if (table.type === 'DerivedTable') {
+      return this.compileDerivedTable(table as DerivedTableNode);
+    }
+    const base = this.compileTableName(table);
+    return table.alias ? `${base} AS ${this.quoteIdentifier(table.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 compileHaving(ast: SelectQueryNode, ctx: CompilerContext): string {
     if (!ast.having) return '';
@@ -172,10 +190,4 @@ export abstract class SqlDialectBase extends Dialect {
     const trimmed = this.stripTrailingSemicolon(sql);
     return `(${trimmed})`;
   }
-}
-
-interface TableSourceNode {
-  name: string;
-  schema?: string;
-  alias?: string;
-}
+}

package/src/core/dialect/mssql/index.ts

@@ -1,7 +1,8 @@
 import { CompilerContext, Dialect } from '../abstract.js';
-import { SelectQueryNode, InsertQueryNode, UpdateQueryNode, DeleteQueryNode } from '../../ast/query.js';
-import { JsonPathNode } from '../../ast/expression.js';
-import { MssqlFunctionStrategy } from './functions.js';
+import { SelectQueryNode, InsertQueryNode, UpdateQueryNode, DeleteQueryNode, TableSourceNode, DerivedTableNode } from '../../ast/query.js';
+import { JsonPathNode } from '../../ast/expression.js';
+import { MssqlFunctionStrategy } from './functions.js';
+import { FunctionTableFormatter } from '../base/function-table-formatter.js';
 
 /**
  * Microsoft SQL Server dialect implementation
@@ -94,13 +95,16 @@ export class SqlServerDialect extends Dialect {
     return `UPDATE ${table} SET ${assignments}${whereClause};`;
   }
 
-  protected compileDeleteAst(ast: DeleteQueryNode, ctx: CompilerContext): string {
-    const table = this.quoteIdentifier(ast.from.name);
-    const whereClause = this.compileWhere(ast.where, ctx);
-    return `DELETE FROM ${table}${whereClause};`;
-  }
-
-  private compileSelectCore(ast: SelectQueryNode, ctx: CompilerContext): string {
+  protected compileDeleteAst(ast: DeleteQueryNode, ctx: CompilerContext): string {
+    if (ast.from.type !== 'Table') {
+      throw new Error('DELETE only supports base tables in the MSSQL dialect.');
+    }
+    const table = this.quoteIdentifier(ast.from.name);
+    const whereClause = this.compileWhere(ast.where, ctx);
+    return `DELETE FROM ${table}${whereClause};`;
+  }
+
+  private compileSelectCore(ast: SelectQueryNode, ctx: CompilerContext): string {
     const columns = ast.columns.map(c => {
       let expr = '';
       if (c.type === 'Function') {
@@ -119,15 +123,15 @@ export class SqlServerDialect extends Dialect {
       }
       return expr;
     }).join(', ');
-
-    const distinct = ast.distinct ? 'DISTINCT ' : '';
-    const from = `${this.quoteIdentifier(ast.from.name)}`;
-
-    const joins = ast.joins.map(j => {
-      const table = this.quoteIdentifier(j.table.name);
-      const cond = this.compileExpression(j.condition, ctx);
-      return `${j.kind} JOIN ${table} ON ${cond}`;
-    }).join(' ');
+
+    const distinct = ast.distinct ? 'DISTINCT ' : '';
+    const from = this.compileTableSource(ast.from, ctx);
+
+    const joins = ast.joins.map(j => {
+      const table = this.compileTableSource(j.table, ctx);
+      const cond = this.compileExpression(j.condition, ctx);
+      return `${j.kind} JOIN ${table} ON ${cond}`;
+    }).join(' ');
     const whereClause = this.compileWhere(ast.where, ctx);
 
     const groupBy = ast.groupBy && ast.groupBy.length > 0
@@ -155,19 +159,40 @@ export class SqlServerDialect extends Dialect {
       .join(', ');
   }
 
-  private compilePagination(ast: SelectQueryNode, orderBy: string): string {
-    const hasLimit = ast.limit !== undefined;
-    const hasOffset = ast.offset !== undefined;
-    if (!hasLimit && !hasOffset) return '';
+  private compilePagination(ast: SelectQueryNode, orderBy: string): string {
+    const hasLimit = ast.limit !== undefined;
+    const hasOffset = ast.offset !== undefined;
+    if (!hasLimit && !hasOffset) return '';
 
     const off = ast.offset ?? 0;
     const orderClause = orderBy || ' ORDER BY (SELECT NULL)';
     let pagination = `${orderClause} OFFSET ${off} ROWS`;
-    if (hasLimit) {
-      pagination += ` FETCH NEXT ${ast.limit} ROWS ONLY`;
-    }
-    return pagination;
-  }
+    if (hasLimit) {
+      pagination += ` FETCH NEXT ${ast.limit} ROWS ONLY`;
+    }
+    return pagination;
+  }
+
+  private compileTableSource(table: TableSourceNode, ctx: CompilerContext): string {
+    if (table.type === 'FunctionTable') {
+      return FunctionTableFormatter.format(table, ctx, this as any);
+    }
+    if (table.type === 'DerivedTable') {
+      return this.compileDerivedTable(table, ctx);
+    }
+    const base = table.schema
+      ? `${this.quoteIdentifier(table.schema)}.${this.quoteIdentifier(table.name)}`
+      : this.quoteIdentifier(table.name);
+    return table.alias ? `${base} AS ${this.quoteIdentifier(table.alias)}` : base;
+  }
+
+  private compileDerivedTable(table: DerivedTableNode, ctx: CompilerContext): string {
+    const sub = this.compileSelectAst(this.normalizeSelectAst(table.query), ctx).trim().replace(/;$/, '');
+    const cols = table.columnAliases?.length
+      ? ` (${table.columnAliases.map(c => this.quoteIdentifier(c)).join(', ')})`
+      : '';
+    return `(${sub}) AS ${this.quoteIdentifier(table.alias)}${cols}`;
+  }
 
   private compileCtes(ast: SelectQueryNode, ctx: CompilerContext): string {
     if (!ast.ctes || ast.ctes.length === 0) return '';