typhex 0.1.0-alpha.0

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

@@ -0,0 +1,161 @@
+/**
+ * Select-list classification.
+ *
+ * A user-written `.select(...)` body can mix three kinds of references:
+ * plain columns (`u.name`), relation roots (`u.author`), and members of
+ * relations (`u.author.name`). How each is rendered depends on whether
+ * its relation is *joined* into the main SELECT (and therefore its
+ * columns can ride along) or *not joined* (and so the data has to be
+ * fetched separately by the relation pipeline).
+ *
+ * `SelectClassifier.classify()` walks the IR select once and produces a
+ * `ClassifiedSelect` that tells the rest of the planner how to handle
+ * each entry:
+ *
+ * - **`columnPaths` / `columnAliases`** — column references that should
+ *   appear in the SQL SELECT list, as `<alias>.<col>` references. These
+ *   include leaf columns, joined-relation members, and any join-key
+ *   columns that need to be added so the row hydrator can pair fetched
+ *   relation rows with their parents.
+ * - **`relationFetches`** — relations that need a separate eager-load
+ *   query (one-to-many, many-to-many, or non-joined many-to-one). The
+ *   relation-fetcher reads this list to produce the WHERE-IN secondary
+ *   queries.
+ * - **`joinedProjections`** — relations whose data came in via the JOIN
+ *   and needs to be re-shaped from flat result columns back into nested
+ *   objects. Drives `RelationAssembler.assembleJoined`.
+ * - **`skipLoadFor`** — relation keys whose data is already in the
+ *   SELECT-list via the JOIN; the eager-loader skips re-fetching these.
+ *
+ * The classifier is constructed once with the inputs that all five
+ * helper methods share, so the methods can be small and read directly
+ * from `this.*` rather than threading a context object.
+ */
+import type { IrSelect } from "../../../ir/types.js";
+import type { RelationsMap } from "../../../entity/relations.js";
+import type { RelationFetchMetadata, JoinedProjection } from "./query-plan.js";
+/**
+ * Result of classifying an IrSelect.
+ *
+ * `columnPaths` / `columnAliases` carry `null` when the original IR's
+ * paths/aliases should be used verbatim — that's the no-relations
+ * fast-path. Otherwise both are non-null and parallel: `columnPaths[i]`
+ * is the path, `columnAliases[i]` is its SELECT-list alias.
+ */
+export interface ClassifiedSelect {
+    columnPaths: string[][] | null;
+    columnAliases: string[] | null;
+    relationFetches: RelationFetchMetadata[];
+    joinedProjections: JoinedProjection[];
+    skipLoadFor: Set<string>;
+    reusableJoinKeys: Set<string>;
+}
+/**
+ * Sentinel used by the planner when classification isn't needed (e.g.
+ * mutations like UPDATE/DELETE that have no SELECT list to classify).
+ * Identity-shared so equality checks stay cheap.
+ */
+export declare const EMPTY_CLASSIFIED: ClassifiedSelect;
+/**
+ * Classifies an `IrSelect` against the known relation map.
+ *
+ * Constructor inputs:
+ * - `select` — the IR select tree from `state.selectIr`.
+ * - `relations` — the relation map of the entity being queried; used to
+ *   recognise relation keys in the IR and build fetch metadata.
+ * - `pkColumns` — primary-key columns of the parent entity. Used for
+ *   `parentPkColumns` on to-many fetches and to ensure key columns are
+ *   included for to-many parents.
+ * - `reusableJoinKeys` — relation keys that the planner has decided to
+ *   join into the main SELECT because the where/orderBy already need
+ *   that join. When non-empty, members of these relations stay in the
+ *   SELECT list rather than triggering a separate fetch.
+ */
+export declare class SelectClassifier {
+    private readonly select;
+    private readonly relations;
+    private readonly pkColumns;
+    private readonly reusableJoinKeys;
+    constructor(select: IrSelect, relations: RelationsMap, pkColumns: string[], reusableJoinKeys: Set<string>);
+    /**
+     * Run the classification pipeline:
+     *
+     * 1. Fast-path: if neither the select's paths nor its `relations` field
+     *    references any known relation, return a no-op classification (the
+     *    planner falls back to the IR's own paths/aliases).
+     * 2. Walk `select.paths` once, populating column lists, fetch metadata,
+     *    joined-projection entries, and the skip-load set as we go.
+     * 3. Walk `select.relations` once, doing the same for nested-relation
+     *    projections (e.g. `{ posts: p => ({ id: p.id, title: p.title }) }`).
+     * 4. Add any join-key columns that fetches need but the user didn't
+     *    explicitly select — the row hydrator can't pair fetched rows with
+     *    parents without them.
+     * 5. Stamp `parentPkColumns` onto to-many fetches.
+     *
+     * `joinedProjections` and `skipLoadFor` are populated incrementally
+     * inside the path/relation walks rather than via two extra passes
+     * because the matching condition (`reusableJoinKeys.has(...)` plus a
+     * length check) is exactly the same as the one that decides whether
+     * a member rides along the JOIN.
+     */
+    classify(): ClassifiedSelect;
+    /**
+     * Walk the IR `select.paths` array — every member-access in the user's
+     * select body lands here as a `string[]` path. Three cases:
+     *
+     * - **Leaf column** (`p.col`) — path doesn't start with a relation key,
+     *   so it goes straight into the SELECT list as `<alias>.<col>`.
+     * - **Relation root** (`p.author`) — path is exactly `[relKey]`. Means
+     *   "fetch the whole related entity"; produces a `relationFetch`.
+     * - **Relation member** (`p.author.name`) — depends on whether the
+     *   relation is in `joinedRelationKeys`:
+     *     - Joined → emit a column path on the JOIN's alias (rendered as
+     *       e.g. `t1.name AS author_name`), record a projection entry on
+     *       `joinedByKey` so the assembler can reshape the flat row, and
+     *       add the relation key to `skipLoadFor` so the eager-loader
+     *       doesn't redundantly fetch it.
+     *     - Not joined → produce a `relationFetch` carrying just that
+     *       sub-path so the eager-loader's secondary query selects only
+     *       what was asked for.
+     *
+     * Side effects on `joinedByKey` and `skipLoadFor` mean we don't need a
+     * second pass over `select.paths` to compute those outputs.
+     */
+    private classifyPathEntries;
+    /**
+     * Walk the IR `select.relations` array — these come from explicit
+     * nested-relation projections (e.g. selecting `posts: p => ({ id, title })`
+     * means the IR carries a `{ name: "posts", outputKey: "posts",
+     * subPaths: [["id"], ["title"]] }` entry).
+     *
+     * `seenOutputKeys` is the set of `outputKey`s already produced by
+     * `classifyPathEntries` — duplicates here would cause the relation
+     * pipeline to fetch the same data twice or produce ambiguous result
+     * shapes, so we just skip them.
+     *
+     * Joined relation with non-empty subPaths → emit each subPath as a
+     * column-list entry (column names like `posts_title`), record a
+     * `joinedByKey` entry (overriding `outputKey` when the user aliased
+     * the relation), and add the relation to `skipLoadFor`. Non-joined or
+     * no subPaths → produce a relationFetch, the eager-loader handles it.
+     */
+    private classifyRelationEntries;
+    /**
+     * Make sure every join-key column a `relationFetch` needs is in the
+     * parent's SELECT list. Without this, the relation-fetcher would have
+     * the secondary query's rows but no way to pair them back to the
+     * correct parent row.
+     *
+     * The "key" columns differ by relation kind:
+     * - **to-many** (one-to-many, many-to-many): the parent's PK columns —
+     *   the secondary query joins the child's FK against this.
+     * - **to-one** (many-to-one, one-to-one): the parent's FK columns
+     *   stored on this row.
+     *
+     * Returns only the *missing* keys. Anything already in `existingPaths`
+     * is skipped to avoid duplicate SELECT entries (which would also break
+     * the row hydrator since aliases would clash).
+     */
+    private missingJoinKeyColumns;
+}
+//# sourceMappingURL=select-classifier.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"select-classifier.d.ts","sourceRoot":"","sources":["../../../../src/orm/helpers/query-plan/select-classifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAoB,MAAM,sBAAsB,CAAC;AACvE,OAAO,KAAK,EACV,YAAY,EAIb,MAAM,8BAA8B,CAAC;AAItC,OAAO,KAAK,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAE/E;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,EAAE,EAAE,GAAG,IAAI,CAAC;IAC/B,aAAa,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC/B,eAAe,EAAE,qBAAqB,EAAE,CAAC;IACzC,iBAAiB,EAAE,gBAAgB,EAAE,CAAC;IACtC,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACzB,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC/B;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,gBAO9B,CAAC;AAcF;;;;;;;;;;;;;;GAcG;AACH,qBAAa,gBAAgB;IAEzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,gBAAgB;gBAHhB,MAAM,EAAE,QAAQ,EAChB,SAAS,EAAE,YAAY,EACvB,SAAS,EAAE,MAAM,EAAE,EACnB,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC;IAGhD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,QAAQ,IAAI,gBAAgB;IAyD5B;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,OAAO,CAAC,mBAAmB;IAoD3B;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,uBAAuB;IAoD/B;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,qBAAqB;CA0B9B"}

