turbine-orm 0.24.0 → 0.26.0

package/dist/cjs/query/utils.js

@@ -12,6 +12,7 @@ exports.escapeLike = escapeLike;
 exports.fnv1a64Hex = fnv1a64Hex;
 exports.sqlToPreparedName = sqlToPreparedName;
 exports.buildCorrelation = buildCorrelation;
+exports.parseDbDate = parseDbDate;
 // ---------------------------------------------------------------------------
 // Identifier quoting — prevents SQL injection via table/column names
 // ---------------------------------------------------------------------------
@@ -139,3 +140,38 @@ function buildCorrelation(leftRef, leftColumns, rightRef, rightColumns) {
         .map((col, i) => `${leftRef}.${quoteIdent(col)} = ${rightRef}.${quoteIdent(rightCols[i])}`)
         .join(' AND ');
 }
+/**
+ * Matches an explicit timezone suffix on a date-time string: a trailing `Z`
+ * or a `±HH`, `±HHMM`, `±HH:MM` offset.
+ */
+const TZ_SUFFIX_RE = /(?:Z|[+-]\d{2}(?::?\d{2})?)$/;
+/**
+ * Parse a database date-time string deterministically.
+ *
+ * Postgres `timestamp` (without time zone) values arrive with no offset —
+ * both from the driver and from `json_agg`/`json_build_object` subquery JSON
+ * (`2026-07-07T17:15:41.896`). JavaScript's `new Date()` interprets such
+ * strings in the SERVER'S LOCAL TIME ZONE, so the same row parses to a
+ * different instant depending on where the code runs. The universal ORM
+ * convention (Prisma, Rails, Django) is to treat offset-less timestamps as
+ * UTC — that is also the only interpretation that round-trips: Postgres
+ * stores exactly the wall-clock fields you sent.
+ *
+ * Strings that carry an explicit offset (`timestamptz` output) are parsed
+ * as-is.
+ */
+function parseDbDate(value) {
+    // Date-only values (`2026-07-07`, from `date` columns in json_agg output)
+    // have no time to zone-pin — and their `-07` tail must not be read as an
+    // offset. JS parses bare ISO dates as UTC midnight already.
+    if (!value.includes(':'))
+        return new Date(value);
+    if (TZ_SUFFIX_RE.test(value)) {
+        // JS Date can't parse colon-less (`-0430`) or bare-hour (`+02`) offsets —
+        // normalize both to `±HH:MM`. Postgres emits the bare-hour form for
+        // whole-hour zones in some text outputs.
+        return new Date(value.replace(/([+-]\d{2})(\d{2})$/, '$1:$2').replace(/([+-]\d{2})$/, '$1:00'));
+    }
+    // normalize `YYYY-MM-DD HH:MM:SS` (driver form) to ISO before pinning UTC
+    return new Date(`${value.replace(' ', 'T')}Z`);
+}

package/dist/cjs/serverless.js

@@ -89,12 +89,29 @@ const client_js_1 = require("./client.js");
  * manage its own `pg.Pool`. The caller retains ownership of the pool's
  * lifecycle — `db.disconnect()` is a no-op.
  *
+ * ## Typed table accessors
+ *
+ * By default `turbineHttp` returns the base {@link TurbineClient}, so you
+ * reach tables through `db.table('users')`. To get the *generated*, fully
+ * typed accessors (`db.users.findMany()`) — identical to what the TCP-path
+ * `turbine()` factory gives you — pass your generated client type as the
+ * `TClient` type argument. The runtime object is the same; the generated
+ * subclass only adds `declare readonly` accessor typings, and the base
+ * constructor already creates those accessors at runtime for every table in
+ * the schema, so the assertion is sound (not a lie about the shape).
+ *
+ * This closes the "identical typed code across transports" gap: the edge
+ * client is now as typed as the direct one, with no `as` casts at the call
+ * site.
+ *
+ * @typeParam TClient - The generated `TurbineClient` subclass (from
+ *   `./generated/turbine`). Defaults to the base client for back-compat.
  * @param pool - Any pg-compatible pool (Neon, Vercel Postgres, etc.)
  * @param schema - Introspected or hand-written schema metadata
  * @param options - Optional logging / defaultLimit / warnOnUnlimited
- * @returns A TurbineClient instance
+ * @returns A TurbineClient instance (typed as `TClient`)
  *
