metal-orm 1.0.43 → 1.0.45

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

@@ -14,6 +14,11 @@ export class DeleteQueryState {
   public readonly table: TableDef;
   public readonly ast: DeleteQueryNode;
 
+  /**
+   * Creates a new DeleteQueryState instance
+   * @param table - The table definition for the DELETE query
+   * @param ast - Optional initial AST node, defaults to a basic DELETE query
+   */
   constructor(table: TableDef, ast?: DeleteQueryNode) {
     this.table = table;
     this.ast = ast ?? {
@@ -27,6 +32,11 @@ export class DeleteQueryState {
     return new DeleteQueryState(this.table, nextAst);
   }
 
+  /**
+   * Adds a WHERE clause to the DELETE query
+   * @param expr - The expression to use as the WHERE condition
+   * @returns A new DeleteQueryState with the WHERE clause added
+   */
   withWhere(expr: ExpressionNode): DeleteQueryState {
     return this.clone({
       ...this.ast,
@@ -34,6 +44,11 @@ export class DeleteQueryState {
     });
   }
 
+  /**
+   * Adds a RETURNING clause to the DELETE query
+   * @param columns - The columns to return after deletion
+   * @returns A new DeleteQueryState with the RETURNING clause added
+   */
   withReturning(columns: ColumnNode[]): DeleteQueryState {
     return this.clone({
       ...this.ast,
@@ -41,6 +56,11 @@ export class DeleteQueryState {
     });
   }
 
+  /**
+   * Adds a USING clause to the DELETE query
+   * @param source - The table source to use in the USING clause
+   * @returns A new DeleteQueryState with the USING clause added
+   */
   withUsing(source: TableSourceNode): DeleteQueryState {
     return this.clone({
       ...this.ast,
@@ -48,6 +68,11 @@ export class DeleteQueryState {
     });
   }
 
+  /**
+   * Adds a JOIN clause to the DELETE query
+   * @param join - The join node to add
+   * @returns A new DeleteQueryState with the JOIN clause added
+   */
   withJoin(join: JoinNode): DeleteQueryState {
     return this.clone({
       ...this.ast,
@@ -55,6 +80,11 @@ export class DeleteQueryState {
     });
   }
 
+  /**
+   * Sets an alias for the table in the DELETE query
+   * @param alias - The alias to assign to the table
+   * @returns A new DeleteQueryState with the table alias set
+   */
   withTableAlias(alias: string): DeleteQueryState {
     return this.clone({
       ...this.ast,

package/src/query-builder/delete.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, DeleteCompiler, 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, DeleteQueryNode } from '../core/ast/query.js';
 import { DeleteQueryState } from './delete-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 DeleteDialectInput = Dialect | DialectKey;
 
@@ -18,6 +20,11 @@ export class DeleteQueryBuilder<T> {
   private readonly table: TableDef;
   private readonly state: DeleteQueryState;
 
+  /**
+   * Creates a new DeleteQueryBuilder instance
+   * @param table - The table definition for the DELETE query
+   * @param state - Optional initial query state, defaults to a new DeleteQueryState
+   */
   constructor(table: TableDef, state?: DeleteQueryState) {
     this.table = table;
     this.state = state ?? new DeleteQueryState(table);
@@ -27,18 +34,41 @@ export class DeleteQueryBuilder<T> {
     return new DeleteQueryBuilder(this.table, state);
   }
 
+  /**
+   * Adds a WHERE clause to the DELETE query
+   * @param expr - The expression to use as the WHERE condition
+   * @returns A new DeleteQueryBuilder with the WHERE clause added
+   */
   where(expr: ExpressionNode): DeleteQueryBuilder<T> {
     return this.clone(this.state.withWhere(expr));
   }
 
+  /**
+   * Sets an alias for the table in the DELETE query
+   * @param alias - The alias to assign to the table
+   * @returns A new DeleteQueryBuilder with the table alias set
+   */
   as(alias: string): DeleteQueryBuilder<T> {
     return this.clone(this.state.withTableAlias(alias));
   }
 
+  /**
+   * Adds a USING clause to the DELETE query
+   * @param source - The table source to use in the USING clause
+   * @returns A new DeleteQueryBuilder with the USING clause added
+   */
   using(source: TableDef | TableSourceNode): DeleteQueryBuilder<T> {
     return this.clone(this.state.withUsing(this.resolveTableSource(source)));
   }
 
+  /**
+   * Adds a JOIN clause to the DELETE 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 DeleteQueryBuilder with the JOIN clause added
+   */
   join(
     table: TableDef | TableSourceNode | string,
     condition: ExpressionNode,
@@ -50,6 +80,11 @@ export class DeleteQueryBuilder<T> {
     return this.clone(this.state.withJoin(joinNode));
   }
 
+  /**
+   * Adds a RETURNING clause to the DELETE query
+   * @param columns - The columns to return after deletion
+   * @returns A new DeleteQueryBuilder with the RETURNING clause added
+   */
   returning(...columns: (ColumnDef | ColumnNode)[]): DeleteQueryBuilder<T> {
     if (!columns.length) return this;
     const nodes = columns.map(column => buildColumnNode(this.table, column));
@@ -68,29 +103,39 @@ export class DeleteQueryBuilder<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: DeleteCompiler): CompiledQuery;
-  // 2) New ergonomic overload:
-  compile(dialect: DeleteDialectInput): CompiledQuery;
-
-  compile(arg: DeleteCompiler | DeleteDialectInput): CompiledQuery {
-    const candidate = arg as { compileDelete?: (ast: DeleteQueryNode) => CompiledQuery };
-    if (typeof candidate.compileDelete === 'function') {
-      // DeleteCompiler path – old behavior
-      return candidate.compileDelete(this.state.ast);
-    }
+  /**
+   * Compiles the DELETE query for the specified dialect
+   * @param dialect - The SQL dialect to compile for
+   * @returns The compiled query with SQL and parameters
+   */
+  compile(dialect: DeleteDialectInput): CompiledQuery {
+    const resolved = resolveDialectInput(dialect);
+    return resolved.compileDelete(this.state.ast);
+  }
 
-    // Dialect | string path – new behavior
-    const dialect = resolveDialectInput(arg as DeleteDialectInput);
-    return dialect.compileDelete(this.state.ast);
+  /**
+   * Returns the SQL string for the DELETE query
+   * @param dialect - The SQL dialect to generate SQL for
+   * @returns The SQL string representation of the query
+   */
+  toSql(dialect: DeleteDialectInput): string {
+    return this.compile(dialect).sql;
   }
 
-  toSql(arg: DeleteCompiler | DeleteDialectInput): string {
-    return this.compile(arg as DeleteCompiler).sql;
+  /**
+   * Executes the DELETE 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 DELETE query
+   */
   getAST(): DeleteQueryNode {
     return this.state.ast;
   }

package/src/query-builder/hydration-manager.ts

@@ -113,6 +113,11 @@ export class HydrationManager {
     return hasPagination && this.hasMultiplyingRelations(plan);
   }
 
+  /**
+   * Checks if the hydration plan contains relations that multiply rows
+   * @param plan - Hydration plan to check
+   * @returns True if plan has HasMany or BelongsToMany relations
+   */
   private hasMultiplyingRelations(plan: HydrationPlan): boolean {
     return plan.relations.some(
       rel => rel.type === RelationKinds.HasMany || rel.type === RelationKinds.BelongsToMany
@@ -203,6 +208,12 @@ export class HydrationManager {
     };
   }
 
+  /**
+   * Generates a unique CTE name by appending a suffix if needed
+   * @param existing - Existing CTE nodes
+   * @param baseName - Base name for the CTE
+   * @returns Unique CTE name
+   */
   private nextCteName(existing: CommonTableExpressionNode[] | undefined, baseName: string): string {
     const names = new Set((existing ?? []).map(cte => cte.name));
     let candidate = baseName;
@@ -216,6 +227,11 @@ export class HydrationManager {
     return candidate;
   }
 
+  /**
+   * Extracts projection names from column nodes
+   * @param columns - Projection nodes
+   * @returns Array of names or undefined if any column lacks name/alias
+   */
   private getProjectionNames(columns: ProjectionNode[]): string[] | undefined {
     const names: string[] = [];
     for (const col of columns) {
@@ -227,6 +243,11 @@ export class HydrationManager {
     return names;
   }
 
+  /**
+   * Builds a map of column keys to their aliases from projection nodes
+   * @param columns - Projection nodes
+   * @returns Map of 'table.name' to alias
+   */
   private buildProjectionAliasMap(columns: ProjectionNode[]): Map<string, string> {
     const map = new Map<string, string>();
     for (const col of columns) {
@@ -238,6 +259,15 @@ export class HydrationManager {
     return map;
   }
 
+  /**
+   * Maps order by nodes to use base CTE alias
+   * @param orderBy - Original order by nodes
+   * @param plan - Hydration plan
+   * @param projectionAliases - Map of column aliases
+   * @param baseAlias - Base CTE alias
+   * @param availableColumns - Set of available column names
+   * @returns Mapped order by nodes, null if cannot map
+   */
   private mapOrderBy(
     orderBy: OrderByNode[] | undefined,
     plan: HydrationPlan,
@@ -261,6 +291,15 @@ export class HydrationManager {
     return mapped;
   }
 
+  /**
+   * Maps a single ordering term to use base CTE alias
+   * @param term - Ordering term to map
+   * @param plan - Hydration plan
+   * @param projectionAliases - Map of column aliases
+   * @param baseAlias - Base CTE alias
+   * @param availableColumns - Set of available column names
+   * @returns Mapped term or null if cannot map
+   */
   private mapOrderingTerm(
     term: OrderByNode['term'],
     plan: HydrationPlan,
@@ -285,6 +324,13 @@ export class HydrationManager {
     return null;
   }
 
+  /**
+   * Builds column nodes for paging CTE
+   * @param primaryKey - Primary key name
+   * @param orderBy - Order by nodes
+   * @param tableAlias - Table alias for columns
+   * @returns Array of column nodes for paging
+   */
   private buildPagingColumns(primaryKey: string, orderBy: OrderByNode[] | undefined, tableAlias: string): ColumnNode[] {
     const columns: ColumnNode[] = [{ type: 'Column', table: tableAlias, name: primaryKey, alias: primaryKey }];
 

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

@@ -20,6 +20,11 @@ export class InsertQueryState {
   public readonly table: TableDef;
   public readonly ast: InsertQueryNode;
 
+  /**
+   * Creates a new InsertQueryState instance
+   * @param table - The table definition for the INSERT query
+   * @param ast - Optional initial AST node, defaults to a basic INSERT query
+   */
   constructor(table: TableDef, ast?: InsertQueryNode) {
     this.table = table;
     this.ast = ast ?? {
@@ -55,6 +60,13 @@ export class InsertQueryState {
     return buildColumnNodes(this.table, names);
   }
 
+  /**
+   * Adds VALUES clause to the INSERT query
+   * @param rows - Array of row objects to insert
+   * @returns A new InsertQueryState with the VALUES clause added
+   * @throws Error if mixing VALUES with SELECT source
+   * @throws Error if invalid values are provided
+   */
   withValues(rows: Record<string, unknown>[]): InsertQueryState {
     if (!rows.length) return this;
 
@@ -88,6 +100,11 @@ export class InsertQueryState {
     });
   }
 
+  /**
+   * Sets the columns for the INSERT query
+   * @param columns - Column nodes to insert into
+   * @returns A new InsertQueryState with the specified columns
+   */
   withColumns(columns: ColumnNode[]): InsertQueryState {
     if (!columns.length) return this;
     return this.clone({
@@ -96,6 +113,14 @@ export class InsertQueryState {
     });
   }
 
+  /**
+   * Adds SELECT source to the INSERT query
+   * @param query - The SELECT query to use as source
+   * @param columns - Target columns for the INSERT
+   * @returns A new InsertQueryState with the SELECT source
+   * @throws Error if mixing SELECT with VALUES source
+   * @throws Error if no destination columns specified
+   */
   withSelect(query: SelectQueryNode, columns: ColumnNode[]): InsertQueryState {
     const targetColumns =
       columns.length
@@ -122,6 +147,11 @@ export class InsertQueryState {
     });
   }
 
+  /**
+   * Adds a RETURNING clause to the INSERT query
+   * @param columns - Columns to return after insertion
+   * @returns A new InsertQueryState with the RETURNING clause added
+   */
   withReturning(columns: ColumnNode[]): InsertQueryState {
     return this.clone({
       ...this.ast,

package/src/query-builder/insert.ts

@@ -17,6 +17,11 @@ export class InsertQueryBuilder<T> {
   private readonly table: TableDef;
   private readonly state: InsertQueryState;
 
+  /**
+   * Creates a new InsertQueryBuilder instance
+   * @param table - The table definition for the INSERT query
+   * @param state - Optional initial query state, defaults to a new InsertQueryState
+   */
   constructor(table: TableDef, state?: InsertQueryState) {
     this.table = table;
     this.state = state ?? new InsertQueryState(table);
@@ -26,17 +31,34 @@ export class InsertQueryBuilder<T> {
     return new InsertQueryBuilder(this.table, state);
   }
 
+  /**
+   * Adds VALUES to the INSERT query
+   * @param rowOrRows - Single row object or array of row objects to insert
+   * @returns A new InsertQueryBuilder with the VALUES clause added
+   */
   values(rowOrRows: Record<string, unknown> | Record<string, unknown>[]): InsertQueryBuilder<T> {
     const rows = Array.isArray(rowOrRows) ? rowOrRows : [rowOrRows];
     if (!rows.length) return this;
     return this.clone(this.state.withValues(rows));
   }
 
+  /**
+   * Specifies the columns for the INSERT query
+   * @param columns - Column definitions or nodes to insert into
+   * @returns A new InsertQueryBuilder with the specified columns
+   */
   columns(...columns: (ColumnDef | ColumnNode)[]): InsertQueryBuilder<T> {
     if (!columns.length) return this;
     return this.clone(this.state.withColumns(this.resolveColumnNodes(columns)));
   }
 
+  /**
+   * Sets the source of the INSERT query to a SELECT query
+   * @template TSource - The source table type
+   * @param query - The SELECT query or query builder to use as source
+   * @param columns - Optional target columns for the INSERT
+   * @returns A new InsertQueryBuilder with the SELECT source
+   */
   fromSelect<TSource extends TableDef>(
     query: SelectQueryNode | SelectQueryBuilder<unknown, TSource>,
     columns: (ColumnDef | ColumnNode)[] = []
@@ -46,6 +68,11 @@ export class InsertQueryBuilder<T> {
     return this.clone(this.state.withSelect(ast, nodes));
   }
 
+  /**
+   * Adds a RETURNING clause to the INSERT query
+   * @param columns - Columns to return after insertion
+   * @returns A new InsertQueryBuilder with the RETURNING clause added
+   */
   returning(...columns: (ColumnDef | ColumnNode)[]): InsertQueryBuilder<T> {
     if (!columns.length) return this;
     const nodes = columns.map(column => buildColumnNode(this.table, column));
@@ -68,9 +95,17 @@ export class InsertQueryBuilder<T> {
 
   // Existing compiler-based compile stays, but we add a new overload.
 
-  // 1) Keep the old behavior (used internally / tests, if any):
+  /**
+   * Compiles the INSERT query
+   * @param compiler - The INSERT compiler to use
+   * @returns The compiled query with SQL and parameters
+   */
   compile(compiler: InsertCompiler): CompiledQuery;
-  // 2) New ergonomic overload:
+  /**
+   * Compiles the INSERT query for the specified dialect
+   * @param dialect - The SQL dialect to compile for
+   * @returns The compiled query with SQL and parameters
+   */
   compile(dialect: InsertDialectInput): CompiledQuery;
 
   compile(arg: InsertCompiler | InsertDialectInput): CompiledQuery {
@@ -85,10 +120,19 @@ export class InsertQueryBuilder<T> {
     return dialect.compileInsert(this.state.ast);
   }
 
+  /**
+   * Returns the SQL string for the INSERT query
+   * @param arg - The compiler or dialect to generate SQL for
+   * @returns The SQL string representation of the query
+   */
   toSql(arg: InsertCompiler | InsertDialectInput): string {
     return this.compile(arg as InsertCompiler).sql;
   }
 
+  /**
+   * Returns the Abstract Syntax Tree (AST) representation of the query
+   * @returns The AST node for the INSERT query
+   */
   getAST(): InsertQueryNode {
     return this.state.ast;
   }

package/src/query-builder/query-ast-service.ts

@@ -251,6 +251,11 @@ export class QueryAstService {
     return existing ? and(existing, next) : next;
   }
 
+  /**
+   * Normalizes an ordering term to a standard OrderingTerm
+   * @param term - Column definition or ordering term to normalize
+   * @returns Normalized ordering term
+   */
   private normalizeOrderingTerm(term: ColumnDef | OrderingTerm): OrderingTerm {
     const from = this.state.ast.from;
     const tableRef = from.type === 'Table' && from.alias ? { ...this.table, alias: from.alias } : this.table;

package/src/query-builder/query-resolution.ts

@@ -0,0 +1,78 @@
+import { SelectQueryNode, UpdateQueryNode, DeleteQueryNode, TableSourceNode } from '../core/ast/query.js';
+import { TableDef } from '../schema/table.js';
+import type { SelectQueryBuilder } from './select.js';
+import type { UpdateQueryBuilder } from './update.js';
+import type { DeleteQueryBuilder } from './delete.js';
+
+/**
+ * Resolves a SelectQueryBuilder or SelectQueryNode to a SelectQueryNode AST
+ * @param query - Query builder or AST node
+ * @returns SelectQueryNode AST
+ */
+export function resolveSelectQuery<TSub extends TableDef>(
+    query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode
+): SelectQueryNode {
+    const candidate = query as { getAST?: () => SelectQueryNode };
+    return typeof candidate.getAST === 'function' && candidate.getAST
+        ? candidate.getAST()
+        : (query as SelectQueryNode);
+}
+
+/**
+ * Resolves a UpdateQueryBuilder or UpdateQueryNode to a UpdateQueryNode AST
+ * @param query - Query builder or AST node
+ * @returns UpdateQueryNode AST
+ */
+export function resolveUpdateQuery<T>(
+    query: UpdateQueryBuilder<T> | UpdateQueryNode
+): UpdateQueryNode {
+    const candidate = query as { getAST?: () => UpdateQueryNode };
+    return typeof candidate.getAST === 'function' && candidate.getAST
+        ? candidate.getAST()
+        : (query as UpdateQueryNode);
+}
+
+/**
+ * Resolves a DeleteQueryBuilder or DeleteQueryNode to a DeleteQueryNode AST
+ * @param query - Query builder or AST node
+ * @returns DeleteQueryNode AST
+ */
+export function resolveDeleteQuery<T>(
+    query: DeleteQueryBuilder<T> | DeleteQueryNode
+): DeleteQueryNode {
+    const candidate = query as { getAST?: () => DeleteQueryNode };
+    return typeof candidate.getAST === 'function' && candidate.getAST
+        ? candidate.getAST()
+        : (query as DeleteQueryNode);
+}
+
+/**
+ * Resolves a TableDef or TableSourceNode to a TableSourceNode
+ * @param source - Table definition or source node
+ * @returns TableSourceNode
+ */
+export function resolveTableSource(source: TableDef | TableSourceNode): TableSourceNode {
+    if (isTableSourceNode(source)) {
+        return source;
+    }
+    return { type: 'Table', name: source.name, schema: source.schema };
+}
+
+/**
+ * Resolves a join target (TableDef, TableSourceNode, or string relation name)
+ * @param table - Join target
+ * @returns TableSourceNode or string
+ */
+export function resolveJoinTarget(table: TableDef | TableSourceNode | string): TableSourceNode | string {
+    if (typeof table === 'string') return table;
+    return resolveTableSource(table);
+}
+
+/**
+ * Type guard to check if a value is a TableSourceNode
+ * @param source - Value to check
+ * @returns True if value is a TableSourceNode
+ */
+function isTableSourceNode(source: TableDef | TableSourceNode): source is TableSourceNode {
+    return typeof (source as TableSourceNode).type === 'string';
+}

package/src/query-builder/raw-column-parser.ts

@@ -4,6 +4,11 @@ import { CommonTableExpressionNode } from '../core/ast/query.js';
 /**
  * Best-effort helper that tries to convert a raw column expression into a `ColumnNode`.
  * This parser is intentionally limited; use it only for simple references or function calls.
+ *
+ * @param col - Raw column expression string (e.g., "column", "table.column", "COUNT(column)")
+ * @param tableName - Default table name to use when no table is specified
+ * @param ctes - Optional array of CTEs for context when parsing column references
+ * @returns A ColumnNode representing the parsed column expression
  */
 export const parseRawColumn = (
   col: string,

package/src/query-builder/relation-alias.ts

@@ -19,6 +19,9 @@ export interface RelationAliasParts {
 
 /**
  * Builds a relation alias from the relation name and column name components.
+ * @param relationName - The name of the relation
+ * @param columnName - The name of the column within the relation
+ * @returns A relation alias string in the format "relationName__columnName"
  */
 export const makeRelationAlias = (relationName: string, columnName: string): string =>
   `${relationName}${RELATION_SEPARATOR}${columnName}`;
@@ -26,6 +29,8 @@ export const makeRelationAlias = (relationName: string, columnName: string): str
 /**
  * Parses a relation alias into its relation/column components.
  * Returns `null` when the alias does not follow the `relation__column` pattern.
+ * @param alias - The relation alias string to parse
+ * @returns Parsed relation alias parts or null if not a valid relation alias
  */
 export const parseRelationAlias = (alias: string): RelationAliasParts | null => {
   const idx = alias.indexOf(RELATION_SEPARATOR);
@@ -38,6 +43,8 @@ export const parseRelationAlias = (alias: string): RelationAliasParts | null =>
 
 /**
  * Determines whether an alias represents a relation column by checking the `__` convention.
+ * @param alias - The alias string to check
+ * @returns True if the alias follows the relation alias pattern
  */
 export const isRelationAlias = (alias?: string): boolean =>
   !!alias && alias.includes(RELATION_SEPARATOR);