turbine-orm 0.35.0 → 0.36.0

package/dist/query/deferred.d.ts

@@ -98,6 +98,13 @@ export interface QueryInterfaceOptions {
      * outside production, so it never touches the production hot path. Set the
      * env var `TURBINE_DISABLE_CACHE_CHECK=1` to opt out when dev traffic is
      * perf-sensitive.
+     *
+     * Production sampling: the check is off in production by default. Set
+     * `TURBINE_CACHE_CHECK_SAMPLE` to a float in `(0,1]` to re-verify that
+     * fraction of cache hits under real load (e.g. `0.001` for one in a
+     * thousand). A sampled mismatch logs `console.error` once per distinct
+     * fingerprint AND throws the same `ValidationError` (E003). `0`, unset, or an
+     * unparseable value keeps the check fully off.
      */
     sqlCache?: boolean;
     /** SQL dialect implementation. Defaults to PostgreSQL. */

package/dist/query/filters.d.ts

@@ -112,6 +112,13 @@ export declare const ARRAY_OPERATOR_KEYS: Set<string>;
  * carve out.
  */
 export declare const ARRAY_UNIQUE_KEYS: Set<string>;
+/**
+ * Value-invariant shape fingerprint for an {@link ArrayFilter} (the INNER part,
+ * without the `arr(...)` wrapper the where fingerprint adds). The boolean
+ * `isEmpty` operator changes the SQL shape (`= '{}'` vs `<> '{}'`), so its
+ * concrete value is part of the shape; the other operators are value-invariant.
+ */
+export declare function fingerprintArrayFilterShape(filter: ArrayFilter): string;
 /** Check if a value is an Array filter object */
 export declare function isArrayFilter(value: unknown): value is ArrayFilter;
 /**

package/dist/query/filters.js

@@ -194,6 +194,17 @@ export const ARRAY_OPERATOR_KEYS = new Set(['has', 'hasEvery', 'hasSome', 'isEmp
  * carve out.
  */
 export const ARRAY_UNIQUE_KEYS = new Set(['has', 'hasEvery', 'hasSome', 'isEmpty']);
+/**
+ * Value-invariant shape fingerprint for an {@link ArrayFilter} (the INNER part,
+ * without the `arr(...)` wrapper the where fingerprint adds). The boolean
+ * `isEmpty` operator changes the SQL shape (`= '{}'` vs `<> '{}'`), so its
+ * concrete value is part of the shape; the other operators are value-invariant.
+ */
+export function fingerprintArrayFilterShape(filter) {
+    const keys = Object.keys(filter).sort();
+    const suffix = filter.isEmpty === undefined ? '' : `:empty=${filter.isEmpty ? 'true' : 'false'}`;
+    return `${keys.join(',')}${suffix}`;
+}
 /** Check if a value is an Array filter object */
 export function isArrayFilter(value) {
     if (value === null ||

package/dist/query/relations.d.ts

@@ -0,0 +1,441 @@
+/**
+ * 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): 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 */
+export declare function parseNestedRow(qi: BuilderCtx, row: Record<string, unknown>, table: string): 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): (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;
+/**
+ * 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): 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;