metal-orm 1.0.56 → 1.0.57

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

@@ -1,17 +1,7 @@
 import { CompilerContext } from '../abstract.js';
-import { OperandNode } from '../../ast/expression.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[];
-}
+import { OperandNode } from '../../ast/expression.js';
+import { FunctionTableNode } from '../../ast/query.js';
+import { SqlDialectBase } from './sql-dialect.js';
 
 /**
  * Formatter for function table expressions (e.g., LATERAL unnest(...) WITH ORDINALITY).
@@ -25,10 +15,10 @@ export class FunctionTableFormatter {
    * @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 {
+  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 base = this.formatBase(fn, schemaPart, args);
     const lateral = this.formatLateral(fn);
     const alias = this.formatAlias(fn, dialect);
     const colAliases = this.formatColumnAliases(fn, dialect);
@@ -76,11 +66,10 @@ export class FunctionTableFormatter {
    * @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}`;
-  }
+  private static formatBase(fn: FunctionTableNode, schemaPart: string, args: string): string {
+    const ordinality = fn.withOrdinality ? ' WITH ORDINALITY' : '';
+    return `${schemaPart}${fn.name}(${args})${ordinality}`;
+  }
 
   /**
    * Formats the LATERAL keyword if present.
@@ -121,13 +110,3 @@ export class FunctionTableFormatter {
   }
 }
 
-export interface FunctionTableNode {
-  type: 'FunctionTable';
-  schema?: string;
-  name: string;
-  args?: unknown[];
-  lateral?: boolean;
-  withOrdinality?: boolean;
-  alias?: string;
-  columnAliases?: string[];
-}

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

@@ -21,6 +21,11 @@ import { GroupByCompiler } from './groupby-compiler.js';
 import { OrderByCompiler } from './orderby-compiler.js';
 
 
+/**
+ * Base class for SQL dialects.
+ * Provides a common framework for compiling AST nodes into SQL strings.
+ * Specific dialects should extend this class and implement dialect-specific logic.
+ */
 export abstract class SqlDialectBase extends Dialect {
   abstract quoteIdentifier(id: string): string;
 
@@ -201,6 +206,25 @@ export abstract class SqlDialectBase extends Dialect {
   }
 
   protected compileFunctionTable(fn: FunctionTableNode, ctx?: CompilerContext): string {
+    const key = fn.key ?? fn.name;
+
+    if (ctx) {
+      const renderer = this.tableFunctionStrategy.getRenderer(key);
+      if (renderer) {
+        const compiledArgs = (fn.args ?? []).map(arg => this.compileOperand(arg, ctx));
+        return renderer({
+          node: fn,
+          compiledArgs,
+          compileOperand: operand => this.compileOperand(operand, ctx),
+          quoteIdentifier: this.quoteIdentifier.bind(this)
+        });
+      }
+
+      if (fn.key) {
+        throw new Error(`Table function "${key}" is not supported by dialect "${this.dialect}".`);
+      }
+    }
+
     return FunctionTableFormatter.format(fn, ctx, this);
   }
 

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

@@ -1,6 +1,10 @@
 import { StandardFunctionStrategy } from '../../functions/standard-strategy.js';
 import { LiteralNode } from '../../ast/expression.js';
 
+/**
+ * Microsoft SQL Server specific function strategy.
+ * Implements and overrides SQL function compilation rules for MSSQL.
+ */
 export class MssqlFunctionStrategy extends StandardFunctionStrategy {
     constructor() {
         super();
@@ -105,5 +109,39 @@ export class MssqlFunctionStrategy extends StandardFunctionStrategy {
             const withinGroup = orderClause ? ` WITHIN GROUP (${orderClause})` : '';
             return `STRING_AGG(${arg}, ${separator})${withinGroup}`;
         });
-    }
-}
+
+        this.add('LENGTH', ({ compiledArgs }) => `LEN(${compiledArgs[0]})`);
+        this.add('CHAR_LENGTH', ({ compiledArgs }) => `LEN(${compiledArgs[0]})`);
+        this.add('CHARACTER_LENGTH', ({ compiledArgs }) => `LEN(${compiledArgs[0]})`);
+        this.add('POSITION', ({ compiledArgs }) => `CHARINDEX(${compiledArgs[0]}, ${compiledArgs[1]})`);
+        this.add('LOCATE', ({ compiledArgs }) => compiledArgs.length === 3 ? `CHARINDEX(${compiledArgs[0]}, ${compiledArgs[1]}, ${compiledArgs[2]})` : `CHARINDEX(${compiledArgs[0]}, ${compiledArgs[1]})`);
+        this.add('INSTR', ({ compiledArgs }) => `CHARINDEX(${compiledArgs[1]}, ${compiledArgs[0]})`);
+        this.add('CHR', ({ compiledArgs }) => `CHAR(${compiledArgs[0]})`);
+
+        this.add('HOUR', ({ compiledArgs }) => `DATEPART(hour, ${compiledArgs[0]})`);
+        this.add('MINUTE', ({ compiledArgs }) => `DATEPART(minute, ${compiledArgs[0]})`);
+        this.add('SECOND', ({ compiledArgs }) => `DATEPART(second, ${compiledArgs[0]})`);
+        this.add('QUARTER', ({ compiledArgs }) => `DATEPART(quarter, ${compiledArgs[0]})`);
+
+        this.add('JSON_SET', ({ compiledArgs }) => {
+            if (compiledArgs.length !== 3) throw new Error('JSON_SET expects 3 arguments on SQL Server');
+            return `JSON_MODIFY(${compiledArgs[0]}, ${compiledArgs[1]}, ${compiledArgs[2]})`;
+        });
+
+        this.add('JSON_LENGTH', () => {
+            throw new Error('JSON_LENGTH is not supported on SQL Server');
+        });
+
+        this.add('JSON_ARRAYAGG', () => {
+            throw new Error('JSON_ARRAYAGG is not supported on SQL Server');
+        });
+
+        this.add('JSON_CONTAINS', () => {
+            throw new Error('JSON_CONTAINS is not supported on SQL Server');
+        });
+
+        this.add('ARRAY_APPEND', () => {
+            throw new Error('ARRAY_APPEND is not supported on SQL Server');
+        });
+    }
+}

