metal-orm 1.0.14 → 1.0.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metal-orm",
-  "version": "1.0.14",
+  "version": "1.0.16",
   "type": "module",
   "exports": {
     ".": {

package/src/codegen/naming-strategy.ts

@@ -0,0 +1,64 @@
+import type { TableNode, FunctionTableNode } from '../core/ast/query.js';
+import type { ColumnNode } from '../core/ast/expression.js';
+
+/**
+ * Strategy interface for converting database names to TypeScript identifiers
+ */
+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;
+
+  /**
+   * Converts a column reference to a property name
+   * @param column - Column node
+   * @returns Valid TypeScript property name
+   */
+  columnToProperty(column: ColumnNode): string;
+}
+
+/**
+ * Default naming strategy that maintains backward compatibility
+ * with the original capitalize() behavior
+ */
+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;
+
+    // Handle schema-qualified names (e.g., "auth.user" → "AuthUser")
+    if (tableName.includes('.')) {
+      return tableName.split('.')
+        .map(part => this.capitalize(part))
+        .join('');
+    }
+
+    return this.capitalize(tableName);
+  }
+
+  /**
+   * Converts column references to property names
+   * @param column - Column node
+   * @returns Column name as-is (for backward compatibility)
+   */
+  columnToProperty(column: ColumnNode): string {
+    return column.name;
+  }
+
+  /**
+   * Capitalizes the first letter of a string
+   * @param s - String to capitalize
+   * @returns Capitalized string
+   */
+  private capitalize(s: string): string {
+    if (!s) return s;
+    return s.charAt(0).toUpperCase() + s.slice(1);
+  }
+}

package/src/codegen/typescript.ts

