metal-orm 1.0.4 → 1.0.6

package/src/ast/query.ts

@@ -1,4 +1,12 @@
-import { ColumnNode, FunctionNode, ExpressionNode, ScalarSubqueryNode, CaseExpressionNode, WindowFunctionNode } from './expression';
+import {
+  ColumnNode,
+  FunctionNode,
+  ExpressionNode,
+  ScalarSubqueryNode,
+  CaseExpressionNode,
+  WindowFunctionNode,
+  OperandNode
+} from './expression';
 import { JoinNode } from './join';
 import { RelationType } from '../schema/relation';
 import { OrderDirection } from '../constants/sql';
@@ -27,27 +35,39 @@ export interface OrderByNode {
   direction: OrderDirection;
 }
 
-/**
- * Plan for hydrating relationship data
- */
-export interface HydrationRelationPlan {
-  /** Name of the relationship */
-  name: string;
-  /** Alias prefix for the relationship */
-  aliasPrefix: string;
-  /** Type of relationship */
-  type: RelationType;
-  /** Target table name */
-  targetTable: string;
-  /** Target table primary key */
-  targetPrimaryKey: string;
-  /** Foreign key column */
-  foreignKey: string;
-  /** Local key column */
-  localKey: string;
-  /** Columns to include */
-  columns: string[];
-}
+/**
+ * Plan describing pivot columns needed for hydration
+ */
+export interface HydrationPivotPlan {
+  table: string;
+  primaryKey: string;
+  aliasPrefix: string;
+  columns: string[];
+}
+
+/**
+ * Plan for hydrating relationship data
+ */
+export interface HydrationRelationPlan {
+  /** Name of the relationship */
+  name: string;
+  /** Alias prefix for the relationship */
+  aliasPrefix: string;
+  /** Type of relationship */
+  type: RelationType;
+  /** Target table name */
+  targetTable: string;
+  /** Target table primary key */
+  targetPrimaryKey: string;
+  /** Foreign key column */
+  foreignKey: string;
+  /** Local key column */
+  localKey: string;
+  /** Columns to include */
+  columns: string[];
+  /** Optional pivot plan for many-to-many relationships */
+  pivot?: HydrationPivotPlan;
+}
 
 /**
  * Complete hydration plan for a query
@@ -89,30 +109,71 @@ export interface CommonTableExpressionNode {
 /**
  * AST node representing a complete SELECT query
  */
-export interface SelectQueryNode {
-  type: 'SelectQuery';
-  /** Optional CTEs (WITH clauses) */
-  ctes?: CommonTableExpressionNode[];
-  /** FROM clause table */
-  from: TableNode;
-  /** 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?: QueryMetadata;
-  /** Optional DISTINCT clause */
-  distinct?: ColumnNode[];
-}
+export interface SelectQueryNode {
+  type: 'SelectQuery';
+  /** Optional CTEs (WITH clauses) */
+  ctes?: CommonTableExpressionNode[];
+  /** FROM clause table */
+  from: TableNode;
+  /** 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?: QueryMetadata;
+  /** Optional DISTINCT clause */
+  distinct?: ColumnNode[];
+}
+
+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[];
+}

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

@@ -0,0 +1,42 @@
+import { TableDef } from '../schema/table';
+import { ColumnNode, ExpressionNode } from '../ast/expression';
+import { TableNode, DeleteQueryNode } from '../ast/query';
+
+const createTableNode = (table: TableDef): TableNode => ({
+  type: 'Table',
+  name: table.name
+});
+
+/**
+ * Maintains immutable state for DELETE queries
+ */
+export class DeleteQueryState {
+  public readonly table: TableDef;
+  public readonly ast: DeleteQueryNode;
+
+  constructor(table: TableDef, ast?: DeleteQueryNode) {
+    this.table = table;
+    this.ast = ast ?? {
+      type: 'DeleteQuery',
+      from: createTableNode(table)
+    };
+  }
+
+  private clone(nextAst: DeleteQueryNode): DeleteQueryState {
+    return new DeleteQueryState(this.table, nextAst);
+  }
+
+  withWhere(expr: ExpressionNode): DeleteQueryState {
+    return this.clone({
+      ...this.ast,
+      where: expr
+    });
+  }
+
+  withReturning(columns: ColumnNode[]): DeleteQueryState {
+    return this.clone({
+      ...this.ast,
+      returning: [...columns]
+    });
+  }
+}

package/src/builder/delete.ts