package/dist/orm/helpers/query-plan/select-classifier.js

@@ -0,0 +1,359 @@
+/**
+ * Select-list classification.
+ *
+ * A user-written `.select(...)` body can mix three kinds of references:
+ * plain columns (`u.name`), relation roots (`u.author`), and members of
+ * relations (`u.author.name`). How each is rendered depends on whether
+ * its relation is *joined* into the main SELECT (and therefore its
+ * columns can ride along) or *not joined* (and so the data has to be
+ * fetched separately by the relation pipeline).
+ *
+ * `SelectClassifier.classify()` walks the IR select once and produces a
+ * `ClassifiedSelect` that tells the rest of the planner how to handle
+ * each entry:
+ *
+ * - **`columnPaths` / `columnAliases`** — column references that should
+ *   appear in the SQL SELECT list, as `<alias>.<col>` references. These
+ *   include leaf columns, joined-relation members, and any join-key
+ *   columns that need to be added so the row hydrator can pair fetched
+ *   relation rows with their parents.
+ * - **`relationFetches`** — relations that need a separate eager-load
+ *   query (one-to-many, many-to-many, or non-joined many-to-one). The
+ *   relation-fetcher reads this list to produce the WHERE-IN secondary
+ *   queries.
+ * - **`joinedProjections`** — relations whose data came in via the JOIN
+ *   and needs to be re-shaped from flat result columns back into nested
+ *   objects. Drives `RelationAssembler.assembleJoined`.
+ * - **`skipLoadFor`** — relation keys whose data is already in the
+ *   SELECT-list via the JOIN; the eager-loader skips re-fetching these.
+ *
+ * The classifier is constructed once with the inputs that all five
+ * helper methods share, so the methods can be small and read directly
+ * from `this.*` rather than threading a context object.
+ */
+import { getPkColumnsFromSchema } from "../../../entity/pk-columns.js";
+import { toArray } from "../../../utils.js";
+/**
+ * Sentinel used by the planner when classification isn't needed (e.g.
+ * mutations like UPDATE/DELETE that have no SELECT list to classify).
+ * Identity-shared so equality checks stay cheap.
+ */
+export const EMPTY_CLASSIFIED = {
+    columnPaths: null,
+    columnAliases: null,
+    relationFetches: [],
+    joinedProjections: [],
+    skipLoadFor: new Set(),
+    reusableJoinKeys: new Set(),
+};
+/**
+ * Classifies an `IrSelect` against the known relation map.
+ *
+ * Constructor inputs:
+ * - `select` — the IR select tree from `state.selectIr`.
+ * - `relations` — the relation map of the entity being queried; used to
+ *   recognise relation keys in the IR and build fetch metadata.
+ * - `pkColumns` — primary-key columns of the parent entity. Used for
+ *   `parentPkColumns` on to-many fetches and to ensure key columns are
+ *   included for to-many parents.
+ * - `reusableJoinKeys` — relation keys that the planner has decided to
+ *   join into the main SELECT because the where/orderBy already need
+ *   that join. When non-empty, members of these relations stay in the
+ *   SELECT list rather than triggering a separate fetch.
+ */
+export class SelectClassifier {
+    select;
+    relations;
+    pkColumns;
+    reusableJoinKeys;
+    constructor(select, relations, pkColumns, reusableJoinKeys) {
+        this.select = select;
+        this.relations = relations;
+        this.pkColumns = pkColumns;
+        this.reusableJoinKeys = reusableJoinKeys;
+    }
+    /**
+     * Run the classification pipeline:
+     *
+     * 1. Fast-path: if neither the select's paths nor its `relations` field
+     *    references any known relation, return a no-op classification (the
+     *    planner falls back to the IR's own paths/aliases).
+     * 2. Walk `select.paths` once, populating column lists, fetch metadata,
+     *    joined-projection entries, and the skip-load set as we go.
+     * 3. Walk `select.relations` once, doing the same for nested-relation
+     *    projections (e.g. `{ posts: p => ({ id: p.id, title: p.title }) }`).
+     * 4. Add any join-key columns that fetches need but the user didn't
+     *    explicitly select — the row hydrator can't pair fetched rows with
+     *    parents without them.
+     * 5. Stamp `parentPkColumns` onto to-many fetches.
+     *
+     * `joinedProjections` and `skipLoadFor` are populated incrementally
+     * inside the path/relation walks rather than via two extra passes
+     * because the matching condition (`reusableJoinKeys.has(...)` plus a
+     * length check) is exactly the same as the one that decides whether
+     * a member rides along the JOIN.
+     */
+    classify() {
+        const { select, relations, reusableJoinKeys } = this;
+        const hasRelations = select.relations?.length || select.paths.some((p) => p.length >= 1 && relations[p[0]]);
+        if (!hasRelations) {
+            return {
+                columnPaths: null,
+                columnAliases: null,
+                relationFetches: [],
+                joinedProjections: [],
+                skipLoadFor: new Set(),
+                reusableJoinKeys,
+            };
+        }
+        const joinedKeys = reusableJoinKeys.size > 0 ? reusableJoinKeys : undefined;
+        const joinedByKey = new Map();
+        const skipLoadFor = new Set();
+        const fromPaths = this.classifyPathEntries(joinedKeys, joinedByKey, skipLoadFor);
+        const seenOutputKeys = new Set(fromPaths.relationFetches.map((m) => m.relation.outputKey));
+        const fromRelations = this.classifyRelationEntries(joinedKeys, seenOutputKeys, joinedByKey, skipLoadFor);
+        const columnPaths = [...fromPaths.columnPaths, ...fromRelations.columnPaths];
+        const columnAliases = [...fromPaths.columnAliases, ...fromRelations.columnAliases];
+        const relationFetches = [...fromPaths.relationFetches, ...fromRelations.relationFetches];
+        const { paths: keyPaths, aliases: keyAliases } = this.missingJoinKeyColumns(relationFetches, columnPaths);
+        columnPaths.push(...keyPaths);
+        columnAliases.push(...keyAliases);
+        for (const f of relationFetches) {
+            if (f.relationType === "one-to-many" || f.relationType === "many-to-many") {
+                f.parentPkColumns = this.pkColumns;
+            }
+        }
+        return {
+            columnPaths,
+            columnAliases,
+            relationFetches,
+            joinedProjections: [...joinedByKey.values()].filter((p) => p.members.length > 0),
+            skipLoadFor,
+            reusableJoinKeys,
+        };
+    }
+    /**
+     * Walk the IR `select.paths` array — every member-access in the user's
+     * select body lands here as a `string[]` path. Three cases:
+     *
+     * - **Leaf column** (`p.col`) — path doesn't start with a relation key,
+     *   so it goes straight into the SELECT list as `<alias>.<col>`.
+     * - **Relation root** (`p.author`) — path is exactly `[relKey]`. Means
+     *   "fetch the whole related entity"; produces a `relationFetch`.
+     * - **Relation member** (`p.author.name`) — depends on whether the
+     *   relation is in `joinedRelationKeys`:
+     *     - Joined → emit a column path on the JOIN's alias (rendered as
+     *       e.g. `t1.name AS author_name`), record a projection entry on
+     *       `joinedByKey` so the assembler can reshape the flat row, and
+     *       add the relation key to `skipLoadFor` so the eager-loader
+     *       doesn't redundantly fetch it.
+     *     - Not joined → produce a `relationFetch` carrying just that
+     *       sub-path so the eager-loader's secondary query selects only
+     *       what was asked for.
+     *
+     * Side effects on `joinedByKey` and `skipLoadFor` mean we don't need a
+     * second pass over `select.paths` to compute those outputs.
+     */
+    classifyPathEntries(joinedRelationKeys, joinedByKey, skipLoadFor) {
+        const { select, relations } = this;
+        const relNames = new Set(Object.keys(relations));
+        const out = {
+            columnPaths: [],
+            columnAliases: [],
+            relationFetches: [],
+        };
+        for (let i = 0; i < select.paths.length; i++) {
+            const path = select.paths[i];
+            const alias = select.aliases?.[i] ?? path[path.length - 1];
+            if (path.length === 1 && relNames.has(path[0])) {
+                const meta = buildRelationFetchMeta({ name: path[0], outputKey: alias }, relations[path[0]]);
+                out.relationFetches.push(meta);
+            }
+            else if (path.length > 1 && relNames.has(path[0])) {
+                if (joinedRelationKeys?.has(path[0])) {
+                    const colAlias = select.aliases?.[i] ?? `${path[0]}_${path[path.length - 1]}`;
+                    out.columnPaths.push(path);
+                    out.columnAliases.push(colAlias);
+                    let proj = joinedByKey.get(path[0]);
+                    if (!proj) {
+                        proj = { relationKey: path[0], outputKey: path[0], members: [] };
+                        joinedByKey.set(path[0], proj);
+                    }
+                    proj.members.push({ alias: colAlias, subPath: path[path.length - 1] });
+                    skipLoadFor.add(path[0]);
+                }
+                else {
+                    const meta = buildRelationFetchMeta({ name: path[0], outputKey: alias, subPaths: [path.slice(1)] }, relations[path[0]]);
+                    out.relationFetches.push(meta);
+                }
+            }
+            else {
+                out.columnPaths.push(path);
+                out.columnAliases.push(alias);
+            }
+        }
+        return out;
+    }
+    /**
+     * Walk the IR `select.relations` array — these come from explicit
+     * nested-relation projections (e.g. selecting `posts: p => ({ id, title })`
+     * means the IR carries a `{ name: "posts", outputKey: "posts",
+     * subPaths: [["id"], ["title"]] }` entry).
+     *
+     * `seenOutputKeys` is the set of `outputKey`s already produced by
+     * `classifyPathEntries` — duplicates here would cause the relation
+     * pipeline to fetch the same data twice or produce ambiguous result
+     * shapes, so we just skip them.
+     *
+     * Joined relation with non-empty subPaths → emit each subPath as a
+     * column-list entry (column names like `posts_title`), record a
+     * `joinedByKey` entry (overriding `outputKey` when the user aliased
+     * the relation), and add the relation to `skipLoadFor`. Non-joined or
+     * no subPaths → produce a relationFetch, the eager-loader handles it.
+     */
+    classifyRelationEntries(joinedRelationKeys, seenOutputKeys, joinedByKey, skipLoadFor) {
+        const { select, relations } = this;
+        const out = {
+            columnPaths: [],
+            columnAliases: [],
+            relationFetches: [],
+        };
+        for (const r of select.relations ?? []) {
+            const relDef = relations[r.name];
+            if (!relDef) {
+                throw new Error(`[typhex] select relation "${r.name}" is not defined on this entity`);
+            }
+            if (seenOutputKeys.has(r.outputKey)) {
+                throw new Error(`[typhex] select relation output "${r.outputKey}" is duplicated`);
+            }
+            seenOutputKeys.add(r.outputKey);
+            if (joinedRelationKeys?.has(r.name) && r.subPaths?.length) {
+                let proj = joinedByKey.get(r.name);
+                if (!proj) {
+                    proj = { relationKey: r.name, outputKey: r.outputKey, members: [] };
+                    joinedByKey.set(r.name, proj);
+                }
+                else {
+                    // A path-driven entry was created earlier with `outputKey: r.name`;
+                    // an explicit relation entry takes precedence (user may have aliased it).
+                    proj.outputKey = r.outputKey;
+                }
+                for (const sub of r.subPaths) {
+                    if (sub.length > 0) {
+                        const alias = `${r.outputKey}_${sub.join("_")}`;
+                        out.columnPaths.push([r.name, ...sub]);
+                        out.columnAliases.push(alias);
+                        proj.members.push({ alias, subPath: sub[sub.length - 1] });
+                    }
+                }
+                skipLoadFor.add(r.name);
+            }
+            else {
+                const meta = buildRelationFetchMeta(r, relDef);
+                out.relationFetches.push(meta);
+            }
+        }
+        return out;
+    }
+    /**
+     * Make sure every join-key column a `relationFetch` needs is in the
+     * parent's SELECT list. Without this, the relation-fetcher would have
+     * the secondary query's rows but no way to pair them back to the
+     * correct parent row.
+     *
+     * The "key" columns differ by relation kind:
+     * - **to-many** (one-to-many, many-to-many): the parent's PK columns —
+     *   the secondary query joins the child's FK against this.
+     * - **to-one** (many-to-one, one-to-one): the parent's FK columns
+     *   stored on this row.
+     *
+     * Returns only the *missing* keys. Anything already in `existingPaths`
+     * is skipped to avoid duplicate SELECT entries (which would also break
+     * the row hydrator since aliases would clash).
+     */
+    missingJoinKeyColumns(fetches, existingPaths) {
+        const paths = [];
+        const aliases = [];
+        const added = new Set(existingPaths.map((p) => p[0]));
+        for (const meta of fetches) {
+            const isMany = meta.relationType === "one-to-many" || meta.relationType === "many-to-many";
+            const cols = isMany ? this.pkColumns : meta.fkColumns;
+            if (isMany && cols.length === 0) {
+                throw new Error(`[typhex] select relation "${meta.relation.name}" requires a primary key on the parent entity`);
+            }
+            for (const col of cols) {
+                if (!added.has(col)) {
+                    paths.push([col]);
+                    aliases.push(col);
+                    added.add(col);
+                }
+            }
+        }
+        return { paths, aliases };
+    }
+}
+/**
+ * Build the runtime metadata the relation-fetcher needs to execute a
+ * secondary load for one relation, given the IR description and the
+ * relation definition from the entity.
+ *
+ * Per relation-kind handling:
+ * - **many-to-one / one-to-one**: FK columns are on the parent; PK
+ *   columns come from the target's schema unless overridden by the
+ *   relation's `references` option.
+ * - **one-to-many**: FK columns are on the child (so we read them off
+ *   the relation options); PK comes from the target schema.
+ * - **many-to-many**: both FK and PK live on the junction table; the
+ *   junction itself is recorded so the fetcher can build the join.
+ */
+function buildRelationFetchMeta(ir, relDef) {
+    const target = relDef._target();
+    const targetEntity = target && typeof target.query === "function"
+        ? target
+        : null;
+    if (!targetEntity) {
+        throw new Error(`[typhex] relation "${ir.name}" target is not a queryable entity`);
+    }
+    const targetPkColumnsFromSchema = getPkColumnsFromSchema(targetEntity.table._schema);
+    switch (relDef._relType) {
+        case "many-to-one":
+        case "one-to-one": {
+            const opts = relDef._options;
+            return {
+                relationType: relDef._relType,
+                relation: ir,
+                fkColumns: toArray(opts.foreignKey),
+                targetPkColumns: opts.references != null ? toArray(opts.references) : targetPkColumnsFromSchema,
+                targetEntity,
+            };
+        }
+        case "one-to-many": {
+            const opts = relDef._options;
+            return {
+                relationType: "one-to-many",
+                relation: ir,
+                fkColumns: toArray(opts.foreignKey),
+                targetPkColumns: targetPkColumnsFromSchema,
+                targetEntity,
+            };
+        }
+        case "many-to-many": {
+            const j = relDef._options;
+            return {
+                relationType: "many-to-many",
+                relation: ir,
+                fkColumns: toArray(j.referenceKey),
+                targetPkColumns: targetPkColumnsFromSchema,
+                targetEntity,
+                junction: {
+                    table: j.junction,
+                    foreignKey: toArray(j.foreignKey),
+                    referenceKey: toArray(j.referenceKey),
+                },
+            };
+        }
+        default:
+            throw new Error(`[typhex] Unsupported relation type: ${relDef._relType}`);
+    }
+}
+//# sourceMappingURL=select-classifier.js.map

