metal-orm 1.0.43 → 1.0.44

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

@@ -251,6 +251,11 @@ export class QueryAstService {
     return existing ? and(existing, next) : next;
   }
 
+  /**
+   * Normalizes an ordering term to a standard OrderingTerm
+   * @param term - Column definition or ordering term to normalize
+   * @returns Normalized ordering term
+   */
   private normalizeOrderingTerm(term: ColumnDef | OrderingTerm): OrderingTerm {
     const from = this.state.ast.from;
     const tableRef = from.type === 'Table' && from.alias ? { ...this.table, alias: from.alias } : this.table;

package/src/query-builder/query-resolution.ts

@@ -0,0 +1,78 @@
+import { SelectQueryNode, UpdateQueryNode, DeleteQueryNode, TableSourceNode } from '../core/ast/query.js';
+import { TableDef } from '../schema/table.js';
+import type { SelectQueryBuilder } from './select.js';
+import type { UpdateQueryBuilder } from './update.js';
+import type { DeleteQueryBuilder } from './delete.js';
+
+/**
+ * Resolves a SelectQueryBuilder or SelectQueryNode to a SelectQueryNode AST
+ * @param query - Query builder or AST node
+ * @returns SelectQueryNode AST
+ */
+export function resolveSelectQuery<TSub extends TableDef>(
+    query: SelectQueryBuilder<unknown, TSub> | SelectQueryNode
+): SelectQueryNode {
+    const candidate = query as { getAST?: () => SelectQueryNode };
+    return typeof candidate.getAST === 'function' && candidate.getAST
+        ? candidate.getAST()
+        : (query as SelectQueryNode);
+}
+
+/**
+ * Resolves a UpdateQueryBuilder or UpdateQueryNode to a UpdateQueryNode AST
+ * @param query - Query builder or AST node
+ * @returns UpdateQueryNode AST
+ */
+export function resolveUpdateQuery<T>(
+    query: UpdateQueryBuilder<T> | UpdateQueryNode
+): UpdateQueryNode {
+    const candidate = query as { getAST?: () => UpdateQueryNode };
+    return typeof candidate.getAST === 'function' && candidate.getAST
+        ? candidate.getAST()
+        : (query as UpdateQueryNode);
+}
+
+/**
+ * Resolves a DeleteQueryBuilder or DeleteQueryNode to a DeleteQueryNode AST
+ * @param query - Query builder or AST node
+ * @returns DeleteQueryNode AST
+ */
+export function resolveDeleteQuery<T>(
+    query: DeleteQueryBuilder<T> | DeleteQueryNode
+): DeleteQueryNode {
+    const candidate = query as { getAST?: () => DeleteQueryNode };
+    return typeof candidate.getAST === 'function' && candidate.getAST
+        ? candidate.getAST()
+        : (query as DeleteQueryNode);
+}
+
+/**
+ * Resolves a TableDef or TableSourceNode to a TableSourceNode
+ * @param source - Table definition or source node
+ * @returns TableSourceNode
+ */
+export function resolveTableSource(source: TableDef | TableSourceNode): TableSourceNode {
+    if (isTableSourceNode(source)) {
+        return source;
+    }
+    return { type: 'Table', name: source.name, schema: source.schema };
+}
+
+/**
+ * Resolves a join target (TableDef, TableSourceNode, or string relation name)
+ * @param table - Join target
+ * @returns TableSourceNode or string
+ */
+export function resolveJoinTarget(table: TableDef | TableSourceNode | string): TableSourceNode | string {
+    if (typeof table === 'string') return table;
+    return resolveTableSource(table);
+}
+
+/**
+ * Type guard to check if a value is a TableSourceNode
+ * @param source - Value to check
+ * @returns True if value is a TableSourceNode
+ */
+function isTableSourceNode(source: TableDef | TableSourceNode): source is TableSourceNode {
+    return typeof (source as TableSourceNode).type === 'string';
+}

package/src/query-builder/raw-column-parser.ts

@@ -4,6 +4,11 @@ import { CommonTableExpressionNode } from '../core/ast/query.js';
 /**
  * Best-effort helper that tries to convert a raw column expression into a `ColumnNode`.
  * This parser is intentionally limited; use it only for simple references or function calls.
+ *
+ * @param col - Raw column expression string (e.g., "column", "table.column", "COUNT(column)")
+ * @param tableName - Default table name to use when no table is specified
+ * @param ctes - Optional array of CTEs for context when parsing column references
+ * @returns A ColumnNode representing the parsed column expression
  */
 export const parseRawColumn = (
   col: string,

package/src/query-builder/relation-alias.ts

@@ -19,6 +19,9 @@ export interface RelationAliasParts {
 
 /**
  * Builds a relation alias from the relation name and column name components.
+ * @param relationName - The name of the relation
+ * @param columnName - The name of the column within the relation
+ * @returns A relation alias string in the format "relationName__columnName"
  */
 export const makeRelationAlias = (relationName: string, columnName: string): string =>
   `${relationName}${RELATION_SEPARATOR}${columnName}`;
@@ -26,6 +29,8 @@ export const makeRelationAlias = (relationName: string, columnName: string): str
 /**
  * Parses a relation alias into its relation/column components.
  * Returns `null` when the alias does not follow the `relation__column` pattern.
+ * @param alias - The relation alias string to parse
+ * @returns Parsed relation alias parts or null if not a valid relation alias
  */
 export const parseRelationAlias = (alias: string): RelationAliasParts | null => {
   const idx = alias.indexOf(RELATION_SEPARATOR);
@@ -38,6 +43,8 @@ export const parseRelationAlias = (alias: string): RelationAliasParts | null =>
 
 /**
  * Determines whether an alias represents a relation column by checking the `__` convention.
+ * @param alias - The alias string to check
+ * @returns True if the alias follows the relation alias pattern
  */
 export const isRelationAlias = (alias?: string): boolean =>
   !!alias && alias.includes(RELATION_SEPARATOR);

package/src/query-builder/relation-conditions.ts

@@ -21,26 +21,26 @@ const assertNever = (value: never): never => {
  * @param relation - Relation definition
  * @returns Expression node representing the join condition
  */
-const baseRelationCondition = (root: TableDef, relation: RelationDef, rootAlias?: string): ExpressionNode => {
-  const rootTable = rootAlias || root.name;
-  const defaultLocalKey =
-  relation.type === RelationKinds.HasMany || relation.type === RelationKinds.HasOne
-    ? findPrimaryKey(root)
-    : findPrimaryKey(relation.target);
-  const localKey = relation.localKey || defaultLocalKey;
+const baseRelationCondition = (root: TableDef, relation: RelationDef, rootAlias?: string): ExpressionNode => {
+  const rootTable = rootAlias || root.name;
+  const defaultLocalKey =
+    relation.type === RelationKinds.HasMany || relation.type === RelationKinds.HasOne
+      ? findPrimaryKey(root)
+      : findPrimaryKey(relation.target);
+  const localKey = relation.localKey || defaultLocalKey;
 
   switch (relation.type) {
-    case RelationKinds.HasMany:
-    case RelationKinds.HasOne:
-      return eq(
-        { type: 'Column', table: relation.target.name, name: relation.foreignKey },
-        { type: 'Column', table: rootTable, name: localKey }
-      );
-    case RelationKinds.BelongsTo:
-      return eq(
-        { type: 'Column', table: relation.target.name, name: localKey },
-        { type: 'Column', table: rootTable, name: relation.foreignKey }
-      );
+    case RelationKinds.HasMany:
+    case RelationKinds.HasOne:
+      return eq(
+        { type: 'Column', table: relation.target.name, name: relation.foreignKey },
+        { type: 'Column', table: rootTable, name: localKey }
+      );
+    case RelationKinds.BelongsTo:
+      return eq(
+        { type: 'Column', table: relation.target.name, name: localKey },
+        { type: 'Column', table: rootTable, name: relation.foreignKey }
+      );
     case RelationKinds.BelongsToMany:
       throw new Error('BelongsToMany relations do not support the standard join condition builder');
     default:
@@ -50,25 +50,36 @@ const baseRelationCondition = (root: TableDef, relation: RelationDef, rootAlias?
 
 /**
  * Builds the join nodes required to include a BelongsToMany relation.
+ * @param root - The root table definition
+ * @param relationName - Name of the relation being joined
+ * @param relation - The BelongsToMany relation definition
+ * @param joinKind - The type of join to perform
+ * @param extra - Optional additional conditions for the target join
+ * @param rootAlias - Optional alias for the root table
+ * @returns Array of join nodes for the pivot and target tables
  */
-export const buildBelongsToManyJoins = (
-  root: TableDef,
-  relationName: string,
-  relation: BelongsToManyRelation,
-  joinKind: JoinKind,
-  extra?: ExpressionNode,
-  rootAlias?: string
-): JoinNode[] => {
-  const rootKey = relation.localKey || findPrimaryKey(root);
-  const targetKey = relation.targetKey || findPrimaryKey(relation.target);
-  const rootTable = rootAlias || root.name;
-
-  const pivotCondition = eq(
-    { type: 'Column', table: relation.pivotTable.name, name: relation.pivotForeignKeyToRoot },
-    { type: 'Column', table: rootTable, name: rootKey }
-  );
+export const buildBelongsToManyJoins = (
+  root: TableDef,
+  relationName: string,
+  relation: BelongsToManyRelation,
+  joinKind: JoinKind,
+  extra?: ExpressionNode,
+  rootAlias?: string
+): JoinNode[] => {
+  const rootKey = relation.localKey || findPrimaryKey(root);
+  const targetKey = relation.targetKey || findPrimaryKey(relation.target);
+  const rootTable = rootAlias || root.name;
 
-  const pivotJoin = createJoinNode(joinKind, relation.pivotTable.name, pivotCondition);
+  const pivotCondition = eq(
+    { type: 'Column', table: relation.pivotTable.name, name: relation.pivotForeignKeyToRoot },
+    { type: 'Column', table: rootTable, name: rootKey }
+  );
+
+  const pivotJoin = createJoinNode(
+    joinKind,
+    { type: 'Table', name: relation.pivotTable.name, schema: relation.pivotTable.schema },
+    pivotCondition
+  );
 
   let targetCondition: ExpressionNode = eq(
     { type: 'Column', table: relation.target.name, name: targetKey },
@@ -81,7 +92,7 @@ export const buildBelongsToManyJoins = (
 
   const targetJoin = createJoinNode(
     joinKind,
-    relation.target.name,
+    { type: 'Table', name: relation.target.name, schema: relation.target.schema },
     targetCondition,
     relationName
   );
@@ -94,24 +105,26 @@ export const buildBelongsToManyJoins = (
  * @param root - Root table definition
  * @param relation - Relation definition
  * @param extra - Optional additional expression to combine with AND
+ * @param rootAlias - Optional alias for the root table
  * @returns Expression node representing the complete join condition
  */
-export const buildRelationJoinCondition = (
-  root: TableDef,
-  relation: RelationDef,
-  extra?: ExpressionNode,
-  rootAlias?: string
-): ExpressionNode => {
-  const base = baseRelationCondition(root, relation, rootAlias);
-  return extra ? and(base, extra) : base;
-};
+export const buildRelationJoinCondition = (
+  root: TableDef,
+  relation: RelationDef,
+  extra?: ExpressionNode,
+  rootAlias?: string
+): ExpressionNode => {
+  const base = baseRelationCondition(root, relation, rootAlias);
+  return extra ? and(base, extra) : base;
+};
 
 /**
  * Builds a relation correlation condition for subqueries
  * @param root - Root table definition
  * @param relation - Relation definition
+ * @param rootAlias - Optional alias for the root table
  * @returns Expression node representing the correlation condition
  */
-export const buildRelationCorrelation = (root: TableDef, relation: RelationDef, rootAlias?: string): ExpressionNode => {
-  return baseRelationCondition(root, relation, rootAlias);
-};
+export const buildRelationCorrelation = (root: TableDef, relation: RelationDef, rootAlias?: string): ExpressionNode => {
+  return baseRelationCondition(root, relation, rootAlias);
+};

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

@@ -20,8 +20,8 @@ import {
 } from './relation-conditions.js';
 import { JoinKind, JOIN_KINDS } from '../core/sql/sql.js';
 import { RelationIncludeOptions } from './relation-types.js';
-import { createJoinNode } from '../core/ast/join-node.js';
-import { getJoinRelationName } from '../core/ast/join-metadata.js';
+import { createJoinNode } from '../core/ast/join-node.js';
+import { getJoinRelationName } from '../core/ast/join-metadata.js';
 import { makeRelationAlias } from './relation-alias.js';
 import { buildDefaultPivotColumns } from './relation-utils.js';
 
@@ -70,17 +70,17 @@ export class RelationService {
    * @param predicate - Optional predicate expression
    * @returns Relation result with updated state and hydration
    */
-  match(
-    relationName: string,
-    predicate?: ExpressionNode
-  ): RelationResult {
-    const joined = this.joinRelation(relationName, JOIN_KINDS.INNER, predicate);
-    const pk = findPrimaryKey(this.table);
-    const distinctCols: ColumnNode[] = [{ type: 'Column', table: this.rootTableName(), name: pk }];
-    const existingDistinct = joined.state.ast.distinct ? joined.state.ast.distinct : [];
-    const nextState = this.astService(joined.state).withDistinct([...existingDistinct, ...distinctCols]);
-    return { state: nextState, hydration: joined.hydration };
-  }
+  match(
+    relationName: string,
+    predicate?: ExpressionNode
+  ): RelationResult {
+    const joined = this.joinRelation(relationName, JOIN_KINDS.INNER, predicate);
+    const pk = findPrimaryKey(this.table);
+    const distinctCols: ColumnNode[] = [{ type: 'Column', table: this.rootTableName(), name: pk }];
+    const existingDistinct = joined.state.ast.distinct ? joined.state.ast.distinct : [];
+    const nextState = this.astService(joined.state).withDistinct([...existingDistinct, ...distinctCols]);
+    return { state: nextState, hydration: joined.hydration };
+  }
 
   /**
    * Includes a relation in the query result
@@ -94,7 +94,7 @@ export class RelationService {
 
     const relation = this.getRelation(relationName);
     const aliasPrefix = options?.aliasPrefix ?? relationName;
-    const alreadyJoined = state.ast.joins.some(j => getJoinRelationName(j) === relationName);
+    const alreadyJoined = state.ast.joins.some(j => getJoinRelationName(j) === relationName);
 
     if (!alreadyJoined) {
       const joined = this.joinRelation(relationName, options?.joinKind ?? JOIN_KINDS.LEFT, options?.filter);
@@ -114,7 +114,7 @@ export class RelationService {
       prefix: string,
       keys: string[],
       missingMsg: (col: string) => string
-    ) : Record<string, ColumnDef> => {
+    ): Record<string, ColumnDef> => {
       return keys.reduce((acc, key) => {
         const def = columns[key];
         if (!def) {
@@ -190,22 +190,22 @@ export class RelationService {
    * @param ast - Query AST to modify
    * @returns Modified query AST with relation correlation
    */
-  applyRelationCorrelation(
-    relationName: string,
-    ast: SelectQueryNode,
-    additionalCorrelation?: ExpressionNode
-  ): SelectQueryNode {
-    const relation = this.getRelation(relationName);
-    const rootAlias = this.state.ast.from.type === 'Table' ? this.state.ast.from.alias : undefined;
-    let correlation = buildRelationCorrelation(this.table, relation, rootAlias);
-    if (additionalCorrelation) {
-      correlation = and(correlation, additionalCorrelation);
-    }
-    const whereInSubquery = ast.where
-      ? and(correlation, ast.where)
-      : correlation;
-
-    return {
+  applyRelationCorrelation(
+    relationName: string,
+    ast: SelectQueryNode,
+    additionalCorrelation?: ExpressionNode
+  ): SelectQueryNode {
+    const relation = this.getRelation(relationName);
+    const rootAlias = this.state.ast.from.type === 'Table' ? this.state.ast.from.alias : undefined;
+    let correlation = buildRelationCorrelation(this.table, relation, rootAlias);
+    if (additionalCorrelation) {
+      correlation = and(correlation, additionalCorrelation);
+    }
+    const whereInSubquery = ast.where
+      ? and(correlation, ast.where)
+      : correlation;
+
+    return {
       ...ast,
       where: whereInSubquery
     };
@@ -219,28 +219,33 @@ export class RelationService {
    * @param extraCondition - Additional join condition
    * @returns Updated query state with join
    */
-  private withJoin(
-    state: SelectQueryState,
-    relationName: string,
-    joinKind: JoinKind,
-    extraCondition?: ExpressionNode
-  ): SelectQueryState {
-    const relation = this.getRelation(relationName);
-    const rootAlias = state.ast.from.type === 'Table' ? state.ast.from.alias : undefined;
-    if (relation.type === RelationKinds.BelongsToMany) {
-      const joins = buildBelongsToManyJoins(
-        this.table,
-        relationName,
-        relation as BelongsToManyRelation,
-        joinKind,
-        extraCondition,
-        rootAlias
-      );
-      return joins.reduce((current, join) => this.astService(current).withJoin(join), state);
-    }
-
-    const condition = buildRelationJoinCondition(this.table, relation, extraCondition, rootAlias);
-    const joinNode = createJoinNode(joinKind, relation.target.name, condition, relationName);
+  private withJoin(
+    state: SelectQueryState,
+    relationName: string,
+    joinKind: JoinKind,
+    extraCondition?: ExpressionNode
+  ): SelectQueryState {
+    const relation = this.getRelation(relationName);
+    const rootAlias = state.ast.from.type === 'Table' ? state.ast.from.alias : undefined;
+    if (relation.type === RelationKinds.BelongsToMany) {
+      const joins = buildBelongsToManyJoins(
+        this.table,
+        relationName,
+        relation as BelongsToManyRelation,
+        joinKind,
+        extraCondition,
+        rootAlias
+      );
+      return joins.reduce((current, join) => this.astService(current).withJoin(join), state);
+    }
+
+    const condition = buildRelationJoinCondition(this.table, relation, extraCondition, rootAlias);
+    const joinNode = createJoinNode(
+      joinKind,
+      { type: 'Table', name: relation.target.name, schema: relation.target.schema },
+      condition,
+      relationName
+    );
 
     return this.astService(state).withJoin(joinNode);
   }
@@ -284,15 +289,15 @@ export class RelationService {
    * @param state - Current query state
    * @returns QueryAstService instance
    */
-  private astService(state: SelectQueryState = this.state): QueryAstService {
-    return this.createQueryAstService(this.table, state);
-  }
-
-  private rootTableName(): string {
-    const from = this.state.ast.from;
-    if (from.type === 'Table' && from.alias) return from.alias;
-    return this.table.name;
-  }
-}
+  private astService(state: SelectQueryState = this.state): QueryAstService {
+    return this.createQueryAstService(this.table, state);
+  }
+
+  private rootTableName(): string {
+    const from = this.state.ast.from;
+    if (from.type === 'Table' && from.alias) return from.alias;
+    return this.table.name;
+  }
+}
 
 export type { RelationResult } from './relation-projection-helper.js';

package/src/query-builder/relation-utils.ts

@@ -2,6 +2,9 @@ import { BelongsToManyRelation } from '../schema/relation.js';
 
 /**
  * Builds a default set of pivot columns, excluding keys used for joins.
+ * @param rel - The BelongsToMany relation definition
+ * @param pivotPk - The primary key column name of the pivot table
+ * @returns Array of column names that can be included in pivot table selections
  */
 export const buildDefaultPivotColumns = (
   rel: BelongsToManyRelation,

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

@@ -0,0 +1,40 @@
+import { SelectQueryNode } 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 Common Table Expressions (WITH clauses)
+ */
+export class SelectCTEFacet {
+    /**
+     * Creates a new SelectCTEFacet 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 Common Table Expression to the query
+     * @param context - Current query context
+     * @param name - CTE name
+     * @param subAst - CTE query AST
+     * @param columns - Optional column names
+     * @param recursive - Whether the CTE is recursive
+     * @returns Updated query context with CTE
+     */
+    withCTE(
+        context: SelectQueryBuilderContext,
+        name: string,
+        subAst: SelectQueryNode,
+        columns: string[] | undefined,
+        recursive: boolean
+    ): SelectQueryBuilderContext {
+        const astService = this.createAstService(context.state);
+        const nextState = astService.withCte(name, subAst, columns, recursive);
+        return { state: nextState, hydration: context.hydration };
+    }
+}

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

@@ -0,0 +1,80 @@
+import { SelectQueryNode } from '../../core/ast/query.js';
+import { OperandNode } from '../../core/ast/expression.js';
+import { derivedTable, fnTable } from '../../core/ast/builders.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 FROM clause operations
+ */
+export class SelectFromFacet {
+    /**
+     * Creates a new SelectFromFacet 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 an alias to the FROM table
+     * @param context - Current query context
+     * @param alias - Alias to apply
+     * @returns Updated query context with aliased FROM
+     */
+    as(context: SelectQueryBuilderContext, alias: string): SelectQueryBuilderContext {
+        const from = context.state.ast.from;
+        if (from.type !== 'Table') {
+            throw new Error('Cannot alias non-table FROM sources');
+        }
+        const nextFrom = { ...from, alias };
+        const astService = this.createAstService(context.state);
+        const nextState = astService.withFrom(nextFrom);
+        return { state: nextState, hydration: context.hydration };
+    }
+
+    /**
+     * Sets the FROM clause to a subquery
+     * @param context - Current query context
+     * @param subAst - Subquery AST
+     * @param alias - Alias for the subquery
+     * @param columnAliases - Optional column aliases
+     * @returns Updated query context with subquery FROM
+     */
+    fromSubquery(
+        context: SelectQueryBuilderContext,
+        subAst: SelectQueryNode,
+        alias: string,
+        columnAliases?: string[]
+    ): SelectQueryBuilderContext {
+        const fromNode = derivedTable(subAst, alias, columnAliases);
+        const astService = this.createAstService(context.state);
+        const nextState = astService.withFrom(fromNode);
+        return { state: nextState, hydration: context.hydration };
+    }
+
+    /**
+     * Sets the FROM clause to a function table
+     * @param context - Current query context
+     * @param name - Function name
+     * @param args - Function arguments
+     * @param alias - Optional alias for the function table
+     * @param options - Optional function table options
+     * @returns Updated query context with function table FROM
+     */
+    fromFunctionTable(
+        context: SelectQueryBuilderContext,
+        name: string,
+        args: OperandNode[],
+        alias?: string,
+        options?: { lateral?: boolean; withOrdinality?: boolean; columnAliases?: string[]; schema?: string }
+    ): SelectQueryBuilderContext {
+        const functionTable = fnTable(name, args, alias, options);
+        const astService = this.createAstService(context.state);
+        const nextState = astService.withFrom(functionTable);
+        return { state: nextState, hydration: context.hydration };
+    }
+}

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

@@ -0,0 +1,62 @@
+import { TableDef } from '../../schema/table.js';
+import { BinaryExpressionNode } from '../../core/ast/expression.js';
+import { SelectQueryNode } from '../../core/ast/query.js';
+import { JoinKind } from '../../core/sql/sql.js';
+import { derivedTable, fnTable } from '../../core/ast/builders.js';
+import { createJoinNode } from '../../core/ast/join-node.js';
+import { SelectQueryBuilderContext, SelectQueryBuilderEnvironment } from '../select-query-builder-deps.js';
+import { QueryAstService } from '../query-ast-service.js';
+import { OperandNode } from '../../core/ast/expression.js';
+import { SelectQueryState } from '../select-query-state.js';
+
+/**
+ * Facet responsible for JOIN operations
+ */
+export class SelectJoinFacet {
+    constructor(
+        private readonly env: SelectQueryBuilderEnvironment,
+        private readonly createAstService: (state: SelectQueryState) => QueryAstService
+    ) { }
+
+    applyJoin(
+        context: SelectQueryBuilderContext,
+        table: TableDef,
+        condition: BinaryExpressionNode,
+        kind: JoinKind
+    ): SelectQueryBuilderContext {
+        const joinNode = createJoinNode(kind, { type: 'Table', name: table.name, schema: table.schema }, condition);
+        const astService = this.createAstService(context.state);
+        const nextState = astService.withJoin(joinNode);
+        return { state: nextState, hydration: context.hydration };
+    }
+
+    joinSubquery(
+        context: SelectQueryBuilderContext,
+        subAst: SelectQueryNode,
+        alias: string,
+        condition: BinaryExpressionNode,
+        joinKind: JoinKind,
+        columnAliases?: string[]
+    ): SelectQueryBuilderContext {
+        const joinNode = createJoinNode(joinKind, derivedTable(subAst, alias, columnAliases), condition);
+        const astService = this.createAstService(context.state);
+        const nextState = astService.withJoin(joinNode);
+        return { state: nextState, hydration: context.hydration };
+    }
+
+    joinFunctionTable(
+        context: SelectQueryBuilderContext,
+        name: string,
+        args: OperandNode[],
+        alias: string,
+        condition: BinaryExpressionNode,
+        joinKind: JoinKind,
+        options?: { lateral?: boolean; withOrdinality?: boolean; columnAliases?: string[]; schema?: string }
+    ): SelectQueryBuilderContext {
+        const functionTable = fnTable(name, args, alias, options);
+        const joinNode = createJoinNode(joinKind, functionTable, condition);
+        const astService = this.createAstService(context.state);
+        const nextState = astService.withJoin(joinNode);
+        return { state: nextState, hydration: context.hydration };
+    }
+}