package/src/core/dialect/mysql/functions.ts

@@ -1,6 +1,10 @@
 import { StandardFunctionStrategy } from '../../functions/standard-strategy.js';
 import { LiteralNode } from '../../ast/expression.js';
 
+/**
+ * MySQL/MariaDB specific function strategy.
+ * Implements and overrides SQL function compilation rules for MySQL.
+ */
 export class MysqlFunctionStrategy extends StandardFunctionStrategy {
     constructor() {
         super();
@@ -96,5 +100,15 @@ export class MysqlFunctionStrategy extends StandardFunctionStrategy {
             }
             return `DATE(${date})`;
         });
-    }
-}
+
+        this.add('HOUR', ({ compiledArgs }) => `HOUR(${compiledArgs[0]})`);
+        this.add('MINUTE', ({ compiledArgs }) => `MINUTE(${compiledArgs[0]})`);
+        this.add('SECOND', ({ compiledArgs }) => `SECOND(${compiledArgs[0]})`);
+        this.add('QUARTER', ({ compiledArgs }) => `QUARTER(${compiledArgs[0]})`);
+
+        this.add('ARRAY_APPEND', ({ compiledArgs }) => {
+            if (compiledArgs.length !== 2) throw new Error('ARRAY_APPEND expects 2 arguments (array, value)');
+            return `JSON_ARRAY_APPEND(${compiledArgs[0]}, '$', ${compiledArgs[1]})`;
+        });
+    }
+}

package/src/core/dialect/postgres/functions.ts

@@ -1,6 +1,10 @@
 import { StandardFunctionStrategy } from '../../functions/standard-strategy.js';
 import { LiteralNode } from '../../ast/expression.js';
 
