metal-orm 1.0.43 → 1.0.44

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

@@ -14,9 +14,21 @@ import {
 import { JoinNode } from '../core/ast/join.js';
 import { createTableNode } from '../core/ast/builders.js';
 
+/**
+ * Literal values that can be used in UPDATE statements
+ */
 type LiteralValue = string | number | boolean | null;
+
+/**
+ * Values allowed in UPDATE SET clauses
+ */
 type UpdateValue = OperandNode | LiteralValue;
 
+/**
+ * Type guard to check if a value is valid for UPDATE operations
+ * @param value - Value to check
+ * @returns True if value is a valid update value
+ */
 const isUpdateValue = (value: unknown): value is UpdateValue => {
   if (value === null) return true;
   switch (typeof value) {
@@ -36,6 +48,11 @@ export class UpdateQueryState {
   public readonly table: TableDef;
   public readonly ast: UpdateQueryNode;
 
+  /**
+   * Creates a new UpdateQueryState instance
+   * @param table - Table definition for the update
+   * @param ast - Optional existing AST
+   */
   constructor(table: TableDef, ast?: UpdateQueryNode) {
     this.table = table;
     this.ast = ast ?? {
@@ -46,10 +63,20 @@ export class UpdateQueryState {
     };
   }
 
+  /**
+   * Creates a new UpdateQueryState with updated AST
+   * @param nextAst - Updated AST
+   * @returns New UpdateQueryState instance
+   */
   private clone(nextAst: UpdateQueryNode): UpdateQueryState {
     return new UpdateQueryState(this.table, nextAst);
   }
 
+  /**
+   * Sets the columns to update with their new values
+   * @param values - Record of column names to values
+   * @returns New UpdateQueryState with SET clause
+   */
   withSet(values: Record<string, unknown>): UpdateQueryState {
     const assignments: UpdateAssignmentNode[] = Object.entries(values).map(([column, rawValue]) => {
       if (!isUpdateValue(rawValue)) {
@@ -74,6 +101,11 @@ export class UpdateQueryState {
     });
   }
 
+  /**
+   * Adds a WHERE condition to the update query
+   * @param expr - WHERE expression
+   * @returns New UpdateQueryState with WHERE clause
+   */
   withWhere(expr: ExpressionNode): UpdateQueryState {
     return this.clone({
       ...this.ast,
@@ -81,6 +113,11 @@ export class UpdateQueryState {
     });
   }
 
+  /**
+   * Adds a RETURNING clause to the update query
+   * @param columns - Columns to return
+   * @returns New UpdateQueryState with RETURNING clause
+   */
   withReturning(columns: ColumnNode[]): UpdateQueryState {
     return this.clone({
       ...this.ast,
@@ -88,6 +125,11 @@ export class UpdateQueryState {
     });
   }
 
+  /**
+   * Sets the FROM clause for the update query
+   * @param from - Table source for FROM
+   * @returns New UpdateQueryState with FROM clause
+   */
   withFrom(from: TableSourceNode): UpdateQueryState {
     return this.clone({
       ...this.ast,
@@ -95,6 +137,11 @@ export class UpdateQueryState {
     });
   }
 
+  /**
+   * Adds a JOIN to the update query
+   * @param join - Join node to add
+   * @returns New UpdateQueryState with JOIN
+   */
   withJoin(join: JoinNode): UpdateQueryState {
     return this.clone({
       ...this.ast,
@@ -102,6 +149,11 @@ export class UpdateQueryState {
     });
   }
 
+  /**
+   * Applies an alias to the table being updated
+   * @param alias - Alias for the table
+   * @returns New UpdateQueryState with table alias
+   */
   withTableAlias(alias: string): UpdateQueryState {
     return this.clone({
       ...this.ast,

package/src/query-builder/update.ts

@@ -2,12 +2,14 @@ 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 { CompiledQuery, Dialect } from '../core/dialect/abstract.js';
 import { DialectKey, resolveDialectInput } from '../core/dialect/dialect-factory.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';
+import { OrmSession } from '../orm/orm-session.js';
+import { QueryResult } from '../core/execution/db-executor.js';
 
 type UpdateDialectInput = Dialect | DialectKey;
 
@@ -18,6 +20,11 @@ export class UpdateQueryBuilder<T> {
   private readonly table: TableDef;
   private readonly state: UpdateQueryState;
 
+  /**
+   * Creates a new UpdateQueryBuilder instance
+   * @param table - The table definition for the UPDATE query
+   * @param state - Optional initial query state, defaults to a new UpdateQueryState
+   */
   constructor(table: TableDef, state?: UpdateQueryState) {
     this.table = table;
     this.state = state ?? new UpdateQueryState(table);
@@ -27,15 +34,33 @@ export class UpdateQueryBuilder<T> {
     return new UpdateQueryBuilder(this.table, state);
   }
 
+  /**
+   * Sets an alias for the table in the UPDATE query
+   * @param alias - The alias to assign to the table
+   * @returns A new UpdateQueryBuilder with the table alias set
+   */
   as(alias: string): UpdateQueryBuilder<T> {
     return this.clone(this.state.withTableAlias(alias));
   }
 
+  /**
+   * Adds a FROM clause to the UPDATE query
+   * @param source - The table source to use in the FROM clause
+   * @returns A new UpdateQueryBuilder with the FROM clause added
+   */
   from(source: TableDef | TableSourceNode): UpdateQueryBuilder<T> {
     const tableSource = this.resolveTableSource(source);
     return this.clone(this.state.withFrom(tableSource));
   }
 
+  /**
+   * Adds a JOIN clause to the UPDATE query
+   * @param table - The table to join with
+   * @param condition - The join condition expression
+   * @param kind - The type of join (defaults to INNER)
+   * @param relationName - Optional name for the relation
+   * @returns A new UpdateQueryBuilder with the JOIN clause added
+   */
   join(
     table: TableDef | TableSourceNode | string,
     condition: ExpressionNode,
@@ -47,14 +72,29 @@ export class UpdateQueryBuilder<T> {
     return this.clone(this.state.withJoin(joinNode));
   }
 
+  /**
+   * Adds a SET clause to the UPDATE query
+   * @param values - The column-value pairs to update
+   * @returns A new UpdateQueryBuilder with the SET clause added
+   */
   set(values: Record<string, unknown>): UpdateQueryBuilder<T> {
     return this.clone(this.state.withSet(values));
   }
 
+  /**
+   * Adds a WHERE clause to the UPDATE query
+   * @param expr - The expression to use as the WHERE condition
+   * @returns A new UpdateQueryBuilder with the WHERE clause added
+   */
   where(expr: ExpressionNode): UpdateQueryBuilder<T> {
     return this.clone(this.state.withWhere(expr));
   }
 
+  /**
+   * Adds a RETURNING clause to the UPDATE query
+   * @param columns - Columns to return after update
+   * @returns A new UpdateQueryBuilder with the RETURNING clause added
+   */
   returning(...columns: (ColumnDef | ColumnNode)[]): UpdateQueryBuilder<T> {
     if (!columns.length) return this;
     const nodes = columns.map(column => buildColumnNode(this.table, column));
@@ -73,29 +113,39 @@ export class UpdateQueryBuilder<T> {
     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):
-  compile(compiler: UpdateCompiler): CompiledQuery;
-  // 2) New ergonomic overload:
-  compile(dialect: UpdateDialectInput): CompiledQuery;
-
-  compile(arg: UpdateCompiler | UpdateDialectInput): CompiledQuery {
-    const candidate = arg as { compileUpdate?: (ast: UpdateQueryNode) => CompiledQuery };
-    if (typeof candidate.compileUpdate === 'function') {
-      // UpdateCompiler path – old behavior
-      return candidate.compileUpdate(this.state.ast);
-    }
+  /**
+   * Compiles the UPDATE query for the specified dialect
+   * @param dialect - The SQL dialect to compile for
+   * @returns The compiled query with SQL and parameters
+   */
+  compile(dialect: UpdateDialectInput): CompiledQuery {
+    const resolved = resolveDialectInput(dialect);
+    return resolved.compileUpdate(this.state.ast);
+  }
 
-    // Dialect | string path – new behavior
-    const dialect = resolveDialectInput(arg as UpdateDialectInput);
-    return dialect.compileUpdate(this.state.ast);
+  /**
+   * Returns the SQL string for the UPDATE query
+   * @param dialect - The SQL dialect to generate SQL for
+   * @returns The SQL string representation of the query
+   */
+  toSql(dialect: UpdateDialectInput): string {
+    return this.compile(dialect).sql;
   }
 
-  toSql(arg: UpdateCompiler | UpdateDialectInput): string {
-    return this.compile(arg as UpdateCompiler).sql;
+  /**
+   * Executes the UPDATE query using the provided session
+   * @param session - The ORM session to execute the query with
+   * @returns A promise that resolves to the query results
+   */
+  async execute(session: OrmSession): Promise<QueryResult[]> {
+    const compiled = this.compile(session.dialect);
+    return session.executor.executeSql(compiled.sql, compiled.params);
   }
 
+  /**
+   * Returns the Abstract Syntax Tree (AST) representation of the query
+   * @returns The AST node for the UPDATE query
+   */
   getAST(): UpdateQueryNode {
     return this.state.ast;
   }

package/src/schema/table-guards.ts

@@ -0,0 +1,31 @@
+import { ColumnDef } from './column.js';
+import type { TableDef } from './table.js';
+
+const isColumnsRecord = (columns: unknown): columns is Record<string, ColumnDef> => {
+    return typeof columns === 'object' && columns !== null;
+};
+
+const isRelationsRecord = (relations: unknown): relations is Record<string, unknown> => {
+    return typeof relations === 'object' && relations !== null;
+};
+
+export const isTableDef = (value: unknown): value is TableDef => {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+
+    const candidate = value as Partial<TableDef>;
+    if (typeof candidate.name !== 'string') {
+        return false;
+    }
+
+    if (!isColumnsRecord(candidate.columns)) {
+        return false;
+    }
+
+    if (!isRelationsRecord(candidate.relations)) {
+        return false;
+    }
+
+    return true;
+};