package/dist/orm/helpers/query-plan/select-classifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"select-classifier.js","sourceRoot":"","sources":["../../../../src/orm/helpers/query-plan/select-classifier.ts"],"names":[],"mappings":"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"}

package/dist/orm/helpers/relations/relation-assembler.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Relation assembler: attaches relation data onto rows.
+ * Handles both flat JOIN columns (assembleJoined) and pre-fetched maps (assembleFetched).
+ */
+import type { JoinedProjection, RelationFetchMetadata } from "../query-plan/query-plan.js";
+export type RelationFetchedData = Map<string, Map<string, unknown> | Map<string, unknown[]>>;
+/** Attaches JOIN-projected and separately fetched relation data onto result rows. */
+export declare class RelationAssembler {
+    private readonly rows;
+    constructor(rows: Record<string, unknown>[]);
+    /**
+     * Reconstruct nested objects from flat JOIN columns
+     * (e.g. author_name to row.author.name) using pre-extracted projections.
+     */
+    assembleJoined(projections: JoinedProjection[]): void;
+    /** Attach fetched relation maps onto rows. */
+    assembleFetched(fetches: RelationFetchMetadata[], fetched: RelationFetchedData, skip: Set<string>): void;
+    private attachToManyRelation;
+    private attachToOneRelation;
+}
+//# sourceMappingURL=relation-assembler.d.ts.map

