turbine-orm 0.9.1 → 0.10.0

package/dist/introspect.js

@@ -66,13 +66,16 @@ const SQL_FOREIGN_KEYS = `
 const SQL_UNIQUE_CONSTRAINTS = `
   SELECT
     tc.table_name,
-    kcu.column_name
+    tc.constraint_name,
+    kcu.column_name,
+    kcu.ordinal_position
   FROM information_schema.table_constraints tc
   JOIN information_schema.key_column_usage kcu
     ON tc.constraint_name = kcu.constraint_name
     AND tc.table_schema = kcu.table_schema
   WHERE tc.constraint_type = 'UNIQUE'
     AND tc.table_schema = $1
+  ORDER BY tc.table_name, tc.constraint_name, kcu.ordinal_position
 `;
 const SQL_INDEXES = `
   SELECT tablename, indexname, indexdef
@@ -153,14 +156,22 @@ export async function introspect(options) {
             pkByTable.get(row.table_name).push(row.column_name);
         }
         // ----- Group unique constraints by table -----
+        // Group rows by (table_name, constraint_name) to correctly handle multi-column unique constraints
         const uniqueByTable = new Map();
+        const uniqueConstraintGroups = new Map();
         for (const row of uniqueResult.rows) {
             if (!tableSet.has(row.table_name))
                 continue;
-            if (!uniqueByTable.has(row.table_name))
-                uniqueByTable.set(row.table_name, []);
-            // Each unique constraint may be multi-column; for simplicity, treat as single-col here
-            uniqueByTable.get(row.table_name).push([row.column_name]);
+            const key = `${row.table_name}::${row.constraint_name}`;
+            if (!uniqueConstraintGroups.has(key)) {
+                uniqueConstraintGroups.set(key, { table: row.table_name, columns: [] });
+            }
+            uniqueConstraintGroups.get(key).columns.push(row.column_name);
+        }
+        for (const { table, columns } of uniqueConstraintGroups.values()) {
+            if (!uniqueByTable.has(table))
+                uniqueByTable.set(table, []);
+            uniqueByTable.get(table).push(columns);
         }
         // ----- Group indexes by table -----
         const indexesByTable = new Map();
@@ -187,17 +198,25 @@ export async function introspect(options) {
                 enums[row.typname] = [];
             enums[row.typname].push(row.enumlabel);
         }
-        const foreignKeys = [];
+        const fkGroups = new Map();
         for (const row of fkResult.rows) {
             if (!tableSet.has(row.source_table) || !tableSet.has(row.target_table))
                 continue;
-            foreignKeys.push({
-                sourceTable: row.source_table,
-                sourceColumn: row.source_column,
-                targetTable: row.target_table,
-                targetColumn: row.target_column,
-            });
+            const key = row.constraint_name;
+            if (!fkGroups.has(key)) {
+                fkGroups.set(key, {
+                    sourceTable: row.source_table,
+                    sourceColumns: [],
+                    targetTable: row.target_table,
+                    targetColumns: [],
+                    constraintName: key,
+                });
+            }
+            const entry = fkGroups.get(key);
+            entry.sourceColumns.push(row.source_column);
+            entry.targetColumns.push(row.target_column);
         }
+        const foreignKeys = Array.from(fkGroups.values());
         // ----- Build relations from foreign keys -----
         // Count FKs per (source, target) pair for disambiguation
         const fkCounts = new Map();