@@ -23,13 +23,9 @@ import {
 import { SQL_OPERATOR_REGISTRY } from '../core/sql/sql-operator-config.js';
 import { SqlOperator } from '../core/sql/sql.js';
 import { isRelationAlias } from '../query-builder/relation-alias.js';
-
-/**
- * Capitalizes the first letter of a string
- * @param s - String to capitalize
- * @returns Capitalized string
- */
-const capitalize = (s: string) => s.charAt(0).toUpperCase() + s.slice(1);
+import { HydrationMetadata } from '../core/hydration/types.js';
+import { getJoinRelationName } from '../core/ast/join-metadata.js';
+import { NamingStrategy, DefaultNamingStrategy } from './naming-strategy.js';
 
 const assertNever = (value: never): never => {
   throw new Error(`Unhandled SQL operator: ${value}`);
@@ -39,6 +35,7 @@ const assertNever = (value: never): never => {
  * Generates TypeScript code from query AST nodes
  */
 export class TypeScriptGenerator implements ExpressionVisitor<string>, OperandVisitor<string> {
+  constructor(private namingStrategy: NamingStrategy = new DefaultNamingStrategy()) {}
 
   /**
    * Generates TypeScript code from a query AST
@@ -59,7 +56,7 @@ export class TypeScriptGenerator implements ExpressionVisitor<string>, OperandVi
    */
   private buildSelectLines(ast: SelectQueryNode): string[] {
     const lines: string[] = [];
-    const hydration = ast.meta?.hydration;
+    const hydration = (ast.meta as HydrationMetadata | undefined)?.hydration;
     const hydratedRelations = new Set(hydration?.relations?.map(r => r.name) ?? []);
 
     const selections = ast.columns
@@ -75,26 +72,27 @@ export class TypeScriptGenerator implements ExpressionVisitor<string>, OperandVi
       lines.push(`  ${sel}${index < selections.length - 1 ? ',' : ''}`);
     });
     lines.push(`})`);
-    lines.push(`.from(${capitalize(ast.from.name)})`);
+    lines.push(`.from(${this.namingStrategy.tableToSymbol(ast.from)})`);
 
     if (ast.distinct && ast.distinct.length) {
-      const cols = ast.distinct.map(c => `${capitalize(c.table)}.${c.name}`).join(', ');
+      const cols = ast.distinct.map(c => `${this.namingStrategy.tableToSymbol(c.table)}.${c.name}`).join(', ');
       lines.push(`.distinct(${cols})`);
     }
 
     ast.joins.forEach(join => {
-      if (join.relationName && hydratedRelations.has(join.relationName)) {
+      const relationName = getJoinRelationName(join);
+      if (relationName && hydratedRelations.has(relationName)) {
         return;
       }
 
-      if (join.relationName) {
+      if (relationName) {
         if (join.kind === 'INNER') {
-          lines.push(`.joinRelation('${join.relationName}')`);
+          lines.push(`.joinRelation('${relationName}')`);
         } else {
-          lines.push(`.joinRelation('${join.relationName}', '${join.kind}')`);
+          lines.push(`.joinRelation('${relationName}', '${join.kind}')`);
         }
       } else {
-        const table = capitalize(join.table.name);
+        const table = this.namingStrategy.tableToSymbol(join.table);
         const cond = this.printExpression(join.condition);
         let method = 'innerJoin';
         if (join.kind === 'LEFT') method = 'leftJoin';
@@ -118,7 +116,7 @@ export class TypeScriptGenerator implements ExpressionVisitor<string>, OperandVi
     }
 
     if (ast.groupBy && ast.groupBy.length) {
-      const cols = ast.groupBy.map(c => `${capitalize(c.table)}.${c.name}`).join(', ');
+      const cols = ast.groupBy.map(c => `${this.namingStrategy.tableToSymbol(c.table)}.${c.name}`).join(', ');
       lines.push(`.groupBy(${cols})`);
     }
 
@@ -128,7 +126,7 @@ export class TypeScriptGenerator implements ExpressionVisitor<string>, OperandVi
 
     if (ast.orderBy && ast.orderBy.length) {
       ast.orderBy.forEach(o => {
-        lines.push(`.orderBy(${capitalize(o.column.table)}.${o.column.name}, '${o.direction}')`);
+        lines.push(`.orderBy(${this.namingStrategy.tableToSymbol(o.column.table)}.${o.column.name}, '${o.direction}')`);
       });
     }
 
@@ -289,7 +287,7 @@ export class TypeScriptGenerator implements ExpressionVisitor<string>, OperandVi
    * @returns TypeScript code representation
    */
   private printColumnOperand(column: ColumnNode): string {
-    return `${capitalize(column.table)}.${column.name}`;
+    return `${this.namingStrategy.tableToSymbol(column.table)}.${column.name}`;
   }
 
   /**
@@ -318,7 +316,7 @@ export class TypeScriptGenerator implements ExpressionVisitor<string>, OperandVi
    * @returns TypeScript code representation
    */
   private printJsonPathOperand(json: JsonPathNode): string {
-    return `jsonPath(${capitalize(json.column.table)}.${json.column.name}, '${json.path}')`;
+    return `jsonPath(${this.namingStrategy.tableToSymbol(json.column.table)}.${json.column.name}, '${json.path}')`;
   }
 
   /**
@@ -361,14 +359,14 @@ export class TypeScriptGenerator implements ExpressionVisitor<string>, OperandVi
 
     if (node.partitionBy && node.partitionBy.length > 0) {
       const partitionClause =
-        'PARTITION BY ' + node.partitionBy.map(col => `${capitalize(col.table)}.${col.name}`).join(', ');
+        'PARTITION BY ' + node.partitionBy.map(col => `${this.namingStrategy.tableToSymbol(col.table)}.${col.name}`).join(', ');
       parts.push(partitionClause);
     }
 
     if (node.orderBy && node.orderBy.length > 0) {
       const orderClause =
         'ORDER BY ' +
-        node.orderBy.map(o => `${capitalize(o.column.table)}.${o.column.name} ${o.direction}`).join(', ');
+        node.orderBy.map(o => `${this.namingStrategy.tableToSymbol(o.column.table)}.${o.column.name} ${o.direction}`).join(', ');
       parts.push(orderClause);
     }
 

package/src/core/ast/adapters.ts

@@ -0,0 +1,21 @@
+import { ColumnDef } from '../../schema/column.js';
+import { TableDef } from '../../schema/table.js';
+import { ColumnRef, TableRef } from './types.js';
+
+/**
+ * Adapts a schema ColumnDef to an AST-friendly ColumnRef.
+ */
+export const toColumnRef = (col: ColumnRef | ColumnDef): ColumnRef => ({
+  name: col.name,
+  table: col.table,
+  alias: (col as ColumnRef).alias
+});
+
+/**
+ * Adapts a schema TableDef to an AST-friendly TableRef.
+ */
+export const toTableRef = (table: TableRef | TableDef): TableRef => ({
+  name: table.name,
+  schema: table.schema,
+  alias: (table as TableRef).alias
+});

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

@@ -1,12 +1,12 @@
-import { ColumnDef } from '../../schema/column.js';
-import { ColumnNode, FunctionNode } from './expression-nodes.js';
-import { columnOperand } from './expression-builders.js';
-
-const buildAggregate = (name: string) => (col: ColumnDef | ColumnNode): FunctionNode => ({
-  type: 'Function',
-  name,
-  args: [columnOperand(col)]
-});
+import { ColumnNode, FunctionNode } from './expression-nodes.js';
+import { columnOperand } from './expression-builders.js';
+import { ColumnRef } from './types.js';
+
+const buildAggregate = (name: string) => (col: ColumnRef | ColumnNode): FunctionNode => ({
+  type: 'Function',
+  name,
+  args: [columnOperand(col)]
+});
 
 /**
  * Creates a COUNT function expression
@@ -17,10 +17,10 @@ export const count = buildAggregate('COUNT');
 
 /**
  * Creates a SUM function expression
- * @param col - Column to sum
- * @returns Function node with SUM
- */
-export const sum = buildAggregate('SUM');
+ * @param col - Column to sum
+ * @returns Function node with SUM
+ */
+export const sum = buildAggregate('SUM');
 
 /**
  * Creates an AVG function expression

package/src/core/ast/builders.ts

@@ -1,43 +1,56 @@
-import { ColumnDef } from '../../schema/column.js';
-import { TableDef } from '../../schema/table.js';
-import { ColumnNode } from './expression-nodes.js';
-import { TableNode } from './query.js';
-
-/**
- * Builds or normalizes a column AST node from a column definition or existing node
- * @param table - Table definition providing a default table name
- * @param column - Column definition or existing column node
- */
-export const buildColumnNode = (table: TableDef, column: ColumnDef | ColumnNode): ColumnNode => {
-  if ((column as ColumnNode).type === 'Column') {
-    return column as ColumnNode;
-  }
-
-  const def = column as ColumnDef;
-  return {
-    type: 'Column',
-    table: def.table || table.name,
-    name: def.name
-  };
-};
-
-/**
- * Builds column AST nodes for a list of column names
- * @param table - Table definition providing the table name
- * @param names - Column names
- */
-export const buildColumnNodes = (table: TableDef, names: string[]): ColumnNode[] =>
-  names.map(name => ({
-    type: 'Column',
-    table: table.name,
-    name
-  }));
-
-/**
- * Builds a table AST node for the provided table definition
- * @param table - Table definition
- */
-export const createTableNode = (table: TableDef): TableNode => ({
-  type: 'Table',
-  name: table.name
-});
+import { ColumnNode } from './expression-nodes.js';
+import { TableNode, FunctionTableNode } from './query.js';
+import { ColumnRef, TableRef } from './types.js';
+
+/**
+ * Builds or normalizes a column AST node from a column definition or existing node
+ * @param table - Table definition providing a default table name
+ * @param column - Column definition or existing column node
+ */
+export const buildColumnNode = (table: TableRef, column: ColumnRef | ColumnNode): ColumnNode => {
+  if ((column as ColumnNode).type === 'Column') {
+    return column as ColumnNode;
+  }
+
+  const def = column as ColumnRef;
+  return {
+    type: 'Column',
+    table: def.table || table.name,
+    name: def.name
+  };
+};
+
+/**
+ * Builds column AST nodes for a list of column names
+ * @param table - Table definition providing the table name
+ * @param names - Column names
+ */
+export const buildColumnNodes = (table: TableRef, names: string[]): ColumnNode[] =>
+  names.map(name => ({
+    type: 'Column',
+    table: table.name,
+    name
+  }));
+
+/**
+ * Builds a table AST node for the provided table definition
+ * @param table - Table definition
+ */
+export const createTableNode = (table: TableRef): TableNode => ({
+  type: 'Table',
+  name: table.name
+});
+
+/**
+ * Creates a FunctionTable node for expressions like `function_name(args...)` used in FROM
+ */
+export const fnTable = (name: string, args: any[] = [], alias?: string, opts?: { lateral?: boolean; withOrdinality?: boolean; columnAliases?: string[]; schema?: string }): FunctionTableNode => ({
+  type: 'FunctionTable',
+  name,
+  args,
+  alias,
+  lateral: opts?.lateral,
+  withOrdinality: opts?.withOrdinality,
+  columnAliases: opts?.columnAliases,
+  schema: opts?.schema
+});

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

@@ -1,6 +1,6 @@
-import { ColumnDef } from '../../schema/column.js';
 import { SelectQueryNode } from './query.js';
 import { SqlOperator } from '../sql/sql.js';
+import { ColumnRef } from './types.js';
 import {
   ColumnNode,
   FunctionNode,
@@ -37,9 +37,9 @@ export const valueToOperand = (value: unknown): OperandNode => {
   return value as OperandNode;
 };
 
-const toNode = (col: ColumnDef | OperandNode): OperandNode => {
+const toNode = (col: ColumnRef | OperandNode): OperandNode => {
   if (isOperandNode(col)) return col as OperandNode;
-  const def = col as ColumnDef;
+  const def = col as ColumnRef;
   return { type: 'Column', table: def.table || 'unknown', name: def.name };
 };
 
@@ -48,20 +48,20 @@ const toLiteralNode = (value: string | number | boolean | null): LiteralNode =>
   value
 });
 
-const toOperand = (val: OperandNode | ColumnDef | string | number | boolean | null): OperandNode => {
+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 };
   }
-  return toNode(val as OperandNode | ColumnDef);
+  return toNode(val as OperandNode | ColumnRef);
 };
 
-export const columnOperand = (col: ColumnDef | ColumnNode): ColumnNode => toNode(col) as ColumnNode;
+export const columnOperand = (col: ColumnRef | ColumnNode): ColumnNode => toNode(col) as ColumnNode;
 
 const createBinaryExpression = (
   operator: SqlOperator,
-  left: OperandNode | ColumnDef,
-  right: OperandNode | ColumnDef | string | number | boolean | null,
+  left: OperandNode | ColumnRef,
+  right: OperandNode | ColumnRef | string | number | boolean | null,
   escape?: string
 ): BinaryExpressionNode => {
   const node: BinaryExpressionNode = {
@@ -84,15 +84,15 @@ const createBinaryExpression = (
  * @param right - Right operand
  * @returns Binary expression node with equality operator
  */
-export const eq = (left: OperandNode | ColumnDef, right: OperandNode | ColumnDef | string | number): BinaryExpressionNode =>
+export const eq = (left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number | boolean): BinaryExpressionNode =>
   createBinaryExpression('=', left, right);
 
 /**
  * Creates a not equal expression (left != right)
  */
 export const neq = (
-  left: OperandNode | ColumnDef,
-  right: OperandNode | ColumnDef | string | number
+  left: OperandNode | ColumnRef,
+  right: OperandNode | ColumnRef | string | number | boolean
 ): BinaryExpressionNode => createBinaryExpression('!=', left, right);
 
 /**
@@ -101,13 +101,13 @@ export const neq = (
  * @param right - Right operand
  * @returns Binary expression node with greater-than operator
  */
-export const gt = (left: OperandNode | ColumnDef, right: OperandNode | ColumnDef | string | number): BinaryExpressionNode =>
+export const gt = (left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number): BinaryExpressionNode =>
   createBinaryExpression('>', left, right);
 
 /**
  * Creates a greater than or equal expression (left >= right)
  */
-export const gte = (left: OperandNode | ColumnDef, right: OperandNode | ColumnDef | string | number): BinaryExpressionNode =>
+export const gte = (left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number): BinaryExpressionNode =>
   createBinaryExpression('>=', left, right);
 
 /**
@@ -116,13 +116,13 @@ export const gte = (left: OperandNode | ColumnDef, right: OperandNode | ColumnDe
  * @param right - Right operand
  * @returns Binary expression node with less-than operator
  */
-export const lt = (left: OperandNode | ColumnDef, right: OperandNode | ColumnDef | string | number): BinaryExpressionNode =>
+export const lt = (left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number): BinaryExpressionNode =>
   createBinaryExpression('<', left, right);
 
 /**
  * Creates a less than or equal expression (left <= right)
  */
-export const lte = (left: OperandNode | ColumnDef, right: OperandNode | ColumnDef | string | number): BinaryExpressionNode =>
+export const lte = (left: OperandNode | ColumnRef, right: OperandNode | ColumnRef | string | number): BinaryExpressionNode =>
   createBinaryExpression('<=', left, right);
 
 /**
@@ -132,7 +132,7 @@ export const lte = (left: OperandNode | ColumnDef, right: OperandNode | ColumnDe
  * @param escape - Optional escape character
  * @returns Binary expression node with LIKE operator
  */
-export const like = (left: OperandNode | ColumnDef, pattern: string, escape?: string): BinaryExpressionNode =>
+export const like = (left: OperandNode | ColumnRef, pattern: string, escape?: string): BinaryExpressionNode =>
   createBinaryExpression('LIKE', left, pattern, escape);
 
 /**
@@ -142,7 +142,7 @@ export const like = (left: OperandNode | ColumnDef, pattern: string, escape?: st
  * @param escape - Optional escape character
  * @returns Binary expression node with NOT LIKE operator
  */
-export const notLike = (left: OperandNode | ColumnDef, pattern: string, escape?: string): BinaryExpressionNode =>
+export const notLike = (left: OperandNode | ColumnRef, pattern: string, escape?: string): BinaryExpressionNode =>
   createBinaryExpression('NOT LIKE', left, pattern, escape);
 
 /**
@@ -172,7 +172,7 @@ export const or = (...operands: ExpressionNode[]): LogicalExpressionNode => ({
  * @param left - Operand to check for null
  * @returns Null expression node with IS NULL operator
  */
-export const isNull = (left: OperandNode | ColumnDef): NullExpressionNode => ({
+export const isNull = (left: OperandNode | ColumnRef): NullExpressionNode => ({
   type: 'NullExpression',
   left: toNode(left),
   operator: 'IS NULL'
@@ -183,7 +183,7 @@ export const isNull = (left: OperandNode | ColumnDef): NullExpressionNode => ({
  * @param left - Operand to check for non-null
  * @returns Null expression node with IS NOT NULL operator
  */
-export const isNotNull = (left: OperandNode | ColumnDef): NullExpressionNode => ({
+export const isNotNull = (left: OperandNode | ColumnRef): NullExpressionNode => ({
   type: 'NullExpression',
   left: toNode(left),
   operator: 'IS NOT NULL'
@@ -191,7 +191,7 @@ export const isNotNull = (left: OperandNode | ColumnDef): NullExpressionNode =>
 
 const createInExpression = (
   operator: 'IN' | 'NOT IN',
-  left: OperandNode | ColumnDef,
+  left: OperandNode | ColumnRef,
   values: (string | number | LiteralNode)[]
 ): InExpressionNode => ({
   type: 'InExpression',
@@ -206,7 +206,7 @@ const createInExpression = (
  * @param values - Values to check against
  * @returns IN expression node
  */
-export const inList = (left: OperandNode | ColumnDef, values: (string | number | LiteralNode)[]): InExpressionNode =>
+export const inList = (left: OperandNode | ColumnRef, values: (string | number | LiteralNode)[]): InExpressionNode =>
   createInExpression('IN', left, values);
 
 /**
@@ -215,14 +215,14 @@ export const inList = (left: OperandNode | ColumnDef, values: (string | number |
  * @param values - Values to check against
  * @returns NOT IN expression node
  */
-export const notInList = (left: OperandNode | ColumnDef, values: (string | number | LiteralNode)[]): InExpressionNode =>
+export const notInList = (left: OperandNode | ColumnRef, values: (string | number | LiteralNode)[]): InExpressionNode =>
   createInExpression('NOT IN', left, values);
 
 const createBetweenExpression = (
   operator: 'BETWEEN' | 'NOT BETWEEN',
-  left: OperandNode | ColumnDef,
-  lower: OperandNode | ColumnDef | string | number,
-  upper: OperandNode | ColumnDef | string | number
+  left: OperandNode | ColumnRef,
+  lower: OperandNode | ColumnRef | string | number,
+  upper: OperandNode | ColumnRef | string | number
 ): BetweenExpressionNode => ({
   type: 'BetweenExpression',
   left: toNode(left),
@@ -239,9 +239,9 @@ const createBetweenExpression = (
  * @returns BETWEEN expression node
  */
 export const between = (
-  left: OperandNode | ColumnDef,
-  lower: OperandNode | ColumnDef | string | number,
-  upper: OperandNode | ColumnDef | string | number
+  left: OperandNode | ColumnRef,
+  lower: OperandNode | ColumnRef | string | number,
+  upper: OperandNode | ColumnRef | string | number
 ): BetweenExpressionNode => createBetweenExpression('BETWEEN', left, lower, upper);
 
 /**
@@ -252,9 +252,9 @@ export const between = (
  * @returns NOT BETWEEN expression node
  */
 export const notBetween = (
-  left: OperandNode | ColumnDef,
-  lower: OperandNode | ColumnDef | string | number,
-  upper: OperandNode | ColumnDef | string | number
+  left: OperandNode | ColumnRef,
+  lower: OperandNode | ColumnRef | string | number,
+  upper: OperandNode | ColumnRef | string | number
 ): BetweenExpressionNode => createBetweenExpression('NOT BETWEEN', left, lower, upper);
 
 /**
@@ -263,7 +263,7 @@ export const notBetween = (
  * @param path - JSON path expression
  * @returns JSON path node
  */
-export const jsonPath = (col: ColumnDef | ColumnNode, path: string): JsonPathNode => ({
+export const jsonPath = (col: ColumnRef | ColumnNode, path: string): JsonPathNode => ({
   type: 'JsonPath',
   column: columnOperand(col),
   path
@@ -276,8 +276,8 @@ export const jsonPath = (col: ColumnDef | ColumnNode, path: string): JsonPathNod
  * @returns CASE expression node
  */
 export const caseWhen = (
-  conditions: { when: ExpressionNode; then: OperandNode | ColumnDef | string | number | boolean | null }[],
-  elseValue?: OperandNode | ColumnDef | string | number | boolean | null
+  conditions: { when: ExpressionNode; then: OperandNode | ColumnRef | string | number | boolean | null }[],
+  elseValue?: OperandNode | ColumnRef | string | number | boolean | null
 ): CaseExpressionNode => ({
   type: 'CaseExpression',
   conditions: conditions.map(c => ({

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

@@ -1,6 +1,6 @@
-import { ColumnDef } from '../../schema/column.js';
-import type { SelectQueryNode, OrderByNode } from './query.js';
-import { SqlOperator } from '../sql/sql.js';
+import type { SelectQueryNode, OrderByNode } from './query.js';
+import { SqlOperator } from '../sql/sql.js';
+import { ColumnRef } from './types.js';
 
 /**
  * AST node representing a literal value
@@ -27,15 +27,17 @@ export interface ColumnNode {
 /**
  * AST node representing a function call
  */
-export interface FunctionNode {
-  type: 'Function';
-  /** Function name (e.g., COUNT, SUM) */
-  name: string;
-  /** Function arguments */
-  args: (ColumnNode | LiteralNode | JsonPathNode)[];
-  /** Optional alias for the function result */
-  alias?: string;
-}
+export interface FunctionNode {
+  type: 'Function';
+  /** Function name (e.g., COUNT, SUM) */
+  name: string;
+  /** Optional canonical function key for dialect-aware rendering */
+  fn?: string;
+  /** Function arguments */
+  args: OperandNode[];
+  /** Optional alias for the function result */
+  alias?: string;
+}
 
 /**
  * AST node representing a JSON path expression
@@ -118,10 +120,10 @@ export const isOperandNode = (node: any): node is OperandNode => node && operand
 export const isFunctionNode = (node: any): node is FunctionNode => node?.type === 'Function';
 export const isCaseExpressionNode = (node: any): node is CaseExpressionNode => node?.type === 'CaseExpression';
 export const isWindowFunctionNode = (node: any): node is WindowFunctionNode => node?.type === 'WindowFunction';
-export const isExpressionSelectionNode = (
-  node: ColumnDef | FunctionNode | CaseExpressionNode | WindowFunctionNode
-): node is FunctionNode | CaseExpressionNode | WindowFunctionNode =>
-  isFunctionNode(node) || isCaseExpressionNode(node) || isWindowFunctionNode(node);
+export const isExpressionSelectionNode = (
+  node: ColumnRef | FunctionNode | CaseExpressionNode | WindowFunctionNode
+): node is FunctionNode | CaseExpressionNode | WindowFunctionNode =>
+  isFunctionNode(node) || isCaseExpressionNode(node) || isWindowFunctionNode(node);
 
 /**
  * AST node representing a binary expression (e.g., column = value)