metal-orm 1.0.16 → 1.0.18

package/src/core/ast/aggregate-functions.ts

@@ -1,6 +1,8 @@
 import { ColumnNode, FunctionNode } from './expression-nodes.js';
-import { columnOperand } from './expression-builders.js';
+import { columnOperand, valueToOperand, ValueOperandInput } from './expression-builders.js';
 import { ColumnRef } from './types.js';
+import { OrderByNode } from './query.js';
+import { ORDER_DIRECTIONS, OrderDirection } from '../sql/sql.js';
 
 const buildAggregate = (name: string) => (col: ColumnRef | ColumnNode): FunctionNode => ({
   type: 'Function',
@@ -25,6 +27,50 @@ export const sum = buildAggregate('SUM');
 /**
  * Creates an AVG function expression
  * @param col - Column to average
- * @returns Function node with AVG
- */
-export const avg = buildAggregate('AVG');
+ * @returns Function node with AVG
+ */
+export const avg = buildAggregate('AVG');
+
+/**
+ * Creates a MIN function expression
+ * @param col - Column to take the minimum of
+ * @returns Function node with MIN
+ */
+export const min = buildAggregate('MIN');
+
+/**
+ * Creates a MAX function expression
+ * @param col - Column to take the maximum of
+ * @returns Function node with MAX
+ */
+export const max = buildAggregate('MAX');
+
+type GroupConcatOrderByInput = {
+  column: ColumnRef | ColumnNode;
+  direction?: OrderDirection;
+};
+
+export type GroupConcatOptions = {
+  separator?: ValueOperandInput;
+  orderBy?: GroupConcatOrderByInput[];
+};
+
+const toOrderByNode = (order: GroupConcatOrderByInput): OrderByNode => ({
+  type: 'OrderBy',
+  column: columnOperand(order.column),
+  direction: order.direction ?? ORDER_DIRECTIONS.ASC
+});
+
+/**
+ * Aggregates grouped strings into a single value.
+ */
+export const groupConcat = (
+  col: ColumnRef | ColumnNode,
+  options?: GroupConcatOptions
+): FunctionNode => ({
+  type: 'Function',
+  name: 'GROUP_CONCAT',
+  args: [columnOperand(col)],
+  orderBy: options?.orderBy?.map(toOrderByNode),
+  separator: options?.separator !== undefined ? valueToOperand(options.separator) : undefined
+});

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

@@ -19,22 +19,23 @@ import {
   isOperandNode
 } from './expression-nodes.js';
 
+export type LiteralValue = LiteralNode['value'];
+export type ValueOperandInput = OperandNode | LiteralValue;
+
 /**
  * Converts a primitive or existing operand into an operand node
  * @param value - Value or operand to normalize
  * @returns OperandNode representing the value
  */
-export const valueToOperand = (value: unknown): OperandNode => {
-  if (
-    value === null ||
-    value === undefined ||
-    typeof value === 'string' ||
-    typeof value === 'number' ||
-    typeof value === 'boolean'
-  ) {
-    return { type: 'Literal', value: value === undefined ? null : value } as LiteralNode;
+export const valueToOperand = (value: ValueOperandInput): OperandNode => {
+  if (isOperandNode(value)) {
+    return value;
   }
-  return value as OperandNode;
+
+  return {
+    type: 'Literal',
+    value
+  } as LiteralNode;
 };
 
 const toNode = (col: ColumnRef | OperandNode): OperandNode => {
@@ -48,15 +49,34 @@ const toLiteralNode = (value: string | number | boolean | null): LiteralNode =>
   value
 });
 
-const toOperand = (val: OperandNode | ColumnRef | string | number | boolean | null): OperandNode => {
-  if (val === null) return { type: 'Literal', value: null };
-  if (typeof val === 'string' || typeof val === 'number' || typeof val === 'boolean') {
-    return { type: 'Literal', value: val };
+const isLiteralValue = (value: unknown): value is LiteralValue =>
+  value === null || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean';
+
+export const isValueOperandInput = (value: unknown): value is ValueOperandInput =>
+  isOperandNode(value) || isLiteralValue(value);
+
+const toOperand = (val: OperandNode | ColumnRef | LiteralValue): OperandNode => {
+  if (isLiteralValue(val)) {
+    return valueToOperand(val);
   }
-  return toNode(val as OperandNode | ColumnRef);
+
+  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
@@ -37,6 +39,12 @@ export interface FunctionNode {
   args: OperandNode[];
   /** Optional alias for the function result */
   alias?: string;
+  /** Optional ORDER BY clause used by aggregations like GROUP_CONCAT */
+  orderBy?: OrderByNode[];
+  /** Optional separator argument used by GROUP_CONCAT-like functions */
+  separator?: OperandNode;
+  /** Optional DISTINCT modifier */
+  distinct?: boolean;
 }
 
 /**

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/ddl/introspect/functions/postgres.ts

@@ -1,14 +1,10 @@
 // Small helpers to build Postgres-specific function calls as AST FunctionNodes
-import { columnOperand, valueToOperand } from '../../../ast/expression-builders.js';
+import { valueToOperand } from '../../../ast/expression-builders.js';
 import type { OperandNode, FunctionNode } from '../../../ast/expression.js';
 
 type OperandInput = OperandNode | string | number | boolean | null;
 
-const toOperand = (v: OperandInput) => {
-  if (v === null) return valueToOperand(null);
-  if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') return valueToOperand(v);
-  return v as OperandNode;
-};
+const toOperand = (v: OperandInput): OperandNode => valueToOperand(v);
 
 const fn = (name: string, args: OperandInput[]): FunctionNode => ({
   type: 'Function',

package/src/core/dialect/abstract.ts

@@ -476,12 +476,16 @@ export abstract class Dialect
   /**
    * Compiles a function operand, using the dialect's function strategy.
    */
-  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 });
-    }
-    return `${fnNode.name}(${compiledArgs.join(', ')})`;
-  }
+  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(', ')})`;
+  }
 }

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;
-}
+}