@@ -0,0 +1,57 @@
+import { TableDef } from '../schema/table';
+import { ColumnDef } from '../schema/column';
+import { ColumnNode, ExpressionNode } from '../ast/expression';
+import { CompiledQuery, DeleteCompiler } from '../dialect/abstract';
+import { DeleteQueryNode } from '../ast/query';
+import { DeleteQueryState } from './delete-query-state';
+
+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
+  };
+};
+
+/**
+ * Builder for DELETE queries
+ */
+export class DeleteQueryBuilder<T> {
+  private readonly table: TableDef;
+  private readonly state: DeleteQueryState;
+
+  constructor(table: TableDef, state?: DeleteQueryState) {
+    this.table = table;
+    this.state = state ?? new DeleteQueryState(table);
+  }
+
+  private clone(state: DeleteQueryState): DeleteQueryBuilder<T> {
+    return new DeleteQueryBuilder(this.table, state);
+  }
+
+  where(expr: ExpressionNode): DeleteQueryBuilder<T> {
+    return this.clone(this.state.withWhere(expr));
+  }
+
+  returning(...columns: (ColumnDef | ColumnNode)[]): DeleteQueryBuilder<T> {
+    if (!columns.length) return this;
+    const nodes = columns.map(column => buildColumnNode(this.table, column));
+    return this.clone(this.state.withReturning(nodes));
+  }
+
+  compile(compiler: DeleteCompiler): CompiledQuery {
+    return compiler.compileDelete(this.state.ast);
+  }
+
+  toSql(compiler: DeleteCompiler): string {
+    return this.compile(compiler).sql;
+  }
+
+  getAST(): DeleteQueryNode {
+    return this.state.ast;
+  }
+}

package/src/builder/hydration-manager.ts

@@ -52,10 +52,11 @@ export class HydrationManager {
     relation: RelationDef,
     relationName: string,
     aliasPrefix: string,
-    targetColumns: string[]
+    targetColumns: string[],
+    pivot?: { aliasPrefix: string; columns: string[] }
   ): HydrationManager {
     const withRoots = this.planner.captureRootColumns(state.ast.columns);
-    const next = withRoots.includeRelation(relation, relationName, aliasPrefix, targetColumns);
+    const next = withRoots.includeRelation(relation, relationName, aliasPrefix, targetColumns, pivot);
     return this.clone(next);
   }
 

package/src/builder/hydration-planner.ts

@@ -1,8 +1,9 @@
 import { TableDef } from '../schema/table';
-import { RelationDef, RelationKinds } from '../schema/relation';
+import { RelationDef, RelationKinds, BelongsToManyRelation } from '../schema/relation';
 import { ProjectionNode } from './select-query-state';
 import { HydrationPlan, HydrationRelationPlan } from '../ast/query';
 import { isRelationAlias } from '../utils/relation-alias';
