typhex 0.1.0-alpha.0

package/dist/orm/helpers/query-plan/query-plan.d.ts

@@ -0,0 +1,164 @@
+/**
+ * QueryPlanBuilder: converts a `QueryState` into a dialect-agnostic `QueryPlan`.
+ *
+ * # Where this fits
+ *
+ * The query pipeline has three layers:
+ *
+ * 1. **QueryBuilder** (`src/orm/query-builder.ts`) — accumulates user calls
+ *    (`.where`, `.orderBy`, `.select`, …) into a `QueryState`. The state
+ *    holds raw IR predicates, the three param bags (where/having/subquery),
+ *    join hints, etc. — it's the user-facing input.
+ * 2. **QueryPlanBuilder** (this file) — takes a `QueryState` and produces
+ *    a `QueryPlan`: a flat, dialect-agnostic structure where every column
+ *    reference has been resolved to a (table-alias, column-path) pair,
+ *    every captured `QueryBuilder` has been inlined as a child plan,
+ *    relations have been split into joins / fetches / projections, and
+ *    the EXISTS / SUBQUERY / IN shapes have been pre-resolved.
+ * 3. **QueryCompiler** (`src/dbs/<dialect>/query-compiler`) — walks the
+ *    `QueryPlan`'s `Expr` tree to emit SQL strings + parameter arrays.
+ *    The dialect never sees IR; the planner is the only IR consumer.
+ *
+ * # The five planning phases
+ *
+ * `build()` runs them in order:
+ *
+ * 1. **Alias scope** (`buildParamToAlias`).
+ *    Decide which row-param names resolve to which SQL table aliases.
+ *    Subqueries inherit their parent's mapping plus their own aliases.
+ * 2. **Relation detection** (`detectRelations`). Decide which relations
+ *    get joined into the main SELECT vs. kept for the relation pipeline,
+ *    and pre-resolve any one-to-many EXISTS predicates. Delegated to
+ *    relation helper classes for the heavy lifting.
+ * 3. **Select classification** (`classifySelect`). Split the IR select
+ *    into joined columns, fetched relations, and joined projections.
+ *    Delegated to `SelectClassifier`.
+ * 4. **IR → Expr conversion**. Pre-build captured child query plans, then
+ *    convert where, having, orderBy, groupBy, and the select-list through
+ *    `ExprBuilder` using only precomputed context.
+ * 5. **Plan assembly**. Stamp everything onto a `QueryPlan` value object.
+ *
+ * # Subqueries
+ *
+ * Inline subqueries (correlated or otherwise) are planned before IR→Expr
+ * conversion. The outer scope (current `paramToAlias` and the chosen
+ * sub-alias) is threaded through so correlated column references in the
+ * inner plan resolve against the outer table alias
+ * — that's how `Author.query().select(a => ({ totalPosts:
+ * Post.query().where(p => p.authorId === a.id).select(() => count()) }))`
+ * compiles to a SQL subquery referencing `t0.id`.
+ */
+import { type IrSelectRelation, type JoinHint } from "../../../ir/types.js";
+import type { RelationType } from "../../../entity/relations.js";
+import type { AnyEntityClass } from "../../../entity/entity.js";
+import type { QueryOperation, WithClause } from "../../../dbs/types.js";
+import type { FromSource } from "../../query-state.js";
+import type { Expr, GroupByItem, JoinSpec, OrderItem, SelectItem } from "../../expr.js";
+/** Default name for the row-param when no explicit one is in scope. */
+export declare const DEFAULT_ROW_PARAM = "u";
+/**
+ * Everything the relation-fetcher needs to execute a secondary load for
+ * one relation. Built by `SelectClassifier.buildRelationFetchMeta` from
+ * the relation definition + IR projection, then read by
+ * `helpers/relations/relation-fetcher.ts`.
+ *
+ * Field layout depends on `relationType`:
+ * - **many-to-one / one-to-one**: `fkColumns` are the parent's FK
+ *   columns, `targetPkColumns` are the related entity's PK; secondary
+ *   query is `SELECT * FROM target WHERE pk IN (...fkValues)`.
+ * - **one-to-many**: `fkColumns` are on the *child*; `parentPkColumns`
+ *   is stamped on after classification with the parent's PK columns;
+ *   secondary query joins child.fk against parent.pk values.
+ * - **many-to-many**: `junction` describes the link table; the fetcher
+ *   joins through it.
+ */
+export interface RelationFetchMetadata {
+    relationType: RelationType;
+    relation: IrSelectRelation;
+    fkColumns: string[];
+    targetPkColumns: string[];
+    targetEntity: AnyEntityClass;
+    parentPkColumns?: string[];
+    junction?: {
+        table: string;
+        foreignKey: string[];
+        referenceKey: string[];
+    };
+}
+/**
+ * Recipe for reshaping flat JOIN-result columns back into nested
+ * relation objects on the parent row. For example, if the parent SELECT
+ * contains `t1.name AS author_name`, the assembler reads
+ * `members: [{ alias: "author_name", subPath: "name" }]` and writes
+ * `parent[outputKey].name = row.author_name`.
+ *
+ * Built by `SelectClassifier` and consumed by `RelationAssembler`.
+ */
+export interface JoinedProjection {
+    relationKey: string;
+    outputKey: string;
+    /** Aliases in the result row that came from the JOIN, paired with their sub-path. */
+    members: Array<{
+        alias: string;
+        subPath: string;
+    }>;
+}
+/**
+ * Dialect-agnostic execution plan. Produced by `QueryPlanBuilder` and
+ * consumed by `QueryCompiler.compilePlan` (which produces SQL) plus the
+ * relation pipeline (which uses the relation* fields to load and shape
+ * fetched data after the main query runs).
+ *
+ * Splits into four logical groups:
+ *
+ * - **Operation + table**: `operation`, `tableName`, `tableAlias`,
+ *   `columnNames` — what to do, on which table, under which alias.
+ * - **SQL pieces**: `where`, `having`, `orderBy`, `groupBy`, `limitNum`,
+ *   `offsetNum`, `selectItems`, `selectAll`, `joins` — the SQL body, all
+ *   in resolved `Expr` form (no IR).
+ * - **Relation pipeline**: `relationFetches`, `joinedProjections`,
+ *   `skipLoadFor` — used after SQL execution to fetch and assemble
+ *   related data.
+ * - **Late-bound params**: `whereParams`, `havingParams` — original
+ *   user-supplied bags; the dialect resolves `__param` sentinels against
+ *   them at compile time.
+ */
+export interface QueryPlan {
+    operation: QueryOperation;
+    tableName: string;
+    tableAlias: string;
+    columnNames: string[];
+    where: Expr | null;
+    having: Expr | null;
+    orderBy: OrderItem[];
+    groupBy: GroupByItem[];
+    limitNum: number | null;
+    offsetNum: number | null;
+    selectItems: SelectItem[];
+    /** When true, no SELECT-list was specified; emit `<alias>.<col>` for every columnName. */
+    selectAll: boolean;
+    joins: JoinSpec[];
+    relationFetches: RelationFetchMetadata[];
+    joinedProjections: JoinedProjection[];
+    skipLoadFor: Set<string>;
+    whereParams: Record<string, unknown>;
+    havingParams: Record<string, unknown>;
+    /** WITH clauses (uncompiled); rendered during compilation. */
+    ctes?: WithClause[];
+    /** Outer FROM source (base table, CTE name, or inline subquery). */
+    fromSource?: FromSource;
+    /** UNION ALL branch for this SELECT. */
+    unionAll?: QueryPlan;
+    /** Primary key columns of the entity table. */
+    pkColumns: string[];
+    /** Resolved SET expressions for UPDATE (literals and/or CTE column refs). */
+    updateSet?: Record<string, Expr>;
+    /** Registered sibling CTE names visible in this plan (callback `withCte` bodies). */
+    inScopeRegisteredCteNames?: string[];
+    /** Registered CTE names referenced in where/having/update IR (planning-time). */
+    referencedRegisteredCtes: string[];
+}
+/** Re-export so the legacy `import type { JoinHint } from "./query-plan"` path
+ *  keeps working for any consumer that still does it. */
+export type { JoinHint };
+//# sourceMappingURL=query-plan.d.ts.map

