metal-orm 1.0.39 → 1.0.41

package/src/query-builder/select-query-state.ts

@@ -1,79 +1,86 @@
-import { TableDef } from '../schema/table.js';
-import { SelectQueryNode, CommonTableExpressionNode, OrderByNode, SetOperationNode, TableSourceNode } from '../core/ast/query.js';
-import {
-  ColumnNode,
-  ExpressionNode,
-  FunctionNode,
-  ScalarSubqueryNode,
-  CaseExpressionNode,
-  WindowFunctionNode
-} from '../core/ast/expression.js';
-import { JoinNode } from '../core/ast/join.js';
-
-/**
- * Node types that can be used in query projections
- */
-export type ProjectionNode =
-  | ColumnNode
-  | FunctionNode
-  | ScalarSubqueryNode
-  | CaseExpressionNode
-  | WindowFunctionNode;
-
-/**
- * Manages the state of a SELECT query being built
- */
-export class SelectQueryState {
-  /**
-   * Table definition for the query
-   */
-  public readonly table: TableDef;
-  /**
-   * Abstract Syntax Tree (AST) representation of the query
-   */
-  public readonly ast: SelectQueryNode;
-
-  /**
-   * Creates a new SelectQueryState instance
-   * @param table - Table definition
-   * @param ast - Optional existing AST
-   */
-  constructor(table: TableDef, ast?: SelectQueryNode) {
-    this.table = table;
-    this.ast = ast ?? {
-      type: 'SelectQuery',
-      from: { type: 'Table', name: table.name },
-      columns: [],
-      joins: []
-    };
-  }
-
-  /**
-   * Creates a new SelectQueryState with updated AST
-   * @param nextAst - Updated AST
-   * @returns New SelectQueryState instance
-   */
-  private clone(nextAst: SelectQueryNode): SelectQueryState {
-    return new SelectQueryState(this.table, nextAst);
-  }
-
-  /**
-   * Adds columns to the query
-   * @param newCols - Columns to add
-   * @returns New SelectQueryState with added columns
-   */
-  withColumns(newCols: ProjectionNode[]): SelectQueryState {
-    return this.clone({
-      ...this.ast,
-      columns: [...(this.ast.columns ?? []), ...newCols]
-    });
-  }
-
-  /**
-   * Adds a join to the query
-   * @param join - Join node to add
-   * @returns New SelectQueryState with added join
-   */
+import { TableDef } from '../schema/table.js';
+import {
+  SelectQueryNode,
+  CommonTableExpressionNode,
+  OrderByNode,
+  SetOperationNode,
+  TableSourceNode,
+  OrderingTerm
+} from '../core/ast/query.js';
+import {
+  ColumnNode,
+  ExpressionNode,
+  FunctionNode,
+  ScalarSubqueryNode,
+  CaseExpressionNode,
+  WindowFunctionNode
+} from '../core/ast/expression.js';
+import { JoinNode } from '../core/ast/join.js';
+
+/**
+ * Node types that can be used in query projections
+ */
+export type ProjectionNode =
+  | ColumnNode
+  | FunctionNode
+  | ScalarSubqueryNode
+  | CaseExpressionNode
+  | WindowFunctionNode;
+
+/**
+ * Manages the state of a SELECT query being built
+ */
+export class SelectQueryState {
+  /**
+   * Table definition for the query
+   */
+  public readonly table: TableDef;
+  /**
+   * Abstract Syntax Tree (AST) representation of the query
+   */
+  public readonly ast: SelectQueryNode;
+
+  /**
+   * Creates a new SelectQueryState instance
+   * @param table - Table definition
+   * @param ast - Optional existing AST
+   */
+  constructor(table: TableDef, ast?: SelectQueryNode) {
+    this.table = table;
+    this.ast = ast ?? {
+      type: 'SelectQuery',
+      from: { type: 'Table', name: table.name },
+      columns: [],
+      joins: []
+    };
+  }
+
+  /**
+   * Creates a new SelectQueryState with updated AST
+   * @param nextAst - Updated AST
+   * @returns New SelectQueryState instance
+   */
+  private clone(nextAst: SelectQueryNode): SelectQueryState {
+    return new SelectQueryState(this.table, nextAst);
+  }
+
+  /**
+   * Adds columns to the query
+   * @param newCols - Columns to add
+   * @returns New SelectQueryState with added columns
+   */
+  withColumns(newCols: ProjectionNode[]): SelectQueryState {
+    return this.clone({
+      ...this.ast,
+      columns: [...(this.ast.columns ?? []), ...newCols]
+    });
+  }
+
+  /**
+   * Adds a join to the query
+   * @param join - Join node to add
+   * @returns New SelectQueryState with added join
+   */
   withJoin(join: JoinNode): SelectQueryState {
     return this.clone({
       ...this.ast,
@@ -92,92 +99,92 @@ export class SelectQueryState {
       from
     });
   }
-
-  /**
-   * Adds a WHERE clause to the query
-   * @param predicate - WHERE predicate expression
-   * @returns New SelectQueryState with WHERE clause
-   */
-  withWhere(predicate: ExpressionNode): SelectQueryState {
-    return this.clone({
-      ...this.ast,
-      where: predicate
-    });
-  }
-
-  /**
-   * Adds a HAVING clause to the query
-   * @param predicate - HAVING predicate expression
-   * @returns New SelectQueryState with HAVING clause
-   */
-  withHaving(predicate: ExpressionNode): SelectQueryState {
-    return this.clone({
-      ...this.ast,
-      having: predicate
-    });
-  }
-
-  /**
-   * Adds GROUP BY columns to the query
-   * @param columns - Columns to group by
-   * @returns New SelectQueryState with GROUP BY clause
-   */
-  withGroupBy(columns: ColumnNode[]): SelectQueryState {
-    return this.clone({
-      ...this.ast,
-      groupBy: [...(this.ast.groupBy ?? []), ...columns]
-    });
-  }
-
-  /**
-   * Adds ORDER BY clauses to the query
-   * @param orderBy - ORDER BY nodes
-   * @returns New SelectQueryState with ORDER BY clause
-   */
-  withOrderBy(orderBy: OrderByNode[]): SelectQueryState {
-    return this.clone({
-      ...this.ast,
-      orderBy: [...(this.ast.orderBy ?? []), ...orderBy]
-    });
-  }
-
-  /**
-   * Adds DISTINCT columns to the query
-   * @param columns - Columns to make distinct
-   * @returns New SelectQueryState with DISTINCT clause
-   */
-  withDistinct(columns: ColumnNode[]): SelectQueryState {
-    return this.clone({
-      ...this.ast,
-      distinct: [...(this.ast.distinct ?? []), ...columns]
-    });
-  }
-
-  /**
-   * Adds a LIMIT clause to the query
-   * @param limit - Maximum number of rows to return
-   * @returns New SelectQueryState with LIMIT clause
-   */
-  withLimit(limit: number): SelectQueryState {
-    return this.clone({
-      ...this.ast,
-      limit
-    });
-  }
-
-  /**
-   * Adds an OFFSET clause to the query
-   * @param offset - Number of rows to skip
-   * @returns New SelectQueryState with OFFSET clause
-   */
-  withOffset(offset: number): SelectQueryState {
-    return this.clone({
-      ...this.ast,
-      offset
-    });
-  }
-
-  /**
+
+  /**
+   * Adds a WHERE clause to the query
+   * @param predicate - WHERE predicate expression
+   * @returns New SelectQueryState with WHERE clause
+   */
+  withWhere(predicate: ExpressionNode): SelectQueryState {
+    return this.clone({
+      ...this.ast,
+      where: predicate
+    });
+  }
+
+  /**
+   * Adds a HAVING clause to the query
+   * @param predicate - HAVING predicate expression
+   * @returns New SelectQueryState with HAVING clause
+   */
+  withHaving(predicate: ExpressionNode): SelectQueryState {
+    return this.clone({
+      ...this.ast,
+      having: predicate
+    });
+  }
+
+  /**
+   * Adds GROUP BY columns to the query
+   * @param columns - Terms to group by
+   * @returns New SelectQueryState with GROUP BY clause
+   */
+  withGroupBy(columns: OrderingTerm[]): SelectQueryState {
+    return this.clone({
+      ...this.ast,
+      groupBy: [...(this.ast.groupBy ?? []), ...columns]
+    });
+  }
+
+  /**
+   * Adds ORDER BY clauses to the query
+   * @param orderBy - ORDER BY nodes
+   * @returns New SelectQueryState with ORDER BY clause
+   */
+  withOrderBy(orderBy: OrderByNode[]): SelectQueryState {
+    return this.clone({
+      ...this.ast,
+      orderBy: [...(this.ast.orderBy ?? []), ...orderBy]
+    });
+  }
+
+  /**
+   * Adds DISTINCT columns to the query
+   * @param columns - Columns to make distinct
+   * @returns New SelectQueryState with DISTINCT clause
+   */
+  withDistinct(columns: ColumnNode[]): SelectQueryState {
+    return this.clone({
+      ...this.ast,
+      distinct: [...(this.ast.distinct ?? []), ...columns]
+    });
+  }
+
+  /**
+   * Adds a LIMIT clause to the query
+   * @param limit - Maximum number of rows to return
+   * @returns New SelectQueryState with LIMIT clause
+   */
+  withLimit(limit: number): SelectQueryState {
+    return this.clone({
+      ...this.ast,
+      limit
+    });
+  }
+
+  /**
+   * Adds an OFFSET clause to the query
+   * @param offset - Number of rows to skip
+   * @returns New SelectQueryState with OFFSET clause
+   */
+  withOffset(offset: number): SelectQueryState {
+    return this.clone({
+      ...this.ast,
+      offset
+    });
+  }
+
+  /**
    * Adds a Common Table Expression (CTE) to the query
    * @param cte - CTE node to add
    * @returns New SelectQueryState with CTE

package/src/query-builder/select.ts

@@ -2,7 +2,7 @@ import { TableDef } from '../schema/table.js';
 
 import { ColumnDef } from '../schema/column.js';
 
-import { SelectQueryNode, SetOperationKind } from '../core/ast/query.js';
+import { OrderingTerm, SelectQueryNode, SetOperationKind } from '../core/ast/query.js';
 
 import { HydrationPlan } from '../core/hydration/types.js';
 
@@ -727,21 +727,13 @@ export class SelectQueryBuilder<T = any, TTable extends TableDef = TableDef> {
 
 
   /**
-
    * Adds a GROUP BY clause to the query
-
-   * @param col - Column definition or column node to group by
-
+   * @param term - Column definition or ordering term to group by
    * @returns New query builder instance with the GROUP BY clause
-
    */
-
-  groupBy(col: ColumnDef | ColumnNode): SelectQueryBuilder<T, TTable> {
-
-    const nextContext = this.applyAst(this.context, service => service.withGroupBy(col));
-
+  groupBy(term: ColumnDef | OrderingTerm): SelectQueryBuilder<T, TTable> {
+    const nextContext = this.applyAst(this.context, service => service.withGroupBy(term));
     return this.clone(nextContext);
-
   }
 
 
@@ -767,23 +759,23 @@ export class SelectQueryBuilder<T = any, TTable extends TableDef = TableDef> {
 
 
   /**
-
    * Adds an ORDER BY clause to the query
-
-   * @param col - Column definition or column node to order by
-
-   * @param direction - Order direction (defaults to ASC)
-
+   * @param term - Column definition or ordering term to order by
+   * @param directionOrOptions - Order direction or options (defaults to ASC)
    * @returns New query builder instance with the ORDER BY clause
-
    */
+  orderBy(
+    term: ColumnDef | OrderingTerm,
+    directionOrOptions: OrderDirection | { direction?: OrderDirection; nulls?: 'FIRST' | 'LAST'; collation?: string } = ORDER_DIRECTIONS.ASC
+  ): SelectQueryBuilder<T, TTable> {
+    const options = typeof directionOrOptions === 'string' ? { direction: directionOrOptions } : directionOrOptions;
+    const dir = options.direction ?? ORDER_DIRECTIONS.ASC;
 
-  orderBy(col: ColumnDef | ColumnNode, direction: OrderDirection = ORDER_DIRECTIONS.ASC): SelectQueryBuilder<T, TTable> {
-
-    const nextContext = this.applyAst(this.context, service => service.withOrderBy(col, direction));
+    const nextContext = this.applyAst(this.context, service =>
+      service.withOrderBy(term, dir, options.nulls, options.collation)
+    );
 
     return this.clone(nextContext);
-
   }
 
 

package/src/query-builder/update-query-state.ts

@@ -1,77 +1,114 @@
-import { TableDef } from '../schema/table.js';
-import { ColumnNode, ExpressionNode, OperandNode, isOperandNode, valueToOperand } from '../core/ast/expression.js';
-import { TableNode, UpdateQueryNode, UpdateAssignmentNode } from '../core/ast/query.js';
-import { createTableNode } from '../core/ast/builders.js';
-type LiteralValue = string | number | boolean | null;
-type UpdateValue = OperandNode | LiteralValue;
-
-const isUpdateValue = (value: unknown): value is UpdateValue => {
-  if (value === null) return true;
-  switch (typeof value) {
-    case 'string':
-    case 'number':
-    case 'boolean':
-      return true;
-    default:
-      return isOperandNode(value);
-  }
-};
-
-/**
- * Immutable state for UPDATE queries
- */
-export class UpdateQueryState {
-  public readonly table: TableDef;
-  public readonly ast: UpdateQueryNode;
-
-  constructor(table: TableDef, ast?: UpdateQueryNode) {
-    this.table = table;
-    this.ast = ast ?? {
-      type: 'UpdateQuery',
-      table: createTableNode(table),
-      set: []
-    };
-  }
-
-  private clone(nextAst: UpdateQueryNode): UpdateQueryState {
-    return new UpdateQueryState(this.table, nextAst);
-  }
-
-  withSet(values: Record<string, unknown>): UpdateQueryState {
-    const assignments: UpdateAssignmentNode[] = Object.entries(values).map(([column, rawValue]) => {
-      if (!isUpdateValue(rawValue)) {
-        throw new Error(
-          `Invalid update value for column "${column}": only primitives, null, or OperandNodes are allowed`
-        );
-      }
-
-      return {
-        column: {
-          type: 'Column',
-          table: this.table.name,
-          name: column
-        },
-        value: valueToOperand(rawValue)
-      };
-    });
-
-    return this.clone({
-      ...this.ast,
-      set: assignments
-    });
-  }
-
-  withWhere(expr: ExpressionNode): UpdateQueryState {
-    return this.clone({
-      ...this.ast,
-      where: expr
-    });
-  }
-
-  withReturning(columns: ColumnNode[]): UpdateQueryState {
-    return this.clone({
-      ...this.ast,
-      returning: [...columns]
-    });
-  }
-}
+import { TableDef } from '../schema/table.js';
+import {
+  ColumnNode,
+  ExpressionNode,
+  OperandNode,
+  isOperandNode,
+  valueToOperand
+} from '../core/ast/expression.js';
+import {
+  TableSourceNode,
+  UpdateQueryNode,
+  UpdateAssignmentNode
+} from '../core/ast/query.js';
+import { JoinNode } from '../core/ast/join.js';
+import { createTableNode } from '../core/ast/builders.js';
+
+type LiteralValue = string | number | boolean | null;
+type UpdateValue = OperandNode | LiteralValue;
+
+const isUpdateValue = (value: unknown): value is UpdateValue => {
+  if (value === null) return true;
+  switch (typeof value) {
+    case 'string':
+    case 'number':
+    case 'boolean':
+      return true;
+    default:
+      return isOperandNode(value);
+  }
+};
+
+/**
+ * Immutable state for UPDATE queries
+ */
+export class UpdateQueryState {
+  public readonly table: TableDef;
+  public readonly ast: UpdateQueryNode;
+
+  constructor(table: TableDef, ast?: UpdateQueryNode) {
+    this.table = table;
+    this.ast = ast ?? {
+      type: 'UpdateQuery',
+      table: createTableNode(table),
+      set: [],
+      joins: []
+    };
+  }
+
+  private clone(nextAst: UpdateQueryNode): UpdateQueryState {
+    return new UpdateQueryState(this.table, nextAst);
+  }
+
+  withSet(values: Record<string, unknown>): UpdateQueryState {
+    const assignments: UpdateAssignmentNode[] = Object.entries(values).map(([column, rawValue]) => {
+      if (!isUpdateValue(rawValue)) {
+        throw new Error(
+          `Invalid update value for column "${column}": only primitives, null, or OperandNodes are allowed`
+        );
+      }
+
+      return {
+        column: {
+          type: 'Column',
+          table: this.table.name,
+          name: column
+        },
+        value: valueToOperand(rawValue)
+      };
+    });
+
+    return this.clone({
+      ...this.ast,
+      set: assignments
+    });
+  }
+
+  withWhere(expr: ExpressionNode): UpdateQueryState {
+    return this.clone({
+      ...this.ast,
+      where: expr
+    });
+  }
+
+  withReturning(columns: ColumnNode[]): UpdateQueryState {
+    return this.clone({
+      ...this.ast,
+      returning: [...columns]
+    });
+  }
+
+  withFrom(from: TableSourceNode): UpdateQueryState {
+    return this.clone({
+      ...this.ast,
+      from
+    });
+  }
+
+  withJoin(join: JoinNode): UpdateQueryState {
+    return this.clone({
+      ...this.ast,
+      joins: [...(this.ast.joins ?? []), join]
+    });
+  }
+
+  withTableAlias(alias: string): UpdateQueryState {
+    return this.clone({
+      ...this.ast,
+      table: {
+        ...this.ast.table,
+        alias
+      }
+    });
+  }
+}

package/src/query-builder/update.ts

@@ -1,10 +1,12 @@
 import { TableDef } from '../schema/table.js';
 import { ColumnDef } from '../schema/column.js';
 import { ColumnNode, ExpressionNode } from '../core/ast/expression.js';
+import { JOIN_KINDS, JoinKind } from '../core/sql/sql.js';
 import { CompiledQuery, UpdateCompiler, Dialect } from '../core/dialect/abstract.js';
 import { DialectKey, resolveDialectInput } from '../core/dialect/dialect-factory.js';
-import { UpdateQueryNode } from '../core/ast/query.js';
+import { TableSourceNode, UpdateQueryNode } from '../core/ast/query.js';
 import { UpdateQueryState } from './update-query-state.js';
+import { createJoinNode } from '../core/ast/join-node.js';
 import { buildColumnNode } from '../core/ast/builders.js';
 
 type UpdateDialectInput = Dialect | DialectKey;
@@ -25,6 +27,26 @@ export class UpdateQueryBuilder<T> {
     return new UpdateQueryBuilder(this.table, state);
   }
 
+  as(alias: string): UpdateQueryBuilder<T> {
+    return this.clone(this.state.withTableAlias(alias));
+  }
+
+  from(source: TableDef | TableSourceNode): UpdateQueryBuilder<T> {
+    const tableSource = this.resolveTableSource(source);
+    return this.clone(this.state.withFrom(tableSource));
+  }
+
+  join(
+    table: TableDef | TableSourceNode | string,
+    condition: ExpressionNode,
+    kind: JoinKind = JOIN_KINDS.INNER,
+    relationName?: string
+  ): UpdateQueryBuilder<T> {
+    const joinTarget = this.resolveJoinTarget(table);
+    const joinNode = createJoinNode(kind, joinTarget, condition, relationName);
+    return this.clone(this.state.withJoin(joinNode));
+  }
+
   set(values: Record<string, unknown>): UpdateQueryBuilder<T> {
     return this.clone(this.state.withSet(values));
   }
@@ -39,6 +61,18 @@ export class UpdateQueryBuilder<T> {
     return this.clone(this.state.withReturning(nodes));
   }
 
+  private resolveTableSource(source: TableDef | TableSourceNode): TableSourceNode {
+    if (isTableSourceNode(source)) {
+      return source;
+    }
+    return { type: 'Table', name: source.name, schema: source.schema };
+  }
+
+  private resolveJoinTarget(table: TableDef | TableSourceNode | string): TableSourceNode | string {
+    if (typeof table === 'string') return table;
+    return this.resolveTableSource(table);
+  }
+
   // Existing compiler-based compile stays, but we add a new overload.
 
   // 1) Keep the old behavior (used internally / tests, if any):
@@ -65,3 +99,6 @@ export class UpdateQueryBuilder<T> {
     return this.state.ast;
   }
 }
+
+const isTableSourceNode = (source: TableDef | TableSourceNode): source is TableSourceNode =>
+  typeof (source as TableSourceNode).type === 'string';