metal-orm 1.0.14 → 1.0.15

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)

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

@@ -19,81 +19,134 @@ import {
 /**
  * Visitor for expression nodes
  */
-export interface ExpressionVisitor<R> {
-  visitBinaryExpression(node: BinaryExpressionNode): R;
-  visitLogicalExpression(node: LogicalExpressionNode): R;
-  visitNullExpression(node: NullExpressionNode): R;
-  visitInExpression(node: InExpressionNode): R;
-  visitExistsExpression(node: ExistsExpressionNode): R;
-  visitBetweenExpression(node: BetweenExpressionNode): R;
-}
-
-/**
- * Visitor for operand nodes
- */
-export interface OperandVisitor<R> {
-  visitColumn(node: ColumnNode): R;
-  visitLiteral(node: LiteralNode): R;
-  visitFunction(node: FunctionNode): R;
-  visitJsonPath(node: JsonPathNode): R;
-  visitScalarSubquery(node: ScalarSubqueryNode): R;
-  visitCaseExpression(node: CaseExpressionNode): R;
-  visitWindowFunction(node: WindowFunctionNode): R;
-}
-
-const unsupportedExpression = (node: ExpressionNode): never => {
-  throw new Error(`Unsupported expression type "${(node as any)?.type ?? 'unknown'}"`);
-};
+export interface ExpressionVisitor<R> {
+  visitBinaryExpression?(node: BinaryExpressionNode): R;
+  visitLogicalExpression?(node: LogicalExpressionNode): R;
+  visitNullExpression?(node: NullExpressionNode): R;
+  visitInExpression?(node: InExpressionNode): R;
+  visitExistsExpression?(node: ExistsExpressionNode): R;
+  visitBetweenExpression?(node: BetweenExpressionNode): R;
+  otherwise?(node: ExpressionNode): R;
+}
+
+/**
+ * Visitor for operand nodes
+ */
+export interface OperandVisitor<R> {
+  visitColumn?(node: ColumnNode): R;
+  visitLiteral?(node: LiteralNode): R;
+  visitFunction?(node: FunctionNode): R;
+  visitJsonPath?(node: JsonPathNode): R;
+  visitScalarSubquery?(node: ScalarSubqueryNode): R;
+  visitCaseExpression?(node: CaseExpressionNode): R;
+  visitWindowFunction?(node: WindowFunctionNode): R;
+  otherwise?(node: OperandNode): R;
+}
+
+type ExpressionDispatch = <R>(node: any, visitor: ExpressionVisitor<R>) => R;
+type OperandDispatch = <R>(node: any, visitor: OperandVisitor<R>) => R;
+
+const expressionDispatchers = new Map<string, ExpressionDispatch>();
+const operandDispatchers = new Map<string, OperandDispatch>();
+
+/**
+ * Registers a dispatcher for a custom expression node type.
+ * Allows new node kinds without modifying the core switch.
+ */
+export const registerExpressionDispatcher = (type: string, dispatcher: ExpressionDispatch): void => {
+  expressionDispatchers.set(type, dispatcher);
+};
+
+/**
+ * Registers a dispatcher for a custom operand node type.
+ * Allows new node kinds without modifying the core switch.
+ */
+export const registerOperandDispatcher = (type: string, dispatcher: OperandDispatch): void => {
+  operandDispatchers.set(type, dispatcher);
+};
+
+/**
+ * Clears all registered dispatchers. Primarily for tests.
+ */
+export const clearExpressionDispatchers = (): void => expressionDispatchers.clear();
+export const clearOperandDispatchers = (): void => operandDispatchers.clear();
+
+const unsupportedExpression = (node: ExpressionNode): never => {
+  throw new Error(`Unsupported expression type "${(node as any)?.type ?? 'unknown'}"`);
+};
 
 const unsupportedOperand = (node: OperandNode): never => {
   throw new Error(`Unsupported operand type "${(node as any)?.type ?? 'unknown'}"`);
 };
 /**
  * Dispatches an expression node to the visitor
- * @param node - Expression node to visit
- * @param visitor - Visitor implementation
- */
-export const visitExpression = <R>(node: ExpressionNode, visitor: ExpressionVisitor<R>): R => {
-  switch (node.type) {
-    case 'BinaryExpression':
-      return visitor.visitBinaryExpression(node);
-    case 'LogicalExpression':
-      return visitor.visitLogicalExpression(node);
-    case 'NullExpression':
-      return visitor.visitNullExpression(node);
-    case 'InExpression':
-      return visitor.visitInExpression(node);
-    case 'ExistsExpression':
-      return visitor.visitExistsExpression(node);
-    case 'BetweenExpression':
-      return visitor.visitBetweenExpression(node);
-    default:
-      return unsupportedExpression(node);
-  }
-};
+ * @param node - Expression node to visit
+ * @param visitor - Visitor implementation
+ */
+export const visitExpression = <R>(node: ExpressionNode, visitor: ExpressionVisitor<R>): R => {
+  const dynamic = expressionDispatchers.get((node as any)?.type);
+  if (dynamic) return dynamic(node as any, visitor);
+
+  switch (node.type) {
+    case 'BinaryExpression':
+      if (visitor.visitBinaryExpression) return visitor.visitBinaryExpression(node);
+      break;
+    case 'LogicalExpression':
+      if (visitor.visitLogicalExpression) return visitor.visitLogicalExpression(node);
+      break;
+    case 'NullExpression':
+      if (visitor.visitNullExpression) return visitor.visitNullExpression(node);
+      break;
+    case 'InExpression':
+      if (visitor.visitInExpression) return visitor.visitInExpression(node);
+      break;
+    case 'ExistsExpression':
+      if (visitor.visitExistsExpression) return visitor.visitExistsExpression(node);
+      break;
+    case 'BetweenExpression':
+      if (visitor.visitBetweenExpression) return visitor.visitBetweenExpression(node);
+      break;
+    default:
+      break;
+  }
+  if (visitor.otherwise) return visitor.otherwise(node);
+  return unsupportedExpression(node);
+};
 
 /**
  * Dispatches an operand node to the visitor
- * @param node - Operand node to visit
- * @param visitor - Visitor implementation
- */
-export const visitOperand = <R>(node: OperandNode, visitor: OperandVisitor<R>): R => {
-  switch (node.type) {
-    case 'Column':
-      return visitor.visitColumn(node);
-    case 'Literal':
-      return visitor.visitLiteral(node);
-    case 'Function':
-      return visitor.visitFunction(node);
-    case 'JsonPath':
-      return visitor.visitJsonPath(node);
-    case 'ScalarSubquery':
-      return visitor.visitScalarSubquery(node);
-    case 'CaseExpression':
-      return visitor.visitCaseExpression(node);
-    case 'WindowFunction':
-      return visitor.visitWindowFunction(node);
-    default:
-      return unsupportedOperand(node);
-  }
-};
+ * @param node - Operand node to visit
+ * @param visitor - Visitor implementation
+ */
+export const visitOperand = <R>(node: OperandNode, visitor: OperandVisitor<R>): R => {
+  const dynamic = operandDispatchers.get((node as any)?.type);
+  if (dynamic) return dynamic(node as any, visitor);
+
+  switch (node.type) {
+    case 'Column':
+      if (visitor.visitColumn) return visitor.visitColumn(node);
+      break;
+    case 'Literal':
+      if (visitor.visitLiteral) return visitor.visitLiteral(node);
+      break;
+    case 'Function':
+      if (visitor.visitFunction) return visitor.visitFunction(node);
+      break;
+    case 'JsonPath':
+      if (visitor.visitJsonPath) return visitor.visitJsonPath(node);
+      break;
+    case 'ScalarSubquery':
+      if (visitor.visitScalarSubquery) return visitor.visitScalarSubquery(node);
+      break;
+    case 'CaseExpression':
+      if (visitor.visitCaseExpression) return visitor.visitCaseExpression(node);
+      break;
+    case 'WindowFunction':
+      if (visitor.visitWindowFunction) return visitor.visitWindowFunction(node);
+      break;
+    default:
+      break;
+  }
+  if (visitor.otherwise) return visitor.otherwise(node);
+  return unsupportedOperand(node);
+};

package/src/core/ast/expression.ts

@@ -1,5 +1,7 @@
 export * from './expression-nodes.js';
-export * from './expression-builders.js';
-export * from './window-functions.js';
-export * from './aggregate-functions.js';
-export * from './expression-visitor.js';
+export * from './expression-builders.js';
+export * from './window-functions.js';
+export * from './aggregate-functions.js';
+export * from './expression-visitor.js';
+export * from './types.js';
+export * from './adapters.js';

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

@@ -0,0 +1,15 @@
+import { JoinNode } from './join.js';
+
+/**
+ * Metadata stored on JoinNode.meta for higher-level concerns.
+ */
+export interface JoinMetadata {
+  relationName?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Retrieves the relation name from join metadata if present.
+ */
+export const getJoinRelationName = (join: JoinNode): string | undefined =>
+  (join.meta as JoinMetadata | undefined)?.relationName;

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

@@ -1,20 +1,22 @@
-import { JoinNode } from './join.js';
-import { ExpressionNode } from './expression.js';
-import { JoinKind } from '../sql/sql.js';
-
-/**
- * Creates a JoinNode ready for AST insertion.
- * Centralizing this avoids copy/pasted object literals when multiple services need to synthesize joins.
- */
-export const createJoinNode = (
-  kind: JoinKind,
-  tableName: string,
-  condition: ExpressionNode,
-  relationName?: string
-): JoinNode => ({
-  type: 'Join',
-  kind,
-  table: { type: 'Table', name: tableName },
-  condition,
-  relationName
-});
+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';
+
+/**
+ * Creates a JoinNode ready for AST insertion.
+ * Centralizing this avoids copy/pasted object literals when multiple services need to synthesize joins.
+ */
+export const createJoinNode = (
+  kind: JoinKind,
+  tableName: string | TableNode | FunctionTableNode,
+  condition: ExpressionNode,
+  relationName?: string
+): JoinNode => ({
+  type: 'Join',
+  kind,
+  table: typeof tableName === 'string' ? { type: 'Table', name: tableName } as TableNode : (tableName as TableNode | FunctionTableNode),
+  condition,
+  meta: relationName ? ({ relationName } as JoinMetadata) : undefined
+});