package/dist/orm/helpers/query-plan/query-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-plan.d.ts","sourceRoot":"","sources":["../../../../src/orm/helpers/query-plan/query-plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAC5E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAA0B,cAAc,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAQhG,OAAO,KAAK,EAAE,UAAU,EAAc,MAAM,sBAAsB,CAAC;AACnE,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAKxF,uEAAuE;AACvE,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAkBrC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,qBAAqB;IACpC,YAAY,EAAE,YAAY,CAAC;IAC3B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,YAAY,EAAE,cAAc,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,QAAQ,CAAC,EAAE;QACT,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,EAAE,CAAC;QACrB,YAAY,EAAE,MAAM,EAAE,CAAC;KACxB,CAAC;CACH;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,qFAAqF;IACrF,OAAO,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACpD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,cAAc,CAAC;IAE1B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,EAAE,CAAC;IAEtB,KAAK,EAAE,IAAI,GAAG,IAAI,CAAC;IACnB,MAAM,EAAE,IAAI,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzB,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,0FAA0F;IAC1F,SAAS,EAAE,OAAO,CAAC;IAEnB,KAAK,EAAE,QAAQ,EAAE,CAAC;IAElB,eAAe,EAAE,qBAAqB,EAAE,CAAC;IACzC,iBAAiB,EAAE,gBAAgB,EAAE,CAAC;IACtC,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAEzB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEtC,8DAA8D;IAC9D,IAAI,CAAC,EAAE,UAAU,EAAE,CAAC;IACpB,oEAAoE;IACpE,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACjC,qFAAqF;IACrF,yBAAyB,CAAC,EAAE,MAAM,EAAE,CAAC;IACrC,iFAAiF;IACjF,wBAAwB,EAAE,MAAM,EAAE,CAAC;CACpC;AAwmBD;yDACyD;AACzD,YAAY,EAAE,QAAQ,EAAE,CAAC"}