metal-orm 1.0.39 → 1.0.41

package/src/core/ast/query.ts

@@ -1,18 +1,19 @@
-import {
-  ColumnNode,
-  FunctionNode,
-  ExpressionNode,
-  ScalarSubqueryNode,
-  CaseExpressionNode,
-  WindowFunctionNode,
-  OperandNode
-} from './expression.js';
-import { JoinNode } from './join.js';
-import { OrderDirection } from '../sql/sql.js';
-
-/**
- * AST node representing a table reference in a query
- */
+import {
+  ColumnNode,
+  FunctionNode,
+  ExpressionNode,
+  ScalarSubqueryNode,
+  CaseExpressionNode,
+  WindowFunctionNode,
+  OperandNode,
+  AliasRefNode
+} from './expression.js';
+import { JoinNode } from './join.js';
+import { OrderDirection } from '../sql/sql.js';
+
+/**
+ * AST node representing a table reference in a query
+ */
 export interface TableNode {
   type: 'Table';
   /** Table name */
@@ -25,18 +26,18 @@ export interface TableNode {
 
 /**
  * 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 */
+ */
+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;
@@ -59,118 +60,149 @@ export interface DerivedTableNode {
 
 export type TableSourceNode = TableNode | FunctionTableNode | DerivedTableNode;
 
+/**
+ * Any expression that can appear in ORDER BY / GROUP BY terms.
+ */
+export type OrderingTerm = OperandNode | ExpressionNode | AliasRefNode;
+
 /**
  * AST node representing an ORDER BY clause
  */
 export interface OrderByNode {
-  type: 'OrderBy';
-  /** Column to order by */
-  column: ColumnNode;
-  /** Order direction (ASC or DESC) */
-  direction: OrderDirection;
-}
-
-/**
- * AST node representing a Common Table Expression (CTE)
- */
-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
- */
+  type: 'OrderBy';
+  /** Expression/operand/alias to order by */
+  term: OrderingTerm;
+  /** Order direction (ASC or DESC) */
+  direction: OrderDirection;
+  /** Optional nulls ordering (NULLS FIRST/LAST) */
+  nulls?: 'FIRST' | 'LAST';
+  /** Optional collation */
+  collation?: string;
+}
+
+/**
+ * AST node representing a Common Table Expression (CTE)
+ */
+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';
   /** Optional CTEs (WITH clauses) */
   ctes?: CommonTableExpressionNode[];
   /** FROM clause table (either a Table or a FunctionTable) */
   from: TableSourceNode;
-  /** SELECT clause columns */
-  columns: (ColumnNode | FunctionNode | ScalarSubqueryNode | CaseExpressionNode | WindowFunctionNode)[];
-  /** JOIN clauses */
-  joins: JoinNode[];
-  /** Optional WHERE clause */
-  where?: ExpressionNode;
-  /** Optional GROUP BY clause */
-  groupBy?: ColumnNode[];
-  /** Optional HAVING clause */
-  having?: ExpressionNode;
-  /** Optional ORDER BY clause */
-  orderBy?: OrderByNode[];
-  /** Optional LIMIT clause */
-  limit?: number;
-  /** Optional OFFSET clause */
-  offset?: number;
-  /** 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';
-  /** Target table */
-  into: TableNode;
-  /** Column order for inserted values */
-  columns: ColumnNode[];
-  /** Rows of values to insert */
-  values: OperandNode[][];
-  /** Optional RETURNING clause */
-  returning?: ColumnNode[];
-}
-
-export interface UpdateAssignmentNode {
-  /** Column to update */
-  column: ColumnNode;
-  /** Value to set */
-  value: OperandNode;
-}
-
-export interface UpdateQueryNode {
-  type: 'UpdateQuery';
-  /** Table being updated */
-  table: TableNode;
-  /** Assignments for SET clause */
-  set: UpdateAssignmentNode[];
-  /** Optional WHERE clause */
-  where?: ExpressionNode;
-  /** Optional RETURNING clause */
-  returning?: ColumnNode[];
-}
-
-export interface DeleteQueryNode {
-  type: 'DeleteQuery';
-  /** Table to delete from */
-  from: TableNode;
-  /** Optional WHERE clause */
-  where?: ExpressionNode;
-  /** Optional RETURNING clause */
-  returning?: ColumnNode[];
-}
+  /** SELECT clause columns */
+  columns: (ColumnNode | FunctionNode | ScalarSubqueryNode | CaseExpressionNode | WindowFunctionNode)[];
+  /** JOIN clauses */
+  joins: JoinNode[];
+  /** Optional WHERE clause */
+  where?: ExpressionNode;
+  /** Optional GROUP BY clause */
+  groupBy?: OrderingTerm[];
+  /** Optional HAVING clause */
+  having?: ExpressionNode;
+  /** Optional ORDER BY clause */
+  orderBy?: OrderByNode[];
+  /** Optional LIMIT clause */
+  limit?: number;
+  /** Optional OFFSET clause */
+  offset?: number;
+  /** Optional query metadata */
+  meta?: Record<string, unknown>;
+  /** Optional DISTINCT clause */
+  distinct?: ColumnNode[];
+  /** Optional set operations chaining this query with others */
+  setOps?: SetOperationNode[];
+}
+
+export interface InsertValuesSourceNode {
+  type: 'InsertValues';
+  /** Rows of values for INSERT rows */
+  rows: OperandNode[][];
+}
+
+export interface InsertSelectSourceNode {
+  type: 'InsertSelect';
+  /** SELECT query providing rows */
+  query: SelectQueryNode;
+}
+
+export type InsertSourceNode = InsertValuesSourceNode | InsertSelectSourceNode;
+
+export interface InsertQueryNode {
+  type: 'InsertQuery';
+  /** Target table */
+  into: TableNode;
+  /** Column order for inserted values */
+  columns: ColumnNode[];
+  /** Source of inserted rows (either literal values or a SELECT query) */
+  source: InsertSourceNode;
+  /** Optional RETURNING clause */
+  returning?: ColumnNode[];
+}
+
+export interface UpdateAssignmentNode {
+  /** Column to update */
+  column: ColumnNode;
+  /** Value to set */
+  value: OperandNode;
+}
+
+export interface UpdateQueryNode {
+  type: 'UpdateQuery';
+  /** Table being updated */
+  table: TableNode;
+  /** Optional FROM clause for multi-table updates */
+  from?: TableSourceNode;
+  /** Optional joins applied to the FROM/USING tables */
+  joins?: JoinNode[];
+  /** Assignments for SET clause */
+  set: UpdateAssignmentNode[];
+  /** Optional WHERE clause */
+  where?: ExpressionNode;
+  /** Optional RETURNING clause */
+  returning?: ColumnNode[];
+}
+
+export interface DeleteQueryNode {
+  type: 'DeleteQuery';
+  /** Table to delete from */
+  from: TableNode;
+  /** Optional USING clause for multi-table deletes */
+  using?: TableSourceNode;
+  /** Optional joins applied to the USING clause */
+  joins?: JoinNode[];
+  /** Optional WHERE clause */
+  where?: ExpressionNode;
+  /** Optional RETURNING clause */
+  returning?: ColumnNode[];
+}

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