+import { buildDefaultPivotColumns } from './relation-utils';
 
 /**
  * Finds the primary key column name for a table
@@ -13,114 +14,169 @@ export const findPrimaryKey = (table: TableDef): string => {
   const pk = Object.values(table.columns).find(c => c.primary);
   return pk?.name || 'id';
 };
-
-/**
- * Manages hydration planning for query results
- */
-export class HydrationPlanner {
-  /**
-   * Creates a new HydrationPlanner instance
-   * @param table - Table definition
-   * @param plan - Optional existing hydration plan
-   */
-  constructor(private readonly table: TableDef, private readonly plan?: HydrationPlan) { }
-
-  /**
-   * Captures root table columns for hydration planning
-   * @param columns - Columns to capture
-   * @returns Updated HydrationPlanner with captured columns
-   */
+
+/**
+ * Manages hydration planning for query results
+ */
+export class HydrationPlanner {
+  /**
+   * Creates a new HydrationPlanner instance
+   * @param table - Table definition
+   * @param plan - Optional existing hydration plan
+   */
+  constructor(private readonly table: TableDef, private readonly plan?: HydrationPlan) { }
+
+  /**
+   * Captures root table columns for hydration planning
+   * @param columns - Columns to capture
+   * @returns Updated HydrationPlanner with captured columns
+   */
   captureRootColumns(columns: ProjectionNode[]): HydrationPlanner {
     const currentPlan = this.getPlanOrDefault();
-    const rootCols = new Set(currentPlan.rootColumns);
-    let changed = false;
-
-    columns.forEach(node => {
-      if (node.type !== 'Column') return;
-      if (node.table !== this.table.name) return;
-
-      const alias = node.alias || node.name;
-      if (isRelationAlias(alias)) return;
-      if (!rootCols.has(alias)) {
-        rootCols.add(alias);
-        changed = true;
-      }
-    });
-
-    if (!changed) return this;
-    return new HydrationPlanner(this.table, {
-      ...currentPlan,
-      rootColumns: Array.from(rootCols)
-    });
-  }
-
-  /**
-   * Includes a relation in the hydration plan
-   * @param rel - Relation definition
-   * @param relationName - Name of the relation
-   * @param aliasPrefix - Alias prefix for relation columns
-   * @param columns - Columns to include from the relation
-   * @returns Updated HydrationPlanner with included relation
-   */
-  includeRelation(rel: RelationDef, relationName: string, aliasPrefix: string, columns: string[]): HydrationPlanner {
-    const currentPlan = this.getPlanOrDefault();
-    const relations = currentPlan.relations.filter(r => r.name !== relationName);
-    relations.push(this.buildRelationPlan(rel, relationName, aliasPrefix, columns));
-    return new HydrationPlanner(this.table, {
-      ...currentPlan,
-      relations
-    });
-  }
-
-  /**
-   * Gets the current hydration plan
-   * @returns Current hydration plan or undefined
-   */
-  getPlan(): HydrationPlan | undefined {
-    return this.plan;
-  }
-
-  /**
-   * Gets the current hydration plan or creates a default one
-   * @returns Current hydration plan or default plan
-   */
-  private getPlanOrDefault(): HydrationPlan {
-    return this.plan ?? buildDefaultHydrationPlan(this.table);
-  }
-
-  /**
-   * Builds a relation plan for hydration
-   * @param rel - Relation definition
-   * @param relationName - Name of the relation
-   * @param aliasPrefix - Alias prefix for relation columns
-   * @param columns - Columns to include from the relation
-   * @returns Hydration relation plan
-   */
-  private buildRelationPlan(rel: RelationDef, relationName: string, aliasPrefix: string, columns: string[]): HydrationRelationPlan {
-    const localKeyFallback =
-      rel.type === RelationKinds.HasMany ? findPrimaryKey(this.table) : findPrimaryKey(rel.target);
+    const rootCols = new Set(currentPlan.rootColumns);
+    let changed = false;
+
+    columns.forEach(node => {
+      if (node.type !== 'Column') return;
+      if (node.table !== this.table.name) return;
+
+      const alias = node.alias || node.name;
+      if (isRelationAlias(alias)) return;
+      if (!rootCols.has(alias)) {
+        rootCols.add(alias);
+        changed = true;
+      }
+    });
+
+    if (!changed) return this;
+    return new HydrationPlanner(this.table, {
+      ...currentPlan,
+      rootColumns: Array.from(rootCols)
+    });
+  }
+
+  /**
+   * Includes a relation in the hydration plan
+   * @param rel - Relation definition
+   * @param relationName - Name of the relation
+   * @param aliasPrefix - Alias prefix for relation columns
+   * @param columns - Columns to include from the relation
+   * @returns Updated HydrationPlanner with included relation
+   */
+  includeRelation(
+    rel: RelationDef,
+    relationName: string,
+    aliasPrefix: string,
+    columns: string[],
+    pivot?: { aliasPrefix: string; columns: string[] }
+  ): HydrationPlanner {
+    const currentPlan = this.getPlanOrDefault();
+    const relations = currentPlan.relations.filter(r => r.name !== relationName);
+    relations.push(this.buildRelationPlan(rel, relationName, aliasPrefix, columns, pivot));
+    return new HydrationPlanner(this.table, {
+      ...currentPlan,
+      relations
+    });
+  }
+
+  /**
+   * Gets the current hydration plan
+   * @returns Current hydration plan or undefined
+   */
+  getPlan(): HydrationPlan | undefined {
+    return this.plan;
+  }
+
+  /**
+   * Gets the current hydration plan or creates a default one
+   * @returns Current hydration plan or default plan
+   */
+  private getPlanOrDefault(): HydrationPlan {
+    return this.plan ?? buildDefaultHydrationPlan(this.table);
+  }
 
-    return {
-      name: relationName,
-      aliasPrefix,
-      type: rel.type,
-      targetTable: rel.target.name,
-      targetPrimaryKey: findPrimaryKey(rel.target),
-      foreignKey: rel.foreignKey,
-      localKey: rel.localKey || localKeyFallback,
-      columns
-    };
+  /**
+   * Builds a relation plan for hydration
+   * @param rel - Relation definition
+   * @param relationName - Name of the relation
+   * @param aliasPrefix - Alias prefix for relation columns
+   * @param columns - Columns to include from the relation
+   * @returns Hydration relation plan
+   */
+  private buildRelationPlan(
+    rel: RelationDef,
+    relationName: string,
+    aliasPrefix: string,
+    columns: string[],
+    pivot?: { aliasPrefix: string; columns: string[] }
+  ): HydrationRelationPlan {
+    switch (rel.type) {
+      case RelationKinds.HasMany: {
+        const localKey = rel.localKey || findPrimaryKey(this.table);
+        return {
+          name: relationName,
+          aliasPrefix,
+          type: rel.type,
+          targetTable: rel.target.name,
+          targetPrimaryKey: findPrimaryKey(rel.target),
+          foreignKey: rel.foreignKey,
+          localKey,
+          columns
+        };
+      }
+      case RelationKinds.BelongsTo: {
+        const localKey = rel.localKey || findPrimaryKey(rel.target);
+        return {
+          name: relationName,
+          aliasPrefix,
+          type: rel.type,
+          targetTable: rel.target.name,
+          targetPrimaryKey: findPrimaryKey(rel.target),
+          foreignKey: rel.foreignKey,
+          localKey,
+          columns
+        };
+      }
+      case RelationKinds.BelongsToMany: {
+        const many = rel as BelongsToManyRelation;
+        const localKey = many.localKey || findPrimaryKey(this.table);
+        const targetPk = many.targetKey || findPrimaryKey(many.target);
+        const pivotPk = many.pivotPrimaryKey || findPrimaryKey(many.pivotTable);
+        const pivotAliasPrefix = pivot?.aliasPrefix ?? `${aliasPrefix}_pivot`;
+        const pivotColumns =
+          pivot?.columns ??
+          many.defaultPivotColumns ??
+          buildDefaultPivotColumns(many, pivotPk);
+
+        return {
+          name: relationName,
+          aliasPrefix,
+          type: rel.type,
+          targetTable: many.target.name,
+          targetPrimaryKey: targetPk,
+          foreignKey: many.pivotForeignKeyToRoot,
+          localKey,
+          columns,
+          pivot: {
+            table: many.pivotTable.name,
+            primaryKey: pivotPk,
+            aliasPrefix: pivotAliasPrefix,
+            columns: pivotColumns
+          }
+        };
+      }
+    }
   }
-}
-
-/**
- * Builds a default hydration plan for a table
- * @param table - Table definition
- * @returns Default hydration plan
- */
+}
+
+/**
+ * Builds a default hydration plan for a table
+ * @param table - Table definition
+ * @returns Default hydration plan
+ */
 const buildDefaultHydrationPlan = (table: TableDef): HydrationPlan => ({
-  rootTable: table.name,
-  rootPrimaryKey: findPrimaryKey(table),
-  rootColumns: [],
-  relations: []
-});
+  rootTable: table.name,
+  rootPrimaryKey: findPrimaryKey(table),
+  rootColumns: [],
+  relations: []
+});

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