- * @example
+ * @example Untyped (back-compat) — reach tables via `db.table(...)`
  * ```ts
  * import { Pool } from '@neondatabase/serverless';
  * import { turbineHttp } from 'turbine-orm/serverless';
@@ -102,10 +119,25 @@ const client_js_1 = require("./client.js");
  *
  * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
  * const db = turbineHttp(pool, SCHEMA);
- *
  * const users = await db.table('users').findMany({ limit: 10 });
  * ```
+ *
+ * @example Typed — generated accessors, identical to the TCP client
+ * ```ts
+ * import { Pool } from '@neondatabase/serverless';
+ * import { turbineHttp } from 'turbine-orm/serverless';
+ * import type { TurbineClient } from './generated/turbine';
+ * import { SCHEMA } from './generated/turbine/metadata.js';
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const db = turbineHttp<TurbineClient>(pool, SCHEMA);
+ * const users = await db.users.findMany({ limit: 10 }); // fully typed, no cast
+ * ```
  */
 function turbineHttp(pool, schema, options = {}) {
+    // The generated subclass only layers `declare readonly` accessor typings
+    // over the base client; the base constructor materializes those same
+    // accessors at runtime (Object.defineProperty per schema table). So the
+    // returned instance genuinely has TClient's shape — the assertion is safe.
     return new client_js_1.TurbineClient({ pool, ...options }, schema);
 }

package/dist/cli/index.d.ts

@@ -12,6 +12,7 @@
  *   turbine migrate status        — Show migration status
  *   turbine seed                  — Run seed file
  *   turbine status                — Show schema summary
+ *   turbine doctor                — Check relations for missing FK indexes (--fix emits migration)
  *   turbine studio                — Launch local read-only web UI
  *   turbine observe               — Launch metrics dashboard (requires TURBINE_OBSERVE_URL)
  *

package/dist/cli/index.js

@@ -12,6 +12,7 @@
  *   turbine migrate status        — Show migration status
  *   turbine seed                  — Run seed file
  *   turbine status                — Show schema summary
+ *   turbine doctor                — Check relations for missing FK indexes (--fix emits migration)
  *   turbine studio                — Launch local read-only web UI
  *   turbine observe               — Launch metrics dashboard (requires TURBINE_OBSERVE_URL)
  *