package/dist/orm/helpers/relations/relation-assembler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relation-assembler.d.ts","sourceRoot":"","sources":["../../../../src/orm/helpers/relations/relation-assembler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAG3F,MAAM,MAAM,mBAAmB,GAAG,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;AAE7F,qFAAqF;AACrF,qBAAa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE;IAE5D;;;OAGG;IACH,cAAc,CAAC,WAAW,EAAE,gBAAgB,EAAE,GAAG,IAAI;IAYrD,8CAA8C;IAC9C,eAAe,CACb,OAAO,EAAE,qBAAqB,EAAE,EAChC,OAAO,EAAE,mBAAmB,EAC5B,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,GAChB,IAAI;IAaP,OAAO,CAAC,oBAAoB;IAQ5B,OAAO,CAAC,mBAAmB;CAM5B"}

package/dist/orm/helpers/relations/relation-assembler.js

@@ -0,0 +1,60 @@
+/**
+ * Relation assembler: attaches relation data onto rows.
+ * Handles both flat JOIN columns (assembleJoined) and pre-fetched maps (assembleFetched).
+ */
+import { makeCompositeKey } from "../../query-helpers.js";
+/** Attaches JOIN-projected and separately fetched relation data onto result rows. */
+export class RelationAssembler {
+    rows;
+    constructor(rows) {
+        this.rows = rows;
+    }
+    /**
+     * Reconstruct nested objects from flat JOIN columns
+     * (e.g. author_name to row.author.name) using pre-extracted projections.
+     */
+    assembleJoined(projections) {
+        for (const proj of projections) {
+            if (proj.members.length === 0)
+                continue;
+            for (const row of this.rows) {
+                const obj = {};
+                for (const member of proj.members)
+                    obj[member.subPath] = row[member.alias];
+                row[proj.outputKey] = obj;
+                for (const member of proj.members)
+                    delete row[member.alias];
+            }
+        }
+    }
+    /** Attach fetched relation maps onto rows. */
+    assembleFetched(fetches, fetched, skip) {
+        for (const meta of fetches) {
+            if (skip.has(meta.relation.name))
+                continue;
+            const data = fetched.get(meta.relation.name);
+            if (!data)
+                continue;
+            if (meta.relationType === "one-to-many" || meta.relationType === "many-to-many") {
+                this.attachToManyRelation(meta, data);
+            }
+            else {
+                this.attachToOneRelation(meta, data);
+            }
+        }
+    }
+    attachToManyRelation(meta, data) {
+        const pkCols = meta.parentPkColumns;
+        for (const row of this.rows) {
+            const key = makeCompositeKey(row, pkCols);
+            row[meta.relation.outputKey] = data.get(key) ?? [];
+        }
+    }
+    attachToOneRelation(meta, data) {
+        for (const row of this.rows) {
+            const key = makeCompositeKey(row, meta.fkColumns);
+            row[meta.relation.outputKey] = data.get(key) ?? null;
+        }
+    }
+}
+//# sourceMappingURL=relation-assembler.js.map

