turbine-orm 0.5.0 → 0.7.1

package/dist/query.d.ts

@@ -1,11 +1,11 @@
 /**
- * @batadata/turbine — Query builder
+ * turbine-orm — Query builder
  *
  * Each table accessor (db.users, db.posts, etc.) returns a QueryInterface<T>
  * that builds parameterized SQL and executes it through the connection pool.
  *
  * Nested relations use json_build_object + json_agg subqueries for single-query
- * resolution — the technique that benchmarks proved 2-3x faster than Prisma.
+ * resolution — a PostgreSQL-native approach that eliminates N+1 query patterns.
  *
  * Schema-driven: all column names, types, and relations come from introspected
  * metadata — nothing is hardcoded.
@@ -61,11 +61,37 @@ export type WhereClause<T> = {
     /** Relation filters — keyed by relation name, value is { some, every, none } */
     [relationName: string]: unknown;
 };
+/**
+ * Unparameterized with clause — accepts any relation name.
+ * Used internally by the query builder at runtime.
+ */
 export interface WithClause {
     [relation: string]: true | WithOptions;
 }
-export interface WithOptions {
-    with?: WithClause;
+/**
+ * Relation-aware with clause. When R (the relations map) is provided,
+ * only keys from R are autocompleted. Used in public method signatures
+ * so the compiler can narrow the return type.
+ *
+ * For typed maps, each relation accepts either `true` (default include) or a
+ * {@link WithOptions} object whose nested `with` is keyed against the relation
+ * target's own relations interface — this is what enables deep
+ * `WithResult` inference.
+ */
+export type TypedWithClause<R extends object = {}> = [keyof R] extends [never] ? WithClause : {
+    [K in keyof R]?: true | WithOptions<RelationRelations<R[K]> & object>;
+};
+/**
+ * Options for an included relation.
+ *
+ * Generic over `NestedR` — the relations interface of the *target* entity —
+ * so the nested `with` clause is autocompleted with the correct relation keys
+ * and so {@link WithResult} can recursively infer the return type. Defaults to
+ * `{}` (no relation suggestions) for callers that use the unparameterized
+ * {@link WithClause}.
+ */
+export interface WithOptions<NestedR extends object = {}> {
+    with?: TypedWithClause<NestedR>;
     where?: Record<string, unknown>;
     orderBy?: Record<string, OrderDirection>;
     limit?: number;
@@ -74,22 +100,103 @@ export interface WithOptions {
     /** Exclude these fields from the relation */
     omit?: Record<string, boolean>;
 }
-export interface FindUniqueArgs<T> {
+/**
+ * A relation descriptor used by generated `*Relations` interfaces to make deep
+ * `with` clause inference work. It bundles three pieces of information that
+ * `WithResult` needs to recurse through nested relations:
+ *
+ *  - `__target`     — the target entity type (e.g. `Post`)
+ *  - `__cardinality`— `'many'` for hasMany, `'one'` for belongsTo / hasOne
+ *  - `__relations`  — the target entity's relations interface (for further recursion)
+ *
+ * **Generator contract (Track 3):** the code generator emits `*Relations`
+ * interfaces in the following shape so that `WithResult` can walk arbitrary
+ * nesting depth:
+ *
+ * ```ts
+ * export interface UserRelations {
+ *   posts:   RelationDescriptor<Post,    'many', PostRelations>;
+ *   profile: RelationDescriptor<Profile, 'one',  ProfileRelations>;
+ * }
+ * ```
+ *
+ * The brand fields are phantom — they exist only for type inference and have
+ * no runtime representation. The runtime always sees the parsed entity values
+ * (arrays for hasMany, single object or null for belongsTo / hasOne) — see the
+ * cardinality projection inside {@link WithResult}.
+ *
+ * **Backward compatibility:** legacy generated code emitted bare types
+ * (`posts: Post[]`, `profile: Profile | null`). `WithResult` still accepts that
+ * shape via a fallback branch — it just cannot recurse into nested `with` for
+ * those relations until the generator is updated.
+ *
+ * @typeParam Target      - The entity type the relation points at.
+ * @typeParam Cardinality - `'many'` (array) or `'one'` (single object | null).
+ * @typeParam Relations   - The target entity's own `*Relations` interface, or
+ *                          `{}` if the target has no relations of its own.
+ */
+export interface RelationDescriptor<Target, Cardinality extends 'one' | 'many', Relations extends object = {}> {
+    readonly __target?: Target;
+    readonly __cardinality?: Cardinality;
+    readonly __relations?: Relations;
+}
+/** Extract the target entity from a relation descriptor or bare relation type. */
+type RelationTarget<Rel> = Rel extends RelationDescriptor<infer Target, infer _C, infer _R> ? Target : Rel extends Array<infer Item> ? Item : Rel extends infer One | null ? One : Rel;
+/** Extract the target's relations map from a relation descriptor (or `{}` for bare types). */
+type RelationRelations<Rel> = Rel extends RelationDescriptor<infer _T, infer _C, infer R> ? R : {};
+/** Project the target type into its runtime shape (array for many, single for one). */
+type ApplyCardinality<Rel, Resolved> = Rel extends RelationDescriptor<infer _T, infer Cardinality, infer _R> ? Cardinality extends 'many' ? Resolved[] : Resolved | null : Rel extends Array<infer _Item> ? Resolved[] : Resolved | null;
+/**
+ * Compute the result type when relations are included via `with`.
+ *
+ * Recursively walks the `with` clause, looking up each relation in `R` and:
+ *
+ *  1. If the relation is included with `true` (or no nested `with`), the
+ *     relation's bare resolved type is grafted onto `T` (e.g. `posts: Post[]`).
+ *  2. If the relation is included with a nested `with: {...}`, the recursion
+ *     looks up the target entity's relations interface (via the
+ *     {@link RelationDescriptor} brand fields the generator emits) and
+ *     recursively applies `WithResult` to the nested target. Cardinality is
+ *     re-applied at each level so a hasMany relation stays an array even after
+ *     deep nesting.
+ *
+ * **When `R` is `{}` (the default):** the recursion short-circuits and the
+ * function returns plain `T` — preserving the existing untyped escape hatch
+ * for callers that have not generated typed clients.
+ *
+ * **When `R` does not contain the requested relations:** the unknown keys are
+ * ignored (the runtime will throw a `RelationError`, but the type system stays
+ * permissive so the legacy `WithClause` index signature still typechecks).
+ *
+ * @typeParam T - Base entity type (e.g. `User`).
+ * @typeParam R - Relations map for `T` (e.g.
+ *                `{ posts: RelationDescriptor<Post, 'many', PostRelations>; ... }`).
+ *                Legacy bare shapes (`{ posts: Post[]; profile: Profile | null }`)
+ *                are also accepted, but cannot recurse beyond one level.
+ * @typeParam W - The `with` clause the user passed (e.g. `{ posts: true }` or
+ *                `{ posts: { with: { comments: true } } }`).
+ */
+export type WithResult<T, R extends object, W> = [keyof R] extends [never] ? T : W extends object ? [keyof W & keyof R] extends [never] ? T : T & {
+    [K in keyof W & keyof R]: W[K] extends true ? ApplyCardinality<R[K], RelationTarget<R[K]>> : W[K] extends {
+        with?: infer NestedW;
+    } ? NestedW extends object ? ApplyCardinality<R[K], WithResult<RelationTarget<R[K]>, RelationRelations<R[K]> & object, NestedW>> : ApplyCardinality<R[K], RelationTarget<R[K]>> : ApplyCardinality<R[K], RelationTarget<R[K]>>;
+} : T;
+export interface FindUniqueArgs<T, R extends object = {}, W extends TypedWithClause<R> = TypedWithClause<R>> {
     where: WhereClause<T>;
     select?: Record<string, boolean>;
     omit?: Record<string, boolean>;
-    with?: WithClause;
+    with?: W;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
 }
-export interface FindManyArgs<T> {
+export interface FindManyArgs<T, R extends object = {}, W extends TypedWithClause<R> = TypedWithClause<R>> {
     where?: WhereClause<T>;
     select?: Record<string, boolean>;
     omit?: Record<string, boolean>;
     orderBy?: Record<string, OrderDirection>;
     limit?: number;
     offset?: number;
-    with?: WithClause;
+    with?: W;
     /** Cursor-based pagination: start after this row */
     cursor?: Partial<T>;
     /** Number of records to take (used with cursor) */
@@ -99,6 +206,10 @@ export interface FindManyArgs<T> {
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
 }
+export interface FindManyStreamArgs<T, R extends object = {}, W extends TypedWithClause<R> = TypedWithClause<R>> extends FindManyArgs<T, R, W> {
+    /** Number of rows to fetch per internal FETCH batch (default: 100) */
+    batchSize?: number;
+}
 export interface CreateArgs<T> {
     data: Partial<T>;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
@@ -111,27 +222,71 @@ export interface CreateManyArgs<T> {
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
 }
+/**
+ * Atomic update operators for a field.
+ *
+ * `set` works on any type; `increment`, `decrement`, `multiply`, and `divide`
+ * are only valid on numeric fields. They generate SQL like
+ * `col = col + $n` (and the corresponding `-`, `*`, `/` variants) instead of
+ * plain absolute assignments, so they are safe against concurrent writers —
+ * the database performs the math atomically.
+ *
+ * @example
+ *   db.posts.update({ where: { id: 5 }, data: { viewCount: { increment: 1 } } });
+ */
+export type UpdateOperatorInput<V> = {
+    set: V;
+} | (V extends number ? {
+    increment: number;
+} : never) | (V extends number ? {
+    decrement: number;
+} : never) | (V extends number ? {
+    multiply: number;
+} : never) | (V extends number ? {
+    divide: number;
+} : never);
+/**
+ * Update data — each field can be a plain value or an atomic operator object.
+ * Back-compatible with `Partial<T>`: plain values still typecheck unchanged.
+ */
+export type UpdateInput<T> = {
+    [K in keyof T]?: T[K] | UpdateOperatorInput<T[K]>;
+};
 export interface UpdateArgs<T> {
     where: WhereClause<T>;
-    data: Partial<T>;
+    data: UpdateInput<T>;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
+    /**
+     * Opt in to running this mutation when `where` resolves to an empty
+     * predicate (e.g. `{}` or `{ id: undefined }`). Default `false` — an
+     * empty predicate throws `ValidationError` to catch the common case of
+     * a filter value accidentally being `undefined`. Set this to `true` only
+     * when an unconditional mutation is the intended behaviour.
+     */
+    allowFullTableScan?: boolean;
 }
 export interface UpdateManyArgs<T> {
     where: WhereClause<T>;
-    data: Partial<T>;
+    data: UpdateInput<T>;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
+    /** See {@link UpdateArgs.allowFullTableScan}. */
+    allowFullTableScan?: boolean;
 }
 export interface DeleteArgs<T> {
     where: WhereClause<T>;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
+    /** See {@link UpdateArgs.allowFullTableScan}. */
+    allowFullTableScan?: boolean;
 }
 export interface DeleteManyArgs<T> {
     where: WhereClause<T>;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
+    /** See {@link UpdateArgs.allowFullTableScan}. */
+    allowFullTableScan?: boolean;
 }
 export interface UpsertArgs<T> {
     where: WhereClause<T>;
@@ -158,8 +313,6 @@ export interface GroupByArgs<T> {
     _min?: Partial<Record<keyof T & string, boolean>>;
     /** Maximum value of fields in each group */
     _max?: Partial<Record<keyof T & string, boolean>>;
-    /** Having clause for filtering groups */
-    having?: Record<string, unknown>;
     /** Order groups */
     orderBy?: Record<string, OrderDirection>;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
@@ -241,10 +394,16 @@ type MiddlewareFn = (params: {
 export interface QueryInterfaceOptions {
     /** Default LIMIT applied to findMany() when no limit is specified */
     defaultLimit?: number;
-    /** Log a warning when findMany() is called without a limit */
+    /**
+     * Log a one-time warning when {@link QueryInterface.findMany} is called
+     * without a `limit`. Defaults to `true` so that accidental unbounded
+     * queries are surfaced loudly during development. Pass `false` to silence
+     * the warning entirely (e.g. for CLI tooling that intentionally streams
+     * full tables).
+     */
     warnOnUnlimited?: boolean;
 }
-export declare class QueryInterface<T extends object> {
+export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly pool;
     private readonly table;
     private readonly schema;
@@ -254,13 +413,29 @@ export declare class QueryInterface<T extends object> {
     private readonly middlewares;
     private readonly defaultLimit?;
     private readonly warnOnUnlimited;
+    /**
+     * Tracks tables that have already triggered an unlimited-query warning so
+     * the user is not spammed once per row. Per-instance state — each
+     * QueryInterface is bound to a single table, so this set will only ever
+     * contain at most one entry, but using a Set keeps the API consistent with
+     * the audit's "Set<string>" guidance and leaves room for future
+     * cross-table sharing.
+     */
+    private readonly warnedTables;
     /** Pre-computed column type lookups (avoids linear scans per query) */
     private readonly columnPgTypeMap;
     private readonly columnArrayTypeMap;
     constructor(pool: pg.Pool, table: string, schema: SchemaMetadata, middlewares?: MiddlewareFn[], options?: QueryInterfaceOptions);
+    /**
+     * Reset the per-instance unlimited-query warning dedupe set.
+     * Exposed for tests so a single test process can verify the warning fires
+     * exactly once per table without bleeding state between assertions.
+     */
+    resetUnlimitedWarnings(): void;
     /**
      * Execute a pool.query with an optional timeout.
      * If timeout is set, races the query against a timer and rejects on expiry.
+     * pg driver errors are translated to typed Turbine errors via wrapPgError.
      */
     private queryWithTimeout;
     /**
@@ -273,21 +448,43 @@ export declare class QueryInterface<T extends object> {
      * To intercept queries before SQL generation, use the raw() method instead.
      */
     private executeWithMiddleware;
+    findUnique<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W>): Promise<WithResult<T, R, W> | null>;
+    buildFindUnique<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W>): DeferredQuery<T | null>;
+    findMany<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W>): Promise<WithResult<T, R, W>[]>;
     /**
-     * Generate a cache key for a query shape.
-     * Same where-keys + same with-clause = same SQL template.
+     * Emit a one-time `console.warn` when {@link findMany} is called without an
+     * explicit `limit`/`take` and `warnOnUnlimited` has not been disabled.
+     *
+     * Deduped per QueryInterface instance via {@link warnedTables} so a busy
+     * loop calling `db.users.findMany()` thousands of times only logs once.
+     * Suppressed when `defaultLimit` is configured (the caller has already
+     * opted in to a bounded query) and when the user passed an explicit
+     * `limit`, `take`, or `cursor`.
+     */
+    private maybeWarnUnlimited;
+    buildFindMany<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W>): DeferredQuery<T[]>;
+    /**
+     * Stream rows from a findMany query using PostgreSQL cursors.
+     * Returns an AsyncIterable that yields individual rows, fetching in batches internally.
+     *
+     * Uses DECLARE CURSOR within a dedicated transaction on a single pooled connection.
+     * The cursor is automatically closed and the connection released when iteration
+     * completes or is terminated early (e.g. `break` from `for await`).
+     *
+     * @example
+     * ```ts
+     * for await (const user of db.users.findManyStream({ where: { orgId: 1 }, batchSize: 500 })) {
+     *   process.stdout.write(`${user.email}\n`);
+     * }
+     * ```
      */
-    private cacheKey;
-    findUnique(args: FindUniqueArgs<T>): Promise<T | null>;
-    buildFindUnique(args: FindUniqueArgs<T>): DeferredQuery<T | null>;
-    findMany(args?: FindManyArgs<T>): Promise<T[]>;
-    buildFindMany(args?: FindManyArgs<T>): DeferredQuery<T[]>;
-    findFirst(args?: FindManyArgs<T>): Promise<T | null>;
-    buildFindFirst(args?: FindManyArgs<T>): DeferredQuery<T | null>;
-    findFirstOrThrow(args?: FindManyArgs<T>): Promise<T>;
-    buildFindFirstOrThrow(args?: FindManyArgs<T>): DeferredQuery<T>;
-    findUniqueOrThrow(args: FindUniqueArgs<T>): Promise<T>;
-    buildFindUniqueOrThrow(args: FindUniqueArgs<T>): DeferredQuery<T>;
+    findManyStream<W extends TypedWithClause<R> = {}>(args?: FindManyStreamArgs<T, R, W>): AsyncGenerator<WithResult<T, R, W>, void, undefined>;
+    findFirst<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W>): Promise<WithResult<T, R, W> | null>;
+    buildFindFirst<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W>): DeferredQuery<T | null>;
+    findFirstOrThrow<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W>): Promise<WithResult<T, R, W>>;
+    buildFindFirstOrThrow<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W>): DeferredQuery<T>;
+    findUniqueOrThrow<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W>): Promise<WithResult<T, R, W>>;
+    buildFindUniqueOrThrow<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W>): DeferredQuery<T>;
     create(args: CreateArgs<T>): Promise<T>;
     buildCreate(args: CreateArgs<T>): DeferredQuery<T>;
     createMany(args: CreateManyArgs<T>): Promise<T[]>;
@@ -325,8 +522,33 @@ export declare class QueryInterface<T extends object> {
     private toColumn;
     /** Convert camelCase field name to a double-quoted SQL identifier */
     private toSqlColumn;
+    /**
+     * Build a single SET clause entry for update/updateMany.
+     *
+     * Supports plain values and atomic operator objects ({ set, increment,
+     * decrement, multiply, divide }). An operator object is detected ONLY when
+     * it has EXACTLY one key that is one of the 5 operator keys — this avoids
+     * misinterpreting JSON column values like `{ set: 'x' }` as operators
+     * (real operator objects always have exactly one key, and a plain JSON
+     * payload that happens to have a single `set` key is extremely unusual).
+     * Multi-key objects are always treated as plain (JSON) values.
+     *
+     * Returns the SQL fragment (e.g., `"view_count" = "view_count" + $3`) and
+     * pushes any required params onto the shared params array so that WHERE
+     * clause numbering continues correctly afterward.
+     */
+    private buildSetClause;
     /** Build WHERE clause from a where object (supports operators, NULL, OR) */
     private buildWhere;
+    /**
+     * Refuse mutations with an empty predicate unless explicitly opted in.
+     *
+     * An empty `where` (e.g. `{}` or `{ id: undefined }`) resolves to a
+     * mutation with no filter — a common footgun when a caller's filter
+     * value accidentally resolves to `undefined`. This guard throws
+     * `ValidationError` in that case unless `allowFullTableScan: true`.
+     */
+    private assertMutationHasPredicate;
     /**
      * Build the inner WHERE expression (without the WHERE keyword).
      * Returns null if no conditions exist.
@@ -355,24 +577,138 @@ export declare class QueryInterface<T extends object> {
     /** Parse a row that may contain JSON nested relation columns */
     private parseNestedRow;
     /**
-     * Build a SELECT clause with nested relation subqueries.
+     * 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.
      *
-     * Uses json_build_object + json_agg — the same approach as the raw-pg benchmark
-     * queries. Generates a single SQL statement that resolves the full object tree.
+     * **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.
      *
-     * Nested where values are parameterized via the shared params array to prevent
-     * SQL injection.
+     * **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.
      */
     private buildSelectWithRelations;
     /**
-     * Build a json_agg subquery for a relation.
+     * 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
+     *    `quoteIdent()` and all values are parameterized.
      *
-     * All user-supplied values in nested where clauses are parameterized
-     * through the shared params array — no string interpolation.
+     * ### 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 parentRef - The alias (or table name) of the parent in the outer query.
-     *                    Used for the correlated WHERE clause: `child.fk = parentRef.pk`.
-     * @param aliasCounter - Shared counter for generating unique aliases across nested levels.
+     * @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).
      */
     private buildRelationSubquery;
     /**