metal-orm 1.0.2 → 1.0.4

package/src/ast/join.ts

@@ -2,10 +2,17 @@ import { TableNode } from './query';
 import { ExpressionNode } from './expression';
 import { JoinKind } from '../constants/sql';
 
+/**
+ * AST node representing a JOIN clause
+ */
 export interface JoinNode {
   type: 'Join';
+  /** Type of join (INNER, LEFT, RIGHT, etc.) */
   kind: JoinKind;
+  /** Table to join */
   table: TableNode;
+  /** Join condition expression */
   condition: ExpressionNode;
-  relationName?: string; // Metadata for code generation to reconstruct .joinRelation()
+  /** Optional relation name for code generation */
+  relationName?: string;
 }

package/src/ast/query.ts

@@ -1,63 +1,118 @@
-import { ColumnNode, FunctionNode, ExpressionNode, ScalarSubqueryNode, CaseExpressionNode, WindowFunctionNode } from './expression';
-import { JoinNode } from './join';
-import { RelationType } from '../schema/relation';
-import { OrderDirection } from '../constants/sql';
+import { ColumnNode, FunctionNode, ExpressionNode, ScalarSubqueryNode, CaseExpressionNode, WindowFunctionNode } from './expression';
+import { JoinNode } from './join';
+import { RelationType } from '../schema/relation';
+import { OrderDirection } from '../constants/sql';
 
+/**
+ * AST node representing a table reference in a query
+ */
 export interface TableNode {
   type: 'Table';
+  /** Table name */
   name: string;
+  /** Optional schema name */
   schema?: string;
+  /** Optional table alias */
   alias?: string;
 }
 
-export interface OrderByNode {
-  type: 'OrderBy';
-  column: ColumnNode;
-  direction: OrderDirection;
-}
+/**
+ * AST node representing an ORDER BY clause
+ */
+export interface OrderByNode {
+  type: 'OrderBy';
+  /** Column to order by */
+  column: ColumnNode;
+  /** Order direction (ASC or DESC) */
+  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[];
 }
 
+/**
+ * Complete hydration plan for a query
+ */
 export interface HydrationPlan {
+  /** Root table name */
   rootTable: string;
+  /** Root table primary key */
   rootPrimaryKey: string;
+  /** Root table columns */
   rootColumns: string[];
+  /** Relationship hydration plans */
   relations: HydrationRelationPlan[];
 }
 
+/**
+ * Query metadata including hydration information
+ */
 export interface QueryMetadata {
+  /** Optional hydration plan */
   hydration?: HydrationPlan;
 }
 
+/**
+ * AST node representing a Common Table Expression (CTE)
+ */
 export interface CommonTableExpressionNode {
   type: 'CommonTableExpression';
+  /** CTE name */
   name: string;
+  /** Optional column names */
   columns?: string[];
+  /** CTE query */
   query: SelectQueryNode;
+  /** Whether the CTE is recursive */
   recursive: boolean;
 }
 