@@ -0,0 +1,62 @@
+import { TableDef } from '../schema/table';
+import { InsertQueryNode, TableNode } from '../ast/query';
+import { ColumnNode, OperandNode, valueToOperand } from '../ast/expression';
+
+const createTableNode = (table: TableDef): TableNode => ({
+  type: 'Table',
+  name: table.name
+});
+
+const buildColumnNodes = (table: TableDef, names: string[]): ColumnNode[] =>
+  names.map(name => ({
+    type: 'Column',
+    table: table.name,
+    name
+  }));
+
+/**
+ * Maintains immutable state for building INSERT queries
+ */
+export class InsertQueryState {
+  public readonly table: TableDef;
+  public readonly ast: InsertQueryNode;
+
+  constructor(table: TableDef, ast?: InsertQueryNode) {
+    this.table = table;
+    this.ast = ast ?? {
+      type: 'InsertQuery',
+      into: createTableNode(table),
+      columns: [],
+      values: []
+    };
+  }
+
+  private clone(nextAst: InsertQueryNode): InsertQueryState {
+    return new InsertQueryState(this.table, nextAst);
+  }
+
+  withValues(rows: Record<string, unknown>[]): InsertQueryState {
+    if (!rows.length) return this;
+
+    const definedColumns = this.ast.columns.length
+      ? this.ast.columns
+      : buildColumnNodes(this.table, Object.keys(rows[0]));
+
+    const newRows: OperandNode[][] = rows.map(row =>
+      definedColumns.map(column => valueToOperand(row[column.name]))
+    );
+
+    return this.clone({
+      ...this.ast,
+      columns: definedColumns,
+      values: [...this.ast.values, ...newRows]
+    });
+  }
+
+  withReturning(columns: ColumnNode[]): InsertQueryState {
+    return this.clone({
+      ...this.ast,
+      returning: [...columns]
+    });
+  }
+}