@@ -3,60 +3,60 @@ 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,
-  args: (ColumnNode | LiteralNode | JsonPathNode)[] = [],
-  partitionBy?: ColumnNode[],
-  orderBy?: OrderByNode[]
-): WindowFunctionNode => {
-  const node: WindowFunctionNode = {
-    type: 'WindowFunction',
-    name,
-    args
-  };
-
-  if (partitionBy && partitionBy.length) {
-    node.partitionBy = partitionBy;
-  }
-
-  if (orderBy && orderBy.length) {
-    node.orderBy = orderBy;
-  }
-
-  return node;
-};
-
-/**
- * Creates a ROW_NUMBER window function
- * @returns Window function node for ROW_NUMBER
- */
-export const rowNumber = (): WindowFunctionNode => buildWindowFunction('ROW_NUMBER');
-
-/**
- * Creates a RANK window function
- * @returns Window function node for RANK
- */
-export const rank = (): WindowFunctionNode => buildWindowFunction('RANK');
-
-/**
- * Creates a DENSE_RANK window function
- * @returns Window function node for DENSE_RANK
- */
-export const denseRank = (): WindowFunctionNode => buildWindowFunction('DENSE_RANK');
-
-/**
- * Creates an NTILE window function
- * @param n - Number of buckets
- * @returns Window function node for NTILE
- */
+
+const buildWindowFunction = (
+  name: string,
+  args: (ColumnNode | LiteralNode | JsonPathNode)[] = [],
+  partitionBy?: ColumnNode[],
+  orderBy?: OrderByNode[]
+): WindowFunctionNode => {
+  const node: WindowFunctionNode = {
+    type: 'WindowFunction',
+    name,
+    args
+  };
+
+  if (partitionBy && partitionBy.length) {
+    node.partitionBy = partitionBy;
+  }
+
+  if (orderBy && orderBy.length) {
+    node.orderBy = orderBy;
+  }
+
+  return node;
+};
+
+/**
+ * Creates a ROW_NUMBER window function
+ * @returns Window function node for ROW_NUMBER
+ */
+export const rowNumber = (): WindowFunctionNode => buildWindowFunction('ROW_NUMBER');
+
+/**
+ * Creates a RANK window function
+ * @returns Window function node for RANK
+ */
+export const rank = (): WindowFunctionNode => buildWindowFunction('RANK');
+
+/**
+ * Creates a DENSE_RANK window function
+ * @returns Window function node for DENSE_RANK
+ */
+export const denseRank = (): WindowFunctionNode => buildWindowFunction('DENSE_RANK');
+
+/**
+ * Creates an NTILE window function
+ * @param n - Number of buckets
+ * @returns Window function node for NTILE
+ */
 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)