+/**
+ * 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[];
 }

package/src/builder/hydration-manager.ts

@@ -4,26 +4,49 @@ import { SelectQueryNode, HydrationPlan } from '../ast/query';
 import { HydrationPlanner } from './hydration-planner';
 import { SelectQueryState, ProjectionNode } from './select-query-state';
 
+/**
+ * Manages hydration planning for query results
+ */
 export class HydrationManager {
+  /**
+   * Creates a new HydrationManager instance
+   * @param table - Table definition
+   * @param planner - Hydration planner
+   */
   constructor(
     private readonly table: TableDef,
-    private readonly planner?: HydrationPlanner
+    private readonly planner: HydrationPlanner
   ) {}
 
-  private getPlanner(): HydrationPlanner {
-    return this.planner ?? new HydrationPlanner(this.table);
-  }
-
+  /**
+   * Creates a new HydrationManager with updated planner
+   * @param nextPlanner - Updated hydration planner
+   * @returns New HydrationManager instance
+   */
   private clone(nextPlanner: HydrationPlanner): HydrationManager {
     return new HydrationManager(this.table, nextPlanner);
   }
 
+  /**
+   * Handles column selection for hydration planning
+   * @param state - Current query state
+   * @param newColumns - Newly selected columns
+   * @returns Updated HydrationManager with captured columns
+   */
   onColumnsSelected(state: SelectQueryState, newColumns: ProjectionNode[]): HydrationManager {
-    const planner = this.getPlanner();
-    const updated = planner.captureRootColumns(state.ast.columns);
+    const updated = this.planner.captureRootColumns(newColumns);
     return this.clone(updated);
   }
 
+  /**
+   * Handles relation inclusion for hydration planning
+   * @param state - Current query state
+   * @param relation - Relation definition
+   * @param relationName - Name of the relation
+   * @param aliasPrefix - Alias prefix for the relation
+   * @param targetColumns - Target columns to include
+   * @returns Updated HydrationManager with included relation
+   */
   onRelationIncluded(
     state: SelectQueryState,
     relation: RelationDef,
@@ -31,14 +54,18 @@ export class HydrationManager {
     aliasPrefix: string,
     targetColumns: string[]
   ): HydrationManager {
-    const planner = this.getPlanner();
-    const withRoots = planner.captureRootColumns(state.ast.columns);
+    const withRoots = this.planner.captureRootColumns(state.ast.columns);
     const next = withRoots.includeRelation(relation, relationName, aliasPrefix, targetColumns);
     return this.clone(next);
   }
 
+  /**
+   * Applies hydration plan to the AST
+   * @param ast - Query AST to modify
+   * @returns AST with hydration metadata
+   */
   applyToAst(ast: SelectQueryNode): SelectQueryNode {
-    const plan = this.planner?.getPlan();
+    const plan = this.planner.getPlan();
     if (!plan) return ast;
     return {
       ...ast,
@@ -49,7 +76,11 @@ export class HydrationManager {
     };
   }
 
+  /**
+   * Gets the current hydration plan
+   * @returns Hydration plan or undefined if none exists
+   */
   getPlan(): HydrationPlan | undefined {
-    return this.planner?.getPlan();
+    return this.planner.getPlan();
   }
 }

package/src/builder/hydration-planner.ts

@@ -1,27 +1,37 @@
-import { TableDef } from '../schema/table';
-import { RelationDef } from '../schema/relation';
-import { ColumnNode, FunctionNode, ScalarSubqueryNode, CaseExpressionNode, WindowFunctionNode } from '../ast/expression';
-import { HydrationPlan, HydrationRelationPlan } from '../ast/query';
-
-export const findPrimaryKey = (table: TableDef): string => {
-  const pk = Object.values(table.columns).find(c => c.primary);
-  return pk?.name || 'id';
-};
-
-const buildDefaultHydrationPlan = (table: TableDef): HydrationPlan => ({
-  rootTable: table.name,
-  rootPrimaryKey: findPrimaryKey(table),
-  rootColumns: [],
-  relations: []
-});
-
-export const isRelationAlias = (alias?: string): boolean => alias ? alias.includes('__') : false;
+import { TableDef } from '../schema/table';
+import { RelationDef, RelationKinds } from '../schema/relation';
+import { ProjectionNode } from './select-query-state';
+import { HydrationPlan, HydrationRelationPlan } from '../ast/query';
+import { isRelationAlias } from '../utils/relation-alias';
+
+/**
+ * Finds the primary key column name for a table
+ * @param table - Table definition
+ * @returns Name of the primary key column, defaults to 'id'
+ */
+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) { }
 
-  captureRootColumns(columns: (ColumnNode | FunctionNode | ScalarSubqueryNode | CaseExpressionNode | WindowFunctionNode)[]): HydrationPlanner {
-    const currentPlan = this.getPlanOrDefault();
+  /**
+   * 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;
 
@@ -44,6 +54,14 @@ export class HydrationPlanner {
     });
   }
 
+  /**
+   * 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);
@@ -54,24 +72,55 @@ export class HydrationPlanner {
     });
   }
 
+  /**
+   * 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 {
-    return {
-      name: relationName,
-      aliasPrefix,
-      type: rel.type,
-      targetTable: rel.target.name,
-      targetPrimaryKey: findPrimaryKey(rel.target),
-      foreignKey: rel.foreignKey,
-      localKey: rel.localKey || 'id',
-      columns
-    };
-  }
+    const localKeyFallback =
+      rel.type === RelationKinds.HasMany ? findPrimaryKey(this.table) : findPrimaryKey(rel.target);
+
+    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 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: []
+});

package/src/builder/operations/column-selector.ts

@@ -1,13 +1,30 @@
 import { ColumnDef } from '../../schema/column';
-import { CaseExpressionNode, ColumnNode, FunctionNode, SelectQueryNode, WindowFunctionNode } from '../../ast/expression';
+import { CaseExpressionNode, ColumnNode, FunctionNode, WindowFunctionNode } from '../../ast/expression';
+import { SelectQueryNode } from '../../ast/query';
 import { buildColumnNode } from '../query-ast-service';
 import { SelectQueryBuilderContext, SelectQueryBuilderEnvironment } from '../select-query-builder-deps';
 
+/**
+ * Type for column selection input
+ */
 type ColumnSelectionInput = Record<string, ColumnDef | FunctionNode | CaseExpressionNode | WindowFunctionNode>;
 
+/**
+ * Handles column selection operations for the query builder
+ */
 export class ColumnSelector {
+  /**
+   * Creates a new ColumnSelector instance
+   * @param env - Query builder environment
+   */
   constructor(private readonly env: SelectQueryBuilderEnvironment) {}
 
+  /**
+   * Selects columns for the query
+   * @param context - Current query context
+   * @param columns - Columns to select
+   * @returns Updated query context with selected columns
+   */
   select(context: SelectQueryBuilderContext, columns: ColumnSelectionInput): SelectQueryBuilderContext {
     const astService = this.env.deps.createQueryAstService(this.env.table, context.state);
     const { state: nextState, addedColumns } = astService.select(columns);
@@ -17,12 +34,25 @@ export class ColumnSelector {
     };
   }
 
+  /**
+   * Selects raw column expressions
+   * @param context - Current query context
+   * @param columns - Raw column expressions
+   * @returns Updated query context with raw column selections
+   */
   selectRaw(context: SelectQueryBuilderContext, columns: string[]): SelectQueryBuilderContext {
     const astService = this.env.deps.createQueryAstService(this.env.table, context.state);
     const nextState = astService.selectRaw(columns).state;
     return { state: nextState, hydration: context.hydration };
   }
 
+  /**
+   * Selects a subquery as a column
+   * @param context - Current query context
+   * @param alias - Alias for the subquery
+   * @param query - Subquery to select
+   * @returns Updated query context with subquery selection
+   */
   selectSubquery(
     context: SelectQueryBuilderContext,
     alias: string,
@@ -33,6 +63,12 @@ export class ColumnSelector {
     return { state: nextState, hydration: context.hydration };
   }
 
+  /**
+   * Adds DISTINCT clause to the query
+   * @param context - Current query context
+   * @param columns - Columns to make distinct
+   * @returns Updated query context with DISTINCT clause
+   */
   distinct(context: SelectQueryBuilderContext, columns: (ColumnDef | ColumnNode)[]): SelectQueryBuilderContext {
     const nodes = columns.map(col => buildColumnNode(this.env.table, col));
     const astService = this.env.deps.createQueryAstService(this.env.table, context.state);

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

@@ -1,9 +1,25 @@
 import { SelectQueryNode } from '../../ast/query';
 import { SelectQueryBuilderContext, SelectQueryBuilderEnvironment } from '../select-query-builder-deps';
 
+/**
+ * Manages Common Table Expressions (CTEs) for query building
+ */
 export class CteManager {
+  /**
+   * Creates a new CteManager instance
+   * @param env - Query builder environment
+   */
   constructor(private readonly env: SelectQueryBuilderEnvironment) {}
 
+  /**
+   * Adds a Common Table Expression (CTE) to the query
+   * @param context - Current query context
+   * @param name - Name of the CTE
+   * @param query - Query for the CTE
+   * @param columns - Optional column names for the CTE
+   * @param recursive - Whether the CTE is recursive
+   * @returns Updated query context with CTE
+   */
   withCte(
     context: SelectQueryBuilderContext,
     name: string,

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

@@ -3,27 +3,59 @@ import { ColumnNode, ExpressionNode } from '../../ast/expression';
 import { SelectQueryBuilderContext, SelectQueryBuilderEnvironment } from '../select-query-builder-deps';
 import { OrderDirection } from '../../constants/sql';
 
+/**
+ * Manages filtering, ordering, and grouping operations for queries
+ */
 export class FilterManager {
+  /**
+   * Creates a new FilterManager instance
+   * @param env - Query builder environment
+   */
   constructor(private readonly env: SelectQueryBuilderEnvironment) {}
 
+  /**
+   * Adds a WHERE clause to the query
+   * @param context - Current query context
+   * @param expr - Expression for the WHERE clause
+   * @returns Updated query context with WHERE clause
+   */
   where(context: SelectQueryBuilderContext, expr: ExpressionNode): SelectQueryBuilderContext {
     const astService = this.env.deps.createQueryAstService(this.env.table, context.state);
     const nextState = astService.withWhere(expr);
     return { state: nextState, hydration: context.hydration };
   }
 
+  /**
+   * Adds a GROUP BY clause to the query
+   * @param context - Current query context
+   * @param column - Column to group by
+   * @returns Updated query context with GROUP BY clause
+   */
   groupBy(context: SelectQueryBuilderContext, column: ColumnDef | ColumnNode): SelectQueryBuilderContext {
     const astService = this.env.deps.createQueryAstService(this.env.table, context.state);
     const nextState = astService.withGroupBy(column);
     return { state: nextState, hydration: context.hydration };
   }
 
+  /**
+   * Adds a HAVING clause to the query
+   * @param context - Current query context
+   * @param expr - Expression for the HAVING clause
+   * @returns Updated query context with HAVING clause
+   */
   having(context: SelectQueryBuilderContext, expr: ExpressionNode): SelectQueryBuilderContext {
     const astService = this.env.deps.createQueryAstService(this.env.table, context.state);
     const nextState = astService.withHaving(expr);
     return { state: nextState, hydration: context.hydration };
   }
 
+  /**
+   * Adds an ORDER BY clause to the query
+   * @param context - Current query context
+   * @param column - Column to order by
+   * @param direction - Order direction (ASC/DESC)
+   * @returns Updated query context with ORDER BY clause
+   */
   orderBy(
     context: SelectQueryBuilderContext,
     column: ColumnDef | ColumnNode,

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

@@ -1,24 +1,34 @@
 import { BinaryExpressionNode } from '../../ast/expression';
-import { JoinNode } from '../../ast/join';
 import { TableDef } from '../../schema/table';
 import { SelectQueryBuilderContext, SelectQueryBuilderEnvironment } from '../select-query-builder-deps';
 import { JoinKind } from '../../constants/sql';
+import { createJoinNode } from '../../utils/join-node';
 
+/**
+ * Manages JOIN operations for query building
+ */
 export class JoinManager {
+  /**
+   * Creates a new JoinManager instance
+   * @param env - Query builder environment
+   */
   constructor(private readonly env: SelectQueryBuilderEnvironment) {}
 
+  /**
+   * Adds a JOIN clause to the query
+   * @param context - Current query context
+   * @param table - Table to join
+   * @param condition - Join condition expression
+   * @param kind - Type of join (INNER, LEFT, RIGHT, etc.)
+   * @returns Updated query context with JOIN clause
+   */
   join(
     context: SelectQueryBuilderContext,
     table: TableDef,
     condition: BinaryExpressionNode,
     kind: JoinKind
   ): SelectQueryBuilderContext {
-    const joinNode: JoinNode = {
-      type: 'Join',
-      kind,
-      table: { type: 'Table', name: table.name },
-      condition
-    };
+    const joinNode = createJoinNode(kind, table.name, condition);
     const astService = this.env.deps.createQueryAstService(this.env.table, context.state);
     const nextState = astService.withJoin(joinNode);
     return { state: nextState, hydration: context.hydration };

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

@@ -1,14 +1,33 @@
 import { SelectQueryBuilderContext, SelectQueryBuilderEnvironment } from '../select-query-builder-deps';
 
+/**
+ * Manages pagination operations (LIMIT and OFFSET) for queries
+ */
 export class PaginationManager {
+  /**
+   * Creates a new PaginationManager instance
+   * @param env - Query builder environment
+   */
   constructor(private readonly env: SelectQueryBuilderEnvironment) {}
 
+  /**
+   * Adds a LIMIT clause to the query
+   * @param context - Current query context
+   * @param value - Maximum number of rows to return
+   * @returns Updated query context with LIMIT clause
+   */
   limit(context: SelectQueryBuilderContext, value: number): SelectQueryBuilderContext {
     const astService = this.env.deps.createQueryAstService(this.env.table, context.state);
     const nextState = astService.withLimit(value);
     return { state: nextState, hydration: context.hydration };
   }
 
+  /**
+   * Adds an OFFSET clause to the query
+   * @param context - Current query context
+   * @param value - Number of rows to skip
+   * @returns Updated query context with OFFSET clause
+   */
   offset(context: SelectQueryBuilderContext, value: number): SelectQueryBuilderContext {
     const astService = this.env.deps.createQueryAstService(this.env.table, context.state);
     const nextState = astService.withOffset(value);