metal-orm 1.0.3 → 1.0.5

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
@@ -62,15 +63,21 @@ export class HydrationPlanner {
    * @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
-    });
-  }
+  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
@@ -96,31 +103,80 @@ export class HydrationPlanner {
    * @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);
+  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: rel.target.name,
-      targetPrimaryKey: findPrimaryKey(rel.target),
-      foreignKey: rel.foreignKey,
-      localKey: rel.localKey || localKeyFallback,
-      columns
-    };
+        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]
+    });
+  }
+}

package/src/builder/insert.ts

@@ -0,0 +1,59 @@
+import { TableDef } from '../schema/table';
+import { ColumnDef } from '../schema/column';
+import { ColumnNode } from '../ast/expression';
+import { CompiledQuery, InsertCompiler } from '../dialect/abstract';
+import { InsertQueryNode } from '../ast/query';
+import { InsertQueryState } from './insert-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 INSERT queries
+ */
+export class InsertQueryBuilder<T> {
+  private readonly table: TableDef;
+  private readonly state: InsertQueryState;
+
+  constructor(table: TableDef, state?: InsertQueryState) {
+    this.table = table;
+    this.state = state ?? new InsertQueryState(table);
+  }
+
+  private clone(state: InsertQueryState): InsertQueryBuilder<T> {
+    return new InsertQueryBuilder(this.table, state);
+  }
+
+  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));
+  }
+
+  returning(...columns: (ColumnDef | ColumnNode)[]): InsertQueryBuilder<T> {
+    if (!columns.length) return this;
+    const nodes = columns.map(column => buildColumnNode(this.table, column));
+    return this.clone(this.state.withReturning(nodes));
+  }
+
+  compile(compiler: InsertCompiler): CompiledQuery {
+    return compiler.compileInsert(this.state.ast);
+  }
+
+  toSql(compiler: InsertCompiler): string {
+    return this.compile(compiler).sql;
+  }
+
+  getAST(): InsertQueryNode {
+    return this.state.ast;
+  }
+}

package/src/builder/operations/relation-manager.ts

@@ -2,29 +2,7 @@ import { ExpressionNode } from '../../ast/expression';
 import { SelectQueryNode } from '../../ast/query';
 import { SelectQueryBuilderContext, SelectQueryBuilderEnvironment } from '../select-query-builder-deps';
 import { JoinKind } from '../../constants/sql';
-import { RelationIncludeJoinKind } from '../relation-types';
-
-/**
- * Options for including relations in queries
- */
-export interface RelationIncludeOptions {
-  /**
-   * Columns to include from the related table
-   */
-  columns?: string[];
-  /**
-   * Alias prefix for the relation columns
-   */
-  aliasPrefix?: string;
-  /**
-   * Filter expression to apply to the relation
-   */
-  filter?: ExpressionNode;
-  /**
-   * Type of join to use for the relation
-   */
-  joinKind?: RelationIncludeJoinKind;
-}
+import { RelationIncludeOptions } from '../relation-types';
 
 /**
  * Manages relation operations (joins, includes, etc.) for query building

package/src/builder/relation-conditions.ts

@@ -1,7 +1,10 @@
 import { TableDef } from '../schema/table';
-import { RelationDef, RelationKinds } from '../schema/relation';
+import { RelationDef, RelationKinds, BelongsToManyRelation } from '../schema/relation';
 import { ExpressionNode, eq, and } from '../ast/expression';
 import { findPrimaryKey } from './hydration-planner';
+import { JoinNode } from '../ast/join';
+import { JoinKind } from '../constants/sql';
+import { createJoinNode } from '../utils/join-node';
 
 /**
  * Utility function to handle unreachable code paths
@@ -36,11 +39,52 @@ const baseRelationCondition = (root: TableDef, relation: RelationDef): Expressio
         { type: 'Column', table: relation.target.name, name: localKey },
         { type: 'Column', table: root.name, name: relation.foreignKey }
       );
+    case RelationKinds.BelongsToMany:
+      throw new Error('BelongsToMany relations do not support the standard join condition builder');
     default:
       return assertNever(relation);
   }
 };
 
+/**
+ * Builds the join nodes required to include a BelongsToMany relation.
+ */
+export const buildBelongsToManyJoins = (
+  root: TableDef,
+  relationName: string,
+  relation: BelongsToManyRelation,
+  joinKind: JoinKind,
+  extra?: ExpressionNode
+): JoinNode[] => {
+  const rootKey = relation.localKey || findPrimaryKey(root);
+  const targetKey = relation.targetKey || findPrimaryKey(relation.target);
+
+  const pivotCondition = eq(
+    { type: 'Column', table: relation.pivotTable.name, name: relation.pivotForeignKeyToRoot },
+    { type: 'Column', table: root.name, name: rootKey }
+  );
+
+  const pivotJoin = createJoinNode(joinKind, relation.pivotTable.name, pivotCondition);
+
+  let targetCondition: ExpressionNode = eq(
+    { type: 'Column', table: relation.target.name, name: targetKey },
+    { type: 'Column', table: relation.pivotTable.name, name: relation.pivotForeignKeyToTarget }
+  );
+
+  if (extra) {
+    targetCondition = and(targetCondition, extra);
+  }
+
+  const targetJoin = createJoinNode(
+    joinKind,
+    relation.target.name,
+    targetCondition,
+    relationName
+  );
+
+  return [pivotJoin, targetJoin];
+};
+
 /**
  * Builds a relation join condition with optional extra conditions
  * @param root - Root table definition