turbine-orm 0.5.0 → 0.7.0

package/dist/query.js

@@ -1,16 +1,17 @@
 /**
- * @batadata/turbine — Query builder
+ * turbine-orm — Query builder
  *
  * Each table accessor (db.users, db.posts, etc.) returns a QueryInterface<T>
  * that builds parameterized SQL and executes it through the connection pool.
  *
  * Nested relations use json_build_object + json_agg subqueries for single-query
- * resolution — the technique that benchmarks proved 2-3x faster than Prisma.
+ * resolution — a PostgreSQL-native approach that eliminates N+1 query patterns.
  *
  * Schema-driven: all column names, types, and relations come from introspected
  * metadata — nothing is hardcoded.
  */
-import { snakeToCamel, camelToSnake } from './schema.js';
+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
 // ---------------------------------------------------------------------------
@@ -42,22 +43,41 @@ function escapeLike(value) {
 }
 /** 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',
+    '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) {
+    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']);
 /** 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) {
+    if (value === null ||
+        value === undefined ||
+        typeof value !== 'object' ||
+        Array.isArray(value) ||
+        value instanceof Date) {
         return false;
     }
     const keys = Object.keys(value);
@@ -67,7 +87,11 @@ function isJsonFilter(value) {
 const ARRAY_OPERATOR_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) {
+    if (value === null ||
+        value === undefined ||
+        typeof value !== 'object' ||
+        Array.isArray(value) ||
+        value instanceof Date) {
         return false;
     }
     const keys = Object.keys(value);
@@ -108,7 +132,9 @@ class LRUCache {
         }
         this.cache.set(key, value);
     }
-    get size() { return this.cache.size; }
+    get size() {
+        return this.cache.size;
+    }
 }
 export class QueryInterface {
     pool;
@@ -129,7 +155,7 @@ export class QueryInterface {
         this.schema = schema;
         const meta = schema.tables[table];
         if (!meta) {
-            throw new Error(`[turbine] Unknown table "${table}". Available: ${Object.keys(schema.tables).join(', ')}`);
+            throw new ValidationError(`[turbine] Unknown table "${table}". Available: ${Object.keys(schema.tables).join(', ')}`);
         }
         this.tableMeta = meta;
         this.middlewares = middlewares ?? [];
@@ -146,18 +172,27 @@ export class QueryInterface {
     /**
      * 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) {
         if (!timeout) {
-            return this.pool.query(sql, params);
+            try {
+                return await this.pool.query(sql, params);
+            }
+            catch (err) {
+                throw wrapPgError(err);
+            }
         }
         let timer;
         const timeoutPromise = new Promise((_, reject) => {
-            timer = setTimeout(() => reject(new Error(`[turbine] Query timed out after ${timeout}ms`)), timeout);
+            timer = setTimeout(() => reject(new TimeoutError(timeout)), timeout);
         });
         try {
             return await Promise.race([this.pool.query(sql, params), timeoutPromise]);
         }
+        catch (err) {
+            throw wrapPgError(err);
+        }
         finally {
             clearTimeout(timer);
         }
@@ -188,18 +223,6 @@ export class QueryInterface {
         };
         return next(params);
     }
-    /**
-     * Generate a cache key for a query shape.
-     * Same where-keys + same with-clause = same SQL template.
-     */
-    cacheKey(op, whereKeys, withClause, extra) {
-        let key = `${op}:${whereKeys.sort().join(',')}`;
-        if (withClause)
-            key += `:w=${JSON.stringify(Object.keys(withClause).sort())}`;
-        if (extra)
-            key += `:${extra}`;
-        return key;
-    }
     // -------------------------------------------------------------------------
     // findUnique
     // -------------------------------------------------------------------------
