metal-orm 1.0.7 → 1.0.9

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

@@ -0,0 +1,30 @@
+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)]
+});
+
+/**
+ * Creates a COUNT function expression
+ * @param col - Column to count
+ * @returns Function node with COUNT
+ */
+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');
+
+/**
+ * Creates an AVG function expression
+ * @param col - Column to average
+ * @returns Function node with AVG
+ */
+export const avg = buildAggregate('AVG');

package/src/core/ast/builders.ts

@@ -0,0 +1,43 @@
+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
+});

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

@@ -0,0 +1,310 @@
+import { ColumnDef } from '../../schema/column.js';
+import { SelectQueryNode } from './query.js';
+import { SqlOperator } from '../sql/sql.js';
+import {
+  ColumnNode,
+  FunctionNode,
+  LiteralNode,
+  JsonPathNode,
+  OperandNode,
+  CaseExpressionNode,
+  WindowFunctionNode,
+  BinaryExpressionNode,
+  ExpressionNode,
+  LogicalExpressionNode,
+  NullExpressionNode,
+  InExpressionNode,
+  ExistsExpressionNode,
+  BetweenExpressionNode,
+  isOperandNode
+} from './expression-nodes.js';
+
+/**
+ * Converts a primitive or existing operand into an operand node
+ * @param value - Value or operand to normalize
+ * @returns OperandNode representing the value
+ */
+export const valueToOperand = (value: unknown): OperandNode => {
+  if (
+    value === null ||
+    value === undefined ||
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    typeof value === 'boolean'
+  ) {
+    return { type: 'Literal', value: value === undefined ? null : value } as LiteralNode;
+  }
+  return value as OperandNode;
+};
+
+const toNode = (col: ColumnDef | OperandNode): OperandNode => {
+  if (isOperandNode(col)) return col as OperandNode;
+  const def = col as ColumnDef;
+  return { type: 'Column', table: def.table || 'unknown', name: def.name };
+};
+
+const toLiteralNode = (value: string | number | boolean | null): LiteralNode => ({
+  type: 'Literal',
+  value
+});
+
+const toOperand = (val: OperandNode | ColumnDef | 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);
+};
+
+export const columnOperand = (col: ColumnDef | ColumnNode): ColumnNode => toNode(col) as ColumnNode;
+
+const createBinaryExpression = (
+  operator: SqlOperator,
+  left: OperandNode | ColumnDef,
+  right: OperandNode | ColumnDef | string | number | boolean | null,
+  escape?: string
+): BinaryExpressionNode => {
+  const node: BinaryExpressionNode = {
+    type: 'BinaryExpression',
+    left: toNode(left),
+    operator,
+    right: toOperand(right)
+  };
+
+  if (escape !== undefined) {
+    node.escape = toLiteralNode(escape);
+  }
+
+  return node;
+};
+
+/**
+ * Creates an equality expression (left = right)
+ * @param left - Left operand
+ * @param right - Right operand
+ * @returns Binary expression node with equality operator
+ */
+export const eq = (left: OperandNode | ColumnDef, right: OperandNode | ColumnDef | string | number): BinaryExpressionNode =>
+  createBinaryExpression('=', left, right);
+
+/**
+ * Creates a not equal expression (left != right)
+ */
+export const neq = (
+  left: OperandNode | ColumnDef,
+  right: OperandNode | ColumnDef | string | number
+): BinaryExpressionNode => createBinaryExpression('!=', left, right);
+
+/**
+ * Creates a greater-than expression (left > right)
+ * @param left - Left operand
+ * @param right - Right operand
+ * @returns Binary expression node with greater-than operator
+ */
+export const gt = (left: OperandNode | ColumnDef, right: OperandNode | ColumnDef | 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 =>
+  createBinaryExpression('>=', left, right);
+
+/**
+ * Creates a less-than expression (left < right)
+ * @param left - Left operand
+ * @param right - Right operand
+ * @returns Binary expression node with less-than operator
+ */
+export const lt = (left: OperandNode | ColumnDef, right: OperandNode | ColumnDef | 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 =>
+  createBinaryExpression('<=', left, right);
+
+/**
+ * Creates a LIKE pattern matching expression
+ * @param left - Left operand
+ * @param pattern - Pattern to match
+ * @param escape - Optional escape character
+ * @returns Binary expression node with LIKE operator
+ */
+export const like = (left: OperandNode | ColumnDef, pattern: string, escape?: string): BinaryExpressionNode =>
+  createBinaryExpression('LIKE', left, pattern, escape);
+
+/**
+ * Creates a NOT LIKE pattern matching expression
+ * @param left - Left operand
+ * @param pattern - Pattern to match
+ * @param escape - Optional escape character
+ * @returns Binary expression node with NOT LIKE operator
+ */
+export const notLike = (left: OperandNode | ColumnDef, pattern: string, escape?: string): BinaryExpressionNode =>
+  createBinaryExpression('NOT LIKE', left, pattern, escape);
+
+/**
+ * Creates a logical AND expression
+ * @param operands - Expressions to combine with AND
+ * @returns Logical expression node with AND operator
+ */
+export const and = (...operands: ExpressionNode[]): LogicalExpressionNode => ({
+  type: 'LogicalExpression',
+  operator: 'AND',
+  operands
+});
+
+/**
+ * Creates a logical OR expression
+ * @param operands - Expressions to combine with OR
+ * @returns Logical expression node with OR operator
+ */
+export const or = (...operands: ExpressionNode[]): LogicalExpressionNode => ({
+  type: 'LogicalExpression',
+  operator: 'OR',
+  operands
+});
+
+/**
+ * Creates an IS NULL expression
+ * @param left - Operand to check for null
+ * @returns Null expression node with IS NULL operator
+ */
+export const isNull = (left: OperandNode | ColumnDef): NullExpressionNode => ({
+  type: 'NullExpression',
+  left: toNode(left),
+  operator: 'IS NULL'
+});
+
+/**
+ * Creates an IS NOT NULL expression
+ * @param left - Operand to check for non-null
+ * @returns Null expression node with IS NOT NULL operator
+ */
+export const isNotNull = (left: OperandNode | ColumnDef): NullExpressionNode => ({
+  type: 'NullExpression',
+  left: toNode(left),
+  operator: 'IS NOT NULL'
+});
+
+const createInExpression = (
+  operator: 'IN' | 'NOT IN',
+  left: OperandNode | ColumnDef,
+  values: (string | number | LiteralNode)[]
+): InExpressionNode => ({
+  type: 'InExpression',
+  left: toNode(left),
+  operator,
+  right: values.map(v => toOperand(v))
+});
+
+/**
+ * Creates an IN expression (value IN list)
+ * @param left - Operand to check
+ * @param values - Values to check against
+ * @returns IN expression node
+ */
+export const inList = (left: OperandNode | ColumnDef, values: (string | number | LiteralNode)[]): InExpressionNode =>
+  createInExpression('IN', left, values);
+
+/**
+ * Creates a NOT IN expression (value NOT IN list)
+ * @param left - Operand to check
+ * @param values - Values to check against
+ * @returns NOT IN expression node
+ */
+export const notInList = (left: OperandNode | ColumnDef, 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
+): BetweenExpressionNode => ({
+  type: 'BetweenExpression',
+  left: toNode(left),
+  operator,
+  lower: toOperand(lower),
+  upper: toOperand(upper)
+});
+
+/**
+ * Creates a BETWEEN expression (value BETWEEN lower AND upper)
+ * @param left - Operand to check
+ * @param lower - Lower bound
+ * @param upper - Upper bound
+ * @returns BETWEEN expression node
+ */
+export const between = (
+  left: OperandNode | ColumnDef,
+  lower: OperandNode | ColumnDef | string | number,
+  upper: OperandNode | ColumnDef | string | number
+): BetweenExpressionNode => createBetweenExpression('BETWEEN', left, lower, upper);
+
+/**
+ * Creates a NOT BETWEEN expression (value NOT BETWEEN lower AND upper)
+ * @param left - Operand to check
+ * @param lower - Lower bound
+ * @param upper - Upper bound
+ * @returns NOT BETWEEN expression node
+ */
+export const notBetween = (
+  left: OperandNode | ColumnDef,
+  lower: OperandNode | ColumnDef | string | number,
+  upper: OperandNode | ColumnDef | string | number
+): BetweenExpressionNode => createBetweenExpression('NOT BETWEEN', left, lower, upper);
+
+/**
+ * Creates a JSON path expression
+ * @param col - Source column
+ * @param path - JSON path expression
+ * @returns JSON path node
+ */
+export const jsonPath = (col: ColumnDef | ColumnNode, path: string): JsonPathNode => ({
+  type: 'JsonPath',
+  column: columnOperand(col),
+  path
+});
+
+/**
+ * Creates a CASE expression
+ * @param conditions - Array of WHEN-THEN conditions
+ * @param elseValue - Optional ELSE value
+ * @returns CASE expression node
+ */
+export const caseWhen = (
+  conditions: { when: ExpressionNode; then: OperandNode | ColumnDef | string | number | boolean | null }[],
+  elseValue?: OperandNode | ColumnDef | string | number | boolean | null
+): CaseExpressionNode => ({
+  type: 'CaseExpression',
+  conditions: conditions.map(c => ({
+    when: c.when,
+    then: toOperand(c.then)
+  })),
+  else: elseValue !== undefined ? toOperand(elseValue) : undefined
+});
+
+/**
+ * Creates an EXISTS expression
+ * @param subquery - Subquery to check for existence
+ * @returns EXISTS expression node
+ */
+export const exists = (subquery: SelectQueryNode): ExistsExpressionNode => ({
+  type: 'ExistsExpression',
+  operator: 'EXISTS',
+  subquery
+});
+
+/**
+ * Creates a NOT EXISTS expression
+ * @param subquery - Subquery to check for non-existence
+ * @returns NOT EXISTS expression node
+ */
+export const notExists = (subquery: SelectQueryNode): ExistsExpressionNode => ({
+  type: 'ExistsExpression',
+  operator: 'NOT EXISTS',
+  subquery
+});

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

@@ -0,0 +1,211 @@
+import { ColumnDef } from '../../schema/column.js';
+import type { SelectQueryNode, OrderByNode } from './query.js';
+import { SqlOperator } from '../sql/sql.js';
+
+/**
+ * AST node representing a literal value
+ */
+export interface LiteralNode {
+  type: 'Literal';
+  /** The literal value (string, number, boolean, or null) */
+  value: string | number | boolean | null;
+}
+
+/**
+ * AST node representing a column reference
+ */
+export interface ColumnNode {
+  type: 'Column';
+  /** Table name the column belongs to */
+  table: string;
+  /** Column name */
+  name: string;
+  /** Optional alias for the column */
+  alias?: string;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * AST node representing a JSON path expression
+ */
+export interface JsonPathNode {
+  type: 'JsonPath';
+  /** Source column */
+  column: ColumnNode;
+  /** JSON path expression */
+  path: string;
+  /** Optional alias for the result */
+  alias?: string;
+}
+
+/**
+ * AST node representing a scalar subquery
+ */
+export interface ScalarSubqueryNode {
+  type: 'ScalarSubquery';
+  /** Subquery to execute */
+  query: SelectQueryNode;
+  /** Optional alias for the subquery result */
+  alias?: string;
+}
+
+/**
+ * AST node representing a CASE expression
+ */
+export interface CaseExpressionNode {
+  type: 'CaseExpression';
+  /** WHEN-THEN conditions */
+  conditions: { when: ExpressionNode; then: OperandNode }[];
+  /** Optional ELSE clause */
+  else?: OperandNode;
+  /** Optional alias for the result */
+  alias?: string;
+}
+
+/**
+ * AST node representing a window function
+ */
+export interface WindowFunctionNode {
+  type: 'WindowFunction';
+  /** Window function name (e.g., ROW_NUMBER, RANK) */
+  name: string;
+  /** Function arguments */
+  args: (ColumnNode | LiteralNode | JsonPathNode)[];
+  /** Optional PARTITION BY clause */
+  partitionBy?: ColumnNode[];
+  /** Optional ORDER BY clause */
+  orderBy?: OrderByNode[];
+  /** Optional alias for the result */
+  alias?: string;
+}
+
+/**
+ * Union type representing any operand that can be used in expressions
+ */
+export type OperandNode =
+  | ColumnNode
+  | LiteralNode
+  | FunctionNode
+  | JsonPathNode
+  | ScalarSubqueryNode
+  | CaseExpressionNode
+  | WindowFunctionNode;
+
+const operandTypes = new Set<OperandNode['type']>([
+  'Column',
+  'Literal',
+  'Function',
+  'JsonPath',
+  'ScalarSubquery',
+  'CaseExpression',
+  'WindowFunction'
+]);
+
+export const isOperandNode = (node: any): node is OperandNode => node && operandTypes.has(node.type);
+
+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);
+
+/**
+ * AST node representing a binary expression (e.g., column = value)
+ */
+export interface BinaryExpressionNode {
+  type: 'BinaryExpression';
+  /** Left operand */
+  left: OperandNode;
+  /** Comparison operator */
+  operator: SqlOperator;
+  /** Right operand */
+  right: OperandNode;
+  /** Optional escape character for LIKE expressions */
+  escape?: LiteralNode;
+}
+
+/**
+ * AST node representing a logical expression (AND/OR)
+ */
+export interface LogicalExpressionNode {
+  type: 'LogicalExpression';
+  /** Logical operator (AND or OR) */
+  operator: 'AND' | 'OR';
+  /** Operands to combine */
+  operands: ExpressionNode[];
+}
+
+/**
+ * AST node representing a null check expression
+ */
+export interface NullExpressionNode {
+  type: 'NullExpression';
+  /** Operand to check for null */
+  left: OperandNode;
+  /** Null check operator */
+  operator: 'IS NULL' | 'IS NOT NULL';
+}
+
+/**
+ * AST node representing an IN/NOT IN expression
+ */
+export interface InExpressionNode {
+  type: 'InExpression';
+  /** Left operand to check */
+  left: OperandNode;
+  /** IN/NOT IN operator */
+  operator: 'IN' | 'NOT IN';
+  /** Values to check against */
+  right: OperandNode[];
+}
+
+/**
+ * AST node representing an EXISTS/NOT EXISTS expression
+ */
+export interface ExistsExpressionNode {
+  type: 'ExistsExpression';
+  /** EXISTS/NOT EXISTS operator */
+  operator: SqlOperator;
+  /** Subquery to check */
+  subquery: SelectQueryNode;
+}
+
+/**
+ * AST node representing a BETWEEN/NOT BETWEEN expression
+ */
+export interface BetweenExpressionNode {
+  type: 'BetweenExpression';
+  /** Operand to check */
+  left: OperandNode;
+  /** BETWEEN/NOT BETWEEN operator */
+  operator: 'BETWEEN' | 'NOT BETWEEN';
+  /** Lower bound */
+  lower: OperandNode;
+  /** Upper bound */
+  upper: OperandNode;
+}
+
+/**
+ * Union type representing any supported expression node
+ */
+export type ExpressionNode =
+  | BinaryExpressionNode
+  | LogicalExpressionNode
+  | NullExpressionNode
+  | InExpressionNode
+  | ExistsExpressionNode
+  | BetweenExpressionNode;

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

@@ -0,0 +1,99 @@
+import {
+  BinaryExpressionNode,
+  LogicalExpressionNode,
+  NullExpressionNode,
+  InExpressionNode,
+  ExistsExpressionNode,
+  BetweenExpressionNode,
+  ExpressionNode,
+  OperandNode,
+  ColumnNode,
+  LiteralNode,
+  FunctionNode,
+  JsonPathNode,
+  ScalarSubqueryNode,
+  CaseExpressionNode,
+  WindowFunctionNode
+} from './expression-nodes.js';
+
+/**
+ * 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'}"`);
+};
+
+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);
+  }
+};
+
+/**
+ * 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);
+  }
+};

package/src/core/ast/expression.ts

@@ -0,0 +1,5 @@
+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';