+
+/**
+ * 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
  */
@@ -65,16 +65,16 @@ export const lag = (col: ColumnRef | ColumnNode, offset: number = 1, defaultValu
     columnOperand(col),
     { type: 'Literal', value: offset }
   ];
-  if (defaultValue !== undefined) {
-    args.push({ type: 'Literal', value: defaultValue });
-  }
-  return buildWindowFunction('LAG', args);
-};
-
-/**
- * Creates a LEAD window function
- * @param col - Column to lead
- * @param offset - Offset (defaults to 1)
+  if (defaultValue !== undefined) {
+    args.push({ type: 'Literal', value: defaultValue });
+  }
+  return buildWindowFunction('LAG', args);
+};
+
+/**
+ * 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
  */
@@ -83,36 +83,36 @@ export const lead = (col: ColumnRef | ColumnNode, offset: number = 1, defaultVal
     columnOperand(col),
     { type: 'Literal', value: offset }
   ];
-  if (defaultValue !== undefined) {
-    args.push({ type: 'Literal', value: defaultValue });
-  }
-  return buildWindowFunction('LEAD', args);
-};
-
-/**
- * Creates a FIRST_VALUE window function
+  if (defaultValue !== undefined) {
+    args.push({ type: 'Literal', value: defaultValue });
+  }
+  return buildWindowFunction('LEAD', args);
+};
+
+/**
+ * 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: ColumnRef | ColumnNode): WindowFunctionNode =>
   buildWindowFunction('FIRST_VALUE', [columnOperand(col)]);
-
-/**
- * Creates a LAST_VALUE window function
+
+/**
+ * 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: ColumnRef | ColumnNode): WindowFunctionNode =>
   buildWindowFunction('LAST_VALUE', [columnOperand(col)]);
-
-/**
- * Creates a custom window function
- * @param name - Window function name
- * @param args - Function arguments
- * @param partitionBy - Optional PARTITION BY columns
- * @param orderBy - Optional ORDER BY clauses
- * @returns Window function node
- */
+
+/**
+ * Creates a custom window function
+ * @param name - Window function name
+ * @param args - Function arguments
+ * @param partitionBy - Optional PARTITION BY columns
+ * @param orderBy - Optional ORDER BY clauses
+ * @returns Window function node
+ */
 export const windowFunction = (
   name: string,
   args: (ColumnRef | ColumnNode | LiteralNode | JsonPathNode)[] = [],
@@ -132,9 +132,9 @@ export const windowFunction = (
   const partitionNodes = partitionBy?.map(col => columnOperand(col)) ?? undefined;
   const orderNodes: OrderByNode[] | undefined = orderBy?.map(o => ({
     type: 'OrderBy',
-    column: columnOperand(o.column),
+    term: columnOperand(o.column),
     direction: o.direction
   }));
-
-  return buildWindowFunction(name, nodeArgs, partitionNodes, orderNodes);
-};
+
+  return buildWindowFunction(name, nodeArgs, partitionNodes, orderNodes);
+};