turbine-orm 0.19.0 → 0.19.1

package/dist/query.js

@@ -1,2705 +0,0 @@
-/**
- * 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 { CircularRelationError, NotFoundError, RelationError, TimeoutError, ValidationError, wrapPgError, } from './errors.js';
-import { camelToSnake, snakeToCamel } from './schema.js';
-// ---------------------------------------------------------------------------
-// Identifier quoting — prevents SQL injection via table/column names
-// ---------------------------------------------------------------------------
-/**
- * Quote a SQL identifier (table name, column name) using Postgres double-quote
- * rules: wrap in double quotes, escape internal double quotes by doubling them.
- *
- * @example
- *   quoteIdent('users')       → '"users"'
- *   quoteIdent('my"table')    → '"my""table"'
- *   quoteIdent('user name')   → '"user name"'
- */
-export function quoteIdent(name) {
-    return `"${name.replace(/"/g, '""')}"`;
-}
-/**
- * Escape single quotes for use as string keys in json_build_object().
- * Doubles single quotes per SQL quoting rules.
- */
-function escSingleQuote(s) {
-    return s.replace(/'/g, "''");
-}
-/**
- * Escape LIKE pattern metacharacters: %, _, and \.
- * Must be used with `ESCAPE '\'` in the LIKE clause.
- */
-function escapeLike(value) {
-    return value.replace(/\\/g, '\\\\').replace(/%/g, '\\%').replace(/_/g, '\\_');
-}
-/** Known operator keys — used to detect operator objects vs plain values */
-const OPERATOR_KEYS = new Set([
-    'gt',
-    'gte',
-    'lt',
-    'lte',
-    'not',
-    'in',
-    'notIn',
-    'contains',
-    'startsWith',
-    'endsWith',
-    'mode',
-]);
-/** Check if a value is a where operator object (has at least one known operator key) */
-function isWhereOperator(value) {
-    if (value === null ||
-        value === undefined ||
-        typeof value !== 'object' ||
-        Array.isArray(value) ||
-        value instanceof Date) {
-        return false;
-    }
-    const keys = Object.keys(value);
-    return keys.length > 0 && keys.every((k) => OPERATOR_KEYS.has(k));
-}
-/** Known atomic-update operator keys — used to detect operator objects vs plain JSON values */
-const UPDATE_OPERATOR_KEYS = new Set(['set', 'increment', 'decrement', 'multiply', 'divide']);
-/** Known JSONB operator keys */
-const JSONB_OPERATOR_KEYS = new Set(['path', 'equals', 'contains', 'hasKey']);
-/**
- * JSONB operator keys that are *unique* to {@link JsonFilter} — they cannot
- * appear in any other where-filter shape, so the presence of one of these is
- * an unambiguous signal that the user meant a JSON filter. Used by the
- * strict-validation path so that `{ contains: 'foo' }` (which is also a valid
- * `WhereOperator` for LIKE) is not misclassified.
- */
-const JSONB_UNIQUE_KEYS = new Set(['path', 'equals', 'hasKey']);
-/** Check if a value is a JSONB filter object */
-function isJsonFilter(value) {
-    if (value === null ||
-        value === undefined ||
-        typeof value !== 'object' ||
-        Array.isArray(value) ||
-        value instanceof Date) {
-        return false;
-    }
-    const keys = Object.keys(value);
-    return keys.length > 0 && keys.some((k) => JSONB_OPERATOR_KEYS.has(k));
-}
-/**
- * Returns the first JSON-unique key found in `value`, or `null` if none.
- * Used to drive the strict-validation error message.
- */
-function findJsonUniqueKey(value) {
-    for (const k of Object.keys(value)) {
-        if (JSONB_UNIQUE_KEYS.has(k))
-            return k;
-    }
-    return null;
-}
-/** Known Array operator keys */
-const ARRAY_OPERATOR_KEYS = new Set(['has', 'hasEvery', 'hasSome', 'isEmpty']);
-/**
- * Array operator keys that are *unique* to {@link ArrayFilter}. None of the
- * array operators currently overlap with `WhereOperator` or `JsonFilter`, so
- * this set equals {@link ARRAY_OPERATOR_KEYS}; it is kept as a separate
- * constant so a future overlap (e.g. a `contains` for arrays) is easy to
- * carve out.
- */
-const ARRAY_UNIQUE_KEYS = new Set(['has', 'hasEvery', 'hasSome', 'isEmpty']);
-/** Check if a value is an Array filter object */
-function isArrayFilter(value) {
-    if (value === null ||
-        value === undefined ||
-        typeof value !== 'object' ||
-        Array.isArray(value) ||
-        value instanceof Date) {
-        return false;
-    }
-    const keys = Object.keys(value);
-    return keys.length > 0 && keys.some((k) => ARRAY_OPERATOR_KEYS.has(k));
-}
-/**
- * Returns the first array-unique key found in `value`, or `null` if none.
- * Used to drive the strict-validation error message.
- */
-function findArrayUniqueKey(value) {
-    for (const k of Object.keys(value)) {
-        if (ARRAY_UNIQUE_KEYS.has(k))
-            return k;
-    }
-    return null;
-}
-// ---------------------------------------------------------------------------
-// LRU cache — bounded SQL template cache to prevent memory leaks
-// ---------------------------------------------------------------------------
-/**
- * Simple LRU (Least Recently Used) cache with a fixed maximum size.
- * When the cache exceeds maxSize, the oldest (least recently used) entry is evicted.
- * Uses Map insertion order for O(1) eviction.
- */
-class LRUCache {
-    maxSize;
-    cache = new Map();
-    constructor(maxSize) {
-        this.maxSize = maxSize;
-    }
-    get(key) {
-        const value = this.cache.get(key);
-        if (value !== undefined) {
-            // Move to end (most recently used)
-            this.cache.delete(key);
-            this.cache.set(key, value);
-        }
-        return value;
-    }
-    set(key, value) {
-        if (this.cache.has(key)) {
-            this.cache.delete(key);
-        }
-        else if (this.cache.size >= this.maxSize) {
-            // Delete oldest (first) entry
-            const firstKey = this.cache.keys().next().value;
-            if (firstKey !== undefined)
-                this.cache.delete(firstKey);
-        }
-        this.cache.set(key, value);
-    }
-    get size() {
-        return this.cache.size;
-    }
-}
-/**
- * FNV-1a 64-bit hash returning 16 lowercase hex chars.
- * Single-loop string iteration. Uses BigInt for 64-bit math.
- *
- * @internal Exported for testing only.
- */
-export function fnv1a64Hex(s) {
-    // FNV-1a offset basis and prime for 64-bit
-    let hash = 0xcbf29ce484222325n;
-    const prime = 0x100000001b3n;
-    const mask = 0xffffffffffffffffn; // 64-bit mask
-    for (let i = 0; i < s.length; i++) {
-        hash ^= BigInt(s.charCodeAt(i));
-        hash = (hash * prime) & mask;
-    }
-    return hash.toString(16).padStart(16, '0');
-}
-/**
- * Derive a prepared-statement name from a SQL string.
- * Format: `t_<16hex>` — always 18 chars, well under NAMEDATALEN (63).
- *
- * @internal Exported for testing only.
- */
-export function sqlToPreparedName(sql) {
-    return `t_${fnv1a64Hex(sql)}`;
-}
-export class QueryInterface {
-    pool;
-    table;
-    schema;
-    tableMeta;
-    /** SQL template cache: cacheKey → SqlCacheEntry (sql + prepared statement name) */
-    sqlTemplateCache = new LRUCache(1000);
-    middlewares;
-    defaultLimit;
-    warnOnUnlimited;
-    preparedStatementsEnabled;
-    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.
-     */
-    warnedTables = new Set();
-    /** Cache hit/miss counters for diagnostics */
-    cacheHits = 0;
-    cacheMisses = 0;
-    /** Pre-computed column type lookups (avoids linear scans per query) */
-    columnPgTypeMap;
-    columnArrayTypeMap;
-    constructor(pool, table, schema, middlewares, options) {
-        this.pool = pool;
-        this.table = table;
-        this.schema = schema;
-        const meta = schema.tables[table];
-        if (!meta) {
-            throw new ValidationError(`[turbine] Unknown table "${table}". Available: ${Object.keys(schema.tables).join(', ')}`);
-        }
-        this.tableMeta = meta;
-        this.middlewares = middlewares ?? [];
-        this.defaultLimit = options?.defaultLimit;
-        // Default to ON: surfacing accidental full-table scans is more valuable
-        // than the (small) risk of noisy logs. Callers explicitly opt out with
-        // `warnOnUnlimited: false`.
-        this.warnOnUnlimited = options?.warnOnUnlimited !== false;
-        this.preparedStatementsEnabled = options?.preparedStatements ?? true;
-        this.sqlCacheEnabled = options?.sqlCache !== false;
-        // Pre-compute column type lookup maps (TASK-26)
-        this.columnPgTypeMap = new Map();
-        this.columnArrayTypeMap = new Map();
-        for (const col of this.tableMeta.columns) {
-            this.columnPgTypeMap.set(col.name, col.pgType);
-            this.columnArrayTypeMap.set(col.name, col.pgArrayType);
-        }
-    }
-    /**
-     * Return cache hit/miss statistics for this QueryInterface instance.
-     * Useful for monitoring and benchmarking.
-     */
-    cacheStats() {
-        const total = this.cacheHits + this.cacheMisses;
-        return {
-            hits: this.cacheHits,
-            misses: this.cacheMisses,
-            hitRate: total > 0 ? this.cacheHits / total : 0,
-            size: this.sqlTemplateCache.size,
-        };
-    }
-    /**
-     * 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.
-     */
-    acquireSql(cacheKey, build) {
-        if (!this.sqlCacheEnabled) {
-            const sql = build();
-            this.cacheMisses++;
-            return { sql, name: sqlToPreparedName(sql) };
-        }
-        const cached = this.sqlTemplateCache.get(cacheKey);
-        if (cached) {
-            this.cacheHits++;
-            return cached;
-        }
-        const sql = build();
-        const entry = { sql, name: sqlToPreparedName(sql) };
-        this.sqlTemplateCache.set(cacheKey, entry);
-        this.cacheMisses++;
-        return entry;
-    }
-    /**
-     * 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() {
-        this.warnedTables.clear();
-    }
-    /**
-     * 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.
-     */
-    async queryWithTimeout(sql, params, timeout, preparedName) {
-        // Build the query argument — use object form with `name` for prepared
-        // statements, or the plain (text, values) form otherwise.
-        const usePrepared = preparedName && this.preparedStatementsEnabled;
-        const exec = usePrepared
-            ? this.pool.query({ name: preparedName, text: sql, values: params })
-            : this.pool.query(sql, params);
-        if (!timeout) {
-            try {
-                return await exec;
-            }
-            catch (err) {
-                throw wrapPgError(err);
-            }
-        }
-        let timer;
-        const timeoutPromise = new Promise((_, reject) => {
-            timer = setTimeout(() => reject(new TimeoutError(timeout)), timeout);
-        });
-        try {
-            return await Promise.race([exec, timeoutPromise]);
-        }
-        catch (err) {
-            throw wrapPgError(err);
-        }
-        finally {
-            clearTimeout(timer);
-        }
-    }
-    /**
-     * 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.
-     */
-    async executeWithMiddleware(action, args, executor) {
-        if (this.middlewares.length === 0) {
-            return executor();
-        }
-        const params = { model: this.table, action, args: { ...args } };
-        // Build middleware chain
-        let index = 0;
-        const next = async (p) => {
-            if (index < this.middlewares.length) {
-                const mw = this.middlewares[index++];
-                return mw(p, next);
-            }
-            // End of chain — execute the actual query
-            return executor();
-        };
-        return next(params);
-    }
-    // -------------------------------------------------------------------------
-    // findUnique
-    // -------------------------------------------------------------------------
-    async findUnique(args) {
-        return this.executeWithMiddleware('findUnique', args, async () => {
-            const deferred = this.buildFindUnique(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
-            return deferred.transform(result);
-        });
-    }
-    buildFindUnique(args) {
-        const columnsList = this.resolveColumns(args.select, args.omit);
-        const whereObj = args.where;
-        const colKey = columnsList ? columnsList.join(',') : '*';
-        const whereFingerprint = this.fingerprintWhere(whereObj);
-        const withFp = args.with ? this.withFingerprint(args.with) : '';
-        const ck = `fu:${whereFingerprint}|c=${colKey}|w=${withFp}`;
-        const params = [];
-        // Check if all where values are simple (plain equality, no operators/null/OR)
-        const whereKeys = Object.keys(whereObj).filter((k) => whereObj[k] !== undefined);
-        const isSimpleWhere = !whereObj.OR &&
-            !whereObj.AND &&
-            !whereObj.NOT &&
-            whereKeys.every((k) => {
-                const v = whereObj[k];
-                return v !== null && !isWhereOperator(v) && !this.tableMeta.relations[k];
-            });
-        // Simple path: plain equality, no operators/null/OR
-        if (!args.with && isSimpleWhere) {
-            const entry = this.acquireSql(ck, () => {
-                const qt = quoteIdent(this.table);
-                const tempParams = whereKeys.map((k) => whereObj[k]);
-                const whereClauses = whereKeys.map((k, i) => `${this.toSqlColumn(k)} = $${i + 1}`);
-                const whereSql = whereClauses.length > 0 ? ` WHERE ${whereClauses.join(' AND ')}` : '';
-                const selectExpr = columnsList ? columnsList.map((c) => `${qt}.${quoteIdent(c)}`).join(', ') : `${qt}.*`;
-                void tempParams; // params are positional, SQL is value-invariant
-                return `SELECT ${selectExpr} FROM ${qt}${whereSql} LIMIT 1`;
-            });
-            // Collect params (same order as build)
-            for (const k of whereKeys) {
-                params.push(whereObj[k]);
-            }
-            return {
-                sql: entry.sql,
-                params,
-                transform: (result) => {
-                    const row = result.rows[0];
-                    return row ? this.parseRow(row, this.table) : null;
-                },
-                tag: `${this.table}.findUnique`,
-                preparedName: entry.name,
-            };
-        }
-        // General path (with operators, null, OR, with clause)
-        if (!args.with) {
-            const entry = this.acquireSql(ck, () => {
-                const freshParams = [];
-                const clause = this.buildWhereClause(whereObj, freshParams);
-                const whereSql = clause ? ` WHERE ${clause}` : '';
-                const qt = quoteIdent(this.table);
-                const selectExpr = columnsList ? columnsList.map((c) => `${qt}.${quoteIdent(c)}`).join(', ') : `${qt}.*`;
-                return `SELECT ${selectExpr} FROM ${qt}${whereSql} LIMIT 1`;
-            });
-            // Collect params
-            this.collectWhereParams(whereObj, params);
-            return {
-                sql: entry.sql,
-                params,
-                transform: (result) => {
-                    const row = result.rows[0];
-                    return row ? this.parseRow(row, this.table) : null;
-                },
-                tag: `${this.table}.findUnique`,
-                preparedName: entry.name,
-            };
-        }
-        // Nested queries with `with` clause.
-        // The param order in the original code is:
-        //   1. buildWhere pushes where params
-        //   2. buildSelectWithRelations pushes relation params to same array
-        // We must preserve this exact order.
-        const entry = this.acquireSql(ck, () => {
-            const freshParams = [];
-            const clause = this.buildWhereClause(whereObj, freshParams);
-            const whereSql = clause ? ` WHERE ${clause}` : '';
-            const selectClause = this.buildSelectWithRelations(this.table, args.with, freshParams, columnsList);
-            return `SELECT ${selectClause} FROM ${quoteIdent(this.table)}${whereSql} LIMIT 1`;
-        });
-        // Collect params in exact build order: where first, then with-clause relations
-        this.collectWhereParams(whereObj, params);
-        this.collectWithParams(args.with, params);
-        return {
-            sql: entry.sql,
-            params,
-            transform: (result) => {
-                const row = result.rows[0];
-                return row ? this.parseNestedRow(row, this.table) : null;
-            },
-            tag: `${this.table}.findUnique`,
-            preparedName: entry.name,
-        };
-    }
-    // -------------------------------------------------------------------------
-    // findMany
-    // -------------------------------------------------------------------------
-    async findMany(args) {
-        this.maybeWarnUnlimited(args);
-        return this.executeWithMiddleware('findMany', (args ?? {}), async () => {
-            const deferred = this.buildFindMany(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout, deferred.preparedName);
-            return deferred.transform(result);
-        });
-    }
-    /**
-     * 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`.
-     */
-    maybeWarnUnlimited(args) {
-        if (!this.warnOnUnlimited)
-            return;
-        if (this.defaultLimit !== undefined)
-            return;
-        const hasExplicitLimit = args?.limit !== undefined || args?.take !== undefined || args?.cursor !== undefined;
-        if (hasExplicitLimit)
-            return;
-        if (this.warnedTables.has(this.table))
-            return;
-        this.warnedTables.add(this.table);
-        console.warn(`[turbine] warning: findMany on "${this.table}" has no limit — this will fetch every row. ` +
-            'Pass `limit` or set `warnOnUnlimited: false` in config to silence.');
-    }
-    buildFindMany(args) {
-        const columnsList = this.resolveColumns(args?.select, args?.omit);
-        const colKey = columnsList ? columnsList.join(',') : '*';
-        const whereObj = (args?.where ?? {});
-        // Build fingerprint for cache lookup
-        const whereFp = args?.where ? this.fingerprintWhere(whereObj) : '';
-        const withFp = args?.with ? this.withFingerprint(args.with) : '';
-        const orderFp = args?.orderBy
-            ? Object.entries(args.orderBy)
-                .map(([k, d]) => `${k}:${d}`)
-                .join(',')
-            : '';
-        const cursorFp = args?.cursor
-            ? Object.keys(args.cursor)
-                .filter((k) => args.cursor[k] !== undefined)
-                .sort()
-                .join(',')
-            : '';
-        const distinctFp = args?.distinct ? args.distinct.slice().sort().join(',') : '';
-        const effectiveLimit = args?.take ?? args?.limit ?? this.defaultLimit;
-        const limitFp = effectiveLimit !== undefined ? '1' : '0';
-        const offsetFp = args?.offset !== undefined ? '1' : '0';
-        const ck = `fm:${whereFp}|c=${colKey}|o=${orderFp}|l=${limitFp}|off=${offsetFp}|cur=${cursorFp}|d=${distinctFp}|w=${withFp}`;
-        const params = [];
-        const entry = this.acquireSql(ck, () => {
-            // Fresh build — generates SQL and populates freshParams
-            const freshParams = [];
-            const { sql: freshWhereSql } = args?.where
-                ? (() => {
-                    const clause = this.buildWhereClause(whereObj, freshParams);
-                    return { sql: clause ? ` WHERE ${clause}` : '' };
-                })()
-                : { sql: '' };
-            const qt = quoteIdent(this.table);
-            let distinctPrefix = '';
-            if (args?.distinct && args.distinct.length > 0) {
-                const distinctCols = args.distinct.map((k) => this.toSqlColumn(k));
-                distinctPrefix = `DISTINCT ON (${distinctCols.join(', ')}) `;
-            }
-            let selectClause;
-            if (args?.with) {
-                selectClause = this.buildSelectWithRelations(this.table, args.with, freshParams, columnsList);
-            }
-            else if (columnsList) {
-                selectClause = columnsList.map((c) => `${qt}.${quoteIdent(c)}`).join(', ');
-            }
-            else {
-                selectClause = `${qt}.*`;
-            }
-            let sql = `SELECT ${distinctPrefix}${selectClause} FROM ${qt}${freshWhereSql}`;
-            if (args?.cursor) {
-                const cursorEntries = Object.entries(args.cursor).filter(([, v]) => v !== undefined);
-                if (cursorEntries.length > 0) {
-                    const cursorConditions = cursorEntries.map(([k, v]) => {
-                        const col = this.toSqlColumn(k);
-                        const dir = args.orderBy?.[k] ?? 'asc';
-                        const op = dir === 'desc' ? '<' : '>';
-                        freshParams.push(v);
-                        return `${qt}.${col} ${op} $${freshParams.length}`;
-                    });
-                    if (freshWhereSql) {
-                        sql += ` AND ${cursorConditions.join(' AND ')}`;
-                    }
-                    else {
-                        sql += ` WHERE ${cursorConditions.join(' AND ')}`;
-                    }
-                }
-            }
-            if (args?.orderBy) {
-                sql += ` ORDER BY ${this.buildOrderBy(args.orderBy)}`;
-            }
-            if (effectiveLimit !== undefined) {
-                freshParams.push(Number(effectiveLimit));
-                sql += ` LIMIT $${freshParams.length}`;
-            }
-            if (args?.offset !== undefined) {
-                freshParams.push(Number(args.offset));
-                sql += ` OFFSET $${freshParams.length}`;
-            }
-            return sql;
-        });
-        // Collect params in exact build order:
-        // 1. WHERE params
-        if (args?.where) {
-            this.collectWhereParams(whereObj, params);
-        }
-        // 2. WITH relation params
-        if (args?.with) {
-            this.collectWithParams(args.with, params);
-        }
-        // 3. Cursor params
-        if (args?.cursor) {
-            const cursorEntries = Object.entries(args.cursor).filter(([, v]) => v !== undefined);
-            for (const [, v] of cursorEntries) {
-                params.push(v);
-            }
-        }
-        // 4. LIMIT param
-        if (effectiveLimit !== undefined) {
-            params.push(Number(effectiveLimit));
-        }
-        // 5. OFFSET param
-        if (args?.offset !== undefined) {
-            params.push(Number(args.offset));
-        }
-        return {
-            sql: entry.sql,
-            params,
-            transform: (result) => result.rows.map((row) => args?.with ? this.parseNestedRow(row, this.table) : this.parseRow(row, this.table)),
-            tag: `${this.table}.findMany`,
-            preparedName: entry.name,
-        };
-    }
-    // -------------------------------------------------------------------------
-    // findManyStream — async iterable using PostgreSQL cursors
-    // -------------------------------------------------------------------------
-    /**
-     * 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`);
-     * }
-     * ```
-     */
-    async *findManyStream(args) {
-        const batchSize = Math.max(1, Math.floor(Number(args?.batchSize ?? 1000)));
-        const hasRelations = !!args?.with;
-        // --- Speculative first fetch: try to satisfy the entire drain in one RTT ---
-        const speculativeDeferred = this.buildFindMany({
-            ...args,
-            limit: batchSize + 1,
-        });
-        const speculativeResult = await this.queryWithTimeout(speculativeDeferred.sql, speculativeDeferred.params, args?.timeout);
-        if (speculativeResult.rows.length <= batchSize) {
-            // Small drain — yield all rows and return, no cursor needed
-            for (const row of speculativeResult.rows) {
-                yield (hasRelations ? this.parseNestedRow(row, this.table) : this.parseRow(row, this.table));
-            }
-            return;
-        }
-        // --- Overflow: fall back to cursor path from scratch ---
-        const deferred = this.buildFindMany(args);
-        // Acquire a dedicated connection — cursors require a single connection in a transaction
-        const client = await this.pool.connect();
-        const cursorName = `turbine_cursor_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
-        const quotedCursor = quoteIdent(cursorName);
-        try {
-            await client.query('BEGIN');
-            await client.query(`DECLARE ${quotedCursor} NO SCROLL CURSOR FOR ${deferred.sql}`, deferred.params);
-            while (true) {
-                const batch = await client.query(`FETCH ${batchSize} FROM ${quotedCursor}`);
-                if (batch.rows.length === 0)
-                    break;
-                for (const row of batch.rows) {
-                    yield (hasRelations ? this.parseNestedRow(row, this.table) : this.parseRow(row, this.table));
-                }
-                if (batch.rows.length < batchSize)
-                    break;
-            }
-            await client.query(`CLOSE ${quotedCursor}`);
-            await client.query('COMMIT');
-        }
-        catch (err) {
-            // Rollback on error (also closes cursor implicitly)
-            try {
-                await client.query('ROLLBACK');
-            }
-            catch {
-                // Connection may already be broken — ignore rollback error
-            }
-            // Wrap pg constraint errors so streaming surfaces typed errors like the rest of the API
-            throw wrapPgError(err);
-        }
-        finally {
-            client.release();
-        }
-    }
-    // -------------------------------------------------------------------------
-    // findFirst — like findMany but returns a single row or null
-    // -------------------------------------------------------------------------
-    async findFirst(args) {
-        return this.executeWithMiddleware('findFirst', (args ?? {}), async () => {
-            const deferred = this.buildFindFirst(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout, deferred.preparedName);
-            return deferred.transform(result);
-        });
-    }
-    buildFindFirst(args) {
-        // Reuse findMany's SQL builder but force LIMIT 1
-        const findManyArgs = { ...args, limit: 1 };
-        const deferred = this.buildFindMany(findManyArgs);
-        return {
-            sql: deferred.sql,
-            params: deferred.params,
-            transform: (result) => {
-                const rows = deferred.transform(result);
-                return rows.length > 0 ? rows[0] : null;
-            },
-            tag: `${this.table}.findFirst`,
-        };
-    }
-    // -------------------------------------------------------------------------
-    // findFirstOrThrow — like findFirst but throws if no record found
-    // -------------------------------------------------------------------------
-    async findFirstOrThrow(args) {
-        return this.executeWithMiddleware('findFirstOrThrow', (args ?? {}), async () => {
-            const deferred = this.buildFindFirstOrThrow(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout, deferred.preparedName);
-            return deferred.transform(result);
-        });
-    }
-    buildFindFirstOrThrow(args) {
-        const inner = this.buildFindFirst(args);
-        return {
-            sql: inner.sql,
-            params: inner.params,
-            transform: (result) => {
-                const row = inner.transform(result);
-                if (row === null) {
-                    throw new NotFoundError({
-                        table: this.table,
-                        where: args?.where,
-                        operation: 'findFirstOrThrow',
-                    });
-                }
-                return row;
-            },
-            tag: `${this.table}.findFirstOrThrow`,
-        };
-    }
-    // -------------------------------------------------------------------------
-    // findUniqueOrThrow — like findUnique but throws if no record found
-    // -------------------------------------------------------------------------
-    async findUniqueOrThrow(args) {
-        return this.executeWithMiddleware('findUniqueOrThrow', args, async () => {
-            const deferred = this.buildFindUniqueOrThrow(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
-            return deferred.transform(result);
-        });
-    }
-    buildFindUniqueOrThrow(args) {
-        const inner = this.buildFindUnique(args);
-        return {
-            sql: inner.sql,
-            params: inner.params,
-            transform: (result) => {
-                const row = inner.transform(result);
-                if (row === null) {
-                    throw new NotFoundError({
-                        table: this.table,
-                        where: args.where,
-                        operation: 'findUniqueOrThrow',
-                    });
-                }
-                return row;
-            },
-            tag: `${this.table}.findUniqueOrThrow`,
-        };
-    }
-    // -------------------------------------------------------------------------
-    // create
-    // -------------------------------------------------------------------------
-    async create(args) {
-        return this.executeWithMiddleware('create', args, async () => {
-            const deferred = this.buildCreate(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
-            return deferred.transform(result);
-        });
-    }
-    buildCreate(args) {
-        const entries = Object.entries(args.data).filter(([, v]) => v !== undefined);
-        const columns = entries.map(([k]) => this.toSqlColumn(k));
-        const params = entries.map(([, v]) => v);
-        const placeholders = entries.map((_, i) => `$${i + 1}`);
-        const sql = `INSERT INTO ${quoteIdent(this.table)} (${columns.join(', ')}) VALUES (${placeholders.join(', ')}) RETURNING *`;
-        return {
-            sql,
-            params,
-            transform: (result) => {
-                const row = result.rows[0];
-                if (!row) {
-                    throw new NotFoundError({
-                        table: this.table,
-                        operation: 'create',
-                        message: `[turbine] create on "${this.table}" returned no row from RETURNING * — this should never happen.`,
-                    });
-                }
-                return this.parseRow(row, this.table);
-            },
-            tag: `${this.table}.create`,
-        };
-    }
-    // -------------------------------------------------------------------------
-    // createMany — uses UNNEST for performance
-    // -------------------------------------------------------------------------
-    async createMany(args) {
-        return this.executeWithMiddleware('createMany', args, async () => {
-            const deferred = this.buildCreateMany(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
-            return deferred.transform(result);
-        });
-    }
-    buildCreateMany(args) {
-        const qt = quoteIdent(this.table);
-        if (args.data.length === 0) {
-            return {
-                sql: `SELECT * FROM ${qt} WHERE false`,
-                params: [],
-                transform: () => [],
-                tag: `${this.table}.createMany`,
-            };
-        }
-        const keys = Object.keys(args.data[0]).filter((k) => args.data[0][k] !== undefined);
-        const columns = keys.map((k) => this.toColumn(k));
-        // Build column arrays for UNNEST
-        const columnArrays = keys.map(() => []);
-        for (const row of args.data) {
-            const record = row;
-            keys.forEach((key, i) => {
-                columnArrays[i].push(record[key]);
-            });
-        }
-        // Use actual Postgres types for array casts
-        const typeCasts = columns.map((col) => this.getColumnArrayType(col));
-        const unnestArgs = columnArrays.map((_, i) => `$${i + 1}::${typeCasts[i]}`);
-        const quotedColumns = columns.map((c) => quoteIdent(c));
-        let sql = `INSERT INTO ${qt} (${quotedColumns.join(', ')}) SELECT * FROM UNNEST(${unnestArgs.join(', ')})`;
-        // skipDuplicates: add ON CONFLICT DO NOTHING
-        if (args.skipDuplicates) {
-            sql += ` ON CONFLICT DO NOTHING`;
-        }
-        sql += ` RETURNING *`;
-        return {
-            sql,
-            params: columnArrays,
-            transform: (result) => result.rows.map((row) => this.parseRow(row, this.table)),
-            tag: `${this.table}.createMany`,
-        };
-    }
-    // -------------------------------------------------------------------------
-    // update
-    // -------------------------------------------------------------------------
-    async update(args) {
-        return this.executeWithMiddleware('update', args, async () => {
-            const deferred = this.buildUpdate(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
-            return deferred.transform(result);
-        });
-    }
-    buildUpdate(args) {
-        const dataObj = args.data;
-        const whereObj = args.where;
-        const setFp = this.fingerprintSet(dataObj);
-        const whereFp = this.fingerprintWhere(whereObj);
-        const ck = `u:${setFp}|${whereFp}`;
-        const params = [];
-        const entry = this.acquireSql(ck, () => {
-            const freshParams = [];
-            const setEntries = Object.entries(dataObj).filter(([, v]) => v !== undefined);
-            const setClauses = setEntries.map(([k, v]) => this.buildSetClause(k, v, freshParams));
-            const whereClause = this.buildWhereClause(whereObj, freshParams);
-            const whereSql = whereClause ? ` WHERE ${whereClause}` : '';
-            this.assertMutationHasPredicate('update', whereSql, args.allowFullTableScan);
-            return `UPDATE ${quoteIdent(this.table)} SET ${setClauses.join(', ')}${whereSql} RETURNING *`;
-        });
-        // On cache hit, validate predicate
-        if (whereFp === '') {
-            this.assertMutationHasPredicate('update', '', args.allowFullTableScan);
-        }
-        // Collect params: SET first, then WHERE (same order as fresh build)
-        this.collectSetParams(dataObj, params);
-        this.collectWhereParams(whereObj, params);
-        return {
-            sql: entry.sql,
-            params,
-            transform: (result) => {
-                const row = result.rows[0];
-                if (!row) {
-                    throw new NotFoundError({
-                        table: this.table,
-                        where: args.where,
-                        operation: 'update',
-                    });
-                }
-                return this.parseRow(row, this.table);
-            },
-            tag: `${this.table}.update`,
-            preparedName: entry.name,
-        };
-    }
-    // -------------------------------------------------------------------------
-    // delete
-    // -------------------------------------------------------------------------
-    async delete(args) {
-        return this.executeWithMiddleware('delete', args, async () => {
-            const deferred = this.buildDelete(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
-            return deferred.transform(result);
-        });
-    }
-    buildDelete(args) {
-        const whereObj = args.where;
-        const whereFp = this.fingerprintWhere(whereObj);
-        const ck = `d:${whereFp}`;
-        const params = [];
-        // We need to check the mutation predicate. Build the whereSql to test it.
-        // On cache hit we still need to validate (the shape may be empty).
-        const entry = this.acquireSql(ck, () => {
-            const freshParams = [];
-            const clause = this.buildWhereClause(whereObj, freshParams);
-            const whereSql = clause ? ` WHERE ${clause}` : '';
-            this.assertMutationHasPredicate('delete', whereSql, args.allowFullTableScan);
-            return `DELETE FROM ${quoteIdent(this.table)}${whereSql} RETURNING *`;
-        });
-        // On cache hit, still validate the predicate
-        if (whereFp === '') {
-            this.assertMutationHasPredicate('delete', '', args.allowFullTableScan);
-        }
-        this.collectWhereParams(whereObj, params);
-        return {
-            sql: entry.sql,
-            params,
-            transform: (result) => {
-                const row = result.rows[0];
-                if (!row) {
-                    throw new NotFoundError({
-                        table: this.table,
-                        where: args.where,
-                        operation: 'delete',
-                    });
-                }
-                return this.parseRow(row, this.table);
-            },
-            tag: `${this.table}.delete`,
-            preparedName: entry.name,
-        };
-    }
-    // -------------------------------------------------------------------------
-    // upsert — INSERT ... ON CONFLICT ... DO UPDATE
-    // -------------------------------------------------------------------------
-    async upsert(args) {
-        return this.executeWithMiddleware('upsert', args, async () => {
-            const deferred = this.buildUpsert(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
-            return deferred.transform(result);
-        });
-    }
-    buildUpsert(args) {
-        // Build the INSERT part from create data
-        const createEntries = Object.entries(args.create).filter(([, v]) => v !== undefined);
-        const columns = createEntries.map(([k]) => this.toSqlColumn(k));
-        const createParams = createEntries.map(([, v]) => v);
-        const placeholders = createEntries.map((_, i) => `$${i + 1}`);
-        // The conflict target comes from `where` keys — must be unique/PK columns
-        const conflictKeys = Object.keys(args.where).filter((k) => args.where[k] !== undefined);
-        const conflictColumns = conflictKeys.map((k) => this.toSqlColumn(k));
-        // Build the UPDATE SET part
-        const updateEntries = Object.entries(args.update).filter(([, v]) => v !== undefined);
-        let paramIdx = createParams.length + 1;
-        const setClauses = updateEntries.map(([k]) => {
-            const clause = `${this.toSqlColumn(k)} = $${paramIdx}`;
-            paramIdx++;
-            return clause;
-        });
-        const updateParams = updateEntries.map(([, v]) => v);
-        const params = [...createParams, ...updateParams];
-        const sql = `INSERT INTO ${quoteIdent(this.table)} (${columns.join(', ')}) VALUES (${placeholders.join(', ')})` +
-            ` ON CONFLICT (${conflictColumns.join(', ')}) DO UPDATE SET ${setClauses.join(', ')}` +
-            ` RETURNING *`;
-        return {
-            sql,
-            params,
-            transform: (result) => {
-                const row = result.rows[0];
-                if (!row) {
-                    throw new NotFoundError({
-                        table: this.table,
-                        where: args.where,
-                        operation: 'upsert',
-                        message: `[turbine] upsert on "${this.table}" returned no row from RETURNING * — this should never happen.`,
-                    });
-                }
-                return this.parseRow(row, this.table);
-            },
-            tag: `${this.table}.upsert`,
-        };
-    }
-    // -------------------------------------------------------------------------
-    // updateMany — UPDATE ... WHERE ... returning count
-    // -------------------------------------------------------------------------
-    async updateMany(args) {
-        return this.executeWithMiddleware('updateMany', args, async () => {
-            const deferred = this.buildUpdateMany(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
-            return deferred.transform(result);
-        });
-    }
-    buildUpdateMany(args) {
-        const dataObj = args.data;
-        const whereObj = args.where;
-        const setFp = this.fingerprintSet(dataObj);
-        const whereFp = this.fingerprintWhere(whereObj);
-        const ck = `um:${setFp}|${whereFp}`;
-        const params = [];
-        const entry = this.acquireSql(ck, () => {
-            const freshParams = [];
-            const setEntries = Object.entries(dataObj).filter(([, v]) => v !== undefined);
-            const setClauses = setEntries.map(([k, v]) => this.buildSetClause(k, v, freshParams));
-            const whereClause = this.buildWhereClause(whereObj, freshParams);
-            const whereSql = whereClause ? ` WHERE ${whereClause}` : '';
-            this.assertMutationHasPredicate('updateMany', whereSql, args.allowFullTableScan);
-            return `UPDATE ${quoteIdent(this.table)} SET ${setClauses.join(', ')}${whereSql}`;
-        });
-        if (whereFp === '') {
-            this.assertMutationHasPredicate('updateMany', '', args.allowFullTableScan);
-        }
-        this.collectSetParams(dataObj, params);
-        this.collectWhereParams(whereObj, params);
-        return {
-            sql: entry.sql,
-            params,
-            transform: (result) => ({ count: result.rowCount ?? 0 }),
-            tag: `${this.table}.updateMany`,
-            preparedName: entry.name,
-        };
-    }
-    // -------------------------------------------------------------------------
-    // deleteMany — DELETE ... WHERE ... returning count
-    // -------------------------------------------------------------------------
-    async deleteMany(args) {
-        return this.executeWithMiddleware('deleteMany', args, async () => {
-            const deferred = this.buildDeleteMany(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
-            return deferred.transform(result);
-        });
-    }
-    buildDeleteMany(args) {
-        const whereObj = args.where;
-        const whereFp = this.fingerprintWhere(whereObj);
-        const ck = `dm:${whereFp}`;
-        const params = [];
-        const entry = this.acquireSql(ck, () => {
-            const freshParams = [];
-            const clause = this.buildWhereClause(whereObj, freshParams);
-            const whereSql = clause ? ` WHERE ${clause}` : '';
-            this.assertMutationHasPredicate('deleteMany', whereSql, args.allowFullTableScan);
-            return `DELETE FROM ${quoteIdent(this.table)}${whereSql}`;
-        });
-        if (whereFp === '') {
-            this.assertMutationHasPredicate('deleteMany', '', args.allowFullTableScan);
-        }
-        this.collectWhereParams(whereObj, params);
-        return {
-            sql: entry.sql,
-            params,
-            transform: (result) => ({ count: result.rowCount ?? 0 }),
-            tag: `${this.table}.deleteMany`,
-            preparedName: entry.name,
-        };
-    }
-    // -------------------------------------------------------------------------
-    // count
-    // -------------------------------------------------------------------------
-    async count(args) {
-        return this.executeWithMiddleware('count', (args ?? {}), async () => {
-            const deferred = this.buildCount(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args?.timeout, deferred.preparedName);
-            return deferred.transform(result);
-        });
-    }
-    buildCount(args) {
-        const whereObj = (args?.where ?? {});
-        const whereFp = args?.where ? this.fingerprintWhere(whereObj) : '';
-        const ck = `cnt:${whereFp}`;
-        const params = [];
-        const entry = this.acquireSql(ck, () => {
-            const freshParams = [];
-            const clause = args?.where ? this.buildWhereClause(whereObj, freshParams) : null;
-            const whereSql = clause ? ` WHERE ${clause}` : '';
-            return `SELECT COUNT(*)::int AS count FROM ${quoteIdent(this.table)}${whereSql}`;
-        });
-        if (args?.where) {
-            this.collectWhereParams(whereObj, params);
-        }
-        return {
-            sql: entry.sql,
-            params,
-            transform: (result) => result.rows[0].count,
-            tag: `${this.table}.count`,
-            preparedName: entry.name,
-        };
-    }
-    // -------------------------------------------------------------------------
-    // groupBy (with aggregate functions)
-    // -------------------------------------------------------------------------
-    async groupBy(args) {
-        return this.executeWithMiddleware('groupBy', args, async () => {
-            const deferred = this.buildGroupBy(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
-            return deferred.transform(result);
-        });
-    }
-    buildGroupBy(args) {
-        const meta = this.schema.tables[this.table];
-        if (meta) {
-            for (const key of args.by) {
-                if (!(key in meta.columnMap)) {
-                    throw new ValidationError(`Unknown column "${key}" in groupBy for table "${this.table}"`);
-                }
-            }
-        }
-        const groupColsRaw = args.by.map((k) => this.toColumn(k));
-        const groupCols = groupColsRaw.map((c) => quoteIdent(c));
-        const { sql: whereSql, params } = args.where ? this.buildWhere(args.where) : { sql: '', params: [] };
-        // Build SELECT expressions: group-by columns + aggregate functions
-        const selectExprs = [...groupCols];
-        // _count
-        if (args._count === true || args._count === undefined) {
-            // default: always include count
-            selectExprs.push('COUNT(*)::int AS _count');
-        }
-        // _sum
-        if (args._sum) {
-            for (const [field, enabled] of Object.entries(args._sum)) {
-                if (enabled) {
-                    const col = this.toColumn(field);
-                    selectExprs.push(`SUM(${quoteIdent(col)}) AS ${quoteIdent(`_sum_${col}`)}`);
-                }
-            }
-        }
-        // _avg
-        if (args._avg) {
-            for (const [field, enabled] of Object.entries(args._avg)) {
-                if (enabled) {
-                    const col = this.toColumn(field);
-                    selectExprs.push(`AVG(${quoteIdent(col)})::float AS ${quoteIdent(`_avg_${col}`)}`);
-                }
-            }
-        }
-        // _min
-        if (args._min) {
-            for (const [field, enabled] of Object.entries(args._min)) {
-                if (enabled) {
-                    const col = this.toColumn(field);
-                    selectExprs.push(`MIN(${quoteIdent(col)}) AS ${quoteIdent(`_min_${col}`)}`);
-                }
-            }
-        }
-        // _max
-        if (args._max) {
-            for (const [field, enabled] of Object.entries(args._max)) {
-                if (enabled) {
-                    const col = this.toColumn(field);
-                    selectExprs.push(`MAX(${quoteIdent(col)}) AS ${quoteIdent(`_max_${col}`)}`);
-                }
-            }
-        }
-        let sql = `SELECT ${selectExprs.join(', ')} FROM ${quoteIdent(this.table)}${whereSql} GROUP BY ${groupCols.join(', ')}`;
-        // ORDER BY
-        if (args.orderBy) {
-            sql += ` ORDER BY ${this.buildOrderBy(args.orderBy)}`;
-        }
-        return {
-            sql,
-            params,
-            transform: (result) => result.rows.map((row) => {
-                const parsed = this.parseRow(row, this.table);
-                // Restructure aggregate results into nested objects (Prisma-style)
-                const restructured = {};
-                // Copy group-by fields
-                for (const field of args.by) {
-                    restructured[field] = parsed[field];
-                }
-                // _count
-                if ('_count' in row) {
-                    restructured._count = row._count;
-                }
-                else if ('count' in row) {
-                    restructured._count = row.count;
-                }
-                // Collect aggregates into nested objects
-                const sumObj = {};
-                const avgObj = {};
-                const minObj = {};
-                const maxObj = {};
-                let hasSums = false, hasAvgs = false, hasMins = false, hasMaxs = false;
-                for (const [rawKey, rawValue] of Object.entries(row)) {
-                    if (rawKey.startsWith('_sum_')) {
-                        const col = rawKey.slice(5);
-                        const field = this.tableMeta.reverseColumnMap[col] ?? snakeToCamel(col);
-                        sumObj[field] = rawValue !== null ? Number(rawValue) : null;
-                        hasSums = true;
-                    }
-                    else if (rawKey.startsWith('_avg_')) {
-                        const col = rawKey.slice(5);
-                        const field = this.tableMeta.reverseColumnMap[col] ?? snakeToCamel(col);
-                        avgObj[field] = rawValue !== null ? Number(rawValue) : null;
-                        hasAvgs = true;
-                    }
-                    else if (rawKey.startsWith('_min_')) {
-                        const col = rawKey.slice(5);
-                        const field = this.tableMeta.reverseColumnMap[col] ?? snakeToCamel(col);
-                        minObj[field] = rawValue;
-                        hasMins = true;
-                    }
-                    else if (rawKey.startsWith('_max_')) {
-                        const col = rawKey.slice(5);
-                        const field = this.tableMeta.reverseColumnMap[col] ?? snakeToCamel(col);
-                        maxObj[field] = rawValue;
-                        hasMaxs = true;
-                    }
-                }
-                if (hasSums)
-                    restructured._sum = sumObj;
-                if (hasAvgs)
-                    restructured._avg = avgObj;
-                if (hasMins)
-                    restructured._min = minObj;
-                if (hasMaxs)
-                    restructured._max = maxObj;
-                return restructured;
-            }),
-            tag: `${this.table}.groupBy`,
-        };
-    }
-    // -------------------------------------------------------------------------
-    // aggregate — standalone aggregation without groupBy
-    // -------------------------------------------------------------------------
-    async aggregate(args) {
-        return this.executeWithMiddleware('aggregate', args, async () => {
-            const deferred = this.buildAggregate(args);
-            const result = await this.queryWithTimeout(deferred.sql, deferred.params, args.timeout, deferred.preparedName);
-            return deferred.transform(result);
-        });
-    }
-    buildAggregate(args) {
-        const { sql: whereSql, params } = args.where ? this.buildWhere(args.where) : { sql: '', params: [] };
-        const meta = this.schema.tables[this.table];
-        if (meta) {
-            for (const group of [args._sum, args._avg, args._min, args._max]) {
-                if (group && typeof group === 'object') {
-                    for (const key of Object.keys(group)) {
-                        if (!(key in meta.columnMap)) {
-                            throw new ValidationError(`Unknown column "${key}" in aggregate for table "${this.table}"`);
-                        }
-                    }
-                }
-            }
-            if (args._count && typeof args._count === 'object') {
-                for (const key of Object.keys(args._count)) {
-                    if (!(key in meta.columnMap)) {
-                        throw new ValidationError(`Unknown column "${key}" in aggregate for table "${this.table}"`);
-                    }
-                }
-            }
-        }
-        const selectExprs = [];
-        // _count
-        if (args._count === true) {
-            selectExprs.push('COUNT(*)::int AS _count');
-        }
-        else if (args._count && typeof args._count === 'object') {
-            for (const [field, enabled] of Object.entries(args._count)) {
-                if (enabled) {
-                    const col = this.toColumn(field);
-                    selectExprs.push(`COUNT(${quoteIdent(col)})::int AS ${quoteIdent(`_count_${col}`)}`);
-                }
-            }
-        }
-        // _sum
-        if (args._sum) {
-            for (const [field, enabled] of Object.entries(args._sum)) {
-                if (enabled) {
-                    const col = this.toColumn(field);
-                    selectExprs.push(`SUM(${quoteIdent(col)}) AS ${quoteIdent(`_sum_${col}`)}`);
-                }
-            }
-        }
-        // _avg
-        if (args._avg) {
-            for (const [field, enabled] of Object.entries(args._avg)) {
-                if (enabled) {
-                    const col = this.toColumn(field);
-                    selectExprs.push(`AVG(${quoteIdent(col)})::float AS ${quoteIdent(`_avg_${col}`)}`);
-                }
-            }
-        }
-        // _min
-        if (args._min) {
-            for (const [field, enabled] of Object.entries(args._min)) {
-                if (enabled) {
-                    const col = this.toColumn(field);
-                    selectExprs.push(`MIN(${quoteIdent(col)}) AS ${quoteIdent(`_min_${col}`)}`);
-                }
-            }
-        }
-        // _max
-        if (args._max) {
-            for (const [field, enabled] of Object.entries(args._max)) {
-                if (enabled) {
-                    const col = this.toColumn(field);
-                    selectExprs.push(`MAX(${quoteIdent(col)}) AS ${quoteIdent(`_max_${col}`)}`);
-                }
-            }
-        }
-        if (selectExprs.length === 0) {
-            selectExprs.push('COUNT(*)::int AS _count');
-        }
-        const sql = `SELECT ${selectExprs.join(', ')} FROM ${quoteIdent(this.table)}${whereSql}`;
-        return {
-            sql,
-            params,
-            transform: (result) => {
-                const row = result.rows[0];
-                const aggResult = {};
-                // _count
-                if (row._count !== undefined) {
-                    aggResult._count = row._count;
-                }
-                else {
-                    // Check for per-column counts
-                    const countObj = {};
-                    let hasCountFields = false;
-                    for (const [key, val] of Object.entries(row)) {
-                        if (key.startsWith('_count_')) {
-                            const col = key.slice(7);
-                            const field = this.tableMeta.reverseColumnMap[col] ?? snakeToCamel(col);
-                            countObj[field] = val;
-                            hasCountFields = true;
-                        }
-                    }
-                    if (hasCountFields)
-                        aggResult._count = countObj;
-                }
-                // Build nested aggregate objects
-                const sumObj = {};
-                const avgObj = {};
-                const minObj = {};
-                const maxObj = {};
-                let hasSums = false, hasAvgs = false, hasMins = false, hasMaxs = false;
-                for (const [key, val] of Object.entries(row)) {
-                    if (key.startsWith('_sum_')) {
-                        const col = key.slice(5);
-                        const field = this.tableMeta.reverseColumnMap[col] ?? snakeToCamel(col);
-                        sumObj[field] = val !== null ? Number(val) : null;
-                        hasSums = true;
-                    }
-                    else if (key.startsWith('_avg_')) {
-                        const col = key.slice(5);
-                        const field = this.tableMeta.reverseColumnMap[col] ?? snakeToCamel(col);
-                        avgObj[field] = val !== null ? Number(val) : null;
-                        hasAvgs = true;
-                    }
-                    else if (key.startsWith('_min_')) {
-                        const col = key.slice(5);
-                        const field = this.tableMeta.reverseColumnMap[col] ?? snakeToCamel(col);
-                        minObj[field] = val;
-                        hasMins = true;
-                    }
-                    else if (key.startsWith('_max_')) {
-                        const col = key.slice(5);
-                        const field = this.tableMeta.reverseColumnMap[col] ?? snakeToCamel(col);
-                        maxObj[field] = val;
-                        hasMaxs = true;
-                    }
-                }
-                if (hasSums)
-                    aggResult._sum = sumObj;
-                if (hasAvgs)
-                    aggResult._avg = avgObj;
-                if (hasMins)
-                    aggResult._min = minObj;
-                if (hasMaxs)
-                    aggResult._max = maxObj;
-                return aggResult;
-            },
-            tag: `${this.table}.aggregate`,
-        };
-    }
-    // =========================================================================
-    // Internal helpers
-    // =========================================================================
-    /**
-     * Resolve select/omit options into a list of snake_case column names.
-     * Returns null if neither is provided (meaning all columns).
-     */
-    resolveColumns(select, omit) {
-        if (select) {
-            // Only include columns where value is true
-            return Object.entries(select)
-                .filter(([, v]) => v)
-                .map(([k]) => this.toColumn(k));
-        }
-        if (omit) {
-            // Include all columns except those where value is true
-            const omitCols = new Set(Object.entries(omit)
-                .filter(([, v]) => v)
-                .map(([k]) => this.toColumn(k)));
-            return this.tableMeta.allColumns.filter((col) => !omitCols.has(col));
-        }
-        return null;
-    }
-    /** Convert camelCase field name to snake_case column name (unquoted, for non-SQL uses) */
-    toColumn(field) {
-        const mapped = this.tableMeta.columnMap[field];
-        if (mapped)
-            return mapped;
-        // Fall back to camelToSnake ONLY if that snake_cased name also exists as a
-        // real column on the table. This preserves the convenience of writing
-        // `userId` when the schema exposes `user_id` under an unusual field name,
-        // but rejects arbitrary strings — closing the defense-in-depth gap for
-        // SQL injection and catching typos like `where: { emial: 'x' }` with a
-        // clear error instead of a cryptic Postgres "column does not exist".
-        const snake = camelToSnake(field);
-        if (this.tableMeta.reverseColumnMap?.[snake]) {
-            return snake;
-        }
-        if (this.tableMeta.allColumns?.includes(snake)) {
-            return snake;
-        }
-        throw new ValidationError(`[turbine] Unknown field "${field}" on table "${this.table}". ` +
-            `Known fields: ${Object.keys(this.tableMeta.columnMap).join(', ') || '(none)'}.`);
-    }
-    /** Convert camelCase field name to a double-quoted SQL identifier */
-    toSqlColumn(field) {
-        return quoteIdent(this.toColumn(field));
-    }
-    /**
-     * 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.
-     */
-    buildSetClause(key, value, params) {
-        const col = this.toSqlColumn(key);
-        // Detect atomic-operator object: plain object (not null, not array, not
-        // Date, not Buffer) with EXACTLY one key matching an operator name.
-        if (value !== null &&
-            typeof value === 'object' &&
-            !Array.isArray(value) &&
-            !(value instanceof Date) &&
-            !Buffer.isBuffer(value)) {
-            const v = value;
-            const keys = Object.keys(v);
-            if (keys.length === 1 && UPDATE_OPERATOR_KEYS.has(keys[0])) {
-                const op = keys[0];
-                const opValue = v[op];
-                if (op === 'set') {
-                    params.push(opValue);
-                    return `${col} = $${params.length}`;
-                }
-                // Arithmetic operators: must be finite numbers
-                if (typeof opValue !== 'number' || !Number.isFinite(opValue)) {
-                    throw new ValidationError(`[turbine] update operator "${op}" on "${this.table}.${key}" requires a finite number, got ${typeof opValue}`);
-                }
-                if (op === 'increment') {
-                    params.push(opValue);
-                    return `${col} = ${col} + $${params.length}`;
-                }
-                if (op === 'decrement') {
-                    params.push(opValue);
-                    return `${col} = ${col} - $${params.length}`;
-                }
-                if (op === 'multiply') {
-                    params.push(opValue);
-                    return `${col} = ${col} * $${params.length}`;
-                }
-                if (op === 'divide') {
-                    params.push(opValue);
-                    return `${col} = ${col} / $${params.length}`;
-                }
-            }
-            // Fall through: multi-key objects or non-operator single-key objects
-            // are treated as plain values (e.g., JSONB column payloads).
-        }
-        // Plain value (including null, Date, Buffer, arrays, JSON objects)
-        params.push(value);
-        return `${col} = $${params.length}`;
-    }
-    // =========================================================================
-    // Fingerprinting — value-invariant shape keys for SQL cache lookup
-    // =========================================================================
-    /**
-     * 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) {
-        const keys = Object.keys(where)
-            .filter((k) => where[k] !== undefined)
-            .sort();
-        if (keys.length === 0)
-            return '';
-        const parts = [];
-        for (const key of keys) {
-            const value = where[key];
-            if (value === undefined)
-                continue;
-            if (key === 'OR') {
-                const orArr = value;
-                if (!Array.isArray(orArr) || orArr.length === 0)
-                    continue;
-                const orParts = orArr.map((cond) => this.fingerprintWhere(cond));
-                parts.push(`OR[${orParts.join(',')}]`);
-                continue;
-            }
-            if (key === 'AND') {
-                const andArr = value;
-                if (!Array.isArray(andArr) || andArr.length === 0)
-                    continue;
-                const andParts = andArr.map((cond) => this.fingerprintWhere(cond));
-                parts.push(`AND[${andParts.join(',')}]`);
-                continue;
-            }
-            if (key === 'NOT') {
-                const notCond = value;
-                parts.push(`NOT(${this.fingerprintWhere(notCond)})`);
-                continue;
-            }
-            // Relation filters: { posts: { some: { published: true } } }
-            const relDef = this.tableMeta.relations[key];
-            if (relDef && typeof value === 'object' && value !== null && !Array.isArray(value)) {
-                const filterObj = value;
-                if ('some' in filterObj || 'every' in filterObj || 'none' in filterObj) {
-                    const relParts = [];
-                    if (filterObj.some !== undefined)
-                        relParts.push(`some(${this.fingerprintRelFilter(relDef.to, filterObj.some)})`);
-                    if (filterObj.every !== undefined)
-                        relParts.push(`every(${this.fingerprintRelFilter(relDef.to, filterObj.every)})`);
-                    if (filterObj.none !== undefined)
-                        relParts.push(`none(${this.fingerprintRelFilter(relDef.to, filterObj.none)})`);
-                    parts.push(`${key}:{${relParts.join(',')}}`);
-                    continue;
-                }
-            }
-            // null → distinct from value
-            if (value === null) {
-                parts.push(`${key}:null`);
-                continue;
-            }
-            // Operator objects
-            if (isWhereOperator(value)) {
-                const opKeys = Object.keys(value)
-                    .filter((k) => k !== 'mode')
-                    .sort();
-                const mode = value.mode;
-                const modeStr = mode === 'insensitive' ? ':i' : '';
-                parts.push(`${key}:op(${opKeys.join(',')}${modeStr})`);
-                continue;
-            }
-            // JSON filter
-            if (typeof value === 'object' && !Array.isArray(value) && isJsonFilter(value)) {
-                const jKeys = Object.keys(value).sort();
-                parts.push(`${key}:json(${jKeys.join(',')})`);
-                continue;
-            }
-            // Array filter
-            if (typeof value === 'object' && !Array.isArray(value) && isArrayFilter(value)) {
-                const aKeys = Object.keys(value).sort();
-                parts.push(`${key}:arr(${aKeys.join(',')})`);
-                continue;
-            }
-            // Plain equality
-            parts.push(`${key}:eq`);
-        }
-        return parts.join('&');
-    }
-    /**
-     * Fingerprint a relation filter sub-where for some/every/none.
-     */
-    fingerprintRelFilter(_targetTable, subWhere) {
-        const keys = Object.keys(subWhere)
-            .filter((k) => subWhere[k] !== undefined)
-            .sort();
-        if (keys.length === 0)
-            return '';
-        const parts = [];
-        for (const key of keys) {
-            const value = subWhere[key];
-            if (value === undefined)
-                continue;
-            if (value === null) {
-                parts.push(`${key}:null`);
-            }
-            else if (isWhereOperator(value)) {
-                const opKeys = Object.keys(value)
-                    .filter((k) => k !== 'mode')
-                    .sort();
-                const mode = value.mode;
-                const modeStr = mode === 'insensitive' ? ':i' : '';
-                parts.push(`${key}:op(${opKeys.join(',')}${modeStr})`);
-            }
-            else {
-                parts.push(`${key}:eq`);
-            }
-        }
-        return parts.join('&');
-    }
-    /**
-     * 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, params) {
-        const keys = Object.keys(where);
-        for (const key of keys) {
-            const value = where[key];
-            if (value === undefined)
-                continue;
-            if (key === 'OR') {
-                const orConditions = value;
-                if (!Array.isArray(orConditions) || orConditions.length === 0)
-                    continue;
-                for (const orCond of orConditions) {
-                    this.collectWhereParams(orCond, params);
-                }
-                continue;
-            }
-            if (key === 'AND') {
-                const andConditions = value;
-                if (!Array.isArray(andConditions) || andConditions.length === 0)
-                    continue;
-                for (const andCond of andConditions) {
-                    this.collectWhereParams(andCond, params);
-                }
-                continue;
-            }
-            if (key === 'NOT') {
-                const notCond = value;
-                this.collectWhereParams(notCond, params);
-                continue;
-            }
-            // Relation filters
-            const relationDef = this.tableMeta.relations[key];
-            if (relationDef && typeof value === 'object' && value !== null && !Array.isArray(value)) {
-                const filterObj = value;
-                if ('some' in filterObj || 'every' in filterObj || 'none' in filterObj) {
-                    if (filterObj.some !== undefined)
-                        this.collectRelFilterParams(relationDef.to, filterObj.some, params);
-                    if (filterObj.none !== undefined)
-                        this.collectRelFilterParams(relationDef.to, filterObj.none, params);
-                    if (filterObj.every !== undefined)
-                        this.collectRelFilterParams(relationDef.to, filterObj.every, params);
-                    continue;
-                }
-            }
-            // null → no param pushed (IS NULL is parameterless)
-            if (value === null)
-                continue;
-            const rawColumn = this.toColumn(key);
-            // JSONB filter
-            if (typeof value === 'object' && !Array.isArray(value) && isJsonFilter(value)) {
-                const colType = this.getColumnPgType(rawColumn);
-                if (colType === 'json' || colType === 'jsonb') {
-                    this.collectJsonFilterParams(value, params);
-                    continue;
-                }
-            }
-            // Array filter
-            if (typeof value === 'object' && !Array.isArray(value) && isArrayFilter(value)) {
-                const colType = this.getColumnPgType(rawColumn);
-                if (colType.startsWith('_')) {
-                    this.collectArrayFilterParams(value, params);
-                    continue;
-                }
-            }
-            // Operator objects
-            if (isWhereOperator(value)) {
-                this.collectOperatorParams(value, params);
-                continue;
-            }
-            // Plain equality
-            params.push(value);
-        }
-    }
-    /** Collect params from a relation filter sub-where. Mirrors buildSubWhereForRelation. */
-    collectRelFilterParams(targetTable, subWhere, params) {
-        const meta = this.schema.tables[targetTable];
-        if (!meta)
-            return;
-        for (const [_field, value] of Object.entries(subWhere)) {
-            if (value === undefined)
-                continue;
-            if (value === null)
-                continue;
-            if (isWhereOperator(value)) {
-                this.collectOperatorParams(value, params);
-                continue;
-            }
-            params.push(value);
-        }
-    }
-    /** Collect params from operator clauses. Mirrors buildOperatorClauses. */
-    collectOperatorParams(op, params) {
-        if (op.gt !== undefined)
-            params.push(op.gt);
-        if (op.gte !== undefined)
-            params.push(op.gte);
-        if (op.lt !== undefined)
-            params.push(op.lt);
-        if (op.lte !== undefined)
-            params.push(op.lte);
-        if (op.not !== undefined && op.not !== null)
-            params.push(op.not);
-        if (op.in !== undefined)
-            params.push(op.in);
-        if (op.notIn !== undefined)
-            params.push(op.notIn);
-        if (op.contains !== undefined)
-            params.push(`%${escapeLike(op.contains)}%`);
-        if (op.startsWith !== undefined)
-            params.push(`${escapeLike(op.startsWith)}%`);
-        if (op.endsWith !== undefined)
-            params.push(`%${escapeLike(op.endsWith)}`);
-    }
-    /** Collect params from JSON filter. Mirrors buildJsonFilterClauses. */
-    collectJsonFilterParams(filter, params) {
-        if (filter.path !== undefined && filter.equals !== undefined) {
-            params.push(filter.path);
-            params.push(String(filter.equals));
-        }
-        else if (filter.equals !== undefined) {
-            params.push(JSON.stringify(filter.equals));
-        }
-        if (filter.contains !== undefined) {
-            params.push(JSON.stringify(filter.contains));
-        }
-        if (filter.hasKey !== undefined) {
-            params.push(filter.hasKey);
-        }
-    }
-    /** Collect params from array filter. Mirrors buildArrayFilterClauses. */
-    collectArrayFilterParams(filter, params) {
-        if (filter.has !== undefined)
-            params.push(filter.has);
-        if (filter.hasEvery !== undefined)
-            params.push(filter.hasEvery);
-        if (filter.hasSome !== undefined)
-            params.push(filter.hasSome);
-        // isEmpty has no params (IS NULL / IS NOT NULL)
-    }
-    /**
-     * Produce a fingerprint for a `with` clause tree. Recursion mirrors
-     * buildSelectWithRelations / buildRelationSubquery.
-     *
-     * @internal Exposed as package-private for testing.
-     */
-    withFingerprint(withClause, table, depth = 0) {
-        if (!withClause)
-            return '';
-        const meta = this.schema.tables[table ?? this.table];
-        if (!meta)
-            return '';
-        const relNames = Object.keys(withClause).sort();
-        const parts = [];
-        for (const relName of relNames) {
-            const spec = withClause[relName];
-            if (!spec)
-                continue;
-            const relDef = meta.relations[relName];
-            if (!relDef)
-                continue;
-            if (spec === true) {
-                parts.push(relName);
-                continue;
-            }
-            const opts = spec;
-            const subParts = [];
-            // select/omit shape
-            if (opts.select) {
-                const selKeys = Object.entries(opts.select)
-                    .filter(([, v]) => v)
-                    .map(([k]) => k)
-                    .sort();
-                subParts.push(`sl=${selKeys.join(',')}`);
-            }
-            if (opts.omit) {
-                const omKeys = Object.entries(opts.omit)
-                    .filter(([, v]) => v)
-                    .map(([k]) => k)
-                    .sort();
-                subParts.push(`om=${omKeys.join(',')}`);
-            }
-            // where shape (value-invariant)
-            if (opts.where) {
-                // Use a target-table QI if possible, or a simplified fingerprint
-                const wKeys = Object.keys(opts.where)
-                    .filter((k) => opts.where[k] !== undefined)
-                    .sort();
-                subParts.push(`w=${wKeys.join(',')}`);
-            }
-            // orderBy shape
-            if (opts.orderBy) {
-                const oEntries = Object.entries(opts.orderBy).map(([k, d]) => `${k}:${d}`);
-                subParts.push(`o=${oEntries.join(',')}`);
-            }
-            // limit presence
-            if (opts.limit !== undefined) {
-                subParts.push('l=1');
-            }
-            // nested with (recurse)
-            if (opts.with) {
-                const nested = this.withFingerprint(opts.with, relDef.to, depth + 1);
-                if (nested)
-                    subParts.push(`W=(${nested})`);
-            }
-            parts.push(subParts.length > 0 ? `${relName}/{${subParts.join('/')}}` : relName);
-        }
-        return parts.join('|');
-    }
-    /**
-     * Collect params from a `with` clause tree. Mirrors buildSelectWithRelations +
-     * buildRelationSubquery param-push order.
-     */
-    collectWithParams(withClause, params, table) {
-        const meta = this.schema.tables[table ?? this.table];
-        if (!meta)
-            return;
-        for (const [relName, relSpec] of Object.entries(withClause)) {
-            const relDef = meta.relations[relName];
-            if (!relDef)
-                continue;
-            this.collectRelationSubqueryParams(relDef, relSpec, params, table ?? this.table);
-        }
-    }
-    /**
-     * Collect params from a single relation subquery. Mirrors buildRelationSubquery.
-     */
-    collectRelationSubqueryParams(relDef, spec, params, _parentRef, depth = 0) {
-        if (spec === true)
-            return; // No params for default include
-        const targetTable = relDef.to;
-        const targetMeta = this.schema.tables[targetTable];
-        if (!targetMeta)
-            return;
-        const willWrap = relDef.type === 'hasMany' && (spec.limit !== undefined || spec.orderBy !== undefined);
-        // Non-wrapped path: nested relations BEFORE where/limit
-        if (!willWrap && spec.with) {
-            for (const [nestedRelName, nestedSpec] of Object.entries(spec.with)) {
-                const nestedRelDef = targetMeta.relations[nestedRelName];
-                if (!nestedRelDef)
-                    continue;
-                this.collectRelationSubqueryParams(nestedRelDef, nestedSpec, params, 'alias', depth + 1);
-            }
-        }
-        // where params
-        if (spec.where) {
-            for (const [, v] of Object.entries(spec.where)) {
-                params.push(v);
-            }
-        }
-        // limit param
-        if (spec.limit) {
-            params.push(Number(spec.limit));
-        }
-        // Wrapped path: nested relations AFTER where/limit (inside inner subquery)
-        if (willWrap && spec.with) {
-            for (const [nestedRelName, nestedSpec] of Object.entries(spec.with)) {
-                const nestedRelDef = targetMeta.relations[nestedRelName];
-                if (!nestedRelDef)
-                    continue;
-                this.collectRelationSubqueryParams(nestedRelDef, nestedSpec, params, 'innerAlias', depth + 1);
-            }
-        }
-    }
-    /**
-     * Fingerprint SET clauses for update/updateMany.
-     * Captures key names + operator types (set/increment/etc) but not values.
-     */
-    fingerprintSet(data) {
-        const entries = Object.entries(data).filter(([, v]) => v !== undefined);
-        const parts = [];
-        for (const [k, v] of entries) {
-            if (v !== null &&
-                typeof v === 'object' &&
-                !Array.isArray(v) &&
-                !(v instanceof Date) &&
-                !(typeof Buffer !== 'undefined' && Buffer.isBuffer(v))) {
-                const keys = Object.keys(v);
-                if (keys.length === 1 && UPDATE_OPERATOR_KEYS.has(keys[0])) {
-                    parts.push(`${k}:${keys[0]}`);
-                    continue;
-                }
-            }
-            parts.push(`${k}:eq`);
-        }
-        return parts.join(',');
-    }
-    /**
-     * Collect SET params for update/updateMany. Mirrors buildSetClause param order.
-     */
-    collectSetParams(data, params) {
-        const entries = Object.entries(data).filter(([, v]) => v !== undefined);
-        for (const [, v] of entries) {
-            if (v !== null &&
-                typeof v === 'object' &&
-                !Array.isArray(v) &&
-                !(v instanceof Date) &&
-                !(typeof Buffer !== 'undefined' && Buffer.isBuffer(v))) {
-                const obj = v;
-                const keys = Object.keys(obj);
-                if (keys.length === 1 && UPDATE_OPERATOR_KEYS.has(keys[0])) {
-                    params.push(obj[keys[0]]);
-                    continue;
-                }
-            }
-            params.push(v);
-        }
-    }
-    /** Build WHERE clause from a where object (supports operators, NULL, OR) */
-    buildWhere(where) {
-        const params = [];
-        const clause = this.buildWhereClause(where, params);
-        if (!clause)
-            return { sql: '', params: [] };
-        return { sql: ` WHERE ${clause}`, params };
-    }
-    /**
-     * 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`.
-     */
-    assertMutationHasPredicate(operation, whereSql, allowFullTableScan) {
-        if (whereSql.length > 0)
-            return;
-        if (allowFullTableScan === true)
-            return;
-        throw new ValidationError(`[turbine] ${operation} on "${this.table}" refused: the \`where\` clause is empty. ` +
-            `Pass \`allowFullTableScan: true\` to opt in, or check that your filter values are defined.`);
-    }
-    /**
-     * 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).
-     */
-    buildWhereClause(where, params) {
-        const keys = Object.keys(where);
-        if (keys.length === 0)
-            return null;
-        const andClauses = [];
-        for (const key of keys) {
-            const value = where[key];
-            if (value === undefined)
-                continue;
-            // Handle OR special key
-            if (key === 'OR') {
-                const orConditions = value;
-                if (!Array.isArray(orConditions) || orConditions.length === 0)
-                    continue;
-                const orClauses = [];
-                for (const orCond of orConditions) {
-                    const sub = this.buildWhereClause(orCond, params);
-                    if (sub)
-                        orClauses.push(sub);
-                }
-                if (orClauses.length > 0) {
-                    andClauses.push(`(${orClauses.join(' OR ')})`);
-                }
-                continue;
-            }
-            // Handle AND special key
-            if (key === 'AND') {
-                const andConditions = value;
-                if (!Array.isArray(andConditions) || andConditions.length === 0)
-                    continue;
-                for (const andCond of andConditions) {
-                    const sub = this.buildWhereClause(andCond, params);
-                    if (sub)
-                        andClauses.push(sub);
-                }
-                continue;
-            }
-            // Handle NOT special key
-            if (key === 'NOT') {
-                const notCond = value;
-                const sub = this.buildWhereClause(notCond, params);
-                if (sub)
-                    andClauses.push(`NOT (${sub})`);
-                continue;
-            }
-            // Handle relation filters: { posts: { some: { published: true } } }
-            const relationDef = this.tableMeta.relations[key];
-            if (relationDef && typeof value === 'object' && value !== null && !Array.isArray(value)) {
-                const filterObj = value;
-                // Check if this is a relation filter (has some/every/none keys)
-                if ('some' in filterObj || 'every' in filterObj || 'none' in filterObj) {
-                    const relClause = this.buildRelationFilter(key, relationDef, filterObj, params);
-                    if (relClause)
-                        andClauses.push(relClause);
-                    continue;
-                }
-            }
-            const rawColumn = this.toColumn(key);
-            const column = quoteIdent(rawColumn);
-            // Handle null → IS NULL
-            if (value === null) {
-                andClauses.push(`${column} IS NULL`);
-                continue;
-            }
-            // Handle JSONB filter operators (for json/jsonb columns)
-            if (typeof value === 'object' && !Array.isArray(value) && isJsonFilter(value)) {
-                const colType = this.getColumnPgType(rawColumn);
-                if (colType === 'json' || colType === 'jsonb') {
-                    const jsonClauses = this.buildJsonFilterClauses(column, value, params);
-                    andClauses.push(...jsonClauses);
-                    continue;
-                }
-                // Strict validation: a JSON-only operator on a non-JSON column was almost
-                // certainly a typo or schema mismatch. Silently falling through to plain
-                // equality (the previous behaviour) wasted hours of debugging time. Only
-                // throw when the operator is unambiguously JSON-specific — `contains` is
-                // shared with WhereOperator's LIKE so it must continue to fall through.
-                const jsonKey = findJsonUniqueKey(value);
-                if (jsonKey) {
-                    throw new ValidationError(`[turbine] Column "${rawColumn}" on table "${this.table}" is not a JSON column ` +
-                        `(actual type: ${colType}); cannot apply JSON operator '${jsonKey}'.`);
-                }
-            }
-            // Handle Array filter operators (for array columns)
-            if (typeof value === 'object' && !Array.isArray(value) && isArrayFilter(value)) {
-                const colType = this.getColumnPgType(rawColumn);
-                if (colType.startsWith('_')) {
-                    const arrayClauses = this.buildArrayFilterClauses(column, value, params, colType);
-                    andClauses.push(...arrayClauses);
-                    continue;
-                }
-                // Strict validation: array operators (`has`, `hasEvery`, ...) on a
-                // non-array column always indicate a mistake. None of these keys
-                // overlap with other filter shapes so we can throw unconditionally.
-                const arrayKey = findArrayUniqueKey(value);
-                if (arrayKey) {
-                    throw new ValidationError(`[turbine] Column "${rawColumn}" on table "${this.table}" is not an array column ` +
-                        `(actual type: ${colType}); cannot apply array operator '${arrayKey}'.`);
-                }
-            }
-            // Handle operator objects
-            if (isWhereOperator(value)) {
-                const opClauses = this.buildOperatorClauses(column, value, params);
-                andClauses.push(...opClauses);
-                continue;
-            }
-            // Plain equality
-            params.push(value);
-            andClauses.push(`${column} = $${params.length}`);
-        }
-        if (andClauses.length === 0)
-            return null;
-        return andClauses.join(' AND ');
-    }
-    /**
-     * Build relation filter SQL: WHERE EXISTS / NOT EXISTS subquery
-     * Supports: some (EXISTS), every (NOT EXISTS ... NOT), none (NOT EXISTS)
-     */
-    buildRelationFilter(_relName, relDef, filterObj, params) {
-        const targetTable = relDef.to;
-        const targetMeta = this.schema.tables[targetTable];
-        if (!targetMeta)
-            return null;
-        const qt = quoteIdent(targetTable);
-        const qSelf = quoteIdent(this.table);
-        const clauses = [];
-        // Correlation: link child table to parent table
-        let correlation;
-        if (relDef.type === 'hasMany' || relDef.type === 'hasOne') {
-            // parent.pk = child.fk
-            correlation = `${qt}.${quoteIdent(relDef.foreignKey)} = ${qSelf}.${quoteIdent(relDef.referenceKey)}`;
-        }
-        else {
-            // belongsTo: parent.fk = child.pk
-            correlation = `${qt}.${quoteIdent(relDef.referenceKey)} = ${qSelf}.${quoteIdent(relDef.foreignKey)}`;
-        }
-        // "some": EXISTS (SELECT 1 FROM target WHERE correlation AND filter)
-        if (filterObj.some !== undefined) {
-            const subWhere = filterObj.some;
-            const filterClause = this.buildSubWhereForRelation(targetTable, subWhere, params);
-            const fullWhere = filterClause ? `${correlation} AND ${filterClause}` : correlation;
-            clauses.push(`EXISTS (SELECT 1 FROM ${qt} WHERE ${fullWhere})`);
-        }
-        // "none": NOT EXISTS (SELECT 1 FROM target WHERE correlation AND filter)
-        if (filterObj.none !== undefined) {
-            const subWhere = filterObj.none;
-            const filterClause = this.buildSubWhereForRelation(targetTable, subWhere, params);
-            const fullWhere = filterClause ? `${correlation} AND ${filterClause}` : correlation;
-            clauses.push(`NOT EXISTS (SELECT 1 FROM ${qt} WHERE ${fullWhere})`);
-        }
-        // "every": NOT EXISTS (SELECT 1 FROM target WHERE correlation AND NOT (filter))
-        if (filterObj.every !== undefined) {
-            const subWhere = filterObj.every;
-            const filterClause = this.buildSubWhereForRelation(targetTable, subWhere, params);
-            if (filterClause) {
-                clauses.push(`NOT EXISTS (SELECT 1 FROM ${qt} WHERE ${correlation} AND NOT (${filterClause}))`);
-            }
-            else {
-                // "every" with empty filter = true (all match trivially)
-            }
-        }
-        return clauses.length > 0 ? clauses.join(' AND ') : null;
-    }
-    /**
-     * Build WHERE clause conditions for a relation filter subquery.
-     * Uses the target table's column mapping to resolve field names.
-     */
-    buildSubWhereForRelation(targetTable, subWhere, params) {
-        const meta = this.schema.tables[targetTable];
-        if (!meta)
-            return null;
-        const qt = quoteIdent(targetTable);
-        const conditions = [];
-        for (const [field, value] of Object.entries(subWhere)) {
-            if (value === undefined)
-                continue;
-            const col = meta.columnMap[field] ?? camelToSnake(field);
-            const qCol = `${qt}.${quoteIdent(col)}`;
-            if (value === null) {
-                conditions.push(`${qCol} IS NULL`);
-                continue;
-            }
-            if (isWhereOperator(value)) {
-                const opClauses = this.buildOperatorClauses(qCol, value, params);
-                conditions.push(...opClauses);
-                continue;
-            }
-            params.push(value);
-            conditions.push(`${qCol} = $${params.length}`);
-        }
-        return conditions.length > 0 ? conditions.join(' AND ') : null;
-    }
-    /**
-     * Build SQL clauses for a single operator object on a column.
-     * Each operator key becomes its own clause, all ANDed together.
-     */
-    buildOperatorClauses(column, op, params) {
-        const clauses = [];
-        if (op.gt !== undefined) {
-            params.push(op.gt);
-            clauses.push(`${column} > $${params.length}`);
-        }
-        if (op.gte !== undefined) {
-            params.push(op.gte);
-            clauses.push(`${column} >= $${params.length}`);
-        }
-        if (op.lt !== undefined) {
-            params.push(op.lt);
-            clauses.push(`${column} < $${params.length}`);
-        }
-        if (op.lte !== undefined) {
-            params.push(op.lte);
-            clauses.push(`${column} <= $${params.length}`);
-        }
-        if (op.not !== undefined) {
-            if (op.not === null) {
-                clauses.push(`${column} IS NOT NULL`);
-            }
-            else {
-                params.push(op.not);
-                clauses.push(`${column} != $${params.length}`);
-            }
-        }
-        if (op.in !== undefined) {
-            params.push(op.in);
-            clauses.push(`${column} = ANY($${params.length})`);
-        }
-        if (op.notIn !== undefined) {
-            params.push(op.notIn);
-            clauses.push(`${column} != ALL($${params.length})`);
-        }
-        // Use ILIKE for case-insensitive mode, LIKE otherwise
-        const likeOp = op.mode === 'insensitive' ? 'ILIKE' : 'LIKE';
-        if (op.contains !== undefined) {
-            params.push(`%${escapeLike(op.contains)}%`);
-            clauses.push(`${column} ${likeOp} $${params.length} ESCAPE '\\'`);
-        }
-        if (op.startsWith !== undefined) {
-            params.push(`${escapeLike(op.startsWith)}%`);
-            clauses.push(`${column} ${likeOp} $${params.length} ESCAPE '\\'`);
-        }
-        if (op.endsWith !== undefined) {
-            params.push(`%${escapeLike(op.endsWith)}`);
-            clauses.push(`${column} ${likeOp} $${params.length} ESCAPE '\\'`);
-        }
-        return clauses;
-    }
-    /** Build ORDER BY clause from an object */
-    buildOrderBy(orderBy) {
-        const meta = this.schema.tables[this.table];
-        return Object.entries(orderBy)
-            .map(([key, dir]) => {
-            if (meta && !(key in meta.columnMap)) {
-                throw new ValidationError(`Unknown column "${key}" in orderBy for table "${this.table}"`);
-            }
-            const safeDir = dir.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
-            return `${this.toSqlColumn(key)} ${safeDir}`;
-        })
-            .join(', ');
-    }
-    /** Parse a flat row: convert snake_case to camelCase + Date coercion */
-    parseRow(row, table) {
-        const parsed = {};
-        const meta = this.schema.tables[table];
-        if (meta) {
-            // Fast path: use pre-computed maps (avoids regex per column per row)
-            const reverseMap = meta.reverseColumnMap;
-            const dateCols = meta.dateColumns;
-            const keys = Object.keys(row);
-            for (let i = 0; i < keys.length; i++) {
-                const col = keys[i];
-                const value = row[col];
-                const field = reverseMap[col] ?? col; // fall back to raw col name, not regex
-                if (dateCols.has(col) && value !== null && !(value instanceof Date)) {
-                    parsed[field] = new Date(value);
-                }
-                else {
-                    parsed[field] = value;
-                }
-            }
-        }
-        else {
-            // Fallback: no metadata, use regex conversion
-            for (const [col, value] of Object.entries(row)) {
-                parsed[snakeToCamel(col)] = value;
-            }
-        }
-        return parsed;
-    }
-    /** Parse a row that may contain JSON nested relation columns */
-    parseNestedRow(row, table) {
-        const parsed = this.parseRow(row, table);
-        const meta = this.schema.tables[table];
-        if (!meta)
-            return parsed;
-        for (const [relName, relDef] of Object.entries(meta.relations)) {
-            const rawValue = row[relName];
-            if (rawValue === undefined)
-                continue;
-            // --- Short-circuit: skip JSON.parse for common empty/null cases ---
-            // hasMany returns '[]' (from COALESCE(..., '[]'::json)); belongsTo/hasOne returns null
-            if (rawValue === null || rawValue === 'null') {
-                parsed[relName] = null;
-                continue;
-            }
-            if (rawValue === '[]') {
-                parsed[relName] = [];
-                continue;
-            }
-            if (Array.isArray(rawValue) && rawValue.length === 0) {
-                parsed[relName] = [];
-                continue;
-            }
-            // --- Non-empty values: full parse path ---
-            if (typeof rawValue === 'string') {
-                try {
-                    const jsonVal = JSON.parse(rawValue);
-                    // After parsing, apply parseRow to each item for snake→camel + date coercion
-                    if (Array.isArray(jsonVal)) {
-                        parsed[relName] = jsonVal.map((item) => typeof item === 'object' && item !== null
-                            ? this.parseRow(item, relDef.to)
-                            : item);
-                    }
-                    else if (typeof jsonVal === 'object' && jsonVal !== null) {
-                        parsed[relName] = this.parseRow(jsonVal, relDef.to);
-                    }
-                    else {
-                        parsed[relName] = jsonVal;
-                    }
-                }
-                catch {
-                    console.warn(`[turbine] Warning: Failed to parse JSON for relation "${relName}" on table "${this.table}". Using raw value.`);
-                    parsed[relName] = rawValue;
-                }
-            }
-            else if (Array.isArray(rawValue)) {
-                parsed[relName] = rawValue.map((item) => typeof item === 'object' && item !== null ? this.parseRow(item, relDef.to) : item);
-            }
-            else if (typeof rawValue === 'object' && rawValue !== null) {
-                parsed[relName] = this.parseRow(rawValue, relDef.to);
-            }
-            else {
-                parsed[relName] = rawValue;
-            }
-        }
-        return parsed;
-    }
-    /**
-     * 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.
-     */
-    buildSelectWithRelations(table, withClause, params, columnsList, depth, path) {
-        const meta = this.schema.tables[table];
-        if (!meta)
-            throw new ValidationError(`[turbine] Unknown table "${table}"`);
-        const cols = columnsList ?? meta.allColumns;
-        const qtbl = quoteIdent(table);
-        const baseCols = cols.map((col) => `${qtbl}.${quoteIdent(col)}`).join(', ');
-        const relationSelects = [];
-        const aliasCounter = { n: 0 };
-        for (const [relName, relSpec] of Object.entries(withClause)) {
-            const relDef = meta.relations[relName];
-            if (!relDef) {
-                throw new RelationError(`[turbine] Unknown relation "${relName}" on table "${table}". ` +
-                    `Available: ${Object.keys(meta.relations).join(', ')}`);
-            }
-            // The main table is not aliased, so pass table name as parentRef
-            const subquery = this.buildRelationSubquery(relDef, relSpec, params, table, aliasCounter, depth, path);
-            relationSelects.push(`(${subquery}) AS ${quoteIdent(relName)}`);
-        }
-        return [baseCols, ...relationSelects].join(', ');
-    }
-    /**
-     * 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).
-     */
-    buildRelationSubquery(relDef, spec, params, parentRef, aliasCounter, depth, path) {
-        const currentDepth = depth ?? 0;
-        const currentPath = path ?? [this.table];
-        const targetTable = relDef.to;
-        // Hard depth cap — the `with` clause is a finite JSON structure so users can't
-        // create true infinite recursion, but extremely deep nesting (10+ levels) produces
-        // unmanageably large SQL. Back-references (e.g. posts → user → posts) are allowed
-        // since they are legitimate queries (Prisma supports the same pattern).
-        if (currentDepth >= 10) {
-            throw new CircularRelationError([...currentPath, targetTable]);
-        }
-        const targetMeta = this.schema.tables[targetTable];
-        if (!targetMeta)
-            throw new RelationError(`[turbine] Unknown relation target "${targetTable}"`);
-        // Generate a unique alias: t0, t1, t2, ...
-        const alias = `t${aliasCounter.n++}`;
-        // Resolve which columns to include based on select/omit
-        let targetColumns = targetMeta.allColumns;
-        if (spec !== true && spec.select) {
-            const selectedFields = Object.entries(spec.select)
-                .filter(([, v]) => v)
-                .map(([k]) => targetMeta.columnMap[k] ?? camelToSnake(k));
-            targetColumns = selectedFields.filter((col) => targetMeta.allColumns.includes(col));
-        }
-        else if (spec !== true && spec.omit) {
-            const omittedFields = new Set(Object.entries(spec.omit)
-                .filter(([, v]) => v)
-                .map(([k]) => targetMeta.columnMap[k] ?? camelToSnake(k)));
-            targetColumns = targetMeta.allColumns.filter((col) => !omittedFields.has(col));
-        }
-        // Build json_build_object pairs for resolved columns
-        const jsonPairs = targetColumns.map((col) => `'${escSingleQuote(targetMeta.reverseColumnMap[col] ?? snakeToCamel(col))}', ${alias}.${quoteIdent(col)}`);
-        // Determine if this hasMany will take the wrapped subquery path (LIMIT or ORDER BY).
-        // When wrapping, nested relations are built in the wrapped path referencing innerAlias,
-        // so we must NOT build them here (they would push orphaned params).
-        const willWrap = relDef.type === 'hasMany' && spec !== true && (spec.limit !== undefined || spec.orderBy !== undefined);
-        // Nested relations — only in the non-wrapped path (wrapped path builds them separately)
-        if (!willWrap && spec !== true && spec.with) {
-            for (const [nestedRelName, nestedSpec] of Object.entries(spec.with)) {
-                const nestedRelDef = targetMeta.relations[nestedRelName];
-                if (!nestedRelDef) {
-                    throw new RelationError(`[turbine] Unknown relation "${nestedRelName}" on table "${targetTable}". ` +
-                        `Available: ${Object.keys(targetMeta.relations).join(', ')}`);
-                }
-                // Recursively build nested subquery, passing THIS alias as the parent reference
-                const nestedSubquery = this.buildRelationSubquery(nestedRelDef, nestedSpec, params, alias, aliasCounter, currentDepth + 1, [...currentPath, relDef.name]);
-                // Use '[]'::json for hasMany (empty array), NULL for belongsTo/hasOne (no object)
-                const fallback = nestedRelDef.type === 'hasMany' ? "'[]'::json" : 'NULL';
-                jsonPairs.push(`'${escSingleQuote(nestedRelName)}', COALESCE((${nestedSubquery}), ${fallback})`);
-            }
-        }
-        const jsonObj = `json_build_object(${jsonPairs.join(', ')})`;
-        // Quote parent ref — can be a table name or auto-generated alias
-        const qParent = quoteIdent(parentRef);
-        const qTarget = quoteIdent(targetTable);
-        // Build ORDER BY for json_agg
-        let orderClause = '';
-        if (spec !== true && spec.orderBy) {
-            const orders = Object.entries(spec.orderBy)
-                .map(([k, dir]) => {
-                const col = camelToSnake(k);
-                if (!targetMeta.allColumns.includes(col)) {
-                    throw new ValidationError(`[turbine] Unknown column "${k}" in orderBy for table "${targetTable}"`);
-                }
-                const safeDir = dir.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
-                return `${alias}.${quoteIdent(col)} ${safeDir}`;
-            })
-                .join(', ');
-            orderClause = ` ORDER BY ${orders}`;
-        }
-        // Build WHERE — correlate to parent via parentRef (alias or table name).
-        // For hasMany: target has FK, so alias.fk = parentRef.pk
-        // For belongsTo: source has FK, so alias.pk = parentRef.fk (reversed)
-        let whereClause;
-        if (relDef.type === 'belongsTo' || relDef.type === 'hasOne') {
-            whereClause = `${alias}.${quoteIdent(relDef.referenceKey)} = ${qParent}.${quoteIdent(relDef.foreignKey)}`;
-        }
-        else {
-            whereClause = `${alias}.${quoteIdent(relDef.foreignKey)} = ${qParent}.${quoteIdent(relDef.referenceKey)}`;
-        }
-        // Additional filters — properly parameterized
-        if (spec !== true && spec.where) {
-            for (const [k, v] of Object.entries(spec.where)) {
-                const col = camelToSnake(k);
-                if (!targetMeta.allColumns.includes(col)) {
-                    throw new ValidationError(`[turbine] Unknown column "${k}" in where for table "${targetTable}"`);
-                }
-                params.push(v);
-                whereClause += ` AND ${alias}.${quoteIdent(col)} = $${params.length}`;
-            }
-        }
-        // LIMIT
-        let limitClause = '';
-        if (spec !== true && spec.limit) {
-            params.push(Number(spec.limit));
-            limitClause = ` LIMIT $${params.length}`;
-        }
-        if (relDef.type === 'hasMany') {
-            // When LIMIT or ORDER BY is used, wrap in a subquery so LIMIT applies to rows
-            // BEFORE json_agg aggregation (otherwise LIMIT on aggregated result is meaningless)
-            if (limitClause || orderClause) {
-                const innerAlias = `${alias}i`;
-                // Rewrite: SELECT json_agg(json_build_object(...)) FROM (SELECT * FROM table WHERE ... ORDER BY ... LIMIT N) AS alias
-                // Inner SELECT always needs all columns for WHERE/ORDER to work; json_build_object filters later
-                const innerSql = `SELECT ${targetMeta.allColumns.map((c) => `${alias}.${quoteIdent(c)}`).join(', ')} FROM ${qTarget} ${alias} WHERE ${whereClause}${orderClause}${limitClause}`;
-                // For the json_build_object, reference the inner alias — only include resolved columns
-                const innerJsonPairs = targetColumns.map((col) => `'${escSingleQuote(targetMeta.reverseColumnMap[col] ?? snakeToCamel(col))}', ${innerAlias}.${quoteIdent(col)}`);
-                // Build nested relation subqueries referencing innerAlias
-                if (spec !== true && spec.with) {
-                    for (const [nestedRelName, nestedSpec] of Object.entries(spec.with)) {
-                        const nestedRelDef = targetMeta.relations[nestedRelName];
-                        if (!nestedRelDef) {
-                            throw new RelationError(`[turbine] Unknown relation "${nestedRelName}" on table "${targetTable}". ` +
-                                `Available: ${Object.keys(targetMeta.relations).join(', ')}`);
-                        }
-                        const nestedSub = this.buildRelationSubquery(nestedRelDef, nestedSpec, params, innerAlias, aliasCounter, currentDepth + 1, [...currentPath, relDef.name]);
-                        const fallback = nestedRelDef.type === 'hasMany' ? "'[]'::json" : 'NULL';
-                        innerJsonPairs.push(`'${escSingleQuote(nestedRelName)}', COALESCE((${nestedSub}), ${fallback})`);
-                    }
-                }
-                const innerJsonObj = `json_build_object(${innerJsonPairs.join(', ')})`;
-                return `SELECT COALESCE(json_agg(${innerJsonObj}), '[]'::json) FROM (${innerSql}) ${innerAlias}`;
-            }
-            return `SELECT COALESCE(json_agg(${jsonObj}${orderClause}), '[]'::json) FROM ${qTarget} ${alias} WHERE ${whereClause}`;
-        }
-        // belongsTo / hasOne — return single object
-        return `SELECT ${jsonObj} FROM ${qTarget} ${alias} WHERE ${whereClause} LIMIT 1`;
-    }
-    /**
-     * 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.
-     */
-    getColumnPgType(column) {
-        return this.columnPgTypeMap.get(column) ?? 'text';
-    }
-    /**
-     * Get the Postgres base element type for an array column.
-     * E.g. '_text' → 'text', '_int4' → 'integer'
-     */
-    getArrayElementType(pgType) {
-        const baseType = pgType.startsWith('_') ? pgType.slice(1) : pgType;
-        const typeMap = {
-            int2: 'smallint',
-            int4: 'integer',
-            int8: 'bigint',
-            float4: 'real',
-            float8: 'double precision',
-            bool: 'boolean',
-            text: 'text',
-            varchar: 'text',
-            uuid: 'uuid',
-            timestamptz: 'timestamptz',
-            timestamp: 'timestamp',
-            jsonb: 'jsonb',
-            json: 'json',
-        };
-        return typeMap[baseType] ?? 'text';
-    }
-    /**
-     * Build SQL clauses for JSONB filter operators on a column.
-     * Supports: path, equals, contains, hasKey.
-     */
-    buildJsonFilterClauses(column, filter, params) {
-        const clauses = [];
-        if (filter.path !== undefined && filter.equals !== undefined) {
-            // Path access + equals: column #>> $N::text[] = $M
-            params.push(filter.path);
-            const pathParam = params.length;
-            params.push(String(filter.equals));
-            clauses.push(`${column} #>> $${pathParam}::text[] = $${params.length}`);
-        }
-        else if (filter.equals !== undefined) {
-            // Containment equality: column @> $N::jsonb
-            params.push(JSON.stringify(filter.equals));
-            clauses.push(`${column} @> $${params.length}::jsonb`);
-        }
-        if (filter.contains !== undefined) {
-            // Containment: column @> $N::jsonb
-            params.push(JSON.stringify(filter.contains));
-            clauses.push(`${column} @> $${params.length}::jsonb`);
-        }
-        if (filter.hasKey !== undefined) {
-            // Key existence: column ? $N
-            params.push(filter.hasKey);
-            clauses.push(`${column} ? $${params.length}`);
-        }
-        return clauses;
-    }
-    /**
-     * Build SQL clauses for Array filter operators on a column.
-     * Supports: has, hasEvery, hasSome, isEmpty.
-     */
-    buildArrayFilterClauses(column, filter, params, pgType) {
-        const clauses = [];
-        const elementType = this.getArrayElementType(pgType);
-        if (filter.has !== undefined) {
-            // value = ANY(column)
-            params.push(filter.has);
-            clauses.push(`$${params.length} = ANY(${column})`);
-        }
-        if (filter.hasEvery !== undefined) {
-            // column @> ARRAY[...]::type[]
-            params.push(filter.hasEvery);
-            clauses.push(`${column} @> $${params.length}::${elementType}[]`);
-        }
-        if (filter.hasSome !== undefined) {
-            // column && ARRAY[...]::type[]
-            params.push(filter.hasSome);
-            clauses.push(`${column} && $${params.length}::${elementType}[]`);
-        }
-        if (filter.isEmpty === true) {
-            // array_length(column, 1) IS NULL
-            clauses.push(`array_length(${column}, 1) IS NULL`);
-        }
-        else if (filter.isEmpty === false) {
-            // array_length(column, 1) IS NOT NULL
-            clauses.push(`array_length(${column}, 1) IS NOT NULL`);
-        }
-        return clauses;
-    }
-    /**
-     * 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.
-     */
-    getColumnArrayType(column) {
-        const arrayType = this.columnArrayTypeMap.get(column);
-        if (arrayType)
-            return arrayType;
-        // Fallback heuristic for unknown columns
-        if (column === 'id' || column.endsWith('_id'))
-            return 'bigint[]';
-        if (column.endsWith('_at'))
-            return 'timestamptz[]';
-        return 'text[]';
-    }
-}
-//# sourceMappingURL=query.js.map