@@ -215,10 +238,11 @@ export class QueryInterface {
         const whereObj = args.where;
         // 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'] && whereKeys.every((k) => {
-            const v = whereObj[k];
-            return v !== null && !isWhereOperator(v);
-        });
+        const isSimpleWhere = !whereObj.OR &&
+            whereKeys.every((k) => {
+                const v = whereObj[k];
+                return v !== null && !isWhereOperator(v);
+            });
         // For simple queries (no nested with, no operators), use cached SQL template
         if (!args.with && isSimpleWhere) {
             const colKey = columnsList ? columnsList.join(',') : '*';
@@ -229,9 +253,7 @@ export class QueryInterface {
                 const qt = quoteIdent(this.table);
                 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}.*`;
+                const selectExpr = columnsList ? columnsList.map((c) => `${qt}.${quoteIdent(c)}`).join(', ') : `${qt}.*`;
                 sql = `SELECT ${selectExpr} FROM ${qt}${whereSql} LIMIT 1`;
                 this.sqlCache.set(ck, sql);
             }
@@ -249,9 +271,7 @@ export class QueryInterface {
         const { sql: whereSql, params } = this.buildWhere(args.where);
         if (!args.with) {
             const qt = quoteIdent(this.table);
-            const selectExpr = columnsList
-                ? columnsList.map((c) => `${qt}.${quoteIdent(c)}`).join(', ')
-                : `${qt}.*`;
+            const selectExpr = columnsList ? columnsList.map((c) => `${qt}.${quoteIdent(c)}`).join(', ') : `${qt}.*`;
             const sql = `SELECT ${selectExpr} FROM ${qt}${whereSql} LIMIT 1`;
             return {
                 sql,
@@ -292,9 +312,7 @@ export class QueryInterface {
         });
     }
     buildFindMany(args) {
-        const { sql: whereSql, params } = args?.where
-            ? this.buildWhere(args.where)
-            : { sql: '', params: [] };
+        const { sql: whereSql, params } = args?.where ? this.buildWhere(args.where) : { sql: '', params: [] };
         const columnsList = this.resolveColumns(args?.select, args?.omit);
         const qt = quoteIdent(this.table);
         // Distinct support
@@ -351,13 +369,68 @@ export class QueryInterface {
         return {
             sql,
             params,
-            transform: (result) => result.rows.map((row) => args?.with
-                ? this.parseNestedRow(row, this.table)
-                : this.parseRow(row, this.table)),
+            transform: (result) => result.rows.map((row) => args?.with ? this.parseNestedRow(row, this.table) : this.parseRow(row, this.table)),
             tag: `${this.table}.findMany`,
         };
     }
     // -------------------------------------------------------------------------
+    // 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.
+     *
+     * Uses DECLARE CURSOR within a dedicated transaction on a single pooled connection.
+     * The cursor is automatically closed and the connection released when iteration
+     * completes or is terminated early (e.g. `break` from `for await`).
+     *
+     * @example
+     * ```ts
+     * for await (const user of db.users.findManyStream({ where: { orgId: 1 }, batchSize: 500 })) {
+     *   process.stdout.write(`${user.email}\n`);
+     * }
+     * ```
+     */
+    async *findManyStream(args) {
+        const batchSize = Math.max(1, Math.floor(Number(args?.batchSize ?? 100)));
+        const deferred = this.buildFindMany(args);
+        const hasRelations = !!args?.with;
+        // 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) {
@@ -399,7 +472,11 @@ export class QueryInterface {
             transform: (result) => {
                 const row = inner.transform(result);
                 if (row === null) {
-                    throw new Error('Record not found');
+                    throw new NotFoundError({
+                        table: this.table,
+                        where: args?.where,
+                        operation: 'findFirstOrThrow',
+                    });
                 }
                 return row;
             },
@@ -424,7 +501,11 @@ export class QueryInterface {
             transform: (result) => {
                 const row = inner.transform(result);
                 if (row === null) {
-                    throw new Error('Record not found');
+                    throw new NotFoundError({
+                        table: this.table,
+                        where: args.where,
+                        operation: 'findUniqueOrThrow',
+                    });
                 }
                 return row;
             },
@@ -452,8 +533,13 @@ export class QueryInterface {
             params,
             transform: (result) => {
                 const row = result.rows[0];
-                if (!row)
-                    throw new Error('[turbine] Expected a row but query returned none');
+                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`,
@@ -518,23 +604,26 @@ export class QueryInterface {
     }
     buildUpdate(args) {
         const setEntries = Object.entries(args.data).filter(([, v]) => v !== undefined);
-        // Build SET params first
+        // Build SET params first (supports atomic operators: set/increment/decrement/multiply/divide)
         const params = [];
-        const setClauses = setEntries.map(([k, v]) => {
-            params.push(v);
-            return `${this.toSqlColumn(k)} = $${params.length}`;
-        });
+        const setClauses = setEntries.map(([k, v]) => this.buildSetClause(k, v, params));
         // Build WHERE using the shared params array (continues numbering after SET params)
         const whereClause = this.buildWhereClause(args.where, params);
         const whereSql = whereClause ? ` WHERE ${whereClause}` : '';
+        this.assertMutationHasPredicate('update', whereSql, args.allowFullTableScan);
         const sql = `UPDATE ${quoteIdent(this.table)} SET ${setClauses.join(', ')}${whereSql} RETURNING *`;
         return {
             sql,
             params,
             transform: (result) => {
                 const row = result.rows[0];
-                if (!row)
-                    throw new Error('[turbine] Expected a row but query returned none');
+                if (!row) {
+                    throw new NotFoundError({
+                        table: this.table,
+                        where: args.where,
+                        operation: 'update',
+                    });
+                }
                 return this.parseRow(row, this.table);
             },
             tag: `${this.table}.update`,
@@ -552,14 +641,20 @@ export class QueryInterface {
     }
     buildDelete(args) {
         const { sql: whereSql, params } = this.buildWhere(args.where);
+        this.assertMutationHasPredicate('delete', whereSql, args.allowFullTableScan);
         const sql = `DELETE FROM ${quoteIdent(this.table)}${whereSql} RETURNING *`;
         return {
             sql,
             params,
             transform: (result) => {
                 const row = result.rows[0];
-                if (!row)
-                    throw new Error('[turbine] Expected a row but query returned none');
+                if (!row) {
+                    throw new NotFoundError({
+                        table: this.table,
+                        where: args.where,
+                        operation: 'delete',
+                    });
+                }
                 return this.parseRow(row, this.table);
             },
             tag: `${this.table}.delete`,
@@ -602,8 +697,14 @@ export class QueryInterface {
             params,
             transform: (result) => {
                 const row = result.rows[0];
-                if (!row)
-                    throw new Error('[turbine] Expected a row but query returned none');
+                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`,
@@ -621,15 +722,13 @@ export class QueryInterface {
     }
     buildUpdateMany(args) {
         const setEntries = Object.entries(args.data).filter(([, v]) => v !== undefined);
-        // Build SET params first
+        // Build SET params first (supports atomic operators: set/increment/decrement/multiply/divide)
         const params = [];
-        const setClauses = setEntries.map(([k, v]) => {
-            params.push(v);
-            return `${this.toSqlColumn(k)} = $${params.length}`;
-        });
+        const setClauses = setEntries.map(([k, v]) => this.buildSetClause(k, v, params));
         // Build WHERE using the shared params array (continues numbering after SET params)
         const whereClause = this.buildWhereClause(args.where, params);
         const whereSql = whereClause ? ` WHERE ${whereClause}` : '';
+        this.assertMutationHasPredicate('updateMany', whereSql, args.allowFullTableScan);
         const sql = `UPDATE ${quoteIdent(this.table)} SET ${setClauses.join(', ')}${whereSql}`;
         return {
             sql,
@@ -650,6 +749,7 @@ export class QueryInterface {
     }
     buildDeleteMany(args) {
         const { sql: whereSql, params } = this.buildWhere(args.where);
+        this.assertMutationHasPredicate('deleteMany', whereSql, args.allowFullTableScan);
         const sql = `DELETE FROM ${quoteIdent(this.table)}${whereSql}`;
         return {
             sql,
@@ -669,9 +769,7 @@ export class QueryInterface {
         });
     }
     buildCount(args) {
-        const { sql: whereSql, params } = args?.where
-            ? this.buildWhere(args.where)
-            : { sql: '', params: [] };
+        const { sql: whereSql, params } = args?.where ? this.buildWhere(args.where) : { sql: '', params: [] };
         const sql = `SELECT COUNT(*)::int AS count FROM ${quoteIdent(this.table)}${whereSql}`;
         return {
             sql,
@@ -691,11 +789,17 @@ export class QueryInterface {
         });
     }
     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: [] };
+        const { sql: whereSql, params } = args.where ? this.buildWhere(args.where) : { sql: '', params: [] };
         // Build SELECT expressions: group-by columns + aggregate functions
         const selectExprs = [...groupCols];
         // _count
@@ -708,7 +812,7 @@ export class QueryInterface {
             for (const [field, enabled] of Object.entries(args._sum)) {
                 if (enabled) {
                     const col = this.toColumn(field);
-                    selectExprs.push(`SUM(${quoteIdent(col)}) AS _sum_${col}`);
+                    selectExprs.push(`SUM(${quoteIdent(col)}) AS ${quoteIdent('_sum_' + col)}`);
                 }
             }
         }
@@ -717,7 +821,7 @@ export class QueryInterface {
             for (const [field, enabled] of Object.entries(args._avg)) {
                 if (enabled) {
                     const col = this.toColumn(field);
-                    selectExprs.push(`AVG(${quoteIdent(col)})::float AS _avg_${col}`);
+                    selectExprs.push(`AVG(${quoteIdent(col)})::float AS ${quoteIdent('_avg_' + col)}`);
                 }
             }
         }
@@ -726,7 +830,7 @@ export class QueryInterface {
             for (const [field, enabled] of Object.entries(args._min)) {
                 if (enabled) {
                     const col = this.toColumn(field);
-                    selectExprs.push(`MIN(${quoteIdent(col)}) AS _min_${col}`);
+                    selectExprs.push(`MIN(${quoteIdent(col)}) AS ${quoteIdent('_min_' + col)}`);
                 }
             }
         }
@@ -735,7 +839,7 @@ export class QueryInterface {
             for (const [field, enabled] of Object.entries(args._max)) {
                 if (enabled) {
                     const col = this.toColumn(field);
-                    selectExprs.push(`MAX(${quoteIdent(col)}) AS _max_${col}`);
+                    selectExprs.push(`MAX(${quoteIdent(col)}) AS ${quoteIdent('_max_' + col)}`);
                 }
             }
         }
@@ -818,9 +922,26 @@ export class QueryInterface {
         });
     }
     buildAggregate(args) {
-        const { sql: whereSql, params } = args.where
-            ? this.buildWhere(args.where)
-            : { sql: '', params: [] };
+        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) {
@@ -830,7 +951,7 @@ export class QueryInterface {
             for (const [field, enabled] of Object.entries(args._count)) {
                 if (enabled) {
                     const col = this.toColumn(field);
-                    selectExprs.push(`COUNT(${quoteIdent(col)})::int AS _count_${col}`);
+                    selectExprs.push(`COUNT(${quoteIdent(col)})::int AS ${quoteIdent('_count_' + col)}`);
                 }
             }
         }
@@ -839,7 +960,7 @@ export class QueryInterface {
             for (const [field, enabled] of Object.entries(args._sum)) {
                 if (enabled) {
                     const col = this.toColumn(field);
-                    selectExprs.push(`SUM(${quoteIdent(col)}) AS _sum_${col}`);
+                    selectExprs.push(`SUM(${quoteIdent(col)}) AS ${quoteIdent('_sum_' + col)}`);
                 }
             }
         }
@@ -848,7 +969,7 @@ export class QueryInterface {
             for (const [field, enabled] of Object.entries(args._avg)) {
                 if (enabled) {
                     const col = this.toColumn(field);
-                    selectExprs.push(`AVG(${quoteIdent(col)})::float AS _avg_${col}`);
+                    selectExprs.push(`AVG(${quoteIdent(col)})::float AS ${quoteIdent('_avg_' + col)}`);
                 }
             }
         }
@@ -857,7 +978,7 @@ export class QueryInterface {
             for (const [field, enabled] of Object.entries(args._min)) {
                 if (enabled) {
                     const col = this.toColumn(field);
-                    selectExprs.push(`MIN(${quoteIdent(col)}) AS _min_${col}`);
+                    selectExprs.push(`MIN(${quoteIdent(col)}) AS ${quoteIdent('_min_' + col)}`);
                 }
             }
         }
@@ -866,7 +987,7 @@ export class QueryInterface {
             for (const [field, enabled] of Object.entries(args._max)) {
                 if (enabled) {
                     const col = this.toColumn(field);
-                    selectExprs.push(`MAX(${quoteIdent(col)}) AS _max_${col}`);
+                    selectExprs.push(`MAX(${quoteIdent(col)}) AS ${quoteIdent('_max_' + col)}`);
                 }
             }
         }
@@ -978,6 +1099,67 @@ export class QueryInterface {
     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}`;
+    }
     /** Build WHERE clause from a where object (supports operators, NULL, OR) */
     buildWhere(where) {
         const params = [];
@@ -986,6 +1168,22 @@ export class QueryInterface {
             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.
@@ -1222,8 +1420,12 @@ export class QueryInterface {
     }
     /** 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}`;
         })
@@ -1272,6 +1474,7 @@ export class QueryInterface {
                         parsed[relName] = JSON.parse(rawValue);
                     }
                     catch {
+                        console.warn(`[turbine] Warning: Failed to parse JSON for relation "${relName}" on table "${this.table}". Using raw value.`);
                         parsed[relName] = rawValue;
                     }
                 }
@@ -1291,52 +1494,173 @@ export class QueryInterface {
         return parsed;
     }
     /**
-     * Build a SELECT clause with nested relation subqueries.
+     * Build a SELECT clause that includes both base columns and nested relation subqueries.
+     *
+     * For each relation specified in the `with` clause, this method generates a correlated
+     * subquery using PostgreSQL's `json_agg(json_build_object(...))` pattern. The result
+     * is a single SQL SELECT clause that resolves the full object tree in one query --
+     * no N+1 problem.
      *
-     * Uses json_build_object + json_agg — the same approach as the raw-pg benchmark
-     * queries. Generates a single SQL statement that resolves the full object tree.
+     * **How it works:**
+     * 1. Resolves the base columns for the root table (all columns, or a subset via `columnsList`).
+     * 2. Iterates over each key in the `with` clause, looking up the relation definition.
+     * 3. For each relation, delegates to {@link buildRelationSubquery} to generate a
+     *    correlated subquery that returns JSON (array for hasMany, object for belongsTo/hasOne).
+     * 4. Each subquery is aliased as the relation name in the final SELECT.
      *
-     * Nested where values are parameterized via the shared params array to prevent
-     * SQL injection.
+     * **aliasCounter:** A shared `{ n: number }` object is passed through all nesting levels.
+     * Each call to `buildRelationSubquery` increments it to produce unique table aliases
+     * (`t0`, `t1`, `t2`, ...) across arbitrarily deep relation trees, preventing alias
+     * collisions in the generated SQL.
+     *
+     * **Example output:**
+     * ```sql
+     * "users"."id", "users"."name", "users"."email",
+     * (SELECT COALESCE(json_agg(json_build_object('id', t0."id", 'title', t0."title")), '[]'::json)
+     *   FROM "posts" t0 WHERE t0."user_id" = "users"."id") AS "posts"
+     * ```
+     *
+     * @param table - The root table name (e.g. `"users"`).
+     * @param withClause - An object mapping relation names to their include specs
+     *                     (`true` for default inclusion, or `WithOptions` for select/omit/where/orderBy/limit).
+     * @param params - Shared parameter array for parameterized values (`$1`, `$2`, ...).
+     *                 Nested where/limit values are pushed here to prevent SQL injection.
+     * @param columnsList - Optional subset of columns to include in the SELECT. When `null`
+     *                      or omitted, all columns from the table's schema metadata are used.
+     * @param depth - Current nesting depth, passed through to {@link buildRelationSubquery}
+     *                for circular-relation detection. Defaults to `0` at the top level.
+     * @param path - Breadcrumb trail of relation names traversed so far, used in error
+     *               messages when circular or too-deep nesting is detected.
+     * @returns A complete SELECT clause string (without the `SELECT` keyword) containing
+     *          base columns and relation subqueries.
      */
-    buildSelectWithRelations(table, withClause, params, columnsList) {
+    buildSelectWithRelations(table, withClause, params, columnsList, depth, path) {
         const meta = this.schema.tables[table];
         if (!meta)
-            throw new Error(`[turbine] Unknown table "${table}"`);
+            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 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 Error(`[turbine] Unknown relation "${relName}" on table "${table}". ` +
+                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);
+            const subquery = this.buildRelationSubquery(relDef, relSpec, params, table, aliasCounter, depth, path);
             relationSelects.push(`(${subquery}) AS ${quoteIdent(relName)}`);
         }
         return [baseCols, ...relationSelects].join(', ');
     }
     /**
-     * Build a json_agg subquery for a relation.
+     * Generate a correlated subquery that returns JSON for a single relation.
+     *
+     * This is the core of Turbine's single-query nested relation strategy. For a given
+     * relation (e.g. `posts` on a `users` query), it produces a self-contained SQL subquery
+     * that PostgreSQL evaluates per parent row, returning either a JSON array (hasMany) or
+     * a single JSON object (belongsTo / hasOne).
+     *
+     * ### Algorithm overview
      *
-     * All user-supplied values in nested where clauses are parameterized
-     * through the shared params array — no string interpolation.
+     * 1. **Alias generation:** Allocates a unique alias (`t0`, `t1`, ...) from the shared
+     *    `aliasCounter` so that deeply nested subqueries never collide.
      *
-     * @param parentRef - The alias (or table name) of the parent in the outer query.
-     *                    Used for the correlated WHERE clause: `child.fk = parentRef.pk`.
-     * @param aliasCounter - Shared counter for generating unique aliases across nested levels.
+     * 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) {
+    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 Error(`[turbine] Unknown relation target "${targetTable}"`);
+            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
@@ -1355,17 +1679,23 @@ export class QueryInterface {
         }
         // Build json_build_object pairs for resolved columns
         const jsonPairs = targetColumns.map((col) => `'${escSingleQuote(targetMeta.reverseColumnMap[col] ?? snakeToCamel(col))}', ${alias}.${quoteIdent(col)}`);
-        // Nested relations?
-        if (spec !== true && spec.with) {
+        // 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 Error(`[turbine] Unknown relation "${nestedRelName}" on table "${targetTable}". ` +
+                    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);
-                jsonPairs.push(`'${escSingleQuote(nestedRelName)}', COALESCE((${nestedSubquery}), '[]'::json)`);
+                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(', ')})`;
@@ -1379,7 +1709,7 @@ export class QueryInterface {
                 .map(([k, dir]) => {
                 const col = camelToSnake(k);
                 if (!targetMeta.allColumns.includes(col)) {
-                    throw new Error(`[turbine] Unknown column "${k}" in orderBy for table "${targetTable}"`);
+                    throw new ValidationError(`[turbine] Unknown column "${k}" in orderBy for table "${targetTable}"`);
                 }
                 const safeDir = dir.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
                 return `${alias}.${quoteIdent(col)} ${safeDir}`;
@@ -1402,7 +1732,7 @@ export class QueryInterface {
             for (const [k, v] of Object.entries(spec.where)) {
                 const col = camelToSnake(k);
                 if (!targetMeta.allColumns.includes(col)) {
-                    throw new Error(`[turbine] Unknown column "${k}" in where for table "${targetTable}"`);
+                    throw new ValidationError(`[turbine] Unknown column "${k}" in where for table "${targetTable}"`);
                 }
                 params.push(v);
                 whereClause += ` AND ${alias}.${quoteIdent(col)} = $${params.length}`;
@@ -1424,14 +1754,17 @@ export class QueryInterface {
                 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)}`);
-                // Re-add nested relation subqueries referencing innerAlias
+                // Build nested relation subqueries referencing innerAlias
                 if (spec !== true && spec.with) {
-                    for (const [nestedRelName] of Object.entries(spec.with)) {
+                    for (const [nestedRelName, nestedSpec] of Object.entries(spec.with)) {
                         const nestedRelDef = targetMeta.relations[nestedRelName];
-                        if (nestedRelDef) {
-                            const nestedSub = this.buildRelationSubquery(nestedRelDef, spec.with[nestedRelName], params, innerAlias, aliasCounter);
-                            innerJsonPairs.push(`'${escSingleQuote(nestedRelName)}', COALESCE((${nestedSub}), '[]'::json)`);
+                        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(', ')})`;