@@ -209,10 +228,17 @@ export async function introspect(options) {
         for (const fk of foreignKeys) {
             const pairKey = `${fk.sourceTable}→${fk.targetTable}`;
             const needsDisambiguation = (fkCounts.get(pairKey) ?? 0) > 1;
+            // For single-column FKs, keep string form for backwards compatibility.
+            // For multi-column (composite) FKs, use array form.
+            const foreignKey = fk.sourceColumns.length === 1 ? fk.sourceColumns[0] : fk.sourceColumns;
+            const referenceKey = fk.targetColumns.length === 1 ? fk.targetColumns[0] : fk.targetColumns;
             // --- belongsTo on the source (child) table ---
             // e.g. posts.user_id → users.id creates posts.user (belongsTo)
+            // For composite FKs with disambiguation, use the constraint name
             const belongsToName = needsDisambiguation
-                ? snakeToCamel(fk.sourceColumn.replace(/_id$/, ''))
+                ? fk.sourceColumns.length === 1
+                    ? snakeToCamel(fk.sourceColumns[0].replace(/_id$/, ''))
+                    : snakeToCamel(fk.constraintName.replace(/^fk_/, '').replace(/_fkey$/, ''))
                 : singularize(snakeToCamel(fk.targetTable));
             if (!relationsByTable.has(fk.sourceTable))
                 relationsByTable.set(fk.sourceTable, {});
@@ -221,13 +247,15 @@ export async function introspect(options) {
                 name: belongsToName,
                 from: fk.sourceTable,
                 to: fk.targetTable,
-                foreignKey: fk.sourceColumn,
-                referenceKey: fk.targetColumn,
+                foreignKey,
+                referenceKey,
             };
             // --- hasMany on the target (parent) table ---
             // e.g. posts.user_id → users.id creates users.posts (hasMany)
             const hasManyName = needsDisambiguation
-                ? snakeToCamel(`${fk.sourceTable}_by_${fk.sourceColumn.replace(/_id$/, '')}`)
+                ? fk.sourceColumns.length === 1
+                    ? snakeToCamel(`${fk.sourceTable}_by_${fk.sourceColumns[0].replace(/_id$/, '')}`)
+                    : snakeToCamel(`${fk.sourceTable}_by_${fk.constraintName.replace(/^fk_/, '').replace(/_fkey$/, '')}`)
                 : snakeToCamel(fk.sourceTable);
             if (!relationsByTable.has(fk.targetTable))
                 relationsByTable.set(fk.targetTable, {});
@@ -236,8 +264,8 @@ export async function introspect(options) {
                 name: hasManyName,
                 from: fk.targetTable,
                 to: fk.sourceTable,
-                foreignKey: fk.sourceColumn,
-                referenceKey: fk.targetColumn,
+                foreignKey,
+                referenceKey,
             };
         }
         // ----- Assemble TableMetadata for each table -----

package/dist/pipeline-submittable.d.ts

@@ -17,7 +17,7 @@
  * to handle N queries in a single pipeline.
  */
 import type { EventEmitter } from 'node:events';
-import type { DeferredQuery } from './query.js';
+import type { DeferredQuery } from './query/index.js';
 /** The pg Connection object — an EventEmitter with wire-protocol methods */
 export interface PgConnection extends EventEmitter {
     stream: {

package/dist/pipeline.d.ts

@@ -19,7 +19,7 @@
  * Hyperdrive), mock pools in tests, and any pool that doesn't expose pg internals.
  */
 import type pg from 'pg';
-import type { DeferredQuery } from './query.js';
+import type { DeferredQuery } from './query/index.js';
 export interface PipelineOptions {
     /**
      * Whether to wrap the pipeline in a transaction (default: true).

package/dist/query/builder.d.ts

@@ -0,0 +1,498 @@
+/**
+ * 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 — 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.
+ */
+import type pg from 'pg';
+import type { SchemaMetadata } from '../schema.js';
+import type { AggregateArgs, AggregateResult, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, TypedWithClause, UpdateArgs, UpdateManyArgs, UpsertArgs, WithClause, WithResult } from './types.js';
+export interface DeferredQuery<T> {
+    /** SQL text with $1, $2 placeholders */
+    sql: string;
+    /** Bound parameter values */
+    params: unknown[];
+    /** How to transform the raw pg.QueryResult into the final value */
+    transform: (result: pg.QueryResult) => T;
+    /** Tag for debugging / logging */
+    tag: string;
+    /** Prepared statement name (t_<16hex>). Set when SQL cache is enabled. */
+    preparedName?: string;
+}
+/** Middleware function type — imported from client to avoid circular deps */
+export type MiddlewareFn = (params: {
+    model: string;
+    action: string;
+    args: Record<string, unknown>;
+}, next: (params: {
+    model: string;
+    action: string;
+    args: Record<string, unknown>;
+}) => Promise<unknown>) => Promise<unknown>;
+/** Options passed from TurbineClient to QueryInterface */
+export interface QueryInterfaceOptions {
+    /** Default LIMIT applied to findMany() when no limit is specified */
+    defaultLimit?: number;
+    /**
+     * 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;
+    /**
+     * Enable prepared statements. When true, queries are submitted with a
+     * `{ name, text, values }` object to the pg driver, which caches the
+     * parse+plan on the server per connection.
+     *
+     * Default: `true` for Turbine-owned pools, `false` for external pools
+     * (serverless drivers may not support named statements).
+     */
+    preparedStatements?: boolean;
+    /**
+     * Enable the SQL template cache. When true, repeated queries with the
+     * same shape (same keys, operators, relations — different values) reuse
+     * cached SQL text instead of rebuilding from scratch.
+     *
+     * Default: `true`. Set to `false` as a nuclear kill switch.
+     */
+    sqlCache?: boolean;
+}
+export declare class QueryInterface<T extends object, R extends object = {}> {
+    private readonly pool;
+    private readonly table;
+    private readonly schema;
+    private readonly tableMeta;
+    /** SQL template cache: cacheKey → SqlCacheEntry (sql + prepared statement name) */
+    private readonly sqlTemplateCache;
+    private readonly middlewares;
+    private readonly defaultLimit?;
+    private readonly warnOnUnlimited;
+    private readonly preparedStatementsEnabled;
+    private readonly sqlCacheEnabled;
+    /**
+     * 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;
+    /** Cache hit/miss counters for diagnostics */
+    private cacheHits;
+    private cacheMisses;
+    /** Pre-computed column type lookups (avoids linear scans per query) */
+    private readonly columnPgTypeMap;
+    private readonly columnArrayTypeMap;
+    /** Tracks tables that have already triggered a deep-with warning (one-time) */
+    private readonly deepWithWarned;
+    constructor(pool: pg.Pool, table: string, schema: SchemaMetadata, middlewares?: MiddlewareFn[], options?: QueryInterfaceOptions);
+    /**
+     * Return cache hit/miss statistics for this QueryInterface instance.
+     * Useful for monitoring and benchmarking.
+     */
+    cacheStats(): {
+        hits: number;
+        misses: number;
+        hitRate: number;
+        size: number;
+    };
+    /**
+     * Look up or build a SQL template in the cache.
+     * On miss, calls `build()` to generate the SQL, stores the entry, and returns it.
+     * On hit, increments counters and returns the cached entry.
+     *
+     * When `sqlCache` is disabled, always calls `build()` without caching.
+     */
+    private acquireSql;
+    /**
+     * 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;
+    /**
+     * Execute a query through the middleware chain.
+     * If no middlewares are registered, executes directly.
+     *
+     * Middleware can inspect and log query parameters, modify results after execution,
+     * and measure timing. Note: query SQL is generated before middleware runs, so
+     * modifying params.args in middleware will NOT affect the executed SQL.
+     * 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>[]>;
+    /**
+     * 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;
+    /**
+     * Recursively measure the maximum depth of a `with` clause tree.
+     * Used by the dev-only deep-with warning guard.
+     */
+    private measureWithDepth;
+    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.
+     *
+     * **Speculative fast-path:** Before opening a cursor, issues a single
+     * `SELECT ... LIMIT batchSize+1`. If the result fits within `batchSize`,
+     * all rows are yielded immediately with zero cursor overhead (no BEGIN /
+     * DECLARE / CLOSE / COMMIT). Only when the result overflows does the
+     * method fall back to the full cursor path.
+     *
+     * **Cursor path:** 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`).
+     *
+     * **Snapshot semantics note:** The speculative fast-path runs outside a
+     * transaction. If the result overflows and the cursor path is opened, the
+     * cursor runs in its own transaction — spanning two separate snapshots.
+     * For strict single-snapshot semantics, wrap the call in `$transaction`.
+     *
+     * @example
+     * ```ts
+     * for await (const user of db.users.findManyStream({ where: { orgId: 1 }, batchSize: 500 })) {
+     *   process.stdout.write(`${user.email}\n`);
+     * }
+     * ```
+     */
+    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[]>;
+    buildCreateMany(args: CreateManyArgs<T>): DeferredQuery<T[]>;
+    update(args: UpdateArgs<T>): Promise<T>;
+    buildUpdate(args: UpdateArgs<T>): DeferredQuery<T>;
+    delete(args: DeleteArgs<T>): Promise<T>;
+    buildDelete(args: DeleteArgs<T>): DeferredQuery<T>;
+    upsert(args: UpsertArgs<T>): Promise<T>;
+    buildUpsert(args: UpsertArgs<T>): DeferredQuery<T>;
+    updateMany(args: UpdateManyArgs<T>): Promise<{
+        count: number;
+    }>;
+    buildUpdateMany(args: UpdateManyArgs<T>): DeferredQuery<{
+        count: number;
+    }>;
+    deleteMany(args: DeleteManyArgs<T>): Promise<{
+        count: number;
+    }>;
+    buildDeleteMany(args: DeleteManyArgs<T>): DeferredQuery<{
+        count: number;
+    }>;
+    count(args?: CountArgs<T>): Promise<number>;
+    buildCount(args?: CountArgs<T>): DeferredQuery<number>;
+    groupBy(args: GroupByArgs<T>): Promise<Record<string, unknown>[]>;
+    buildGroupBy(args: GroupByArgs<T>): DeferredQuery<Record<string, unknown>[]>;
+    aggregate(args: AggregateArgs<T>): Promise<AggregateResult<T>>;
+    buildAggregate(args: AggregateArgs<T>): DeferredQuery<AggregateResult<T>>;
+    /**
+     * Resolve select/omit options into a list of snake_case column names.
+     * Returns null if neither is provided (meaning all columns).
+     */
+    private resolveColumns;
+    /** Convert camelCase field name to snake_case column name (unquoted, for non-SQL uses) */
+    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;
+    /**
+     * Produce a value-invariant fingerprint of a where clause.
+     * Same keys + same operator shapes + same combinator structure => same string.
+     * Different values (e.g. id=1 vs id=999) => identical fingerprint.
+     *
+     * @internal Exposed as package-private for testing via class access.
+     */
+    fingerprintWhere(where: Record<string, unknown>): string;
+    /**
+     * Fingerprint a relation filter sub-where for some/every/none.
+     */
+    private fingerprintRelFilter;
+    /**
+     * Walk a where clause and push ONLY values into `params`, in the EXACT same
+     * order that `buildWhereClause` pushes them. Used on cache hit to fill params
+     * without rebuilding SQL.
+     *
+     * @internal Exposed as package-private for testing.
+     */
+    collectWhereParams(where: Record<string, unknown>, params: unknown[]): void;
+    /** Collect params from a relation filter sub-where. Mirrors buildSubWhereForRelation. */
+    private collectRelFilterParams;
+    /** Collect params from operator clauses. Mirrors buildOperatorClauses. */
+    private collectOperatorParams;
+    /** Collect params from JSON filter. Mirrors buildJsonFilterClauses. */
+    private collectJsonFilterParams;
+    /** Collect params from array filter. Mirrors buildArrayFilterClauses. */
+    private collectArrayFilterParams;
+    /**
+     * Produce a fingerprint for a `with` clause tree. Recursion mirrors
+     * buildSelectWithRelations / buildRelationSubquery.
+     *
+     * @internal Exposed as package-private for testing.
+     */
+    withFingerprint(withClause: WithClause | undefined, table?: string, depth?: number): string;
+    /**
+     * Collect params from a `with` clause tree. Mirrors buildSelectWithRelations +
+     * buildRelationSubquery param-push order.
+     */
+    private collectWithParams;
+    /**
+     * Collect params from a single relation subquery. Mirrors buildRelationSubquery.
+     */
+    private collectRelationSubqueryParams;
+    /**
+     * Fingerprint SET clauses for update/updateMany.
+     * Captures key names + operator types (set/increment/etc) but not values.
+     */
+    private fingerprintSet;
+    /**
+     * Collect SET params for update/updateMany. Mirrors buildSetClause param order.
+     */
+    private collectSetParams;
+    /** 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.
+     * Supports: equality, operators, NULL, OR, AND, NOT, relation filters (some/every/none).
+     */
+    private buildWhereClause;
+    /**
+     * Build relation filter SQL: WHERE EXISTS / NOT EXISTS subquery
+     * Supports: some (EXISTS), every (NOT EXISTS ... NOT), none (NOT EXISTS)
+     */
+    private buildRelationFilter;
+    /**
+     * Build WHERE clause conditions for a relation filter subquery.
+     * Uses the target table's column mapping to resolve field names.
+     */
+    private buildSubWhereForRelation;
+    /**
+     * Build SQL clauses for a single operator object on a column.
+     * Each operator key becomes its own clause, all ANDed together.
+     */
+    private buildOperatorClauses;
+    /** Build ORDER BY clause from an object */
+    private buildOrderBy;
+    /** Parse a flat row: convert snake_case to camelCase + Date coercion */
+    private parseRow;
+    /** Parse a row that may contain JSON nested relation columns */
+    private parseNestedRow;
+    /**
+     * 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.
+     */
+    private buildSelectWithRelations;
+    /**
+     * 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.
+     *
+     * ### 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).
+     */
+    private buildRelationSubquery;
+    /**
+     * Get the Postgres type for a column (e.g. 'jsonb', 'text', '_int4').
+     * Used to detect JSONB/array columns for specialized operators.
+     * Uses pre-computed Map for O(1) lookup instead of linear scan.
+     */
+    private getColumnPgType;
+    /**
+     * Get the Postgres base element type for an array column.
+     * E.g. '_text' → 'text', '_int4' → 'integer'
+     */
+    private getArrayElementType;
+    /**
+     * Build SQL clauses for JSONB filter operators on a column.
+     * Supports: path, equals, contains, hasKey.
+     */
+    private buildJsonFilterClauses;
+    /**
+     * Build SQL clauses for Array filter operators on a column.
+     * Supports: has, hasEvery, hasSome, isEmpty.
+     */
+    private buildArrayFilterClauses;
+    /**
+     * Get the Postgres array type for a column (used by UNNEST in createMany).
+     * Uses pre-computed Map for O(1) lookup instead of linear scan.
+     */
+    private getColumnArrayType;
+}
+//# sourceMappingURL=builder.d.ts.map