package/dist/orm/helpers/relations/relation-assembler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relation-assembler.js","sourceRoot":"","sources":["../../../../src/orm/helpers/relations/relation-assembler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAI1D,qFAAqF;AACrF,MAAM,OAAO,iBAAiB;IACC;IAA7B,YAA6B,IAA+B;QAA/B,SAAI,GAAJ,IAAI,CAA2B;IAAG,CAAC;IAEhE;;;OAGG;IACH,cAAc,CAAC,WAA+B;QAC5C,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;YAC/B,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC;gBAAE,SAAS;YACxC,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;gBAC5B,MAAM,GAAG,GAA4B,EAAE,CAAC;gBACxC,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO;oBAAE,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBAC3E,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,GAAG,CAAC;gBAC1B,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO;oBAAE,OAAO,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC9D,CAAC;QACH,CAAC;IACH,CAAC;IAED,8CAA8C;IAC9C,eAAe,CACb,OAAgC,EAChC,OAA4B,EAC5B,IAAiB;QAEjB,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;YAC3B,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAAE,SAAS;YAC3C,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YAC7C,IAAI,CAAC,IAAI;gBAAE,SAAS;YACpB,IAAI,IAAI,CAAC,YAAY,KAAK,aAAa,IAAI,IAAI,CAAC,YAAY,KAAK,cAAc,EAAE,CAAC;gBAChF,IAAI,CAAC,oBAAoB,CAAC,IAAI,EAAE,IAA8B,CAAC,CAAC;YAClE,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,mBAAmB,CAAC,IAAI,EAAE,IAA4B,CAAC,CAAC;YAC/D,CAAC;QACH,CAAC;IACH,CAAC;IAEO,oBAAoB,CAAC,IAA2B,EAAE,IAA4B;QACpF,MAAM,MAAM,GAAG,IAAI,CAAC,eAAgB,CAAC;QACrC,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YAC5B,MAAM,GAAG,GAAG,gBAAgB,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YAC1C,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;QACrD,CAAC;IACH,CAAC;IAEO,mBAAmB,CAAC,IAA2B,EAAE,IAA0B;QACjF,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YAC5B,MAAM,GAAG,GAAG,gBAAgB,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;YAClD,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC;QACvD,CAAC;IACH,CAAC;CACF"}

