metal-orm 1.0.43 → 1.0.44

package/src/query-builder/select/predicate-facet.ts

@@ -0,0 +1,103 @@
+import { ColumnDef } from '../../schema/column.js';
+import { ExpressionNode } from '../../core/ast/expression.js';
+import { OrderingTerm } from '../../core/ast/query.js';
+import { OrderDirection } from '../../core/sql/sql.js';
+import { SelectQueryBuilderContext, SelectQueryBuilderEnvironment } from '../select-query-builder-deps.js';
+import { QueryAstService } from '../query-ast-service.js';
+import { SelectQueryState } from '../select-query-state.js';
+
+/**
+ * Facet responsible for filtering and ordering operations
+ */
+export class SelectPredicateFacet {
+    /**
+     * Creates a new SelectPredicateFacet instance
+     * @param env - Query builder environment
+     * @param createAstService - Function to create AST service
+     */
+    constructor(
+        private readonly env: SelectQueryBuilderEnvironment,
+        private readonly createAstService: (state: SelectQueryState) => QueryAstService
+    ) { }
+
+    /**
+     * Adds a WHERE condition to the query
+     * @param context - Current query context
+     * @param expr - WHERE expression
+     * @returns Updated query context with WHERE condition
+     */
+    where(context: SelectQueryBuilderContext, expr: ExpressionNode): SelectQueryBuilderContext {
+        const astService = this.createAstService(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 term - Column or ordering term to group by
+     * @returns Updated query context with GROUP BY clause
+     */
+    groupBy(context: SelectQueryBuilderContext, term: ColumnDef | OrderingTerm): SelectQueryBuilderContext {
+        const astService = this.createAstService(context.state);
+        const nextState = astService.withGroupBy(term);
+        return { state: nextState, hydration: context.hydration };
+    }
+
+    /**
+     * Adds a HAVING condition to the query
+     * @param context - Current query context
+     * @param expr - HAVING expression
+     * @returns Updated query context with HAVING condition
+     */
+    having(context: SelectQueryBuilderContext, expr: ExpressionNode): SelectQueryBuilderContext {
+        const astService = this.createAstService(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 term - Column or ordering term to order by
+     * @param direction - Order direction
+     * @param nulls - Nulls ordering
+     * @param collation - Collation
+     * @returns Updated query context with ORDER BY clause
+     */
+    orderBy(
+        context: SelectQueryBuilderContext,
+        term: ColumnDef | OrderingTerm,
+        direction: OrderDirection,
+        nulls?: 'FIRST' | 'LAST',
+        collation?: string
+    ): SelectQueryBuilderContext {
+        const astService = this.createAstService(context.state);
+        const nextState = astService.withOrderBy(term, direction, nulls, collation);
+        return { state: nextState, hydration: context.hydration };
+    }
+
+    /**
+     * Adds a LIMIT clause to the query
+     * @param context - Current query context
+     * @param n - Maximum number of rows
+     * @returns Updated query context with LIMIT clause
+     */
+    limit(context: SelectQueryBuilderContext, n: number): SelectQueryBuilderContext {
+        const astService = this.createAstService(context.state);
+        const nextState = astService.withLimit(n);
+        return { state: nextState, hydration: context.hydration };
+    }
+
+    /**
+     * Adds an OFFSET clause to the query
+     * @param context - Current query context
+     * @param n - Number of rows to skip
+     * @returns Updated query context with OFFSET clause
+     */
+    offset(context: SelectQueryBuilderContext, n: number): SelectQueryBuilderContext {
+        const astService = this.createAstService(context.state);
+        const nextState = astService.withOffset(n);
+        return { state: nextState, hydration: context.hydration };
+    }
+}

package/src/query-builder/select/projection-facet.ts

@@ -0,0 +1,69 @@
+import { ColumnDef } from '../../schema/column.js';
+import { ColumnNode, FunctionNode, CaseExpressionNode, WindowFunctionNode } from '../../core/ast/expression.js';
+import { SelectQueryBuilderContext } from '../select-query-builder-deps.js';
+import { ColumnSelector } from '../column-selector.js';
+import { SelectQueryNode } from '../../core/ast/query.js';
+
+type ColumnSelectionValue = ColumnDef | FunctionNode | CaseExpressionNode | WindowFunctionNode;
+
+/**
+ * Facet responsible for projection operations (SELECT, DISTINCT, etc.)
+ */
+export class SelectProjectionFacet {
+    /**
+     * Creates a new SelectProjectionFacet instance
+     * @param columnSelector - Column selector dependency
+     */
+    constructor(private readonly columnSelector: ColumnSelector) { }
+
+    /**
+     * 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: Record<string, ColumnSelectionValue>
+    ): SelectQueryBuilderContext {
+        return { ...context, state: this.columnSelector.select(context, columns).state };
+    }
+
+    /**
+     * Selects raw column expressions
+     * @param context - Current query context
+     * @param cols - Raw column expressions
+     * @returns Updated query context with raw column selections
+     */
+    selectRaw(context: SelectQueryBuilderContext, cols: string[]): SelectQueryBuilderContext {
+        return { ...context, state: this.columnSelector.selectRaw(context, cols).state };
+    }
+
+    /**
+     * 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,
+        query: SelectQueryNode
+    ): SelectQueryBuilderContext {
+        return { ...context, state: this.columnSelector.selectSubquery(context, alias, query).state };
+    }
+
+    /**
+     * Adds DISTINCT clause to the query
+     * @param context - Current query context
+     * @param cols - Columns to make distinct
+     * @returns Updated query context with DISTINCT clause
+     */
+    distinct(
+        context: SelectQueryBuilderContext,
+        cols: (ColumnDef | ColumnNode)[]
+    ): SelectQueryBuilderContext {
+        return { ...context, state: this.columnSelector.distinct(context, cols).state };
+    }
+}

package/src/query-builder/select/relation-facet.ts

@@ -0,0 +1,81 @@
+import { ExpressionNode } from '../../core/ast/expression.js';
+import { JoinKind } from '../../core/sql/sql.js';
+import { SelectQueryBuilderContext } from '../select-query-builder-deps.js';
+import { RelationManager } from '../relation-manager.js';
+import { RelationIncludeOptions } from '../relation-types.js';
+import { SelectQueryNode } from '../../core/ast/query.js';
+
+/**
+ * Facet responsible for relation operations (include, match, whereHas, etc.)
+ */
+export class SelectRelationFacet {
+    /**
+     * Creates a new SelectRelationFacet instance
+     * @param relationManager - Relation manager dependency
+     */
+    constructor(private readonly relationManager: RelationManager) { }
+
+    /**
+     * Matches records based on a relationship
+     * @param context - Current query context
+     * @param relationName - Name of the relationship
+     * @param predicate - Optional predicate
+     * @returns Updated query context with relation match
+     */
+    match(
+        context: SelectQueryBuilderContext,
+        relationName: string,
+        predicate?: ExpressionNode
+    ): SelectQueryBuilderContext {
+        return this.relationManager.match(context, relationName, predicate);
+    }
+
+    /**
+     * Joins a related table
+     * @param context - Current query context
+     * @param relationName - Name of the relationship
+     * @param joinKind - Type of join
+     * @param extraCondition - Optional additional condition
+     * @returns Updated query context with relation join
+     */
+    joinRelation(
+        context: SelectQueryBuilderContext,
+        relationName: string,
+        joinKind: JoinKind,
+        extraCondition?: ExpressionNode
+    ): SelectQueryBuilderContext {
+        return this.relationManager.joinRelation(context, relationName, joinKind, extraCondition);
+    }
+
+    /**
+     * Includes related data in the query results
+     * @param context - Current query context
+     * @param relationName - Name of the relationship to include
+     * @param options - Optional include options
+     * @returns Updated query context with relation inclusion
+     */
+    include(
+        context: SelectQueryBuilderContext,
+        relationName: string,
+        options?: RelationIncludeOptions
+    ): SelectQueryBuilderContext {
+        return this.relationManager.include(context, relationName, options);
+    }
+
+    /**
+     * Applies correlation for relation-based subqueries
+     * @param context - Current query context
+     * @param relationName - Name of the relationship
+     * @param subAst - Subquery AST
+     * @param extraCorrelate - Optional additional correlation
+     * @returns Modified subquery AST with correlation
+     */
+    applyRelationCorrelation(
+        context: SelectQueryBuilderContext,
+        relationName: string,
+        subAst: SelectQueryNode,
+        extraCorrelate?: ExpressionNode
+    ): SelectQueryNode {
+        return this.relationManager.applyRelationCorrelation(context, relationName, subAst, extraCorrelate);
+    }
+}

package/src/query-builder/select/setop-facet.ts

@@ -0,0 +1,36 @@
+import { SelectQueryNode, SetOperationKind } from '../../core/ast/query.js';
+import { SelectQueryBuilderContext, SelectQueryBuilderEnvironment } from '../select-query-builder-deps.js';
+import { QueryAstService } from '../query-ast-service.js';
+import { SelectQueryState } from '../select-query-state.js';
+
+/**
+ * Facet responsible for set operations (UNION, INTERSECT, EXCEPT)
+ */
+export class SelectSetOpFacet {
+    /**
+     * Creates a new SelectSetOpFacet instance
+     * @param env - Query builder environment
+     * @param createAstService - Function to create AST service
+     */
+    constructor(
+        private readonly env: SelectQueryBuilderEnvironment,
+        private readonly createAstService: (state: SelectQueryState) => QueryAstService
+    ) { }
+
+    /**
+     * Applies a set operation to the query
+     * @param context - Current query context
+     * @param operator - Set operation kind
+     * @param subAst - Subquery AST to combine
+     * @returns Updated query context with set operation
+     */
+    applySetOperation(
+        context: SelectQueryBuilderContext,
+        operator: SetOperationKind,
+        subAst: SelectQueryNode
+    ): SelectQueryBuilderContext {
+        const astService = this.createAstService(context.state);
+        const nextState = astService.withSetOperation(operator, subAst);
+        return { state: nextState, hydration: context.hydration };
+    }
+}

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

@@ -4,6 +4,12 @@ import { getTableDefFromEntity } from '../decorators/bootstrap.js';
 
 /**
  * Build a typed selection map from a TableDef.
+ * @template TTable - The table definition type
+ * @template K - The column name keys
+ * @param table - The table definition to select columns from
+ * @param cols - Column names to include in the selection
+ * @returns A typed record mapping column names to their definitions
+ * @throws Error if a specified column is not found on the table
  */
 export function sel<
   TTable extends TableDef,
@@ -26,6 +32,13 @@ type Ctor<T> = { new(...args: unknown[]): T };
 
 /**
  * Build a typed selection map from an entity constructor.
+ * @template TEntity - The entity type
+ * @template K - The property name keys
+ * @param entity - The entity constructor to get table definition from
+ * @param props - Property names to include in the selection
+ * @returns A record mapping property names to their column definitions
+ * @throws Error if no table definition is registered for the entity
+ * @throws Error if a specified property is not found as a column
  */
 export function esel<TEntity extends object, K extends keyof TEntity & string>(
   entity: Ctor<TEntity>,

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

@@ -4,6 +4,8 @@ import { HydrationManager } from './hydration-manager.js';
 import { HydrationPlanner } from './hydration-planner.js';
 import { QueryAstService } from './query-ast-service.js';
 import { RelationService } from './relation-service.js';
+import { ColumnSelector } from './column-selector.js';
+import { RelationManager } from './relation-manager.js';
 
 /**
  * Context for query building operations
@@ -60,6 +62,18 @@ export interface SelectQueryBuilderDependencies {
     state: SelectQueryState,
     hydration: HydrationManager
   ) => RelationService;
+  /**
+   * Creates a new column selector
+   * @param env - Query builder environment
+   * @returns New column selector
+   */
+  createColumnSelector: (env: SelectQueryBuilderEnvironment) => ColumnSelector;
+  /**
+   * Creates a new relation manager
+   * @param env - Query builder environment
+   * @returns New relation manager
+   */
+  createRelationManager: (env: SelectQueryBuilderEnvironment) => RelationManager;
 }
 
 /**
@@ -99,13 +113,17 @@ export const resolveSelectQueryBuilderDependencies = (
   const createRelationService =
     overrides.createRelationService ??
     ((table, state, hydration) => new RelationService(table, state, hydration, createQueryAstService));
+  const createColumnSelector = overrides.createColumnSelector ?? (env => new ColumnSelector(env));
+  const createRelationManager = overrides.createRelationManager ?? (env => new RelationManager(env));
 
   return {
     createState: overrides.createState ?? (table => new SelectQueryState(table)),
     createHydration,
     createHydrationPlanner,
     createQueryAstService,
-    createRelationService
+    createRelationService,
+    createColumnSelector,
+    createRelationManager
   };
 };
 

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

@@ -7,6 +7,7 @@ import {
   TableSourceNode,
   OrderingTerm
 } from '../core/ast/query.js';
+import { createTableNode } from '../core/ast/builders.js';
 import {
   ColumnNode,
   ExpressionNode,
@@ -49,7 +50,7 @@ export class SelectQueryState {
     this.table = table;
     this.ast = ast ?? {
       type: 'SelectQuery',
-      from: { type: 'Table', name: table.name },
+      from: createTableNode(table),
       columns: [],
       joins: []
     };