metal-orm 1.0.14 → 1.0.16

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

package/src/core/ast/join.ts

@@ -1,4 +1,4 @@
-import { TableNode } from './query.js';
+import { TableNode, FunctionTableNode } from './query.js';
 import { ExpressionNode } from './expression.js';
 import { JoinKind } from '../sql/sql.js';
 
@@ -10,9 +10,9 @@ export interface JoinNode {
   /** Type of join (INNER, LEFT, RIGHT, etc.) */
   kind: JoinKind;
   /** Table to join */
-  table: TableNode;
-  /** Join condition expression */
+  table: TableNode | FunctionTableNode;
+ /** Join condition expression */
   condition: ExpressionNode;
-  /** Optional relation name for code generation */
-  relationName?: string;
+  /** Optional metadata for non-SQL concerns (e.g., relation name) */
+  meta?: Record<string, unknown>;
 }

package/src/core/ast/query.ts

@@ -8,7 +8,6 @@ import {
   OperandNode
 } from './expression.js';
 import { JoinNode } from './join.js';
-import { RelationType } from '../../schema/relation.js';
 import { OrderDirection } from '../sql/sql.js';
 
 /**
@@ -24,6 +23,27 @@ export interface TableNode {
   alias?: string;
 }
 
+/**
+ * AST node representing a function used as a table source (table-valued function)
+ */
+export interface FunctionTableNode {
+  type: 'FunctionTable';
+  /** Function name */
+  name: string;
+  /** Optional schema for the function (some dialects) */
+  schema?: string;
+  /** Function arguments as operand nodes */
+  args?: any[]; // use any to avoid circular import here; caller should supply OperandNode
+  /** 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
  */
@@ -36,101 +56,45 @@ export interface OrderByNode {
 }
 
 /**
- * Plan describing pivot columns needed for hydration
- */
-export interface HydrationPivotPlan {
-  table: string;
-  primaryKey: string;
-  aliasPrefix: string;
-  columns: string[];
-}
-
-/**
- * Plan for hydrating relationship data
+ * AST node representing a Common Table Expression (CTE)
  */
-export interface HydrationRelationPlan {
-  /** Name of the relationship */
+export interface CommonTableExpressionNode {
+  type: 'CommonTableExpression';
+  /** CTE name */
   name: string;
-  /** Alias prefix for the relationship */
-  aliasPrefix: string;
-  /** Type of relationship */
-  type: RelationType;
-  /** Target table name */
-  targetTable: string;
-  /** Target table primary key */
-  targetPrimaryKey: string;
-  /** Foreign key column */
-  foreignKey: string;
-  /** Local key column */
-  localKey: string;
-  /** Columns to include */
-  columns: string[];
-  /** Optional pivot plan for many-to-many relationships */
-  pivot?: HydrationPivotPlan;
+  /** Optional column names */
+  columns?: string[];
+  /** CTE query */
+  query: SelectQueryNode;
+  /** Whether the CTE is recursive */
+  recursive: boolean;
 }
 
 /**
- * Complete hydration plan for a query
+ * Supported set operation kinds for compound SELECT queries
  */
-export interface HydrationPlan {
-  /** Root table name */
-  rootTable: string;
-  /** Root table primary key */
-  rootPrimaryKey: string;
-  /** Root table columns */
-  rootColumns: string[];
-  /** Relationship hydration plans */
-  relations: HydrationRelationPlan[];
-}
+export type SetOperationKind = 'UNION' | 'UNION ALL' | 'INTERSECT' | 'EXCEPT';
 
 /**
- * Query metadata including hydration information
+ * AST node representing a set operation (UNION, INTERSECT, etc.)
  */
-export interface QueryMetadata {
-  /** Optional hydration plan */
-  hydration?: HydrationPlan;
+export interface SetOperationNode {
+  type: 'SetOperation';
+  /** Operator to combine queries */
+  operator: SetOperationKind;
+  /** Right-hand query in the compound expression */
+  query: SelectQueryNode;
 }
 
 /**
- * AST node representing a Common Table Expression (CTE)
+ * AST node representing a complete SELECT query
  */
-export interface CommonTableExpressionNode {
-  type: 'CommonTableExpression';
-  /** CTE name */
-  name: string;
-  /** Optional column names */
-  columns?: string[];
-  /** CTE query */
-  query: SelectQueryNode;
-  /** Whether the CTE is recursive */
-  recursive: boolean;
-}
-
-/**
- * Supported set operation kinds for compound SELECT queries
- */
-export type SetOperationKind = 'UNION' | 'UNION ALL' | 'INTERSECT' | 'EXCEPT';
-
-/**
- * AST node representing a set operation (UNION, INTERSECT, etc.)
- */
-export interface SetOperationNode {
-  type: 'SetOperation';
-  /** Operator to combine queries */
-  operator: SetOperationKind;
-  /** Right-hand query in the compound expression */
-  query: SelectQueryNode;
-}
-
-/**
- * AST node representing a complete SELECT query
- */
-export interface SelectQueryNode {
-  type: 'SelectQuery';
+export interface SelectQueryNode {
+  type: 'SelectQuery';
   /** Optional CTEs (WITH clauses) */
   ctes?: CommonTableExpressionNode[];
-  /** FROM clause table */
-  from: TableNode;
+  /** FROM clause table (either a Table or a FunctionTable) */
+  from: TableNode | FunctionTableNode;
   /** SELECT clause columns */
   columns: (ColumnNode | FunctionNode | ScalarSubqueryNode | CaseExpressionNode | WindowFunctionNode)[];
   /** JOIN clauses */
@@ -147,13 +111,13 @@ export interface SelectQueryNode {
   limit?: number;
   /** Optional OFFSET clause */
   offset?: number;
-  /** Optional query metadata */
-  meta?: QueryMetadata;
-  /** Optional DISTINCT clause */
-  distinct?: ColumnNode[];
-  /** Optional set operations chaining this query with others */
-  setOps?: SetOperationNode[];
-}
+  /** Optional query metadata */
+  meta?: Record<string, unknown>;
+  /** Optional DISTINCT clause */
+  distinct?: ColumnNode[];
+  /** Optional set operations chaining this query with others */
+  setOps?: SetOperationNode[];
+}
 
 export interface InsertQueryNode {
   type: 'InsertQuery';

package/src/core/ast/types.ts

@@ -0,0 +1,20 @@
+/**
+ * Minimal column reference used by AST builders.
+ * Accepts any object with a name and optional table/alias fields
+ * (schema ColumnDef/TableDef remain structurally compatible).
+ */
+export interface ColumnRef {
+  name: string;
+  table?: string;
+  alias?: string;
+}
+
+/**
+ * Minimal table reference used by AST builders.
+ * Keeps AST decoupled from full schema TableDef shape.
+ */
+export interface TableRef {
+  name: string;
+  schema?: string;
+  alias?: string;
+}

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

@@ -1,8 +1,8 @@
-import { ColumnDef } from '../../schema/column.js';
-import { ColumnNode, LiteralNode, JsonPathNode, WindowFunctionNode } from './expression-nodes.js';
-import { columnOperand } from './expression-builders.js';
-import { OrderDirection } from '../sql/sql.js';
-import { OrderByNode } from './query.js';
+import { ColumnNode, LiteralNode, JsonPathNode, WindowFunctionNode } from './expression-nodes.js';
+import { columnOperand } from './expression-builders.js';
+import { OrderDirection } from '../sql/sql.js';
+import { OrderByNode } from './query.js';
+import { ColumnRef } from './types.js';
 
 const buildWindowFunction = (
   name: string,
@@ -50,21 +50,21 @@ export const denseRank = (): WindowFunctionNode => buildWindowFunction('DENSE_RA
  * @param n - Number of buckets
  * @returns Window function node for NTILE
  */
-export const ntile = (n: number): WindowFunctionNode =>
-  buildWindowFunction('NTILE', [{ type: 'Literal', value: n }]);
+export const ntile = (n: number): WindowFunctionNode =>
+  buildWindowFunction('NTILE', [{ type: 'Literal', value: n }]);
 
 /**
  * Creates a LAG window function
  * @param col - Column to lag
  * @param offset - Offset (defaults to 1)
- * @param defaultValue - Default value if no row exists
- * @returns Window function node for LAG
- */
-export const lag = (col: ColumnDef | ColumnNode, offset: number = 1, defaultValue?: any): WindowFunctionNode => {
-  const args: (ColumnNode | LiteralNode | JsonPathNode)[] = [
-    columnOperand(col),
-    { type: 'Literal', value: offset }
-  ];
+ * @param defaultValue - Default value if no row exists
+ * @returns Window function node for LAG
+ */
+export const lag = (col: ColumnRef | ColumnNode, offset: number = 1, defaultValue?: any): WindowFunctionNode => {
+  const args: (ColumnNode | LiteralNode | JsonPathNode)[] = [
+    columnOperand(col),
+    { type: 'Literal', value: offset }
+  ];
   if (defaultValue !== undefined) {
     args.push({ type: 'Literal', value: defaultValue });
   }
@@ -75,14 +75,14 @@ export const lag = (col: ColumnDef | ColumnNode, offset: number = 1, defaultValu
  * Creates a LEAD window function
  * @param col - Column to lead
  * @param offset - Offset (defaults to 1)
- * @param defaultValue - Default value if no row exists
- * @returns Window function node for LEAD
- */
-export const lead = (col: ColumnDef | ColumnNode, offset: number = 1, defaultValue?: any): WindowFunctionNode => {
-  const args: (ColumnNode | LiteralNode | JsonPathNode)[] = [
-    columnOperand(col),
-    { type: 'Literal', value: offset }
-  ];
+ * @param defaultValue - Default value if no row exists
+ * @returns Window function node for LEAD
+ */
+export const lead = (col: ColumnRef | ColumnNode, offset: number = 1, defaultValue?: any): WindowFunctionNode => {
+  const args: (ColumnNode | LiteralNode | JsonPathNode)[] = [
+    columnOperand(col),
+    { type: 'Literal', value: offset }
+  ];
   if (defaultValue !== undefined) {
     args.push({ type: 'Literal', value: defaultValue });
   }
@@ -91,19 +91,19 @@ export const lead = (col: ColumnDef | ColumnNode, offset: number = 1, defaultVal
 
 /**
  * Creates a FIRST_VALUE window function
- * @param col - Column to get first value from
- * @returns Window function node for FIRST_VALUE
- */
-export const firstValue = (col: ColumnDef | ColumnNode): WindowFunctionNode =>
-  buildWindowFunction('FIRST_VALUE', [columnOperand(col)]);
+ * @param col - Column to get first value from
+ * @returns Window function node for FIRST_VALUE
+ */
+export const firstValue = (col: ColumnRef | ColumnNode): WindowFunctionNode =>
+  buildWindowFunction('FIRST_VALUE', [columnOperand(col)]);
 
 /**
  * Creates a LAST_VALUE window function
- * @param col - Column to get last value from
- * @returns Window function node for LAST_VALUE
- */
-export const lastValue = (col: ColumnDef | ColumnNode): WindowFunctionNode =>
-  buildWindowFunction('LAST_VALUE', [columnOperand(col)]);
+ * @param col - Column to get last value from
+ * @returns Window function node for LAST_VALUE
+ */
+export const lastValue = (col: ColumnRef | ColumnNode): WindowFunctionNode =>
+  buildWindowFunction('LAST_VALUE', [columnOperand(col)]);
 
 /**
  * Creates a custom window function
@@ -113,28 +113,28 @@ export const lastValue = (col: ColumnDef | ColumnNode): WindowFunctionNode =>
  * @param orderBy - Optional ORDER BY clauses
  * @returns Window function node
  */
-export const windowFunction = (
-  name: string,
-  args: (ColumnDef | ColumnNode | LiteralNode | JsonPathNode)[] = [],
-  partitionBy?: (ColumnDef | ColumnNode)[],
-  orderBy?: { column: ColumnDef | ColumnNode; direction: OrderDirection }[]
-): WindowFunctionNode => {
-  const nodeArgs = args.map(arg => {
-    if (typeof (arg as LiteralNode).value !== 'undefined') {
-      return arg as LiteralNode;
-    }
-    if ('path' in arg) {
-      return arg as JsonPathNode;
-    }
-    return columnOperand(arg as ColumnDef | ColumnNode);
-  });
-
-  const partitionNodes = partitionBy?.map(col => columnOperand(col)) ?? undefined;
-  const orderNodes: OrderByNode[] | undefined = orderBy?.map(o => ({
-    type: 'OrderBy',
-    column: columnOperand(o.column),
-    direction: o.direction
-  }));
+export const windowFunction = (
+  name: string,
+  args: (ColumnRef | ColumnNode | LiteralNode | JsonPathNode)[] = [],
+  partitionBy?: (ColumnRef | ColumnNode)[],
+  orderBy?: { column: ColumnRef | ColumnNode; direction: OrderDirection }[]
+): WindowFunctionNode => {
+  const nodeArgs = args.map(arg => {
+    if (typeof (arg as LiteralNode).value !== 'undefined') {
+      return arg as LiteralNode;
+    }
+    if ('path' in arg) {
+      return arg as JsonPathNode;
+    }
+    return columnOperand(arg as ColumnRef | ColumnNode);
+  });
+
+  const partitionNodes = partitionBy?.map(col => columnOperand(col)) ?? undefined;
+  const orderNodes: OrderByNode[] | undefined = orderBy?.map(o => ({
+    type: 'OrderBy',
+    column: columnOperand(o.column),
+    direction: o.direction
+  }));
 
   return buildWindowFunction(name, nodeArgs, partitionNodes, orderNodes);
 };