metal-orm 1.0.2 → 1.0.3

package/src/builder/select-query-builder-deps.ts

@@ -1,18 +1,60 @@
 import { TableDef } from '../schema/table';
 import { SelectQueryState } from './select-query-state';
 import { HydrationManager } from './hydration-manager';
+import { HydrationPlanner } from './hydration-planner';
 import { QueryAstService } from './query-ast-service';
 import { RelationService } from './relation-service';
 
+/**
+ * Context for query building operations
+ */
 export interface SelectQueryBuilderContext {
+  /**
+   * Current query state
+   */
   readonly state: SelectQueryState;
+  /**
+   * Hydration manager for the query
+   */
   readonly hydration: HydrationManager;
 }
 
+/**
+ * Dependencies for query builder operations
+ */
 export interface SelectQueryBuilderDependencies {
+  /**
+   * Creates a new query state
+   * @param table - Table definition
+   * @returns New query state
+   */
   createState: (table: TableDef) => SelectQueryState;
+  /**
+   * Creates a new hydration manager
+   * @param table - Table definition
+   * @returns New hydration manager
+   */
   createHydration: (table: TableDef) => HydrationManager;
+  /**
+   * Creates a new hydration planner
+   * @param table - Table definition
+   * @returns Hydration planner
+   */
+  createHydrationPlanner: (table: TableDef) => HydrationPlanner;
+  /**
+   * Creates a new query AST service
+   * @param table - Table definition
+   * @param state - Query state
+   * @returns New query AST service
+   */
   createQueryAstService: (table: TableDef, state: SelectQueryState) => QueryAstService;
+  /**
+   * Creates a new relation service
+   * @param table - Table definition
+   * @param state - Query state
+   * @param hydration - Hydration manager
+   * @returns New relation service
+   */
   createRelationService: (
     table: TableDef,
     state: SelectQueryState,
@@ -20,14 +62,33 @@ export interface SelectQueryBuilderDependencies {
   ) => RelationService;
 }
 
+/**
+ * Environment for query builder operations
+ */
 export interface SelectQueryBuilderEnvironment {
+  /**
+   * Table definition
+   */
   readonly table: TableDef;
+  /**
+   * Query builder dependencies
+   */
   readonly deps: SelectQueryBuilderDependencies;
 }
 
+/**
+ * Default implementation of query builder dependencies
+ */
+const defaultCreateQueryAstService = (table: TableDef, state: SelectQueryState) => new QueryAstService(table, state);
+const defaultCreateHydrationPlanner = (table: TableDef) => new HydrationPlanner(table);
+const defaultCreateHydration = (table: TableDef) =>
+  new HydrationManager(table, defaultCreateHydrationPlanner(table));
+
 export const defaultSelectQueryBuilderDependencies: SelectQueryBuilderDependencies = {
   createState: table => new SelectQueryState(table),
-  createHydration: table => new HydrationManager(table),
-  createQueryAstService: (table, state) => new QueryAstService(table, state),
-  createRelationService: (table, state, hydration) => new RelationService(table, state, hydration)
+  createHydration: defaultCreateHydration,
+  createHydrationPlanner: defaultCreateHydrationPlanner,
+  createQueryAstService: defaultCreateQueryAstService,
+  createRelationService: (table, state, hydration) =>
+    new RelationService(table, state, hydration, defaultCreateQueryAstService)
 };

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

@@ -10,6 +10,9 @@ import {
 } from '../ast/expression';
 import { JoinNode } from '../ast/join';
 
+/**
+ * Node types that can be used in query projections
+ */
 export type ProjectionNode =
   | ColumnNode
   | FunctionNode
@@ -17,10 +20,24 @@ export type ProjectionNode =
   | CaseExpressionNode
   | WindowFunctionNode;
 
+/**
+ * Manages the state of a SELECT query being built
+ */
 export class SelectQueryState {
+  /**
+   * Table definition for the query
+   */
   public readonly table: TableDef;
+  /**
+   * Abstract Syntax Tree (AST) representation of the query
+   */
   public readonly ast: SelectQueryNode;
 
+  /**
+   * Creates a new SelectQueryState instance
+   * @param table - Table definition
+   * @param ast - Optional existing AST
+   */
   constructor(table: TableDef, ast?: SelectQueryNode) {
     this.table = table;
     this.ast = ast ?? {
@@ -31,10 +48,20 @@ export class SelectQueryState {
     };
   }
 
+  /**
+   * Creates a new SelectQueryState with updated AST
+   * @param nextAst - Updated AST
+   * @returns New SelectQueryState instance
+   */
   private clone(nextAst: SelectQueryNode): SelectQueryState {
     return new SelectQueryState(this.table, nextAst);
   }
 
+  /**
+   * Adds columns to the query
+   * @param newCols - Columns to add
+   * @returns New SelectQueryState with added columns
+   */
   withColumns(newCols: ProjectionNode[]): SelectQueryState {
     return this.clone({
       ...this.ast,
@@ -42,6 +69,11 @@ export class SelectQueryState {
     });
   }
 
+  /**
+   * Adds a join to the query
+   * @param join - Join node to add
+   * @returns New SelectQueryState with added join
+   */
   withJoin(join: JoinNode): SelectQueryState {
     return this.clone({
       ...this.ast,
@@ -49,6 +81,11 @@ export class SelectQueryState {
     });
   }
 
+  /**
+   * Adds a WHERE clause to the query
+   * @param predicate - WHERE predicate expression
+   * @returns New SelectQueryState with WHERE clause
+   */
   withWhere(predicate: ExpressionNode): SelectQueryState {
     return this.clone({
       ...this.ast,
@@ -56,6 +93,11 @@ export class SelectQueryState {
     });
   }
 
+  /**
+   * Adds a HAVING clause to the query
+   * @param predicate - HAVING predicate expression
+   * @returns New SelectQueryState with HAVING clause
+   */
   withHaving(predicate: ExpressionNode): SelectQueryState {
     return this.clone({
       ...this.ast,
@@ -63,6 +105,11 @@ export class SelectQueryState {
     });
   }
 
+  /**
+   * Adds GROUP BY columns to the query
+   * @param columns - Columns to group by
+   * @returns New SelectQueryState with GROUP BY clause
+   */
   withGroupBy(columns: ColumnNode[]): SelectQueryState {
     return this.clone({
       ...this.ast,
@@ -70,6 +117,11 @@ export class SelectQueryState {
     });
   }
 
+  /**
+   * Adds ORDER BY clauses to the query
+   * @param orderBy - ORDER BY nodes
+   * @returns New SelectQueryState with ORDER BY clause
+   */
   withOrderBy(orderBy: OrderByNode[]): SelectQueryState {
     return this.clone({
       ...this.ast,
@@ -77,6 +129,11 @@ export class SelectQueryState {
     });
   }
 
+  /**
+   * Adds DISTINCT columns to the query
+   * @param columns - Columns to make distinct
+   * @returns New SelectQueryState with DISTINCT clause
+   */
   withDistinct(columns: ColumnNode[]): SelectQueryState {
     return this.clone({
       ...this.ast,
@@ -84,6 +141,11 @@ export class SelectQueryState {
     });
   }
 
+  /**
+   * Adds a LIMIT clause to the query
+   * @param limit - Maximum number of rows to return
+   * @returns New SelectQueryState with LIMIT clause
+   */
   withLimit(limit: number): SelectQueryState {
     return this.clone({
       ...this.ast,
@@ -91,6 +153,11 @@ export class SelectQueryState {
     });
   }
 
+  /**
+   * Adds an OFFSET clause to the query
+   * @param offset - Number of rows to skip
+   * @returns New SelectQueryState with OFFSET clause
+   */
   withOffset(offset: number): SelectQueryState {
     return this.clone({
       ...this.ast,
@@ -98,6 +165,11 @@ export class SelectQueryState {
     });
   }
 
+  /**
+   * Adds a Common Table Expression (CTE) to the query
+   * @param cte - CTE node to add
+   * @returns New SelectQueryState with CTE
+   */
   withCte(cte: CommonTableExpressionNode): SelectQueryState {
     return this.clone({
       ...this.ast,

package/src/builder/select.ts

@@ -29,6 +29,10 @@ import { PaginationManager } from './operations/pagination-manager';
 import { RelationManager, RelationIncludeOptions } from './operations/relation-manager';
 import { JOIN_KINDS, JoinKind, ORDER_DIRECTIONS, OrderDirection } from '../constants/sql';
 
+/**
+ * Main query builder class for constructing SQL SELECT queries
+ * @typeParam T - Type of the result data
+ */
 export class SelectQueryBuilder<T> {
   private readonly env: SelectQueryBuilderEnvironment;
   private readonly context: SelectQueryBuilderContext;
@@ -39,6 +43,13 @@ export class SelectQueryBuilder<T> {
   private readonly paginationManager: PaginationManager;
   private readonly relationManager: RelationManager;
 
+  /**
+   * Creates a new SelectQueryBuilder instance
+   * @param table - Table definition to query
+   * @param state - Optional initial query state
+   * @param hydration - Optional hydration manager
+   * @param dependencies - Optional query builder dependencies
+   */
   constructor(
     table: TableDef,
     state?: SelectQueryState,
@@ -75,51 +86,112 @@ export class SelectQueryBuilder<T> {
     return new SelectQueryBuilder(table, undefined, undefined, this.env.deps);
   }
 
+  /**
+   * Selects specific columns for the query
+   * @param columns - Record of column definitions, function nodes, case expressions, or window functions
+   * @returns New query builder instance with selected columns
+   */
   select(columns: Record<string, ColumnDef | FunctionNode | CaseExpressionNode | WindowFunctionNode>): SelectQueryBuilder<T> {
     return this.clone(this.columnSelector.select(this.context, columns));
   }
 
+  /**
+   * Selects raw column expressions
+   * @param cols - Column expressions as strings
+   * @returns New query builder instance with raw column selections
+   */
   selectRaw(...cols: string[]): SelectQueryBuilder<T> {
     return this.clone(this.columnSelector.selectRaw(this.context, cols));
   }
 
+  /**
+   * Adds a Common Table Expression (CTE) to the query
+   * @param name - Name of the CTE
+   * @param query - Query builder or query node for the CTE
+   * @param columns - Optional column names for the CTE
+   * @returns New query builder instance with the CTE
+   */
   with(name: string, query: SelectQueryBuilder<any> | SelectQueryNode, columns?: string[]): SelectQueryBuilder<T> {
     const subAst = this.resolveQueryNode(query);
     const nextContext = this.cteManager.withCte(this.context, name, subAst, columns, false);
     return this.clone(nextContext);
   }
 
+  /**
+   * Adds a recursive Common Table Expression (CTE) to the query
+   * @param name - Name of the CTE
+   * @param query - Query builder or query node for the CTE
+   * @param columns - Optional column names for the CTE
+   * @returns New query builder instance with the recursive CTE
+   */
   withRecursive(name: string, query: SelectQueryBuilder<any> | SelectQueryNode, columns?: string[]): SelectQueryBuilder<T> {
     const subAst = this.resolveQueryNode(query);
     const nextContext = this.cteManager.withCte(this.context, name, subAst, columns, true);
     return this.clone(nextContext);
   }
 
+  /**
+   * Selects a subquery as a column
+   * @param alias - Alias for the subquery column
+   * @param sub - Query builder or query node for the subquery
+   * @returns New query builder instance with the subquery selection
+   */
   selectSubquery(alias: string, sub: SelectQueryBuilder<any> | SelectQueryNode): SelectQueryBuilder<T> {
     const query = this.resolveQueryNode(sub);
     return this.clone(this.columnSelector.selectSubquery(this.context, alias, query));
   }
 
+  /**
+   * Adds an INNER JOIN to the query
+   * @param table - Table to join
+   * @param condition - Join condition expression
+   * @returns New query builder instance with the INNER JOIN
+   */
   innerJoin(table: TableDef, condition: BinaryExpressionNode): SelectQueryBuilder<T> {
     const nextContext = this.joinManager.join(this.context, table, condition, JOIN_KINDS.INNER);
     return this.clone(nextContext);
   }
 
+  /**
+   * Adds a LEFT JOIN to the query
+   * @param table - Table to join
+   * @param condition - Join condition expression
+   * @returns New query builder instance with the LEFT JOIN
+   */
   leftJoin(table: TableDef, condition: BinaryExpressionNode): SelectQueryBuilder<T> {
     const nextContext = this.joinManager.join(this.context, table, condition, JOIN_KINDS.LEFT);
     return this.clone(nextContext);
   }
 
+  /**
+   * Adds a RIGHT JOIN to the query
+   * @param table - Table to join
+   * @param condition - Join condition expression
+   * @returns New query builder instance with the RIGHT JOIN
+   */
   rightJoin(table: TableDef, condition: BinaryExpressionNode): SelectQueryBuilder<T> {
     const nextContext = this.joinManager.join(this.context, table, condition, JOIN_KINDS.RIGHT);
     return this.clone(nextContext);
   }
 
+  /**
+   * Matches records based on a relationship
+   * @param relationName - Name of the relationship to match
+   * @param predicate - Optional predicate expression
+   * @returns New query builder instance with the relationship match
+   */
   match(relationName: string, predicate?: ExpressionNode): SelectQueryBuilder<T> {
     const nextContext = this.relationManager.match(this.context, relationName, predicate);
     return this.clone(nextContext);
   }
 
+  /**
+   * Joins a related table
+   * @param relationName - Name of the relationship to join
+   * @param joinKind - Type of join (defaults to INNER)
+   * @param extraCondition - Optional additional join condition
+   * @returns New query builder instance with the relationship join
+   */
   joinRelation(
     relationName: string,
     joinKind: JoinKind = JOIN_KINDS.INNER,
@@ -129,55 +201,113 @@ export class SelectQueryBuilder<T> {
     return this.clone(nextContext);
   }
 
+  /**
+   * Includes related data in the query results
+   * @param relationName - Name of the relationship to include
+   * @param options - Optional include options
+   * @returns New query builder instance with the relationship inclusion
+   */
   include(relationName: string, options?: RelationIncludeOptions): SelectQueryBuilder<T> {
     const nextContext = this.relationManager.include(this.context, relationName, options);
     return this.clone(nextContext);
   }
 
+  /**
+   * Adds a WHERE condition to the query
+   * @param expr - Expression for the WHERE clause
+   * @returns New query builder instance with the WHERE condition
+   */
   where(expr: ExpressionNode): SelectQueryBuilder<T> {
     const nextContext = this.filterManager.where(this.context, expr);
     return this.clone(nextContext);
   }
 
+  /**
+   * Adds a GROUP BY clause to the query
+   * @param col - Column definition or column node to group by
+   * @returns New query builder instance with the GROUP BY clause
+   */
   groupBy(col: ColumnDef | ColumnNode): SelectQueryBuilder<T> {
     const nextContext = this.filterManager.groupBy(this.context, col);
     return this.clone(nextContext);
   }
 
+  /**
+   * Adds a HAVING condition to the query
+   * @param expr - Expression for the HAVING clause
+   * @returns New query builder instance with the HAVING condition
+   */
   having(expr: ExpressionNode): SelectQueryBuilder<T> {
     const nextContext = this.filterManager.having(this.context, expr);
     return this.clone(nextContext);
   }
 
+  /**
+   * Adds an ORDER BY clause to the query
+   * @param col - Column definition or column node to order by
+   * @param direction - Order direction (defaults to ASC)
+   * @returns New query builder instance with the ORDER BY clause
+   */
   orderBy(col: ColumnDef | ColumnNode, direction: OrderDirection = ORDER_DIRECTIONS.ASC): SelectQueryBuilder<T> {
     const nextContext = this.filterManager.orderBy(this.context, col, direction);
     return this.clone(nextContext);
   }
 
+  /**
+   * Adds a DISTINCT clause to the query
+   * @param cols - Columns to make distinct
+   * @returns New query builder instance with the DISTINCT clause
+   */
   distinct(...cols: (ColumnDef | ColumnNode)[]): SelectQueryBuilder<T> {
     return this.clone(this.columnSelector.distinct(this.context, cols));
   }
 
+  /**
+   * Adds a LIMIT clause to the query
+   * @param n - Maximum number of rows to return
+   * @returns New query builder instance with the LIMIT clause
+   */
   limit(n: number): SelectQueryBuilder<T> {
     const nextContext = this.paginationManager.limit(this.context, n);
     return this.clone(nextContext);
   }
 
+  /**
+   * Adds an OFFSET clause to the query
+   * @param n - Number of rows to skip
+   * @returns New query builder instance with the OFFSET clause
+   */
   offset(n: number): SelectQueryBuilder<T> {
     const nextContext = this.paginationManager.offset(this.context, n);
     return this.clone(nextContext);
   }
 
+  /**
+   * Adds a WHERE EXISTS condition to the query
+   * @param subquery - Subquery to check for existence
+   * @returns New query builder instance with the WHERE EXISTS condition
+   */
   whereExists(subquery: SelectQueryBuilder<any> | SelectQueryNode): SelectQueryBuilder<T> {
     const subAst = this.resolveQueryNode(subquery);
     return this.where(exists(subAst));
   }
 
+  /**
+   * Adds a WHERE NOT EXISTS condition to the query
+   * @param subquery - Subquery to check for non-existence
+   * @returns New query builder instance with the WHERE NOT EXISTS condition
+   */
   whereNotExists(subquery: SelectQueryBuilder<any> | SelectQueryNode): SelectQueryBuilder<T> {
     const subAst = this.resolveQueryNode(subquery);
     return this.where(notExists(subAst));
   }
 
+  /**
+   * Adds a WHERE EXISTS condition based on a relationship
+   * @param relationName - Name of the relationship to check
+   * @param callback - Optional callback to modify the relationship query
+   * @returns New query builder instance with the relationship existence check
+   */
   whereHas(
     relationName: string,
     callback?: (qb: SelectQueryBuilder<any>) => SelectQueryBuilder<any>
@@ -197,6 +327,12 @@ export class SelectQueryBuilder<T> {
     return this.where(exists(finalSubAst));
   }
 
+  /**
+   * Adds a WHERE NOT EXISTS condition based on a relationship
+   * @param relationName - Name of the relationship to check
+   * @param callback - Optional callback to modify the relationship query
+   * @returns New query builder instance with the relationship non-existence check
+   */
   whereHasNot(
     relationName: string,
     callback?: (qb: SelectQueryBuilder<any>) => SelectQueryBuilder<any>
@@ -216,22 +352,52 @@ export class SelectQueryBuilder<T> {
     return this.where(notExists(finalSubAst));
   }
 
+  /**
+   * Compiles the query to SQL for a specific dialect
+   * @param dialect - Database dialect to compile for
+   * @returns Compiled query with SQL and parameters
+   */
   compile(dialect: Dialect): CompiledQuery {
     return dialect.compileSelect(this.context.state.ast);
   }
 
+  /**
+   * Converts the query to SQL string for a specific dialect
+   * @param dialect - Database dialect to generate SQL for
+   * @returns SQL string representation of the query
+   */
   toSql(dialect: Dialect): string {
     return this.compile(dialect).sql;
   }
 
+  /**
+   * Gets the hydration plan for the query
+   * @returns Hydration plan or undefined if none exists
+   */
   getHydrationPlan(): HydrationPlan | undefined {
     return this.context.hydration.getPlan();
   }
 
+  /**
+   * Gets the Abstract Syntax Tree (AST) representation of the query
+   * @returns Query AST with hydration applied
+   */
   getAST(): SelectQueryNode {
     return this.context.hydration.applyToAst(this.context.state.ast);
   }
 }
 
+/**
+ * Creates a column node for use in expressions
+ * @param table - Table name
+ * @param name - Column name
+ * @returns ColumnNode with the specified table and name
+ */
 export const createColumn = (table: string, name: string): ColumnNode => ({ type: 'Column', table, name });
+
+/**
+ * Creates a literal value node for use in expressions
+ * @param val - Literal value (string or number)
+ * @returns LiteralNode with the specified value
+ */
 export const createLiteral = (val: string | number): LiteralNode => ({ type: 'Literal', value: val });