turbine-orm 0.49.0 → 0.50.0

package/dist/cjs/query/relations.d.ts

@@ -0,0 +1,609 @@
+/**
+ * turbine-orm: relation + orderBy compilation (extracted from builder.ts)
+ *
+ * The json_agg nested-relation machinery (buildSelectWithRelations,
+ * buildRelationSubquery, buildManyToManySubquery), the positional-encoding
+ * shapes + nested-row parser, the full orderBy surface (plain / JSON-path /
+ * vector KNN / relation _count / pick-row), relation _count expressions and
+ * their global-filter params, and the with-clause fingerprint + param
+ * collectors. All functions take a {@link BuilderCtx} first argument; WHERE
+ * compilation is reused from where.ts (whereMod.*), the PII column set from
+ * writes.ts (writesMod.*), and the remaining primitives stay class-resident,
+ * reached through the ctx. See builder.ts for the thin delegating methods and
+ * the findMany/findUnique execute assembly.
+ */
+import { ValidationError } from '../errors.js';
+import type { RelationDef, TableMetadata } from '../schema.js';
+import type { JsonPathOrderBy, OrderByClause, RelationPickOrderBy, WithClause, WithOptions } from './types.js';
+import type { BuilderCtx } from './where.js';
+/**
+ * Decode descriptor for `jsonEncoding: 'positional'`. Built during SQL
+ * generation (see {@link buildRelationShape}) and consumed by the
+ * transform to map key-less positional arrays back to keyed objects.
+ *
+ * - `keys` — camelCase field names in emitted array position, INCLUDING nested
+ *   relation slots (a nested relation occupies one more position after the
+ *   scalar columns, in `sortedEntries(with)` order).
+ * - `nested` — sub-shape for each key in `keys` that is itself a relation slot.
+ * - `cardinality` — `'one'` (belongsTo/hasOne, a single positional array or
+ *   null) vs `'many'` (an array of positional arrays).
+ */
+export interface RelationShape {
+    keys: string[];
+    nested: Record<string, RelationShape>;
+    cardinality: 'many' | 'one';
+}
+/**
+ * Resolve select/omit options into a list of snake_case column names.
+ * Returns null if neither is provided (meaning all columns).
+ */
+export declare function resolveColumns(qi: BuilderCtx, select?: Record<string, boolean>, omit?: Record<string, boolean>, includePii?: boolean): string[] | null;
+/**
+ * Produce a fingerprint for a `with` clause tree. Recursion mirrors
+ * buildSelectWithRelations / buildRelationSubquery.
+ *
+ * @internal Exposed as package-private for testing.
+ */
+export declare function withFingerprint(qi: BuilderCtx, withClause: WithClause | undefined, table?: string, depth?: number): string;
+/**
+ * Collect params from a `with` clause tree. Mirrors buildSelectWithRelations +
+ * buildRelationSubquery param-push order.
+ */
+export declare function collectWithParams(qi: BuilderCtx, withClause: WithClause, params: unknown[], table?: string, flattenPlan?: FlattenPlan | null): void;
+/**
+ * Collect params from a single relation subquery. Mirrors buildRelationSubquery.
+ */
+export declare function collectRelationSubqueryParams(qi: BuilderCtx, relDef: RelationDef, spec: true | WithOptions, params: unknown[], _parentRef: string, depth?: number): void;
+/**
+ * Value-shape fingerprint for a single orderBy entry, so two queries whose
+ * ORDER BY differs only in nulls placement, vector metric, or relation-count
+ * vs relation-column never collide on one cached SQL string. Captures the
+ * SQL-shaping bits (direction, nulls, metric, relation keys) — never values.
+ */
+export declare function orderByEntryFingerprint(qi: BuilderCtx, d: unknown, targetTable?: string): string;
+export declare function buildOrderBy(qi: BuilderCtx, orderBy: OrderByClause, params?: unknown[], lateralSink?: string[]): string;
+/**
+ * True when an orderBy value is a relation-ordering object: a plain object
+ * that is neither a vector KNN ordering nor an {@link OrderBySpec}. Its key
+ * in the orderBy clause is a relation name.
+ */
+export declare function isRelationOrderByValue(_qi: BuilderCtx, value: unknown): boolean;
+/**
+ * Render the ` NULLS FIRST` / ` NULLS LAST` suffix for a column ordering.
+ * Only PostgreSQL and SQLite support the `NULLS FIRST/LAST` grammar — on any
+ * other engine a caller asking for explicit nulls placement gets a clear
+ * {@link UnsupportedFeatureError} (E017) instead of broken SQL.
+ */
+export declare function nullsSuffix(qi: BuilderCtx, nulls: 'first' | 'last' | undefined): string;
+/**
+ * Resolve an orderBy key to its snake_case column via the table's columnMap
+ * (camelToSnake fallback), throwing the SAME unknown-field E003 the top-level
+ * where path uses. Shared by top-level JSON-path ordering and every nested
+ * relation orderBy path so nested orderBy accepts exactly what top-level
+ * accepts (the 0.30.x bug: nested orderBy skipped the columnMap and rejected
+ * camelCase-named DB columns like "sortOrder").
+ */
+export declare function resolveOrderByColumn(_qi: BuilderCtx, table: string, meta: TableMetadata, key: string): string;
+/**
+ * Validate a {@link JsonPathOrderBy} entry: column must exist AND be
+ * json/jsonb, path must be a non-empty array of keys/indexes: and return
+ * the resolved column. Shared by the SQL-build path
+ * ({@link buildJsonPathOrderEntry}) and the cache-hit param-collect mirrors
+ * so both always throw identically.
+ */
+export declare function validateJsonPathOrderBy(qi: BuilderCtx, table: string, meta: TableMetadata, field: string, spec: JsonPathOrderBy): string;
+/**
+ * Compile one {@link JsonPathOrderBy} entry:
+ * `("col" #>> $n::text[])::numeric ASC`: the numeric cast only with
+ * `type: 'numeric'` (default is text comparison), the extraction routed
+ * through the dialect's JSON hook exactly like the JSON where-filters, the
+ * path bound as ONE text[] param (mirrored by the order-param collectors).
+ * `prefix` scopes the column (`''` top-level, `t0.` inside a relation
+ * subquery).
+ */
+export declare function buildJsonPathOrderEntry(qi: BuilderCtx, table: string, meta: TableMetadata, field: string, spec: JsonPathOrderBy, prefix: string, params?: unknown[]): string;
+/**
+ * Compile a relation ordering term. For a to-many relation the only allowed
+ * key is `_count`, which becomes a correlated `COUNT(*)` subquery. For a
+ * to-one relation each entry names a target column and becomes a correlated
+ * scalar subquery (supporting {@link OrderBySpec} nulls placement).
+ *
+ * Validation: relation must exist (E005); to-many only allows `_count`, and
+ * to-one only allows real target columns (E003).
+ *
+ * `ctx` generalizes the term beyond the root table: inside a relation
+ * subquery's orderBy the relations live on the TARGET table's metadata and
+ * the correlation parent is the relation's alias, not `qi.table`.
+ */
+export declare function buildRelationOrderBy(qi: BuilderCtx, relName: string, value: Record<string, unknown>, alias: string, params?: unknown[], ctx?: {
+    meta: TableMetadata;
+    table: string;
+    parentRef: string;
+}, lateralSink?: string[]): string;
+/**
+ * Validate a {@link RelationPickOrderBy} entry's scope and shape. Shared by
+ * the SQL-build path ({@link buildRelationPickOrderBy}) and the cache-hit
+ * param-collect mirror ({@link collectRelationPickOrderParams}) so both
+ * always throw identically:
+ *
+ *  - `nested` (inside a relation subquery's orderBy or a pick.orderBy):
+ *    top-level findMany only in this release (E003),
+ *  - manyToMany: not supported (E003 naming the limitation),
+ *  - to-one: order by the target column directly instead (E003),
+ *  - `pick.orderBy` is REQUIRED (deterministic row choice),
+ *  - `by` must be a target column name or a `{ field, path }` JSON-path spec.
+ */
+export declare function pickOrderNestedError(_qi: BuilderCtx, relName: string): ValidationError;
+export declare function validatePickOrderBy(qi: BuilderCtx, relName: string, relDef: RelationDef, spec: RelationPickOrderBy, nested: boolean): void;
+/**
+ * Compile a {@link RelationPickOrderBy} term: a correlated scalar subquery
+ * that picks ONE related row (`ORDER BY <pick.orderBy> LIMIT 1`, optionally
+ * filtered by `pick.where` and the target's global filter) and surfaces one
+ * value from it (a plain target column or a JSON-path extraction) as the
+ * parent ORDER BY key:
+ *
+ * ```sql
+ * (SELECT ord0."data" #>> $1::text[] FROM "versions" ord0
+ *   WHERE ord0."instance_id" = "instances"."id" AND ord0."is_current" = $2
+ *   ORDER BY ord0."created_at" DESC LIMIT 1) ASC NULLS LAST
+ * ```
+ *
+ * Param-push order (mirrored EXACTLY by
+ * {@link collectRelationPickOrderParams}): `by` JSON path (if any) →
+ * target global filter → `pick.where` → `pick.orderBy` JSON paths.
+ */
+export declare function buildRelationPickOrderBy(qi: BuilderCtx, relName: string, relDef: RelationDef, spec: RelationPickOrderBy, alias: string, parentRef: string, params?: unknown[], lateralSink?: string[]): string;
+/**
+ * Compile the shared inner pieces of a pick-row ordering against `childAlias`
+ * (the table alias the related row is read from): the `by` value expression,
+ * the correlation + target global filter + `pick.where` predicate, and the
+ * `pick.orderBy` clause. Factored out of {@link buildRelationPickOrderBy} so
+ * the subquery and lateral plans build IDENTICAL pieces in the SAME param
+ * push order (`by` JSON path → target global filter → `pick.where` →
+ * `pick.orderBy` JSON paths), which is why the collect mirror
+ * ({@link collectRelationPickOrderParams}) is plan-agnostic.
+ */
+export declare function compilePickPieces(qi: BuilderCtx, relDef: RelationDef, targetMeta: TableMetadata, spec: RelationPickOrderBy, childAlias: string, parentRef: string, params: unknown[]): {
+    byExpr: string;
+    where: string;
+    orderClause: string;
+};
+/**
+ * Param-collect mirror of {@link buildRelationPickOrderBy}: re-runs the same
+ * validation (a warmed cache can never skip it), then pushes in the same
+ * order: `by` JSON path → target global filter → `pick.where` →
+ * `pick.orderBy` JSON paths.
+ */
+export declare function collectRelationPickOrderParams(qi: BuilderCtx, relName: string, relDef: RelationDef, spec: RelationPickOrderBy, params: unknown[]): void;
+/**
+ * Compile the ORDER BY terms of a relation `with` clause against the
+ * relation's table alias. One unified path for every relation shape
+ * (hasMany / manyToMany / belongsTo / hasOne) supporting exactly what the
+ * top-level orderBy accepts at this level:
+ *
+ *  - scalar columns via columnMap resolution (camelToSnake fallback) with
+ *    {@link OrderBySpec} nulls placement,
+ *  - {@link JsonPathOrderBy} entries (path bound as one text[] param),
+ *  - relation ordering on the TARGET's relations (`_count` for to-many, a
+ *    target column for to-one), correlated to the relation alias,
+ *  - vector KNN ordering stays top-level-only (E003, same as before).
+ *
+ * Param pushes (JSON paths, relation-order global filters) MUST be mirrored,
+ * in the same order, by {@link collectRelationOrderParams}.
+ */
+export declare function buildRelationOrderClause(qi: BuilderCtx, targetTable: string, targetMeta: TableMetadata, alias: string, orderEntries: [string, unknown][], params: unknown[]): string;
+/**
+ * Param-collect mirror of {@link buildRelationOrderClause}: JSON-path
+ * entries push their path (one text[] param each); relation-order entries
+ * mirror {@link collectOrderByParams}' relation branch (count / to-one
+ * global-filter params); scalar entries push nothing but re-run the same
+ * column validation so a warmed cache can never skip it.
+ */
+export declare function collectRelationOrderParams(qi: BuilderCtx, targetTable: string, targetMeta: TableMetadata, orderEntries: [string, unknown][], params: unknown[]): void;
+/**
+ * Build a correlated `(SELECT COUNT(*) …)` scalar subquery for a to-many
+ * relation, correlated to `parentRef`. hasMany counts child rows via the FK;
+ * manyToMany counts junction rows via the source key. Shared by the `_count`
+ * `with` key and to-many relation orderBy.
+ *
+ * When `params` is supplied and the target has a global filter, it is
+ * AND-merged so the count only sees surviving rows (a soft-deleted child is
+ * not counted): hasMany filters the counted rows directly; manyToMany adds an
+ * `EXISTS` on the target through the junction (the junction rows themselves
+ * carry no filter). Params are mirrored by {@link collectRelationCountParams}.
+ */
+export declare function buildRelationCountExpr(qi: BuilderCtx, relDef: RelationDef, parentRef: string, alias: string, params?: unknown[]): string;
+/**
+ * `EXISTS (SELECT 1 FROM <target> <talias> WHERE <join> AND <gf>)` restricting
+ * a manyToMany `_count` to targets that survive their global filter. `''` when
+ * the target has no filter. Pushes gf params; mirror:
+ * {@link collectManyToManyTargetGlobalFilter}.
+ */
+export declare function manyToManyTargetGlobalFilterExists(qi: BuilderCtx, relDef: RelationDef, alias: string, jalias: string, params: unknown[]): string;
+/** Param-collect mirror of {@link manyToManyTargetGlobalFilterExists}. */
+export declare function collectManyToManyTargetGlobalFilter(qi: BuilderCtx, relDef: RelationDef, params: unknown[]): void;
+/**
+ * Param-collect mirror of {@link buildRelationCountExpr}'s global-filter
+ * params (hasMany direct filter, or manyToMany EXISTS-on-target). Only pushes
+ * when a filter applies — no-op otherwise.
+ */
+export declare function collectRelationCountParams(qi: BuilderCtx, relDef: RelationDef, params: unknown[]): void;
+export declare function getCamelDateFields(qi: BuilderCtx, table: string, meta: TableMetadata): Set<string>;
+/**
+ * Parse a row that may contain JSON nested relation columns.
+ *
+ * `fromJson` says where THIS row's own scalar columns came from. A root row
+ * (join, batched, flatten) is read straight off the driver, so `false`; a row
+ * decoded out of a `json_agg`/`json_build_object` column is `true` and gets
+ * its divergent scalars decoded back to the driver's representation first (see
+ * the JSON-wire section above). Recursion into a relation column is always
+ * `true`, which is exactly right on every strategy: `batched` and `flatten`
+ * hand this function driver rows, but any relation still nested INSIDE one of
+ * those rows arrived as a correlated JSON subquery.
+ */
+export declare function parseNestedRow(qi: BuilderCtx, row: Record<string, unknown>, table: string, fromJson?: boolean): Record<string, unknown>;
+/**
+ * Resolve the emitted column list for a relation, honoring `select` / `omit`.
+ * Shared by {@link buildRelationSubquery} (json order) and
+ * {@link buildRelationShape} (decode key order) so they can never diverge.
+ */
+export declare function resolveTargetColumns(qi: BuilderCtx, spec: true | WithOptions, targetMeta: TableMetadata, includePii?: boolean): string[];
+/**
+ * Render a single relation row's JSON: a keyed object (`'object'`) or a
+ * positional array (`'positional'`). The array drops the keys but keeps the
+ * exact expression order, so {@link RelationShape.keys} maps positions back.
+ */
+export declare function buildJsonRow(qi: BuilderCtx, jsonPairs: [key: string, expr: string][]): string;
+/**
+ * Build the top-level relation shapes for a `with` clause, mirroring
+ * {@link buildSelectWithRelations}: same relation iteration order, same
+ * per-relation column resolution, same nested recursion.
+ */
+export declare function buildRelationShapes(qi: BuilderCtx, table: string, withClause: WithClause, includePii?: boolean): Record<string, RelationShape>;
+/**
+ * Recursively describe one relation's positional layout: the camelCase key
+ * order (scalar columns first, then nested relation slots in the same order
+ * {@link buildRelationSubquery} appends them), the nested sub-shapes, and the
+ * cardinality (single object for belongsTo/hasOne, array for the rest).
+ */
+export declare function buildRelationShape(qi: BuilderCtx, relDef: RelationDef, spec: true | WithOptions, parentMeta: TableMetadata, includePii?: boolean): RelationShape;
+/**
+ * Build the row parser for a `with` clause. In object mode this is just
+ * {@link parseNestedRow}. In positional mode it decodes each relation's
+ * positional arrays into the object form first (shapes built once, not per
+ * row), then delegates to parseNestedRow for date/snake-camel coercion.
+ */
+export declare function makeNestedParser(qi: BuilderCtx, withClause: WithClause, includePii?: boolean, flattenPlan?: FlattenPlan | null): (row: Record<string, unknown>) => Record<string, unknown>;
+/**
+ * Return a shallow copy of a top-level row with each relation column decoded
+ * from its positional array(s) into the object representation. Only relation
+ * columns are positional — base scalar columns stay object-keyed — so the
+ * result is exactly what the object encoding would have handed parseNestedRow.
+ */
+export declare function decodePositionalRelations(qi: BuilderCtx, row: Record<string, unknown>, shapes: Record<string, RelationShape>): Record<string, unknown>;
+/**
+ * Decode one relation's positional JSON value. `json_agg` returns the value as
+ * a JSON string at the top level (JSON.parse once); nested relation slots are
+ * already-parsed arrays. A `'many'` value is an array of positional arrays; a
+ * `'one'` value is a single positional array or null.
+ */
+export declare function decodePositionalValue(qi: BuilderCtx, raw: unknown, shape: RelationShape): unknown;
+/** Map one positional array back to a keyed object using the shape's key order. */
+export declare function decodePositionalObject(qi: BuilderCtx, arr: unknown, shape: RelationShape): unknown;
+/** One relation `'flatten'` declined, with the reason, for the dev warning. */
+export interface FlattenReject {
+    /** Dotted path from the root table's `with`, e.g. `order.customer`. */
+    relation: string;
+    reason: string;
+}
+/**
+ * One entry in a flattened relation's nested `with`, in
+ * `sortedEntries(spec.with)` order. `'flat'` is another LEFT JOIN; `'json'` is
+ * a correlated subquery projected as a single JSON column, exactly as the
+ * default strategy would have emitted it (with the join alias as its parent
+ * reference). Ordering is preserved so the assembled object's key order matches
+ * the join strategy's byte for byte.
+ */
+export interface FlattenSlot {
+    relName: string;
+    kind: 'flat' | 'json';
+}
+/** A single to-one relation compiled as a LEFT JOIN plus a prefixed projection. */
+export interface FlattenNode {
+    relName: string;
+    relDef: RelationDef;
+    spec: true | WithOptions;
+    targetTable: string;
+    targetMeta: TableMetadata;
+    /** Output-name prefix, and the derived-table alias for a top-level node (`f0`). */
+    alias: string;
+    /** Alias of the real target table inside the derived table (`f0s`). */
+    srcAlias: string;
+    /** Target-side correlation columns (provably unique — see {@link provableUniqueTargetKey}). */
+    keyColumns: string[];
+    /**
+     * Match discriminator. A top-level node projects the constant `1` (its
+     * derived-table row exists only when the target matched, and the outer LEFT
+     * JOIN null-extends it otherwise); a nested node projects the predicate
+     * `(src.key IS NOT NULL)`. Either way the discriminator carries no cell
+     * VALUE, so a PII-tagged key column never leaves the database merely because
+     * a discriminator was needed: no PII column enters the wire, the projection
+     * or the assembled object unless the caller selected it or passed
+     * `includePii`. Without it, "the join matched nothing" would be
+     * indistinguishable from "the row exists and every projected column is NULL".
+     */
+    discAlias: string;
+    /** `[snake_case column, output alias]` for every projected column. */
+    cols: [column: string, sqlAlias: string][];
+    /** Nested `with` entries in emission order. */
+    slots: FlattenSlot[];
+    /** Nested flattened relations, keyed by relation name (the `'flat'` slots). */
+    children: Record<string, FlattenNode>;
+    /** Output alias of each `'json'` slot's correlated subquery column. */
+    jsonAliases: Record<string, string>;
+    /**
+     * Top-level nodes only: the correlation columns re-exposed by the derived
+     * table (`f0__$c0`, ...) so the OUTER join condition can reference them
+     * without the real column names entering the outer scope. Never surfaced to
+     * the caller.
+     */
+    corrAliases: string[];
+    /** Nesting depth, matching {@link buildRelationSubquery}'s depth accounting. */
+    depth: number;
+    /** Breadcrumb trail for {@link CircularRelationError} parity. */
+    path: string[];
+}
+/**
+ * The compiled `'flatten'` plan for one `with` clause: which top-level
+ * relations become LEFT JOINs, and a signature that keys the SQL template
+ * cache. Relations absent from `nodes` compile exactly as they do today.
+ */
+export interface FlattenPlan {
+    nodes: Record<string, FlattenNode>;
+    /** Every SELECT-list alias the plan introduces (flat rows carry them all). */
+    aliases: string[];
+    /** Structural signature for the `fl=` SQL-cache-key segment. */
+    signature: string;
+}
+/**
+ * The target-side correlation columns of a to-one relation, but ONLY when the
+ * schema PROVES they are unique on the target table. This is the row-
+ * multiplication guard: a LEFT JOIN over a non-unique key silently duplicates
+ * parent rows, which would change results rather than just the plan.
+ *
+ * Proof sources, all exact set matches (a unique index on `(a, b)` does NOT
+ * make `a` unique):
+ *   - the target's primary key,
+ *   - a declared unique constraint (`uniqueColumns`),
+ *   - a full, non-expression UNIQUE index. Partial unique indexes are refused
+ *     (they only constrain the rows matching their predicate) and PowDB
+ *     doc-field expression indexes are refused (they index a JSON path, not the
+ *     raw column).
+ *
+ * Returns `null` for to-many / manyToMany relations and for anything it cannot
+ * prove, which routes the relation back to the correlated subquery.
+ *
+ * NULLs need no special handling: a unique constraint permits repeated NULLs,
+ * but `target.key = parent.fk` never matches a NULL key, so a null-keyed target
+ * row can never join.
+ */
+export declare function provableUniqueTargetKey(relDef: RelationDef, targetMeta: TableMetadata): string[] | null;
+/**
+ * Compile the `'flatten'` plan for a top-level `with` clause, or return `null`
+ * when nothing in it is eligible (in which case the caller emits exactly the SQL
+ * it emits today, down to the cache key).
+ *
+ * The plan is a pure function of the schema, the `with` clause shape and
+ * `includePii` — never of any bound value — so the build path, the cache-hit
+ * param-collect path and the row assembler can each recompute it and agree.
+ */
+export declare function planFlattenWith(qi: BuilderCtx, table: string, withClause: WithClause, includePii?: boolean): FlattenPlan | null;
+/**
+ * Emit one TOP-LEVEL flattened relation: a derived table holding its whole
+ * to-one subtree, joined to the parent on the re-exposed correlation columns,
+ * plus the pass-through projection of every name that subtree contributes.
+ *
+ * ```sql
+ *  LEFT JOIN (
+ *    SELECT 1 AS "f0__$k", f0s."id" AS "f0__$c0",
+ *           f0s."id" AS "f0__id", f0s."name" AS "f0__name",
+ *           (f1s."id" IS NOT NULL) AS "f1__$k", f1s."code" AS "f1__code"
+ *    FROM "orgs" f0s
+ *    LEFT JOIN "regions" f1s ON f1s."id" = f0s."region_id"
+ *    WHERE f0s."deleted" = $1
+ *  ) f0 ON f0."f0__$c0" = "users"."org_id"
+ * ```
+ *
+ * See the derived-table note above for why the join cannot expose the target's
+ * real column names.
+ */
+export declare function emitFlattenNode(qi: BuilderCtx, node: FlattenNode, parentRef: string, params: unknown[], joinSink: string[], selectSink: string[], aliasCounter: {
+    n: number;
+}, includePii?: boolean): void;
+/** Param-collect mirror of {@link emitFlattenNode}. */
+export declare function collectFlattenNodeParams(qi: BuilderCtx, node: FlattenNode, params: unknown[]): void;
+/**
+ * Rebuild one flattened relation's object from a flat row.
+ *
+ * Returns `null` when the discriminator is NULL (the LEFT JOIN matched
+ * nothing), which is the ONLY signal that distinguishes "no related row" from
+ * "a related row whose every projected column is NULL".
+ *
+ * The sub-row is keyed by the target's raw snake_case column names and handed
+ * to {@link parseNestedRow}, so the flattened object goes through the very same
+ * camelCase mapping, Date coercion and nested-JSON parsing the join strategy's
+ * `json_build_object` output does. Nested flattened relations are assigned
+ * after the parse, over placeholder keys inserted in slot order, so the
+ * assembled object's key order matches the join strategy's exactly.
+ */
+export declare function assembleFlattenNode(qi: BuilderCtx, row: Record<string, unknown>, node: FlattenNode): Record<string, unknown> | null;
+/**
+ * Row parser for a `'flatten'` plan: strip the prefixed join columns out of the
+ * flat row (inserting a placeholder at the position each relation's block
+ * started, so key order is preserved), parse the remainder exactly as the join
+ * strategy does, then assemble each flattened relation.
+ */
+export declare function makeFlattenParser(qi: BuilderCtx, plan: FlattenPlan): (row: Record<string, unknown>) => Record<string, unknown>;
+/**
+ * Build a SELECT clause that includes both base columns and nested relation subqueries.
+ *
+ * For each relation specified in the `with` clause, this method generates a correlated
+ * subquery using PostgreSQL's `json_agg(json_build_object(...))` pattern. The result
+ * is a single SQL SELECT clause that resolves the full object tree in one query --
+ * no N+1 problem.
+ *
+ * **How it works:**
+ * 1. Resolves the base columns for the root table (all columns, or a subset via `columnsList`).
+ * 2. Iterates over each key in the `with` clause, looking up the relation definition.
+ * 3. For each relation, delegates to {@link buildRelationSubquery} to generate a
+ *    correlated subquery that returns JSON (array for hasMany, object for belongsTo/hasOne).
+ * 4. Each subquery is aliased as the relation name in the final SELECT.
+ *
+ * **aliasCounter:** A shared `{ n: number }` object is passed through all nesting levels.
+ * Each call to `buildRelationSubquery` increments it to produce unique table aliases
+ * (`t0`, `t1`, `t2`, ...) across arbitrarily deep relation trees, preventing alias
+ * collisions in the generated SQL.
+ *
+ * **Example output:**
+ * ```sql
+ * "users"."id", "users"."name", "users"."email",
+ * (SELECT COALESCE(json_agg(json_build_object('id', t0."id", 'title', t0."title")), '[]'::json)
+ *   FROM "posts" t0 WHERE t0."user_id" = "users"."id") AS "posts"
+ * ```
+ *
+ * @param table - The root table name (e.g. `"users"`).
+ * @param withClause - An object mapping relation names to their include specs
+ *                     (`true` for default inclusion, or `WithOptions` for select/omit/where/orderBy/limit).
+ * @param params - Shared parameter array for parameterized values (`$1`, `$2`, ...).
+ *                 Nested where/limit values are pushed here to prevent SQL injection.
+ * @param columnsList - Optional subset of columns to include in the SELECT. When `null`
+ *                      or omitted, all columns from the table's schema metadata are used.
+ * @param depth - Current nesting depth, passed through to {@link buildRelationSubquery}
+ *                for circular-relation detection. Defaults to `0` at the top level.
+ * @param path - Breadcrumb trail of relation names traversed so far, used in error
+ *               messages when circular or too-deep nesting is detected.
+ * @returns A complete SELECT clause string (without the `SELECT` keyword) containing
+ *          base columns and relation subqueries.
+ */
+export declare function buildSelectWithRelations(qi: BuilderCtx, table: string, withClause: WithClause, params: unknown[], columnsList?: string[] | null, depth?: number, path?: string[], includePii?: boolean, flatten?: {
+    plan: FlattenPlan;
+    joinSink: string[];
+}): string;
+/**
+ * Generate a correlated subquery that returns JSON for a single relation.
+ *
+ * This is the core of Turbine's single-query nested relation strategy. For a given
+ * relation (e.g. `posts` on a `users` query), it produces a self-contained SQL subquery
+ * that PostgreSQL evaluates per parent row, returning either a JSON array (hasMany) or
+ * a single JSON object (belongsTo / hasOne).
+ *
+ * ### Algorithm overview
+ *
+ * 1. **Alias generation:** Allocates a unique alias (`t0`, `t1`, ...) from the shared
+ *    `aliasCounter` so that deeply nested subqueries never collide.
+ *
+ * 2. **Column resolution:** Honors `select` / `omit` options to control which columns
+ *    appear in the output JSON.
+ *
+ * 3. **`json_build_object`:** Builds a JSON object for each row by mapping camelCase
+ *    field names to their column values:
+ *    ```sql
+ *    json_build_object('id', t0."id", 'title', t0."title", 'createdAt', t0."created_at")
+ *    ```
+ *
+ * 4. **`json_agg` wrapping (hasMany):** For one-to-many relations, wraps the
+ *    `json_build_object` call in `json_agg(...)` to aggregate all matching child rows
+ *    into a JSON array. Uses `COALESCE(..., '[]'::json)` so the result is never NULL.
+ *    For belongsTo / hasOne, no aggregation is used -- just the single JSON object
+ *    with `LIMIT 1`.
+ *
+ * 5. **Correlation (WHERE clause):** Links the subquery to the parent row:
+ *    - **hasMany:** `alias.foreignKey = parentRef.referenceKey`
+ *      (e.g. `t0."user_id" = "users"."id"` -- child FK points to parent PK)
+ *    - **belongsTo / hasOne:** `alias.referenceKey = parentRef.foreignKey`
+ *      (e.g. `t0."id" = "posts"."author_id"` -- parent FK points to child PK)
+ *
+ * 6. **Recursion:** If the spec includes a nested `with` clause, this method calls
+ *    itself recursively for each nested relation, passing the current alias as
+ *    `parentRef`. The nested subquery appears as an additional key in the
+ *    `json_build_object` call, wrapped in `COALESCE(..., '[]'::json)`.
+ *    Depth is incremented and capped at 10 to guard against circular relations.
+ *
+ * 7. **LIMIT / ORDER BY wrapping:** For hasMany relations with `limit` or `orderBy`,
+ *    the query is restructured into a two-level form:
+ *    ```sql
+ *    SELECT COALESCE(json_agg(json_build_object(...)), '[]'::json)
+ *    FROM (
+ *      SELECT t0.* FROM "posts" t0
+ *      WHERE t0."user_id" = "users"."id"
+ *      ORDER BY t0."created_at" DESC
+ *      LIMIT $1
+ *    ) t0i
+ *    ```
+ *    This ensures LIMIT and ORDER BY apply to the raw rows *before* `json_agg`
+ *    aggregation. Without the inner subquery, LIMIT would be meaningless because
+ *    `json_agg` produces a single aggregated row.
+ *
+ * 8. **Parameter threading:** All user-supplied values (where filters, limit) are
+ *    pushed to the shared `params` array with `$N` placeholders. No string
+ *    interpolation of user data ever occurs -- all identifiers go through
+ *    `qi.q()` and all values are parameterized.
+ *
+ * ### Example output (hasMany with nested relation)
+ * ```sql
+ * SELECT COALESCE(json_agg(json_build_object(
+ *   'id', t0."id",
+ *   'title', t0."title",
+ *   'comments', COALESCE((
+ *     SELECT COALESCE(json_agg(json_build_object('id', t1."id", 'body', t1."body")), '[]'::json)
+ *     FROM "comments" t1 WHERE t1."post_id" = t0."id"
+ *   ), '[]'::json)
+ * )), '[]'::json) FROM "posts" t0 WHERE t0."user_id" = "users"."id"
+ * ```
+ *
+ * @param relDef - The relation definition from schema metadata (contains `to`, `type`,
+ *                 `foreignKey`, `referenceKey`).
+ * @param spec - Either `true` (include with defaults) or a `WithOptions` object that
+ *               can specify `select`, `omit`, `where`, `orderBy`, `limit`, and nested `with`.
+ * @param params - Shared parameter array. User-supplied values are pushed here and
+ *                 referenced as `$1`, `$2`, etc. in the generated SQL.
+ * @param parentRef - The alias (e.g. `"t0"`) or table name (e.g. `"users"`) of the
+ *                    parent query. Used to build the correlated WHERE clause that ties
+ *                    child rows to their parent row.
+ * @param aliasCounter - Shared mutable counter (`{ n: number }`) for generating unique
+ *                       table aliases (`t0`, `t1`, `t2`, ...) across all nesting levels.
+ *                       Each call increments `n` by 1.
+ * @param depth - Current nesting depth (starts at `0`). Incremented on each recursive
+ *                call. If it reaches 10, a {@link CircularRelationError} is thrown.
+ * @param path - Breadcrumb trail of relation/table names traversed so far
+ *               (e.g. `["users", "posts", "comments"]`). Used in the error message
+ *               when circular or too-deep nesting is detected.
+ * @returns A complete SQL subquery string (without surrounding parentheses) that
+ *          evaluates to a JSON array (hasMany) or a JSON object (belongsTo/hasOne).
+ */
+export declare function buildRelationSubquery(qi: BuilderCtx, relDef: RelationDef, spec: true | WithOptions, params: unknown[], parentRef: string, aliasCounter: {
+    n: number;
+}, depth?: number, path?: string[], includePii?: boolean): string;
+/**
+ * Build the json_agg subquery for a `manyToMany` relation, JOINing the target
+ * table through a junction (join) table.
+ *
+ * Shape (no LIMIT/ORDER):
+ * ```sql
+ * SELECT COALESCE(json_agg(json_build_object(...)), '[]'::json)
+ * FROM <target> <talias>
+ * JOIN <junction> <jalias> ON <jalias>.<targetKey> = <talias>.<targetPK>
+ * WHERE <jalias>.<sourceKey> = <parentRef>.<referenceKey>
+ * ```
+ *
+ * With LIMIT/ORDER, the rows are wrapped in an inner subquery so the LIMIT
+ * applies BEFORE aggregation (identical strategy to hasMany).
+ *
+ * Cardinality is always 'many' → empty-array fallback, never NULL.
+ *
+ * IMPORTANT: every `params.push` here MUST be mirrored, in the same order, in
+ * {@link collectRelationSubqueryParams} or pipeline batching will desync.
+ */
+export declare function buildManyToManySubquery(qi: BuilderCtx, relDef: RelationDef, spec: true | WithOptions, params: unknown[], parentRef: string, aliasCounter: {
+    n: number;
+}, currentDepth: number, currentPath: string[], talias: string, targetMeta: TableMetadata, targetColumns: string[], includePii?: boolean): string;