turbine-orm 0.25.0 → 0.27.0

package/dist/dialect.d.ts

@@ -229,6 +229,17 @@ export interface Dialect {
     readonly nullJsonLiteral: string;
     /** Build a JSON object expression from output keys and SQL expressions. */
     buildJsonObject(pairs: [key: string, expr: string][]): string;
+    /**
+     * Build a positional JSON ARRAY expression from ordered SQL expressions —
+     * the key-less counterpart to {@link buildJsonObject} used by the opt-in
+     * `jsonEncoding: 'positional'` mode. Emitting `json_build_array(v1, v2, …)`
+     * instead of `json_build_object('k1', v1, …)` drops every repeated key name
+     * from every nested object of every row (the decode side maps positions back
+     * to keys via a build-time shape descriptor). Postgres-only in v1 — other
+     * engines never reach this because the builder gates positional encoding to
+     * `dialect.name === 'postgresql'`, so the method is optional on the contract.
+     */
+    buildJsonArray?(exprs: string[]): string;
     /** Build a JSON array aggregation expression with a dialect-specific empty-array fallback. */
     buildJsonArrayAgg(jsonObjectExpr: string, orderBy?: string): string;
     /**

package/dist/dialect.js

@@ -32,8 +32,32 @@ export const postgresDialect = {
     },
     buildJsonObject(pairs) {
         const args = pairs.map(([key, expr]) => `'${this.escapeStringLiteral(key)}', ${expr}`);
+        // Postgres caps function calls at 100 arguments (= 50 key/value pairs).
+        // Wide tables (or wide select+relation trees) exceed that, so chunk into
+        // multiple jsonb_build_object calls merged with `||`, cast back to json.
+        if (pairs.length > 50) {
+            const chunks = [];
+            for (let i = 0; i < args.length; i += 50) {
+                chunks.push(`jsonb_build_object(${args.slice(i, i + 50).join(', ')})`);
+            }
+            return `(${chunks.join(' || ')})::json`;
+        }
         return `json_build_object(${args.join(', ')})`;
     },
+    buildJsonArray(exprs) {
+        // Mirror buildJsonObject's chunking at the SAME 50-element threshold: for
+        // wide rows, concatenate 50-element jsonb_build_array calls with `||` (which
+        // concatenates jsonb arrays) and cast back to json. `jsonb ||` preserves
+        // element order, so positions map back to keys unchanged after decode.
+        if (exprs.length > 50) {
+            const chunks = [];
+            for (let i = 0; i < exprs.length; i += 50) {
+                chunks.push(`jsonb_build_array(${exprs.slice(i, i + 50).join(', ')})`);
+            }
+            return `(${chunks.join(' || ')})::json`;
+        }
+        return `json_build_array(${exprs.join(', ')})`;
+    },
     buildJsonArrayAgg(jsonObjectExpr, orderBy) {
         const suffix = orderBy ? ` ${orderBy}` : '';
         return `COALESCE(json_agg(${jsonObjectExpr}${suffix}), ${this.emptyJsonArrayLiteral})`;

package/dist/index-advisor.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Index advisor — finds relation probes that lack index support.
+ *
+ * Turbine loads `with` relations as correlated subqueries: for every parent row,
+ * the child table is probed by its FK column(s) (`child.fk = parent.pk`). Relation
+ * filters (`some`/`none`/`every`, `is`/`isNot`) probe the same columns. This
+ * strategy outperforms batched loading (`WHERE fk IN (ids)`) when the probed
+ * column is indexed — but with NO index, each probe is a full table scan and the
+ * cost multiplies by the parent rowcount, while batched loading would pay the
+ * scan only once. A missing FK index that is invisible under a batched-loader
+ * ORM becomes pathological under a correlated one.
+ *
+ * This module derives every column set Turbine will probe from SchemaMetadata's
+ * relations and checks each against the table's known indexes (and primary key).
+ * Consumed by `turbine doctor` (CLI report + fix migration) and by the dev-mode
+ * runtime warning in query/builder.ts.
+ */
+import { type SchemaMetadata, type TableMetadata } from './schema.js';
+export interface RelationProbe {
+    /** Table on which the relation is declared */
+    from: string;
+    /** Relation field name */
+    relation: string;
+    /** Relation type */
+    type: 'hasMany' | 'hasOne' | 'belongsTo' | 'manyToMany';
+}
+export interface MissingRelationIndex {
+    /** Table that gets probed per parent row */
+    table: string;
+    /** Probed column(s) — equality lookups, so a covering index must LEAD with one of them */
+    columns: string[];
+    /** Every relation that generates this probe */
+    probes: RelationProbe[];
+    /** Suggested index name (matches the --fix migration) */
+    indexName: string;
+    /** CREATE INDEX statement for the fix migration */
+    createSql: string;
+    /** DROP INDEX statement for the fix migration's DOWN section */
+    dropSql: string;
+}
+/**
+ * Whether an equality probe on `columns` is served by the table's indexes.
+ *
+ * All probe columns are equality predicates, so any index whose FIRST column is
+ * one of the probed columns gives the planner an index path (a btree can't use
+ * a column that isn't in its leading prefix). This is deliberately the loose
+ * direction: it never flags a table that has *any* usable index for the probe,
+ * at the cost of not demanding the ideal multi-column index. The primary key
+ * counts as an index.
+ */
+export declare function isProbeIndexed(meta: TableMetadata, columns: string[]): boolean;
+/**
+ * Scan every relation in the schema and return the probes with no index support,
+ * deduplicated by (table, column set) with all contributing relations attached.
+ *
+ * Only meaningful when the metadata carries index information (i.e. it came from
+ * introspection or a generated client). Callers that may hold index-less metadata
+ * should gate on {@link schemaHasIndexInfo} to avoid blanket false positives.
+ */
+export declare function findMissingRelationIndexes(schema: SchemaMetadata): MissingRelationIndex[];
+/** True when at least one table in the schema carries index metadata. */
+export declare function schemaHasIndexInfo(schema: SchemaMetadata): boolean;
+/**
+ * Single-relation check for the dev-mode runtime warning: the (table, columns)
+ * this relation probes and whether that probe is unindexed. Returns null when
+ * indexed, unknown, or when the schema carries no index info at all (metadata
+ * built without introspection — warning would be a blanket false positive).
+ */
+export declare function missingIndexForRelation(schema: SchemaMetadata, relDef: {
+    name: string;
+    type: RelationProbe['type'];
+    to: string;
+    foreignKey: string | string[];
+    referenceKey: string | string[];
+    through?: {
+        table: string;
+        sourceKey: string | string[];
+    };
+}): {
+    table: string;
+    columns: string[];
+    createSql: string;
+} | null;

package/dist/mssql.js

@@ -766,7 +766,9 @@ function buildForJsonSubquery(dialect, ctx) {
         return buildForJsonManyToMany(dialect, ctx, { colSelect, buildNested, buildPaging, hasLimit });
     }
     const isToOne = relDef.type === 'belongsTo' || relDef.type === 'hasOne';
-    const correlation = isToOne
+    // Correlation direction is about WHERE THE FK LIVES, not cardinality:
+    // belongsTo has it on the source; hasMany AND hasOne have it on the target.
+    const correlation = relDef.type === 'belongsTo'
         ? dialect.buildCorrelation(alias, relDef.referenceKey, qParent, relDef.foreignKey)
         : dialect.buildCorrelation(alias, relDef.foreignKey, qParent, relDef.referenceKey);
     // ----- to-one (belongsTo / hasOne): single object, no paging --------------

package/dist/query/batched-loader.d.ts

@@ -0,0 +1,120 @@
+/**
+ * turbine-orm — Batched relation loader (the `relationLoadStrategy: 'batched'` path)
+ *
+ * ## Why this exists
+ *
+ * Turbine's default `with`-clause strategy resolves nested relations in ONE SQL
+ * statement using correlated `json_agg(json_build_object(...))` subqueries — one
+ * probe per parent row (see `buildRelationSubquery` in builder.ts). That is the
+ * right default: a single round-trip, and when the child FK columns are indexed
+ * each probe is an index seek. But it degrades in two situations:
+ *
+ *   1. **Missing FK index** — a correlated probe per parent row becomes
+ *      N-parents × full-table-scan. A batched-loader ORM pays that missing index
+ *      only ONCE (a single `WHERE fk = ANY($1)` seq-scan), which is why schemas
+ *      migrated from those ORMs often lack the index the json_agg path needs.
+ *   2. **Huge unpaginated result sets** — the JSON wire format
+ *      (`json_build_object` per row, re-serialized inside `json_agg`) is heavy to
+ *      encode/decode compared with flat rows.
+ *
+ * This module implements the alternative, opt-in strategy: run the base query
+ * WITHOUT relation subqueries, collect the parent keys, then issue ONE flat
+ * follow-up query per relation (`SELECT ... FROM child WHERE fk = ANY($1)`),
+ * and stitch the children onto the parents in memory. D relation levels cost D
+ * extra round-trips instead of one, but each is a single indexed lookup over a
+ * key set, and rows come back flat.
+ *
+ * ## Design constraints (see CLAUDE.md)
+ *
+ *   - **Same executor / connection path.** Every follow-up query runs through the
+ *     caller's own executor ({@link RelationLoadContext.exec}) and child query
+ *     interfaces built on the caller's pool. Inside a `$transaction` that pool is
+ *     the pinned-connection `txPool`, so batched loads join the transaction — no
+ *     separate pool checkout per query.
+ *   - **Identical output shape.** The stitched result is byte-for-byte the same
+ *     shape the join strategy produces: relation arrays for hasMany/manyToMany
+ *     (`[]` when empty), single-or-null for hasOne/belongsTo, with the same
+ *     camelCase keys and Date coercion — because the child rows are parsed by the
+ *     very same `parseRow`/`buildFindMany` machinery via a child QueryInterface.
+ *   - **Stitch keys never leak.** To stitch, the follow-up query must select the
+ *     FK/PK it joins on even when the caller's `select`/`omit` excluded it; the
+ *     loader adds those columns for the query and strips them from the returned
+ *     entities afterwards ({@link includeKeysForBatching}).
+ *
+ * PowDB (powql.ts) has its own batched loaders for the same reasons — this is the
+ * clean Postgres/SQL implementation, deliberately NOT shared with PowQL.
+ *
+ * @module
+ */
+import type pg from 'pg';
+import { type SchemaMetadata, type TableMetadata } from '../schema.js';
+import type { ReselectExecutor } from './builder.js';
+import type { WithClause } from './types.js';
+/**
+ * A DeferredQuery, minimally typed for what the loader consumes. Kept local to
+ * avoid a value import of builder.ts (which imports this module).
+ */
+interface Deferred {
+    sql: string;
+    params: unknown[];
+    preparedName?: string;
+    transform: (result: pg.QueryResult) => unknown;
+}
+/**
+ * The read surface the loader needs from a child QueryInterface: build (but do
+ * not execute) a flat findMany. The loader runs the built SQL through
+ * {@link RelationLoadContext.exec}, so execution stays on the caller's connection.
+ */
+export interface BatchedChildReader {
+    buildFindMany(args: Record<string, unknown>): Deferred;
+}
+/**
+ * Everything the loader needs from the owning QueryInterface, passed as closures
+ * so this module never imports builder.ts at runtime (it is imported BY it).
+ */
+export interface RelationLoadContext {
+    /** Metadata of the table whose rows are the current `parents`. */
+    parentMeta: TableMetadata;
+    schema: SchemaMetadata;
+    /** Build a child reader for `table`, bound to the caller's pool (tx-safe). */
+    makeChild: (table: string) => BatchedChildReader;
+    /** Run raw SQL through the caller's executor (same timeout/instrumentation path). */
+    exec: ReselectExecutor;
+    /** Quote an identifier via the active dialect. */
+    quote: (name: string) => string;
+    /** Build an `IN`/`ANY` predicate via the active dialect (PG: `expr = ANY($n)`). */
+    buildInClause: (expr: string, paramRef: string, negated: boolean) => string;
+    /** The single bound value for an `IN` list (PG: the array as-is). */
+    inClauseParam: (values: unknown[]) => unknown;
+    /** Placeholder for a 1-indexed parameter position (PG: `$n`). */
+    paramPlaceholder: (index: number) => string;
+}
+/**
+ * Adjust a `select`/`omit` pair so that `fields` are guaranteed present in the
+ * query result, returning the adjusted projection plus the list of fields that
+ * were added ONLY for stitching and must be stripped from the final entities.
+ *
+ * Used both for the base query (parent keys) and each follow-up query (child
+ * keys) so a caller's `select: { title: true }` on a relation still stitches even
+ * though the FK was not requested — and the FK never appears in the output.
+ */
+export declare function includeKeysForBatching(select: Record<string, boolean> | undefined, omit: Record<string, boolean> | undefined, fields: string[]): {
+    select?: Record<string, boolean>;
+    omit?: Record<string, boolean>;
+    strip: string[];
+};
+/** Delete stitch-only key fields from each row (no-op when `fields` is empty). */
+export declare function stripFields(rows: Record<string, unknown>[], fields: string[]): void;
+/**
+ * The set of parent FIELD names a batched load of `withClause` needs present on
+ * each parent row in order to stitch (the local key of every requested relation).
+ * The caller adds these to the base query and strips the added ones afterwards.
+ */
+export declare function neededParentKeyFields(parentMeta: TableMetadata, withClause: WithClause): string[];
+/**
+ * Load every relation in `withClause` for `parents` and attach it onto each row
+ * in place. Mirrors the join strategy's output shape exactly. Recurses for nested
+ * `with` by re-running itself against the freshly-loaded child rows.
+ */
+export declare function loadRelationsBatched(ctx: RelationLoadContext, parents: Record<string, unknown>[], withClause: WithClause, timeout?: number, depth?: number, path?: string[]): Promise<void>;
+export {};

package/dist/query/batched-loader.js

@@ -0,0 +1,386 @@
+/**
+ * turbine-orm — Batched relation loader (the `relationLoadStrategy: 'batched'` path)
+ *
+ * ## Why this exists
+ *
+ * Turbine's default `with`-clause strategy resolves nested relations in ONE SQL
+ * statement using correlated `json_agg(json_build_object(...))` subqueries — one
+ * probe per parent row (see `buildRelationSubquery` in builder.ts). That is the
+ * right default: a single round-trip, and when the child FK columns are indexed
+ * each probe is an index seek. But it degrades in two situations:
+ *
+ *   1. **Missing FK index** — a correlated probe per parent row becomes
+ *      N-parents × full-table-scan. A batched-loader ORM pays that missing index
+ *      only ONCE (a single `WHERE fk = ANY($1)` seq-scan), which is why schemas
+ *      migrated from those ORMs often lack the index the json_agg path needs.
+ *   2. **Huge unpaginated result sets** — the JSON wire format
+ *      (`json_build_object` per row, re-serialized inside `json_agg`) is heavy to
+ *      encode/decode compared with flat rows.
+ *
+ * This module implements the alternative, opt-in strategy: run the base query
+ * WITHOUT relation subqueries, collect the parent keys, then issue ONE flat
+ * follow-up query per relation (`SELECT ... FROM child WHERE fk = ANY($1)`),
+ * and stitch the children onto the parents in memory. D relation levels cost D
+ * extra round-trips instead of one, but each is a single indexed lookup over a
+ * key set, and rows come back flat.
+ *
+ * ## Design constraints (see CLAUDE.md)
+ *
+ *   - **Same executor / connection path.** Every follow-up query runs through the
+ *     caller's own executor ({@link RelationLoadContext.exec}) and child query
+ *     interfaces built on the caller's pool. Inside a `$transaction` that pool is
+ *     the pinned-connection `txPool`, so batched loads join the transaction — no
+ *     separate pool checkout per query.
+ *   - **Identical output shape.** The stitched result is byte-for-byte the same
+ *     shape the join strategy produces: relation arrays for hasMany/manyToMany
+ *     (`[]` when empty), single-or-null for hasOne/belongsTo, with the same
+ *     camelCase keys and Date coercion — because the child rows are parsed by the
+ *     very same `parseRow`/`buildFindMany` machinery via a child QueryInterface.
+ *   - **Stitch keys never leak.** To stitch, the follow-up query must select the
+ *     FK/PK it joins on even when the caller's `select`/`omit` excluded it; the
+ *     loader adds those columns for the query and strips them from the returned
+ *     entities afterwards ({@link includeKeysForBatching}).
+ *
+ * PowDB (powql.ts) has its own batched loaders for the same reasons — this is the
+ * clean Postgres/SQL implementation, deliberately NOT shared with PowQL.
+ *
+ * @module
+ */
+import { CircularRelationError, UnsupportedFeatureError, ValidationError } from '../errors.js';
+import { normalizeKeyColumns } from '../schema.js';
+/**
+ * Max parent keys per follow-up query. On Postgres the whole key set travels as
+ * ONE array parameter (`= ANY($1)`), so this is not a bind-parameter limit — it
+ * only bounds planner/memory cost per statement. Keep it large: every extra
+ * chunk is an extra network round-trip, and round-trips are exactly what the
+ * batched strategy exists to minimize (a 9-chunk load was measured 2× slower
+ * than a single-statement one over a WAN link).
+ */
+const MAX_RELATION_KEYS = 32_000;
+/** Nesting cap — parity with the join strategy's depth-10 guard. */
+const MAX_DEPTH = 10;
+/**
+ * Adjust a `select`/`omit` pair so that `fields` are guaranteed present in the
+ * query result, returning the adjusted projection plus the list of fields that
+ * were added ONLY for stitching and must be stripped from the final entities.
+ *
+ * Used both for the base query (parent keys) and each follow-up query (child
+ * keys) so a caller's `select: { title: true }` on a relation still stitches even
+ * though the FK was not requested — and the FK never appears in the output.
+ */
+export function includeKeysForBatching(select, omit, fields) {
+    const unique = [...new Set(fields)];
+    if (select) {
+        const next = { ...select };
+        const strip = [];
+        for (const f of unique) {
+            if (!next[f]) {
+                next[f] = true;
+                strip.push(f); // not requested by the caller — added only to stitch
+            }
+        }
+        return { select: next, omit, strip };
+    }
+    if (omit) {
+        const next = { ...omit };
+        const strip = [];
+        for (const f of unique) {
+            if (next[f]) {
+                delete next[f]; // un-omit so the key is present; the caller wanted it gone
+                strip.push(f);
+            }
+        }
+        return { select, omit: next, strip };
+    }
+    // Neither select nor omit — every column is already present; nothing to strip.
+    return { select, omit, strip: [] };
+}
+/** Delete stitch-only key fields from each row (no-op when `fields` is empty). */
+export function stripFields(rows, fields) {
+    if (fields.length === 0)
+        return;
+    for (const row of rows) {
+        for (const f of fields)
+            delete row[f];
+    }
+}
+/**
+ * The set of parent FIELD names a batched load of `withClause` needs present on
+ * each parent row in order to stitch (the local key of every requested relation).
+ * The caller adds these to the base query and strips the added ones afterwards.
+ */
+export function neededParentKeyFields(parentMeta, withClause) {
+    const fields = new Set();
+    for (const [relName, spec] of Object.entries(withClause)) {
+        if (!spec)
+            continue;
+        const rel = parentMeta.relations[relName];
+        if (!rel)
+            continue; // unknown relation — the join path throws; let the loader surface it
+        for (const col of localKeyColumns(rel)) {
+            fields.add(parentMeta.reverseColumnMap[col] ?? col);
+        }
+    }
+    return [...fields];
+}
+/**
+ * The parent-side key column(s) used to correlate a relation:
+ *   - hasMany / hasOne:  the parent's `referenceKey` (child's FK points at it)
+ *   - belongsTo:         the parent's `foreignKey`   (points at the child's PK)
+ *   - manyToMany:        the parent's `referenceKey` (junction's sourceKey → it)
+ */
+function localKeyColumns(rel) {
+    if (rel.type === 'belongsTo')
+        return normalizeKeyColumns(rel.foreignKey);
+    return normalizeKeyColumns(rel.referenceKey);
+}
+/** Stringified stitch key — robust to number/uuid/bigint type drift across a join. */
+function keyOf(value) {
+    return String(value);
+}
+/**
+ * Load every relation in `withClause` for `parents` and attach it onto each row
+ * in place. Mirrors the join strategy's output shape exactly. Recurses for nested
+ * `with` by re-running itself against the freshly-loaded child rows.
+ */
+export async function loadRelationsBatched(ctx, parents, withClause, timeout, depth = 0, path = [ctx.parentMeta.name]) {
+    if (depth >= MAX_DEPTH)
+        throw new CircularRelationError([...path, '…']);
+    if (parents.length === 0)
+        return;
+    // Sibling relations are independent (each writes only its own parent[relName]
+    // and reads only parent keys), so load them concurrently — on a pool that's
+    // real parallelism, inside a transaction pg queues them on the one connection.
+    const loads = [];
+    for (const [relName, spec] of Object.entries(withClause)) {
+        if (!spec)
+            continue;
+        const rel = ctx.parentMeta.relations[relName];
+        if (!rel) {
+            throw new ValidationError(`[turbine] Unknown relation "${relName}" on table "${ctx.parentMeta.name}". ` +
+                `Available: ${Object.keys(ctx.parentMeta.relations).join(', ')}`);
+        }
+        const options = spec === true ? {} : spec;
+        loads.push(rel.type === 'manyToMany'
+            ? loadManyToMany(ctx, parents, rel, relName, options, timeout, depth, path)
+            : loadToOneOrMany(ctx, parents, rel, relName, options, timeout, depth, path));
+    }
+    await Promise.all(loads);
+}
+/**
+ * hasMany / hasOne / belongsTo: one follow-up `SELECT ... WHERE childKey = ANY($1)`
+ * (chunked), grouped by the correlation key and attached (array vs single-or-null).
+ */
+async function loadToOneOrMany(ctx, parents, rel, relName, options, timeout, depth, path) {
+    const fk = normalizeKeyColumns(rel.foreignKey);
+    const rk = normalizeKeyColumns(rel.referenceKey);
+    if (fk.length > 1 || rk.length > 1) {
+        throw new UnsupportedFeatureError('composite-key batched relation loading', 'relationLoadStrategy: "batched"', `relation "${relName}" — use the default 'join' strategy for composite-key relations`);
+    }
+    const targetMeta = requireTable(ctx.schema, rel.to, relName);
+    // Local key lives on the parent; the correlating key lives on the child.
+    //   hasMany/hasOne: parent.referenceKey  ←  child.foreignKey
+    //   belongsTo:      parent.foreignKey     →  child.referenceKey
+    const parentKeyCol = rel.type === 'belongsTo' ? fk[0] : rk[0];
+    const childKeyCol = rel.type === 'belongsTo' ? rk[0] : fk[0];
+    const parentKeyField = ctx.parentMeta.reverseColumnMap[parentKeyCol] ?? parentKeyCol;
+    const childKeyField = targetMeta.reverseColumnMap[childKeyCol] ?? childKeyCol;
+    const keys = uniqueKeys(parents, parentKeyField);
+    const single = rel.type === 'belongsTo' || rel.type === 'hasOne';
+    if (keys.length === 0) {
+        for (const parent of parents)
+            parent[relName] = single ? null : [];
+        return;
+    }
+    // The follow-up must project the child correlation key even if the caller's
+    // select/omit excluded it; strip it back off afterwards so the shape matches join.
+    const proj = includeKeysForBatching(options.select, options.omit, [childKeyField]);
+    const child = ctx.makeChild(rel.to);
+    const chunks = [];
+    for (let i = 0; i < keys.length; i += MAX_RELATION_KEYS)
+        chunks.push(keys.slice(i, i + MAX_RELATION_KEYS));
+    // Chunks run concurrently, results concatenated in chunk order. Per-relation
+    // `limit` is NOT pushed down here: `LIMIT` on a `fk = ANY($1)` query over the
+    // whole batch would cap TOTAL children, not children-per-parent. It is applied
+    // client-side per group after stitching (below).
+    const chunkResults = await Promise.all(chunks.map(async (chunk) => {
+        const deferred = child.buildFindMany({
+            where: mergeChildWhere(options.where, childKeyField, chunk),
+            select: proj.select,
+            omit: proj.omit,
+            orderBy: options.orderBy,
+        });
+        const result = await ctx.exec(deferred.sql, deferred.params, deferred.preparedName);
+        return deferred.transform(result);
+    }));
+    const allChildren = chunkResults.flat();
+    // Recurse for nested `with` BEFORE stripping keys (children carry their own keys).
+    if (options.with && allChildren.length > 0) {
+        await loadRelationsBatched({ ...ctx, parentMeta: targetMeta }, allChildren, options.with, timeout, depth + 1, [...path, relName]);
+    }
+    const byKey = groupBy(allChildren, childKeyField);
+    const limit = options.limit;
+    for (const parent of parents) {
+        const bucket = byKey.get(keyOf(parent[parentKeyField])) ?? [];
+        if (single) {
+            parent[relName] = bucket[0] ?? null;
+        }
+        else {
+            parent[relName] = limit !== undefined ? bucket.slice(0, limit) : bucket;
+        }
+    }
+    stripFields(allChildren, proj.strip);
+}
+/**
+ * manyToMany: a three-hop batched loader (no join pushdown):
+ *   (1) read junction rows for all parents (`sourceKey = ANY($1)` chunks),
+ *   (2) read the target rows for the collected targetKeys,
+ *   (3) stitch parent → junction targetKeys → target rows in memory.
+ * Composite junction/target keys fall back to the join strategy (throw E017).
+ */
+async function loadManyToMany(ctx, parents, rel, relName, options, timeout, depth, path) {
+    const through = rel.through;
+    if (!through) {
+        throw new ValidationError(`[turbine] manyToMany relation "${relName}" is missing its junction (\`through\`).`);
+    }
+    const sourceJ = normalizeKeyColumns(through.sourceKey);
+    const targetJ = normalizeKeyColumns(through.targetKey);
+    const sourceRef = normalizeKeyColumns(rel.referenceKey);
+    const targetMeta = requireTable(ctx.schema, rel.to, relName);
+    if (sourceJ.length > 1 || targetJ.length > 1 || sourceRef.length > 1 || targetMeta.primaryKey.length !== 1) {
+        throw new UnsupportedFeatureError('composite-key batched manyToMany loading', 'relationLoadStrategy: "batched"', `relation "${relName}" — use the default 'join' strategy for composite-key m2m relations`);
+    }
+    const sourceJCol = sourceJ[0];
+    const targetJCol = targetJ[0];
+    const sourceRefCol = sourceRef[0];
+    const targetPkCol = targetMeta.primaryKey[0];
+    const parentRefField = ctx.parentMeta.reverseColumnMap[sourceRefCol] ?? sourceRefCol;
+    const targetPkField = targetMeta.reverseColumnMap[targetPkCol] ?? targetPkCol;
+    const parentKeys = uniqueKeys(parents, parentRefField);
+    if (parentKeys.length === 0) {
+        for (const parent of parents)
+            parent[relName] = [];
+        return;
+    }
+    // (1) Junction rows: sourceKeyVal → [targetKeyVal]. Raw SQL through the caller's
+    // executor (the junction table has no relations we need, so no child reader).
+    const targetsBySource = new Map();
+    const targetValSet = new Set();
+    const jTable = ctx.quote(through.table);
+    const jSource = ctx.quote(sourceJCol);
+    const jTarget = ctx.quote(targetJCol);
+    const jChunks = [];
+    for (let i = 0; i < parentKeys.length; i += MAX_RELATION_KEYS) {
+        jChunks.push(parentKeys.slice(i, i + MAX_RELATION_KEYS));
+    }
+    const jResults = await Promise.all(jChunks.map((chunk) => {
+        const params = [ctx.inClauseParam(chunk)];
+        const predicate = ctx.buildInClause(`${jTable}.${jSource}`, ctx.paramPlaceholder(1), false);
+        const sql = `SELECT ${jTable}.${jSource} AS "s", ${jTable}.${jTarget} AS "t" FROM ${jTable} WHERE ${predicate}`;
+        return ctx.exec(sql, params);
+    }));
+    for (const { rows } of jResults) {
+        for (const row of rows) {
+            const sv = keyOf(row.s);
+            const tv = row.t;
+            if (tv == null)
+                continue;
+            const bucket = targetsBySource.get(sv);
+            if (bucket)
+                bucket.push(tv);
+            else
+                targetsBySource.set(sv, [tv]);
+            targetValSet.add(tv);
+        }
+    }
+    // (2) Target rows by PK, honouring the relation's own where/select/omit/orderBy.
+    const proj = includeKeysForBatching(options.select, options.omit, [targetPkField]);
+    const child = ctx.makeChild(rel.to);
+    const targetVals = [...targetValSet];
+    const tChunks = [];
+    for (let i = 0; i < targetVals.length; i += MAX_RELATION_KEYS) {
+        tChunks.push(targetVals.slice(i, i + MAX_RELATION_KEYS));
+    }
+    const tResults = await Promise.all(tChunks.map(async (chunk) => {
+        const deferred = child.buildFindMany({
+            where: mergeChildWhere(options.where, targetPkField, chunk),
+            select: proj.select,
+            omit: proj.omit,
+            orderBy: options.orderBy,
+        });
+        const result = await ctx.exec(deferred.sql, deferred.params, deferred.preparedName);
+        return deferred.transform(result);
+    }));
+    const targetsInOrder = tResults.flat();
+    // Nested `with` on the target rows (before stripping their PK).
+    if (options.with && targetsInOrder.length > 0) {
+        await loadRelationsBatched({ ...ctx, parentMeta: targetMeta }, targetsInOrder, options.with, timeout, depth + 1, [...path, relName]);
+    }
+    const targetByPk = new Map();
+    for (const t of targetsInOrder)
+        targetByPk.set(keyOf(t[targetPkField]), t);
+    // (3) Stitch. Iterate `targetsInOrder` (already ordered by the relation's
+    // orderBy) and pick the ones each parent links to, so per-parent order honours
+    // orderBy; then apply the per-relation `limit` client-side.
+    const limit = options.limit;
+    for (const parent of parents) {
+        const linked = new Set((targetsBySource.get(keyOf(parent[parentRefField])) ?? []).map(keyOf));
+        if (linked.size === 0) {
+            parent[relName] = [];
+            continue;
+        }
+        const out = [];
+        for (const t of targetsInOrder) {
+            if (linked.has(keyOf(t[targetPkField]))) {
+                out.push(t);
+                if (limit !== undefined && out.length >= limit)
+                    break;
+            }
+        }
+        parent[relName] = out;
+    }
+    stripFields(targetsInOrder, proj.strip);
+}
+// ---------------------------------------------------------------------------
+// Small helpers
+// ---------------------------------------------------------------------------
+/** Merge the batched correlation predicate (`key IN chunk`) into the relation's own where. */
+function mergeChildWhere(where, keyField, chunk) {
+    return { ...(where ?? {}), [keyField]: { in: chunk } };
+}
+/** Distinct, non-null values of `field` across `rows`. */
+function uniqueKeys(rows, field) {
+    const seen = new Set();
+    const out = [];
+    for (const row of rows) {
+        const v = row[field];
+        if (v == null)
+            continue;
+        const k = keyOf(v);
+        if (seen.has(k))
+            continue;
+        seen.add(k);
+        out.push(v);
+    }
+    return out;
+}
+/** Group rows by the stringified value of `field`, preserving input order. */
+function groupBy(rows, field) {
+    const map = new Map();
+    for (const row of rows) {
+        const k = keyOf(row[field]);
+        const bucket = map.get(k);
+        if (bucket)
+            bucket.push(row);
+        else
+            map.set(k, [row]);
+    }
+    return map;
+}
+/** Resolve a table's metadata or throw a clear relation error. */
+function requireTable(schema, table, relName) {
+    const meta = schema.tables[table];
+    if (!meta)
+        throw new ValidationError(`[turbine] Relation "${relName}" targets unknown table "${table}".`);
+    return meta;
+}