@@ -24,6 +25,7 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, writ
 import { dirname, relative, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { generate } from '../generate.js';
+import { findMissingRelationIndexes } from '../index-advisor.js';
 import { introspect } from '../introspect.js';
 import { schemaDiff, schemaPush } from '../schema-sql.js';
 import { configTemplate, findConfigFile, loadConfig, looksLikeSchemaFilePath, resolveConfig } from './config.js';
@@ -88,6 +90,9 @@ function parseArgs() {
             case '--allow-empty':
                 result.allowEmpty = true;
                 break;
+            case '--fix':
+                result.fix = true;
+                break;
             case '--force':
             case '-f':
                 result.force = true;
@@ -974,6 +979,80 @@ async function cmdStatus(_args, config) {
     }
 }
 // ---------------------------------------------------------------------------
+// Command: doctor — relation/index health check
+// ---------------------------------------------------------------------------
+async function cmdDoctor(args, config) {
+    banner();
+    const url = requireUrl(config);
+    label('Database', redactUrl(url));
+    label('Schema', config.schema);
+    newline();
+    const spinner = new Spinner('Introspecting database').start();
+    const schema = await introspect({
+        connectionString: url,
+        schema: config.schema,
+        include: config.include.length ? config.include : undefined,
+        exclude: config.exclude.length ? config.exclude : undefined,
+    });
+    const missing = findMissingRelationIndexes(schema);
+    if (missing.length === 0) {
+        spinner.succeed('Every relation probe is backed by an index');
+        newline();
+        return;
+    }
+    spinner.succeed(`Scanned ${bold(String(Object.keys(schema.tables).length))} tables`);
+    warn(`Found ${bold(String(missing.length))} unindexed relation probe(s)`);
+    newline();
+    // Row counts put the findings in severity order: a missing index on a 300-row
+    // table is noise; on a 300K-row table it is the whole page load.
+    const rowCounts = new Map();
+    {
+        const { Pool } = (await import('pg')).default;
+        const pool = new Pool({ connectionString: url, max: 1 });
+        try {
+            const tables = [...new Set(missing.map((m) => m.table))];
+            const res = await pool.query(`SELECT c.relname, c.reltuples::bigint::text AS reltuples
+           FROM pg_class c
+           JOIN pg_namespace n ON n.oid = c.relnamespace
+          WHERE n.nspname = $1 AND c.relname = ANY($2)`, [config.schema, tables]);
+            for (const row of res.rows)
+                rowCounts.set(row.relname, Math.max(0, Number(row.reltuples)));
+        }
+        finally {
+            await pool.end();
+        }
+    }
+    missing.sort((a, b) => (rowCounts.get(b.table) ?? 0) - (rowCounts.get(a.table) ?? 0));
+    console.log(`  ${dim('Turbine loads relations as correlated subqueries — the child table is probed')}`);
+    console.log(`  ${dim('once per parent row, so an unindexed FK costs a full table scan PER PARENT.')}`);
+    newline();
+    for (const m of missing) {
+        const rows = rowCounts.get(m.table);
+        const rowsLabel = rows !== undefined ? `~${rows.toLocaleString()} rows` : 'row count unknown';
+        console.log(`  ${yellow(symbols.warning)} ${bold(cyan(m.table))} ${dim(`(${m.columns.join(', ')})`)}  ${gray(rowsLabel)}`);
+        for (const p of m.probes) {
+            console.log(`    ${dim(symbols.tee)} probed by ${p.from}.${blue(p.relation)} ${dim(`(${p.type})`)}`);
+        }
+        console.log(`    ${dim(symbols.teeEnd)} ${green(m.createSql)}`);
+        newline();
+    }
+    if (args.fix) {
+        const up = missing.map((m) => m.createSql).join('\n');
+        const down = missing.map((m) => m.dropSql).join('\n');
+        const file = createMigration(config.migrationsDir, 'add_relation_fk_indexes', { up, down });
+        success(`Created migration: ${bold(file.filename)}`);
+        newline();
+        console.log(`  ${dim('Review it, then apply with:')} ${cyan('npx turbine migrate up')}`);
+        console.log(`  ${dim('Large, hot tables: consider running the statements manually with')} ${cyan('CREATE INDEX CONCURRENTLY')}`);
+        console.log(`  ${dim('(cannot run inside a transaction, so it is not emitted in the migration).')}`);
+        newline();
+    }
+    else {
+        console.log(`  ${dim('Generate a fix migration with:')} ${cyan('npx turbine doctor --fix')}`);
+        newline();
+    }
+}
+// ---------------------------------------------------------------------------
 // Command: studio — local read-only web UI
 // ---------------------------------------------------------------------------
 async function cmdStudio(args, config) {
@@ -1252,6 +1331,7 @@ function showHelp() {
     console.log(`      ${dim('status')}           Show applied/pending migrations`);
     console.log(`    ${cyan('seed')}               Run seed file`);
     console.log(`    ${cyan('status')} ${dim('| info')}      Show schema summary`);
+    console.log(`    ${cyan('doctor')}             Check relations for missing FK indexes ${dim('(--fix emits migration)')}`);
     console.log(`    ${cyan('studio')}             Launch local read-only web UI`);
     console.log(`    ${cyan('observe')}            Launch metrics dashboard ${dim('(requires TURBINE_OBSERVE_URL)')}`);
     newline();
@@ -1404,6 +1484,9 @@ async function main() {
             case 'info':
                 await cmdStatus(args, config);
                 break;
+            case 'doctor':
+                await cmdDoctor(args, config);
+                break;
             case 'studio':
                 await cmdStudio(args, config);
                 break;

package/dist/client.d.ts

@@ -26,7 +26,7 @@ import { type Dialect } from './dialect.js';
 import { type ErrorMessageMode } from './errors.js';
 import { type ObserveConfig, type ObserveHandle } from './observe.js';
 import { type PipelineOptions, type PipelineResults } from './pipeline.js';
-import { type DeferredQuery, type QueryEventListener, QueryInterface, type QueryInterfaceOptions } from './query/index.js';
+import { type DeferredQuery, type QueryEventListener, QueryInterface, type QueryInterfaceOptions, type RelationLoadStrategy } from './query/index.js';
 import { type NotificationHandler, type Subscription } from './realtime.js';
 import type { SchemaMetadata } from './schema.js';
 import { TypedSqlQuery } from './typed-sql.js';
@@ -140,6 +140,44 @@ export interface TurbineConfig {
     defaultLimit?: number;
     /** Log a warning when findMany() is called without a limit (default: false) */
     warnOnUnlimited?: boolean;
+    /**
+     * Interpret Postgres `timestamp` (without time zone) values as UTC — both
+     * at the driver level (OID 1114 type parser, registered only when Turbine
+     * owns the pool) and when coercing nested-relation JSON dates. This is the
+     * Prisma/Rails/Django convention and makes results independent of the
+     * server's local time zone. Default: `true`. Set `false` for the legacy
+     * local-time interpretation.
+     */
+    utcTimestamps?: boolean;
+    /**
+     * Default strategy for resolving `with`-clause relations, applied to every
+     * `findMany`/`findUnique`/`findFirst` unless overridden per query.
+     *
+     *   - `'join'` (default) — one SQL statement using correlated
+     *     `json_agg(json_build_object(...))` subqueries.
+     *   - `'batched'` — run the base query, then one flat follow-up query per
+     *     relation (`WHERE fk = ANY($1)`), stitching children client-side. Wins
+     *     when child FK columns are unindexed or result sets are large.
+     *
+     * Precedence: per-query `relationLoadStrategy` arg > this config > `'join'`.
+     */
+    relationLoadStrategy?: RelationLoadStrategy;
+    /**
+     * How nested-relation subqueries encode each row's JSON.
+     *
+     *   - `'object'` (default) — `json_agg(json_build_object('key', v, …))`. Every
+     *     key name is repeated in every nested object of every row.
+     *   - `'positional'` — `json_agg(json_build_array(v, …))`. Turbine knows the
+     *     column order at build time, so it emits a key-less array and maps
+     *     positions back to keys client-side. Same information, a fraction of the
+     *     bytes on wide/deeply-nested `with` trees. Parsed output is byte-identical
+     *     to `'object'`.
+     *
+     * Postgres-only in v1: setting `'positional'` on a non-Postgres engine throws
+     * `UnsupportedFeatureError` (E017) when a `with` clause is present. Default:
+     * `'object'` (today's behavior, byte-unchanged).
+     */
+    jsonEncoding?: 'object' | 'positional';
     /**
      * Controls how `NotFoundError` (and other where-aware errors) format their
      * messages.
@@ -263,6 +301,7 @@ export declare class TurbineClient {
     /** The schema metadata this client was built from */
     readonly schema: SchemaMetadata;
     private static int8ParserRegistered;
+    private static utcTimestampParserRegistered;
     private readonly logging;
     /** Active SQL dialect — owns transaction keywords, set_config, raw-SQL placeholders, capability flags. */
     private readonly dialect;

package/dist/client.js

@@ -197,6 +197,7 @@ export class TurbineClient {
     /** The schema metadata this client was built from */
     schema;
     static int8ParserRegistered = false;
+    static utcTimestampParserRegistered = false;
     logging;
     /** Active SQL dialect — owns transaction keywords, set_config, raw-SQL placeholders, capability flags. */
     dialect;
@@ -244,6 +245,16 @@ export class TurbineClient {
             });
             TurbineClient.int8ParserRegistered = true;
         }
+        // Parse `timestamp` (OID 1114) as UTC instead of server-local time. The
+        // pg driver's default hands back a Date built in the process's local zone,
+        // so the same row yields a different instant per deployment region. The
+        // ORM convention (Prisma, Rails, Django) — and the only interpretation
+        // that round-trips what Postgres stores — is UTC. Same ownership rule as
+        // the int8 parser: never mutate parser state on external pools.
+        if (!config.pool && config.utcTimestamps !== false && !TurbineClient.utcTimestampParserRegistered) {
+            pg.types.setTypeParser(1114, (val) => new Date(`${val.replace(' ', 'T')}Z`));
+            TurbineClient.utcTimestampParserRegistered = true;
+        }
         this.logging = config.logging ?? false;
         this.dialect = config.dialect ?? postgresDialect;
         this.schema = schema;
@@ -253,6 +264,9 @@ export class TurbineClient {
         this.queryOptions = {
             defaultLimit: config.defaultLimit,
             warnOnUnlimited: config.warnOnUnlimited,
+            utcTimestamps: config.utcTimestamps,
+            relationLoadStrategy: config.relationLoadStrategy,
+            jsonEncoding: config.jsonEncoding,
             preparedStatements: envDisablePrepared ? false : (config.preparedStatements ?? !config.pool),
             sqlCache: config.sqlCache ?? true,
             dialect: config.dialect,

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 {};