+/**
+ * PostgreSQL specific function strategy.
+ * Implements and overrides SQL function compilation rules for PostgreSQL.
+ */
 export class PostgresFunctionStrategy extends StandardFunctionStrategy {
     constructor() {
         super();
@@ -99,5 +103,65 @@ export class PostgresFunctionStrategy extends StandardFunctionStrategy {
             const separator = ctx.compileOperand(separatorOperand);
             return `STRING_AGG(${arg}, ${separator}${orderSegment})`;
         });
-    }
-}
+
+        this.add('CHR', ({ compiledArgs }) => `CHR(${compiledArgs[0]})`);
+
+        this.add('HOUR', ({ compiledArgs }) => `EXTRACT(HOUR FROM ${compiledArgs[0]})`);
+        this.add('MINUTE', ({ compiledArgs }) => `EXTRACT(MINUTE FROM ${compiledArgs[0]})`);
+        this.add('SECOND', ({ compiledArgs }) => `EXTRACT(SECOND FROM ${compiledArgs[0]})`);
+        this.add('QUARTER', ({ compiledArgs }) => `EXTRACT(QUARTER FROM ${compiledArgs[0]})`);
+
+        this.add('JSON_LENGTH', ({ compiledArgs }) => {
+            if (compiledArgs.length !== 1) throw new Error('JSON_LENGTH expects 1 argument on PostgreSQL');
+            return `jsonb_array_length(${compiledArgs[0]})`;
+        });
+
+        this.add('JSON_ARRAYAGG', ({ compiledArgs }) => {
+            if (compiledArgs.length !== 1) throw new Error('JSON_ARRAYAGG expects 1 argument on PostgreSQL');
+            return `jsonb_agg(${compiledArgs[0]})`;
+        });
+
+        this.add('JSON_CONTAINS', ({ compiledArgs }) => {
+            if (compiledArgs.length !== 2) throw new Error('JSON_CONTAINS expects 2 arguments on PostgreSQL');
+            return `(${compiledArgs[0]}::jsonb @> ${compiledArgs[1]}::jsonb)`;
+        });
+
+        this.add('ARRAY_APPEND', ({ compiledArgs }) => {
+            if (compiledArgs.length !== 2) throw new Error('ARRAY_APPEND expects 2 arguments on PostgreSQL');
+            return `array_append(${compiledArgs[0]}, ${compiledArgs[1]})`;
+        });
+
+        this.add('JSON_SET', ({ node, compiledArgs }) => {
+            if (compiledArgs.length !== 3) throw new Error('JSON_SET expects exactly 3 arguments on PostgreSQL');
+            const pathNode = node.args[1];
+            if (pathNode.type !== 'Literal') {
+                throw new Error('PostgreSQL JSON_SET currently supports literal paths only');
+            }
+            const pathArray = this.formatJsonbPathArray(pathNode);
+            return `jsonb_set(${compiledArgs[0]}, ${pathArray}, ${compiledArgs[2]}::jsonb, true)`;
+        });
+    }
+
+    private formatJsonbPathArray(pathNode: LiteralNode): string {
+        const rawPath = String(pathNode.value ?? '');
+        if (!rawPath.startsWith('$')) {
+            throw new Error('PostgreSQL JSON_SET paths must start with "$"');
+        }
+        const trimmed = rawPath === '$' ? '' : rawPath.startsWith('$.') ? rawPath.slice(2) : rawPath.slice(1);
+        if (!trimmed) {
+            throw new Error('PostgreSQL JSON_SET requires a non-root path');
+        }
+        if (trimmed.includes('[') || trimmed.includes(']')) {
+            throw new Error('PostgreSQL JSON_SET currently only supports simple dot-separated paths');
+        }
+        const segments = trimmed
+            .split('.')
+            .map(segment => segment.replace(/^['"]?/, '').replace(/['"]?$/, '').trim())
+            .filter(Boolean);
+        if (!segments.length) {
+            throw new Error('PostgreSQL JSON_SET requires at least one path segment');
+        }
+        const escapedSegments = segments.map(segment => `'${segment.replace(/'/g, "''")}'`);
+        return `ARRAY[${escapedSegments.join(', ')}]`;
+    }
+}

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

@@ -1,7 +1,8 @@
 import { CompilerContext } from '../abstract.js';
-import { JsonPathNode, ColumnNode } from '../../ast/expression.js';
-import { SqlDialectBase } from '../base/sql-dialect.js';
-import { PostgresFunctionStrategy } from './functions.js';
+import { JsonPathNode, ColumnNode, BitwiseExpressionNode } from '../../ast/expression.js';
+import { SqlDialectBase } from '../base/sql-dialect.js';
+import { PostgresFunctionStrategy } from './functions.js';
+import { PostgresTableFunctionStrategy } from './table-functions.js';
 
 /**
  * PostgreSQL dialect implementation
@@ -12,7 +13,19 @@ export class PostgresDialect extends SqlDialectBase {
    * Creates a new PostgresDialect instance
    */
   public constructor() {
-    super(new PostgresFunctionStrategy());
+    super(new PostgresFunctionStrategy(), new PostgresTableFunctionStrategy());
+    this.registerExpressionCompiler('BitwiseExpression', (node: BitwiseExpressionNode, ctx) => {
+      const left = this.compileOperand(node.left, ctx);
+      const right = this.compileOperand(node.right, ctx);
+      const op = node.operator === '^' ? '#' : node.operator;
+      return `${left} ${op} ${right}`;
+    });
+    this.registerOperandCompiler('BitwiseExpression', (node: BitwiseExpressionNode, ctx) => {
+      const left = this.compileOperand(node.left, ctx);
+      const right = this.compileOperand(node.right, ctx);
+      const op = node.operator === '^' ? '#' : node.operator;
+      return `(${left} ${op} ${right})`;
+    });
   }
 
   /**

package/src/core/dialect/postgres/table-functions.ts

@@ -0,0 +1,27 @@
+import { StandardTableFunctionStrategy } from '../../functions/standard-table-strategy.js';
+
+export class PostgresTableFunctionStrategy extends StandardTableFunctionStrategy {
+  constructor() {
+    super();
+    this.registerOverrides();
+  }
+
+  private registerOverrides() {
+    this.add('ARRAY_UNNEST', ({ node, compiledArgs, quoteIdentifier }) => {
+      const lateral = node.lateral ?? true;
+      const withOrd = node.withOrdinality ?? false;
+      const base = `unnest(${compiledArgs.join(', ')})${withOrd ? ' WITH ORDINALITY' : ''}`;
+
+      if (node.columnAliases?.length && !node.alias) {
+        throw new Error('tvf(ARRAY_UNNEST) with columnAliases requires an alias.');
+      }
+
+      const alias = node.alias ? ` AS ${quoteIdentifier(node.alias)}` : '';
+      const cols = node.columnAliases?.length
+        ? `(${node.columnAliases.map(quoteIdentifier).join(', ')})`
+        : '';
+
+      return `${lateral ? 'LATERAL ' : ''}${base}${alias}${cols}`;
+    });
+  }
+}

package/src/core/dialect/sqlite/functions.ts

@@ -1,6 +1,10 @@
 import { StandardFunctionStrategy } from '../../functions/standard-strategy.js';
 import { LiteralNode } from '../../ast/expression.js';
 
+/**
+ * SQLite specific function strategy.
+ * Implements and overrides SQL function compilation rules for SQLite.
+ */
 export class SqliteFunctionStrategy extends StandardFunctionStrategy {
     constructor() {
         super();
@@ -117,5 +121,35 @@ export class SqliteFunctionStrategy extends StandardFunctionStrategy {
             const separator = ctx.compileOperand(separatorOperand);
             return `GROUP_CONCAT(${arg}, ${separator})`;
         });
+
+        this.add('HOUR', ({ compiledArgs }) => `CAST(strftime('%H', ${compiledArgs[0]}) AS INTEGER)`);
+        this.add('MINUTE', ({ compiledArgs }) => `CAST(strftime('%M', ${compiledArgs[0]}) AS INTEGER)`);
+        this.add('SECOND', ({ compiledArgs }) => `CAST(strftime('%S', ${compiledArgs[0]}) AS INTEGER)`);
+        this.add('QUARTER', ({ compiledArgs }) => `((CAST(strftime('%m', ${compiledArgs[0]}) AS INTEGER) + 2) / 3)`);
+
+        this.add('JSON_LENGTH', ({ compiledArgs }) => {
+            if (compiledArgs.length === 0 || compiledArgs.length > 2) {
+                throw new Error('JSON_LENGTH expects 1 or 2 arguments on SQLite');
+            }
+            return `json_array_length(${compiledArgs.join(', ')})`;
+        });
+
+        this.add('JSON_ARRAYAGG', ({ compiledArgs }) => {
+            if (compiledArgs.length !== 1) {
+                throw new Error('JSON_ARRAYAGG expects 1 argument on SQLite');
+            }
+            return `json_group_array(${compiledArgs[0]})`;
+        });
+
+        this.add('JSON_CONTAINS', () => {
+            throw new Error('JSON_CONTAINS is not supported on SQLite');
+        });
+
+        this.add('ARRAY_APPEND', ({ compiledArgs }) => {
+            if (compiledArgs.length !== 2) throw new Error('ARRAY_APPEND expects 2 arguments (array, value)');
+            return `json_array_append(${compiledArgs[0]}, '$', ${compiledArgs[1]})`;
+        });
+
+        this.add('CHR', ({ compiledArgs }) => `CHAR(${compiledArgs[0]})`);
     }
 }

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

@@ -1,5 +1,5 @@
 import { CompilerContext } from '../abstract.js';
-import { JsonPathNode, ColumnNode } from '../../ast/expression.js';
+import { JsonPathNode, ColumnNode, BitwiseExpressionNode } from '../../ast/expression.js';
 import { TableNode } from '../../ast/query.js';
 import { SqlDialectBase } from '../base/sql-dialect.js';
 import { SqliteFunctionStrategy } from './functions.js';
@@ -14,6 +14,22 @@ export class SqliteDialect extends SqlDialectBase {
    */
   public constructor() {
     super(new SqliteFunctionStrategy());
+    this.registerExpressionCompiler('BitwiseExpression', (node: BitwiseExpressionNode, ctx) => {
+      const left = this.compileOperand(node.left, ctx);
+      const right = this.compileOperand(node.right, ctx);
+      if (node.operator === '^') {
+        return `(${left} | ${right}) & ~(${left} & ${right})`;
+      }
+      return `${left} ${node.operator} ${right}`;
+    });
+    this.registerOperandCompiler('BitwiseExpression', (node: BitwiseExpressionNode, ctx) => {
+      const left = this.compileOperand(node.left, ctx);
+      const right = this.compileOperand(node.right, ctx);
+      if (node.operator === '^') {
+        return `((${left} | ${right}) & ~(${left} & ${right}))`;
+      }
+      return `(${left} ${node.operator} ${right})`;
+    });
   }
 
   /**

package/src/core/driver/database-driver.ts

@@ -2,10 +2,18 @@ import type { Dialect } from '../dialect/abstract.js';
 import type { SchemaDialect } from '../ddl/schema-dialect.js';
 import type { SchemaIntrospector } from '../ddl/schema-introspect.js';
 
+/**
+ * Interface for database drivers.
+ * A driver provides access to dialect-specific compilers and introspectors.
+ */
 export interface DatabaseDriver {
-  readonly name: string; // e.g. "postgres"
+  /** The name of the driver (e.g., "postgres", "mysql"). */
+  readonly name: string;
 
+  /** Creates a query compiler dialect. */
   createDialect(): Dialect;
+  /** Creates a DDL/schema dialect. */
   createSchemaDialect(): SchemaDialect;
+  /** Creates a schema introspector. */
   createIntrospector(): SchemaIntrospector;
 }

package/src/core/driver/mssql-driver.ts

@@ -3,6 +3,9 @@ import { SqlServerDialect } from '../dialect/mssql/index.js';
 import { MSSqlSchemaDialect } from '../ddl/dialects/mssql-schema-dialect.js';
 import { mssqlIntrospector } from '../ddl/introspect/mssql.js';
 
+/**
+ * Database driver for Microsoft SQL Server.
+ */
 export class MssqlDriver implements DatabaseDriver {
   readonly name = 'mssql';
 

package/src/core/driver/mysql-driver.ts

@@ -3,6 +3,9 @@ import { MySqlDialect } from '../dialect/mysql/index.js';
 import { MySqlSchemaDialect } from '../ddl/dialects/mysql-schema-dialect.js';
 import { mysqlIntrospector } from '../ddl/introspect/mysql.js';
 
+/**
+ * Database driver for MySQL.
+ */
 export class MySqlDriver implements DatabaseDriver {
   readonly name = 'mysql';
 

package/src/core/driver/postgres-driver.ts

@@ -3,6 +3,9 @@ import { PostgresDialect } from '../dialect/postgres/index.js';
 import { PostgresSchemaDialect } from '../ddl/dialects/postgres-schema-dialect.js';
 import { postgresIntrospector } from '../ddl/introspect/postgres.js';
 
+/**
+ * Database driver for PostgreSQL.
+ */
 export class PostgresDriver implements DatabaseDriver {
   readonly name = 'postgres';
 

package/src/core/driver/sqlite-driver.ts

@@ -3,6 +3,9 @@ import { SqliteDialect } from '../dialect/sqlite/index.js';
 import { SQLiteSchemaDialect } from '../ddl/dialects/sqlite-schema-dialect.js';
 import { sqliteIntrospector } from '../ddl/introspect/sqlite.js';
 
+/**
+ * Database driver for SQLite.
+ */
 export class SqliteDriver implements DatabaseDriver {
   readonly name = 'sqlite';
 

package/src/core/execution/executors/mssql-executor.ts

@@ -14,6 +14,11 @@ export interface MssqlClientLike {
   rollback?(): Promise<void>;
 }
 
+/**
+ * Creates a database executor for Microsoft SQL Server.
+ * @param client A SQL Server client instance.
+ * @returns A DbExecutor implementation for MSSQL.
+ */
 export function createMssqlExecutor(
   client: MssqlClientLike
 ): DbExecutor {

package/src/core/execution/executors/mysql-executor.ts

@@ -14,6 +14,11 @@ export interface MysqlClientLike {
   rollback?(): Promise<void>;
 }
 
+/**
+ * Creates a database executor for MySQL.
+ * @param client A MySQL client instance.
+ * @returns A DbExecutor implementation for MySQL.
+ */
 export function createMysqlExecutor(
   client: MysqlClientLike
 ): DbExecutor {

package/src/core/execution/executors/postgres-executor.ts

@@ -11,6 +11,11 @@ export interface PostgresClientLike {
   ): Promise<{ rows: Array<Record<string, unknown>> }>;
 }
 
+/**
+ * Creates a database executor for PostgreSQL.
+ * @param client A PostgreSQL client or pool instance.
+ * @returns A DbExecutor implementation for Postgres.
+ */
 export function createPostgresExecutor(
   client: PostgresClientLike
 ): DbExecutor {

package/src/core/execution/executors/sqlite-executor.ts

@@ -15,6 +15,11 @@ export interface SqliteClientLike {
   rollbackTransaction?(): Promise<void>;
 }
 
+/**
+ * Creates a database executor for SQLite.
+ * @param client A SQLite client instance.
+ * @returns A DbExecutor implementation for SQLite.
+ */
 export function createSqliteExecutor(
   client: SqliteClientLike
 ): DbExecutor {

package/src/core/functions/array.ts

@@ -0,0 +1,26 @@
+// Pure AST Builders - No Dialect Logic Here!
+
+import { ColumnDef } from '../../schema/column-types.js';
+import { columnOperand, valueToOperand } from '../ast/expression-builders.js';
+import { FunctionNode, OperandNode, isOperandNode } from '../ast/expression.js';
+
+type OperandInput = OperandNode | ColumnDef | string | number | boolean | null;
+
+const isColumnDef = (val: unknown): val is ColumnDef => !!val && typeof val === 'object' && 'type' in val && 'name' in val;
+
+const toOperand = (input: OperandInput): OperandNode => {
+    if (isOperandNode(input)) return input;
+    if (isColumnDef(input)) return columnOperand(input);
+
+    return valueToOperand(input);
+};
+
+const fn = (key: string, args: OperandInput[]): FunctionNode => ({
+    type: 'Function',
+    name: key,
+    fn: key,
+    args: args.map(toOperand)
+});
+
+export const arrayAppend = (array: OperandInput, value: OperandInput): FunctionNode =>
+    fn('ARRAY_APPEND', [array, value]);

package/src/core/functions/control-flow.ts

@@ -0,0 +1,69 @@
+// Pure AST Builders - No Dialect Logic Here!
+
+import { ColumnDef } from '../../schema/column-types.js';
+import { columnOperand, valueToOperand } from '../ast/expression-builders.js';
+import { FunctionNode, OperandNode, isOperandNode } from '../ast/expression.js';
+
+type OperandInput = OperandNode | ColumnDef | string | number | boolean | null;
+
+const isColumnDef = (val: unknown): val is ColumnDef => !!val && typeof val === 'object' && 'type' in val && 'name' in val;
+
+const toOperand = (input: OperandInput): OperandNode => {
+  if (isOperandNode(input)) return input;
+  if (isColumnDef(input)) return columnOperand(input);
+
+  return valueToOperand(input);
+};
+
+const fn = (key: string, args: OperandInput[]): FunctionNode => ({
+  type: 'Function',
+  name: key,
+  fn: key,
+  args: args.map(toOperand)
+});
+
+/**
+ * Returns the first non-null value in a list.
+ * @param args - The list of values to check.
+ * @returns A FunctionNode representing the COALESCE SQL function.
+ */
+export const coalesce = (...args: OperandInput[]): FunctionNode => {
+  if (args.length < 2) throw new Error('coalesce() expects at least 2 arguments');
+  return fn('COALESCE', args);
+};
+
+/**
+ * Returns null if the two arguments are equal, otherwise returns the first argument.
+ * @param val1 - The first value.
+ * @param val2 - The second value.
+ * @returns A FunctionNode representing the NULLIF SQL function.
+ */
+export const nullif = (val1: OperandInput, val2: OperandInput): FunctionNode => fn('NULLIF', [val1, val2]);
+
+/**
+ * Returns the largest value in a list.
+ * @param args - The list of values to compare.
+ * @returns A FunctionNode representing the GREATEST SQL function.
+ */
+export const greatest = (...args: OperandInput[]): FunctionNode => {
+  if (args.length < 2) throw new Error('greatest() expects at least 2 arguments');
+  return fn('GREATEST', args);
+};
+
+/**
+ * Returns the smallest value in a list.
+ * @param args - The list of values to compare.
+ * @returns A FunctionNode representing the LEAST SQL function.
+ */
+export const least = (...args: OperandInput[]): FunctionNode => {
+  if (args.length < 2) throw new Error('least() expects at least 2 arguments');
+  return fn('LEAST', args);
+};
+
+/**
+ * Returns the first argument if it is not null, otherwise returns the second argument.
+ * @param val - The value to check.
+ * @param defaultValue - The default value to return if val is null.
+ * @returns A FunctionNode representing the COALESCE SQL function.
+ */
+export const ifNull = (val: OperandInput, defaultValue: OperandInput): FunctionNode => coalesce(val, defaultValue);