package/dist/orm/helpers/relations/relation-fetcher.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Relation fetcher: fetches related entities via WHERE IN queries.
+ * Does NOT mutate rows — returns fetched data as maps.
+ */
+import type { QueryExecutor } from "../../db.js";
+import type { RelationFetchMetadata } from "../query-plan/query-plan.js";
+export type RelationFetchResult = Map<string, Map<string, unknown> | Map<string, unknown[]>>;
+/** Runs one WHERE IN query per pending relation fetch and collects keyed result maps. */
+export declare class RelationFetcher {
+    private readonly qe;
+    private readonly rows;
+    private readonly fetches;
+    private readonly skip;
+    constructor(qe: QueryExecutor, rows: Record<string, unknown>[], fetches: RelationFetchMetadata[], skip: Set<string>);
+    fetch(): Promise<RelationFetchResult>;
+    private fetchRelation;
+    /** Fetch a to-many relation: WHERE IN on FK columns, grouped by FK composite key. */
+    private fetchOneToMany;
+    /** Fetch a to-one relation: WHERE IN on FK to target-PK, indexed by target PK composite key. */
+    private fetchOneToOne;
+    /** Many-to-many: two fetchRows calls through the junction, grouped by parent composite key. */
+    private fetchManyToMany;
+    private buildTargetParentIndex;
+    /** Batch-fetch rows from `entity` by mapping source column values onto target columns. */
+    private fetchRows;
+    private remapCols;
+    private indexByCompositeKey;
+    private groupByCompositeKey;
+}
+//# sourceMappingURL=relation-fetcher.d.ts.map