metal-orm 1.0.2 → 1.0.4

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

@@ -1,25 +1,61 @@
 import { ExpressionNode } from '../../ast/expression';
 import { SelectQueryNode } from '../../ast/query';
 import { SelectQueryBuilderContext, SelectQueryBuilderEnvironment } from '../select-query-builder-deps';
-import { JoinKind, JOIN_KINDS } from '../../constants/sql';
-
-type RelationIncludeJoinKind = typeof JOIN_KINDS.LEFT | typeof JOIN_KINDS.INNER;
+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;
 }
 
+/**
+ * Manages relation operations (joins, includes, etc.) for query building
+ */
 export class RelationManager {
+  /**
+   * Creates a new RelationManager instance
+   * @param env - Query builder environment
+   */
   constructor(private readonly env: SelectQueryBuilderEnvironment) {}
 
+  /**
+   * Matches records based on a relation with an optional predicate
+   * @param context - Current query context
+   * @param relationName - Name of the relation to match
+   * @param predicate - Optional predicate expression
+   * @returns Updated query context with relation match
+   */
   match(context: SelectQueryBuilderContext, relationName: string, predicate?: ExpressionNode): SelectQueryBuilderContext {
     const result = this.createService(context).match(relationName, predicate);
     return { state: result.state, hydration: result.hydration };
   }
 
+  /**
+   * Joins a relation to the query
+   * @param context - Current query context
+   * @param relationName - Name of the relation to join
+   * @param joinKind - Type of join to use
+   * @param extraCondition - Additional join condition
+   * @returns Updated query context with relation join
+   */
   joinRelation(
     context: SelectQueryBuilderContext,
     relationName: string,
@@ -30,6 +66,13 @@ export class RelationManager {
     return { state: result.state, hydration: result.hydration };
   }
 
+  /**
+   * Includes a relation in the query result
+   * @param context - Current query context
+   * @param relationName - Name of the relation to include
+   * @param options - Options for relation inclusion
+   * @returns Updated query context with included relation
+   */
   include(
     context: SelectQueryBuilderContext,
     relationName: string,
@@ -39,10 +82,22 @@ export class RelationManager {
     return { state: result.state, hydration: result.hydration };
   }
 
+  /**
+   * Applies relation correlation to a query AST
+   * @param context - Current query context
+   * @param relationName - Name of the relation
+   * @param ast - Query AST to modify
+   * @returns Modified query AST with relation correlation
+   */
   applyRelationCorrelation(context: SelectQueryBuilderContext, relationName: string, ast: SelectQueryNode): SelectQueryNode {
     return this.createService(context).applyRelationCorrelation(relationName, ast);
   }
 
+  /**
+   * Creates a relation service instance
+   * @param context - Current query context
+   * @returns Relation service instance
+   */
   private createService(context: SelectQueryBuilderContext) {
     return this.env.deps.createRelationService(this.env.table, context.state, context.hydration);
   }

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

@@ -8,12 +8,20 @@ import {
   CaseExpressionNode,
   WindowFunctionNode,
   ScalarSubqueryNode,
-  and
+  and,
+  isExpressionSelectionNode
 } from '../ast/expression';
 import { JoinNode } from '../ast/join';
 import { SelectQueryState, ProjectionNode } from './select-query-state';
 import { OrderDirection } from '../constants/sql';
-
+import { parseRawColumn } from '../utils/raw-column-parser';
+
+/**
+ * Builds a column node from a column definition or existing column node
+ * @param table - Table definition
+ * @param col - Column definition or column node
+ * @returns Column node
+ */
 export const buildColumnNode = (table: TableDef, col: ColumnDef | ColumnNode): ColumnNode => {
   if ((col as ColumnNode).type === 'Column') {
     return col as ColumnNode;
@@ -27,14 +35,36 @@ export const buildColumnNode = (table: TableDef, col: ColumnDef | ColumnNode): C
   };
 };
 
+/**
+ * Result of column selection operation
+ */
 export interface ColumnSelectionResult {
+  /**
+   * Updated query state
+   */
   state: SelectQueryState;
+  /**
+   * Columns that were added
+   */
   addedColumns: ProjectionNode[];
 }
 
+/**
+ * Service for manipulating query AST (Abstract Syntax Tree)
+ */
 export class QueryAstService {
+  /**
+   * Creates a new QueryAstService instance
+   * @param table - Table definition
+   * @param state - Current query state
+   */
   constructor(private readonly table: TableDef, private readonly state: SelectQueryState) {}
 
+  /**
+   * Selects columns for the query
+   * @param columns - Columns to select (key: alias, value: column definition or expression)
+   * @returns Column selection result with updated state and added columns
+   */
   select(
     columns: Record<string, ColumnDef | FunctionNode | CaseExpressionNode | WindowFunctionNode>
   ): ColumnSelectionResult {
@@ -45,11 +75,7 @@ export class QueryAstService {
     const newCols = Object.entries(columns).reduce<ProjectionNode[]>((acc, [alias, val]) => {
       if (existingAliases.has(alias)) return acc;
 
-      if (
-        (val as any).type === 'Function' ||
-        (val as any).type === 'CaseExpression' ||
-        (val as any).type === 'WindowFunction'
-      ) {
+      if (isExpressionSelectionNode(val)) {
         acc.push({ ...(val as FunctionNode | CaseExpressionNode | WindowFunctionNode), alias } as ProjectionNode);
         return acc;
       }
@@ -68,12 +94,25 @@ export class QueryAstService {
     return { state: nextState, addedColumns: newCols };
   }
 
+  /**
+   * Selects raw column expressions (best-effort parser for simple references/functions)
+   * @param cols - Raw column expressions
+   * @returns Column selection result with updated state and added columns
+   */
   selectRaw(cols: string[]): ColumnSelectionResult {
-    const newCols = cols.map(c => this.parseRawColumn(c));
+    const newCols = cols.map(col => parseRawColumn(col, this.table.name, this.state.ast.ctes));
     const nextState = this.state.withColumns(newCols);
     return { state: nextState, addedColumns: newCols };
   }
 
+  /**
+   * Adds a Common Table Expression (CTE) to the query
+   * @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 state with CTE
+   */
   withCte(name: string, query: SelectQueryNode, columns?: string[], recursive = false): SelectQueryState {
     const cte: CommonTableExpressionNode = {
       type: 'CommonTableExpression',
@@ -86,70 +125,102 @@ export class QueryAstService {
     return this.state.withCte(cte);
   }
 
+  /**
+   * Selects a subquery as a column
+   * @param alias - Alias for the subquery
+   * @param query - Subquery to select
+   * @returns Updated query state with subquery selection
+   */
   selectSubquery(alias: string, query: SelectQueryNode): SelectQueryState {
     const node: ScalarSubqueryNode = { type: 'ScalarSubquery', query, alias };
     return this.state.withColumns([node]);
   }
 
+  /**
+   * Adds a JOIN clause to the query
+   * @param join - Join node to add
+   * @returns Updated query state with JOIN
+   */
   withJoin(join: JoinNode): SelectQueryState {
     return this.state.withJoin(join);
   }
 
+  /**
+   * Adds a WHERE clause to the query
+   * @param expr - Expression for the WHERE clause
+   * @returns Updated query state with WHERE clause
+   */
   withWhere(expr: ExpressionNode): SelectQueryState {
     const combined = this.combineExpressions(this.state.ast.where, expr);
     return this.state.withWhere(combined);
   }
 
+  /**
+   * Adds a GROUP BY clause to the query
+   * @param col - Column to group by
+   * @returns Updated query state with GROUP BY clause
+   */
   withGroupBy(col: ColumnDef | ColumnNode): SelectQueryState {
     const node = buildColumnNode(this.table, col);
     return this.state.withGroupBy([node]);
   }
 
+  /**
+   * Adds a HAVING clause to the query
+   * @param expr - Expression for the HAVING clause
+   * @returns Updated query state with HAVING clause
+   */
   withHaving(expr: ExpressionNode): SelectQueryState {
     const combined = this.combineExpressions(this.state.ast.having, expr);
     return this.state.withHaving(combined);
   }
 
+  /**
+   * Adds an ORDER BY clause to the query
+   * @param col - Column to order by
+   * @param direction - Order direction (ASC/DESC)
+   * @returns Updated query state with ORDER BY clause
+   */
   withOrderBy(col: ColumnDef | ColumnNode, direction: OrderDirection): SelectQueryState {
     const node = buildColumnNode(this.table, col);
     return this.state.withOrderBy([{ type: 'OrderBy', column: node, direction }]);
   }
 
+  /**
+   * Adds a DISTINCT clause to the query
+   * @param cols - Columns to make distinct
+   * @returns Updated query state with DISTINCT clause
+   */
   withDistinct(cols: ColumnNode[]): SelectQueryState {
     return this.state.withDistinct(cols);
   }
 
+  /**
+   * Adds a LIMIT clause to the query
+   * @param limit - Maximum number of rows to return
+   * @returns Updated query state with LIMIT clause
+   */
   withLimit(limit: number): SelectQueryState {
     return this.state.withLimit(limit);
   }
 
+  /**
+   * Adds an OFFSET clause to the query
+   * @param offset - Number of rows to skip
+   * @returns Updated query state with OFFSET clause
+   */
   withOffset(offset: number): SelectQueryState {
     return this.state.withOffset(offset);
   }
 
+  /**
+   * Combines expressions with AND operator
+   * @param existing - Existing expression
+   * @param next - New expression to combine
+   * @returns Combined expression
+   */
   private combineExpressions(existing: ExpressionNode | undefined, next: ExpressionNode): ExpressionNode {
     return existing ? and(existing, next) : next;
   }
 
-  private parseRawColumn(col: string): ColumnNode {
-    if (col.includes('(')) {
-      const [fn, rest] = col.split('(');
-      const colName = rest.replace(')', '');
-      const [table, name] = colName.includes('.') ? colName.split('.') : [this.table.name, colName];
-      return { type: 'Column', table, name, alias: col };
-    }
-
-    if (col.includes('.')) {
-      const [potentialCteName, columnName] = col.split('.');
-      const hasCte = this.state.ast.ctes && this.state.ast.ctes.some(cte => cte.name === potentialCteName);
-
-      if (hasCte) {
-        return { type: 'Column', table: this.table.name, name: col };
-      }
-
-      return { type: 'Column', table: potentialCteName, name: columnName };
-    }
-
-    return { type: 'Column', table: this.table.name, name: col };
-  }
 }

package/src/builder/relation-conditions.ts

@@ -1,13 +1,29 @@
 import { TableDef } from '../schema/table';
 import { RelationDef, RelationKinds } from '../schema/relation';
 import { ExpressionNode, eq, and } from '../ast/expression';
+import { findPrimaryKey } from './hydration-planner';
 
+/**
+ * Utility function to handle unreachable code paths
+ * @param value - Value that should never occur
+ * @throws Error indicating unhandled relation type
+ */
 const assertNever = (value: never): never => {
   throw new Error(`Unhandled relation type: ${JSON.stringify(value)}`);
 };
 
+/**
+ * Builds the base condition for a relation join
+ * @param root - Root table definition
+ * @param relation - Relation definition
+ * @returns Expression node representing the join condition
+ */
 const baseRelationCondition = (root: TableDef, relation: RelationDef): ExpressionNode => {
-  const localKey = relation.localKey || 'id';
+  const defaultLocalKey =
+    relation.type === RelationKinds.HasMany
+      ? findPrimaryKey(root)
+      : findPrimaryKey(relation.target);
+  const localKey = relation.localKey || defaultLocalKey;
 
   switch (relation.type) {
     case RelationKinds.HasMany:
@@ -25,6 +41,13 @@ const baseRelationCondition = (root: TableDef, relation: RelationDef): Expressio
   }
 };
 
+/**
+ * Builds a relation join condition with optional extra conditions
+ * @param root - Root table definition
+ * @param relation - Relation definition
+ * @param extra - Optional additional expression to combine with AND
+ * @returns Expression node representing the complete join condition
+ */
 export const buildRelationJoinCondition = (
   root: TableDef,
   relation: RelationDef,
@@ -34,6 +57,12 @@ export const buildRelationJoinCondition = (
   return extra ? and(base, extra) : base;
 };
 
+/**
+ * Builds a relation correlation condition for subqueries
+ * @param root - Root table definition
+ * @param relation - Relation definition
+ * @returns Expression node representing the correlation condition
+ */
 export const buildRelationCorrelation = (root: TableDef, relation: RelationDef): ExpressionNode => {
   return baseRelationCondition(root, relation);
 };

package/src/builder/relation-projection-helper.ts

@@ -3,25 +3,52 @@ import { ColumnDef } from '../schema/column';
 import { SelectQueryState } from './select-query-state';
 import { HydrationManager } from './hydration-manager';
 import { ColumnNode } from '../ast/expression';
-import { findPrimaryKey, isRelationAlias } from './hydration-planner';
+import { findPrimaryKey } from './hydration-planner';
+import { isRelationAlias } from '../utils/relation-alias';
 
+/**
+ * Result of a relation operation
+ */
 export interface RelationResult {
+  /**
+   * Updated query state
+   */
   state: SelectQueryState;
+  /**
+   * Updated hydration manager
+   */
   hydration: HydrationManager;
 }
 
+/**
+ * Callback function for selecting columns
+ */
 type SelectColumnsCallback = (
   state: SelectQueryState,
   hydration: HydrationManager,
   columns: Record<string, ColumnDef>
 ) => RelationResult;
 
+/**
+ * Helper class for managing relation projections in queries
+ */
 export class RelationProjectionHelper {
+  /**
+   * Creates a new RelationProjectionHelper instance
+   * @param table - Table definition
+   * @param selectColumns - Callback for selecting columns
+   */
   constructor(
     private readonly table: TableDef,
     private readonly selectColumns: SelectColumnsCallback
   ) {}
 
+  /**
+   * Ensures base projection is included in the query
+   * @param state - Current query state
+   * @param hydration - Hydration manager
+   * @returns Relation result with updated state and hydration
+   */
   ensureBaseProjection(state: SelectQueryState, hydration: HydrationManager): RelationResult {
     const primaryKey = findPrimaryKey(this.table);
 
@@ -38,10 +65,21 @@ export class RelationProjectionHelper {
     return { state, hydration };
   }
 
+  /**
+   * Checks if base projection exists in the query
+   * @param state - Current query state
+   * @returns True if base projection exists
+   */
   private hasBaseProjection(state: SelectQueryState): boolean {
     return state.ast.columns.some(col => !isRelationAlias((col as ColumnNode).alias));
   }
 
+  /**
+   * Checks if primary key is selected in the query
+   * @param state - Current query state
+   * @param primaryKey - Primary key name
+   * @returns True if primary key is selected
+   */
   private hasPrimarySelected(state: SelectQueryState, primaryKey: string): boolean {
     return state.ast.columns.some(col => {
       const alias = (col as ColumnNode).alias;
@@ -50,6 +88,10 @@ export class RelationProjectionHelper {
     });
   }
 
+  /**
+   * Gets all base columns for the table
+   * @returns Record of all table columns
+   */
   private getBaseColumns(): Record<string, ColumnDef> {
     return Object.keys(this.table.columns).reduce((acc, key) => {
       acc[key] = (this.table.columns as Record<string, ColumnDef>)[key];

package/src/builder/relation-service.ts

@@ -7,7 +7,6 @@ import {
   ExpressionNode,
   and
 } from '../ast/expression';
-import { JoinNode } from '../ast/join';
 import { SelectQueryState } from './select-query-state';
 import { HydrationManager } from './hydration-manager';
 import { QueryAstService } from './query-ast-service';
@@ -16,22 +15,40 @@ import { RelationProjectionHelper } from './relation-projection-helper';
 import type { RelationResult } from './relation-projection-helper';
 import { buildRelationJoinCondition, buildRelationCorrelation } from './relation-conditions';
 import { JoinKind, JOIN_KINDS } from '../constants/sql';
+import { RelationIncludeJoinKind } from './relation-types';
+import { createJoinNode } from '../utils/join-node';
+import { makeRelationAlias } from '../utils/relation-alias';
 
-type RelationIncludeJoinKind = typeof JOIN_KINDS.LEFT | typeof JOIN_KINDS.INNER;
-
+/**
+ * Service for handling relation operations (joins, includes, etc.)
+ */
 export class RelationService {
   private readonly projectionHelper: RelationProjectionHelper;
 
+  /**
+   * Creates a new RelationService instance
+   * @param table - Table definition
+   * @param state - Current query state
+   * @param hydration - Hydration manager
+   */
   constructor(
     private readonly table: TableDef,
     private readonly state: SelectQueryState,
-    private readonly hydration: HydrationManager
+    private readonly hydration: HydrationManager,
+    private readonly createQueryAstService: (table: TableDef, state: SelectQueryState) => QueryAstService
   ) {
     this.projectionHelper = new RelationProjectionHelper(table, (state, hydration, columns) =>
       this.selectColumns(state, hydration, columns)
     );
   }
 
+  /**
+   * Joins a relation to the query
+   * @param relationName - Name of the relation to join
+   * @param joinKind - Type of join to use
+   * @param extraCondition - Additional join condition
+   * @returns Relation result with updated state and hydration
+   */
   joinRelation(
     relationName: string,
     joinKind: JoinKind,
@@ -41,6 +58,12 @@ export class RelationService {
     return { state: nextState, hydration: this.hydration };
   }
 
+  /**
+   * Matches records based on a relation with an optional predicate
+   * @param relationName - Name of the relation to match
+   * @param predicate - Optional predicate expression
+   * @returns Relation result with updated state and hydration
+   */
   match(
     relationName: string,
     predicate?: ExpressionNode
@@ -53,6 +76,12 @@ export class RelationService {
     return { state: nextState, hydration: joined.hydration };
   }
 
+  /**
+   * Includes a relation in the query result
+   * @param relationName - Name of the relation to include
+   * @param options - Options for relation inclusion
+   * @returns Relation result with updated state and hydration
+   */
   include(
     relationName: string,
     options?: { columns?: string[]; aliasPrefix?: string; filter?: ExpressionNode; joinKind?: RelationIncludeJoinKind }
@@ -82,7 +111,7 @@ export class RelationService {
       if (!def) {
         throw new Error(`Column '${key}' not found on relation '${relationName}'`);
       }
-      acc[`${aliasPrefix}__${key}`] = def;
+      acc[makeRelationAlias(aliasPrefix, key)] = def;
       return acc;
     }, {} as Record<string, ColumnDef>);
 
@@ -101,6 +130,12 @@ export class RelationService {
     return { state, hydration };
   }
 
+  /**
+   * Applies relation correlation to a query AST
+   * @param relationName - Name of the relation
+   * @param ast - Query AST to modify
+   * @returns Modified query AST with relation correlation
+   */
   applyRelationCorrelation(
     relationName: string,
     ast: SelectQueryNode
@@ -117,6 +152,14 @@ export class RelationService {
     };
   }
 
+  /**
+   * Creates a join node for a relation
+   * @param state - Current query state
+   * @param relationName - Name of the relation
+   * @param joinKind - Type of join to use
+   * @param extraCondition - Additional join condition
+   * @returns Updated query state with join
+   */
   private withJoin(
     state: SelectQueryState,
     relationName: string,
@@ -126,17 +169,18 @@ export class RelationService {
     const relation = this.getRelation(relationName);
     const condition = buildRelationJoinCondition(this.table, relation, extraCondition);
 
-    const joinNode: JoinNode = {
-      type: 'Join',
-      kind: joinKind,
-      table: { type: 'Table', name: relation.target.name },
-      condition,
-      relationName
-    };
+    const joinNode = createJoinNode(joinKind, relation.target.name, condition, relationName);
 
     return this.astService(state).withJoin(joinNode);
   }
 
+  /**
+   * Selects columns for a relation
+   * @param state - Current query state
+   * @param hydration - Hydration manager
+   * @param columns - Columns to select
+   * @returns Relation result with updated state and hydration
+   */
   private selectColumns(
     state: SelectQueryState,
     hydration: HydrationManager,
@@ -149,6 +193,12 @@ export class RelationService {
     };
   }
 
+  /**
+   * Gets a relation definition by name
+   * @param relationName - Name of the relation
+   * @returns Relation definition
+   * @throws Error if relation is not found
+   */
   private getRelation(relationName: string): RelationDef {
     const relation = this.table.relations[relationName];
     if (!relation) {
@@ -158,8 +208,13 @@ export class RelationService {
     return relation;
   }
 
+  /**
+   * Creates a QueryAstService instance
+   * @param state - Current query state
+   * @returns QueryAstService instance
+   */
   private astService(state: SelectQueryState = this.state): QueryAstService {
-    return new QueryAstService(this.table, state);
+    return this.createQueryAstService(this.table, state);
   }
 }
 

package/src/builder/relation-types.ts

@@ -0,0 +1,6 @@
+import { JOIN_KINDS } from '../constants/sql';
+
+/**
+ * Join kinds allowed when including a relation using `.include(...)`.
+ */
+export type RelationIncludeJoinKind = typeof JOIN_KINDS.LEFT | typeof JOIN_KINDS.INNER;