turbine-orm 0.50.0 → 0.51.0

package/dist/query/builder.js

@@ -1,14 +1,14 @@
 /**
- * turbine-orm — 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 — a PostgreSQL-native approach that eliminates N+1 query patterns.
+ * 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.
+ * metadata, nothing is hardcoded.
  */
 import { postgresDialect } from '../dialect.js';
 import { NotFoundError, TimeoutError, UnsupportedFeatureError, ValidationError, wrapPgError } from '../errors.js';
@@ -20,7 +20,7 @@ import { defaultProjectionFields, includeKeysForBatching, loadRelationsBatched,
 import { expandCompoundUniqueWhere } from './compound-unique.js';
 import { isJsonPathOrderBy, isOrderBySpec, isRelationPickOrderBy, isVectorOrderBy, isWhereOperator, orderByEntries, sortedEntries, } from './filters.js';
 import * as relationsMod from './relations.js';
-import { LRUCache, ownLookup, parseDbDate, sqlToPreparedName } from './utils.js';
+import { LRUCache, ownLookup, parseDbDate, sqlToPreparedName, unknownFieldMessage, } from './utils.js';
 import { shouldWarnOnce, WARN_NS } from './warn-registry.js';
 import * as whereMod from './where.js';
 import * as writesMod from './writes.js';
@@ -239,7 +239,7 @@ function isEmptyOrderBy(orderBy) {
     }
     return orderBy === undefined || orderBy === null;
 }
-// biome-ignore lint/complexity/noBannedTypes: {} means "no relations known" — intentional for untyped table access
+// biome-ignore lint/complexity/noBannedTypes: {} means "no relations known", intentional for untyped table access
 export class QueryInterface {
     pool;
     table;
@@ -263,6 +263,7 @@ export class QueryInterface {
     middlewares;
     defaultLimit;
     warnOnUnlimited;
+    scopedConnect;
     utcTimestamps;
     preparedStatementsEnabled;
     /**
@@ -310,7 +311,7 @@ export class QueryInterface {
     globalFilters;
     /**
      * Tracks tables that have already triggered an unlimited-query warning so
-     * the user is not spammed once per row. Per-instance state — each
+     * 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
@@ -325,7 +326,7 @@ export class QueryInterface {
     columnArrayTypeMap;
     /**
      * Columns whose type lives in a DIFFERENT schema than the introspected one
-     * (ColumnMetadata.pgTypeSchema is recorded only in that case) — such columns
+     * (ColumnMetadata.pgTypeSchema is recorded only in that case), such columns
      * must never receive this schema's `::"enum"` cast (see enumTypeForColumn).
      */
     crossSchemaTypeColumns;
@@ -339,7 +340,7 @@ export class QueryInterface {
     camelDateFieldCache = new Map();
     /** True when this QI runs inside an active transaction (set via _txScoped option). */
     txScoped;
-    /** Original options reference — forwarded to child QIs in nested writes. */
+    /** Original options reference, forwarded to child QIs in nested writes. */
     options;
     /** Set by executeWithMiddleware so queryWithTimeout can include it in events. */
     currentAction = 'raw';
@@ -355,7 +356,7 @@ export class QueryInterface {
     /**
      * The active query's `skipGlobalFilters` opt-out, set at the top of each
      * `build*` method and read deep in the (synchronous) SQL-build + param-collect
-     * tree — so relation subqueries, relation filters, `_count`, and relation
+     * tree, so relation subqueries, relation filters, `_count`, and relation
      * `orderBy` all see it without threading it through dozens of signatures.
      * Only load-bearing when {@link globalFilters} is configured; build+collect are
      * synchronous per call, so this transient is never observed across an await.
@@ -399,8 +400,8 @@ export class QueryInterface {
         // `warnOnUnlimited: false`, per table with `warnOnUnlimited: { users:
         // false }` (unlisted tables keep the default), or per call via
         // `findMany({ warnOnUnlimited: false })`.
-        // Per-table maps accept BOTH key forms — the snake_case table name
-        // (`user_profiles`) and the camelCase accessor (`userProfiles`) — since
+        // Per-table maps accept BOTH key forms, the snake_case table name
+        // (`user_profiles`) and the camelCase accessor (`userProfiles`), since
         // users naturally key by the accessor they type everywhere else. The
         // snake_case entry wins when both are present.
         const warnOpt = options?.warnOnUnlimited;
@@ -408,6 +409,7 @@ export class QueryInterface {
             typeof warnOpt === 'object' && warnOpt !== null
                 ? (warnOpt[table] ?? warnOpt[snakeToCamel(table)]) !== false
                 : warnOpt !== false;
+        this.scopedConnect = options?.scopedConnect === true;
         this.utcTimestamps = options?.utcTimestamps !== false;
         this.preparedStatementsEnabled = options?.preparedStatements ?? true;
         // SQL template cache capacity. `sqlCacheSize: 0` disables caching entirely
@@ -518,7 +520,7 @@ export class QueryInterface {
      * SQLite use ` LIMIT <ph>` and/or ` OFFSET <ph>`. SQL Server has no `LIMIT`, so
      * its dialect implements {@link Dialect.buildLimitOffset} to emit
      * `[ORDER BY (SELECT NULL)] OFFSET <off> ROWS [FETCH NEXT <lim> ROWS ONLY]`.
-     * Param-push order (limit before offset) is owned by the caller and unchanged —
+     * Param-push order (limit before offset) is owned by the caller and unchanged -
      * this only varies the SQL text, so PG output stays byte-identical.
      */
     buildPagination(limitPh, offsetPh, hasOrderBy) {
@@ -948,7 +950,7 @@ export class QueryInterface {
      * join for a to-one relation.
      *
      * Resolution order:
-     *   1. an explicit `autoToOneJoinMaxRows` — an instruction, used verbatim
+     *   1. an explicit `autoToOneJoinMaxRows`, an instruction, used verbatim
      *      (no clamping: the caller has measured their own workload);
      *   2. the configured `autoRoundTripMs` divided by
      *      {@link AUTO_JOIN_PENALTY_MS_PER_ROW}, clamped to
@@ -962,7 +964,7 @@ export class QueryInterface {
      * put, so any single constant is wrong for someone by more than the margin it
      * is trying to save. Placing the switch AT the break-even is also what removes
      * the old cliff: two plans that cost the same at the boundary make the regret
-     * there ~1.0x, rising only as the true row count moves away from it — where
+     * there ~1.0x, rising only as the true row count moves away from it, where
      * the previous fixed 1000 put its WORST case (1.44x measured) immediately
      * below its own switch point.
      *
@@ -1126,7 +1128,7 @@ export class QueryInterface {
      * Build the {@link RelationLoadContext} the batched loader needs, closing over
      * this interface's pool/dialect/executor. Child readers are constructed on the
      * SAME pool (so they join an active transaction) with `defaultLimit` cleared
-     * and unlimited-warnings silenced — a relation load must fetch every matching
+     * and unlimited-warnings silenced, a relation load must fetch every matching
      * child, and the per-relation `limit` is applied client-side by the loader.
      */
     batchedContext(timeout, skip, includePii) {
@@ -1358,7 +1360,7 @@ export class QueryInterface {
     async queryWithTimeout(sql, params, timeout, preparedName) {
         const start = performance.now();
         const action = this.currentAction;
-        // Build the query argument — use object form with `name` for prepared
+        // 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
@@ -1401,7 +1403,7 @@ export class QueryInterface {
      *
      *   - `'returning'` / `'output'`: the statement returns its own affected rows
      *     (`RETURNING *` / `OUTPUT INSERTED.*`). Byte-identical to the historical
-     *     single `queryWithTimeout` + `transform(result)` path — the PostgreSQL
+     *     single `queryWithTimeout` + `transform(result)` path, the PostgreSQL
      *     route is unchanged.
      *   - `'reselect'`: the engine cannot return rows from a write, so the build
      *     method attached a {@link DeferredQuery.reselect} plan that runs the
@@ -1455,7 +1457,7 @@ export class QueryInterface {
      *
      * Middleware can inspect and log query parameters, measure timing, and
      * transform the result returned by `next()`. Note: query SQL is generated
-     * BEFORE middleware runs — `params.args` is a read-only snapshot, and
+     * BEFORE middleware runs, `params.args` is a read-only snapshot, and
      * mutating it does NOT change the executed SQL. Cross-cutting filters
      * (e.g. soft deletes) belong in the query itself: pass an explicit
      * `where: { deletedAt: null }` or wrap the table accessor in a small helper.
@@ -1473,7 +1475,7 @@ export class QueryInterface {
                 const mw = this.middlewares[index++];
                 return mw(p, next);
             }
-            // End of chain — execute the actual query
+            // End of chain, execute the actual query
             return executor();
         };
         return next(params);
@@ -1525,7 +1527,7 @@ export class QueryInterface {
         stripFields([entity], proj.strip);
         return entity;
     }
-    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
+    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause", matches TypedWithClause default
     buildFindUnique(args) {
         this.currentSkip = args.skipGlobalFilters;
         // Prisma compound-unique selector expansion (before global-filter merge and
@@ -1559,7 +1561,7 @@ export class QueryInterface {
         const ck = `fu:${whereFingerprint}|c=${colKey}|w=${withFp}|pii=${includePii ? 1 : 0}${this.globalFilterCacheSegment()}`;
         const params = [];
         // Check if all where values are simple (plain equality, no operators/null/OR).
-        // Keys are sorted to match fingerprintWhere — insertion order here would let
+        // Keys are sorted to match fingerprintWhere, insertion order here would let
         // permuted where literals share a cache entry with misaligned params.
         const whereKeys = Object.keys(whereObj)
             .filter((k) => whereObj[k] !== undefined)
@@ -1663,7 +1665,7 @@ export class QueryInterface {
             if (args?.with) {
                 const depth = this.measureWithDepth(args.with);
                 if (depth > 5 && shouldWarnOnce(WARN_NS.deepWith, this.table)) {
-                    console.warn(`[turbine] Deep with clause (depth ${depth}) on "${this.tableMeta.name}" — ` +
+                    console.warn(`[turbine] Deep with clause (depth ${depth}) on "${this.tableMeta.name}", ` +
                         'consider splitting into separate queries for better performance.');
                 }
             }
@@ -1763,12 +1765,53 @@ export class QueryInterface {
         const hasExplicitLimit = args?.limit !== undefined || args?.take !== undefined || args?.cursor !== undefined;
         if (hasExplicitLimit)
             return;
+        if (this.whereMatchesAtMostOneRow(args?.where))
+            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 silence with `warnOnUnlimited: false` (per call, per table, or in config).');
     }
+    /**
+     * Whether `where` can match at most one row, because it pins every column of
+     * the primary key or of some unique column set to a literal value.
+     *
+     * The unlimited-read warning is about accidentally fetching a whole table,
+     * so firing it on `findMany({ where: { id: 1 } })` is noise: that query is
+     * bounded by a uniqueness constraint just as firmly as by a `limit`, and a
+     * warning that cries wolf on correct code trains people to disable it.
+     *
+     * Deliberately conservative. Only DIRECT equality on a literal counts: an
+     * operator object (`{ id: { in: [...] } }`, `{ id: { gt: 1 } }`) can match
+     * many rows, and any `OR` / `NOT` / relation filter can widen the result, so
+     * anything that is not a plain scalar equality leaves the warning in place.
+     * A compound-unique SELECTOR (`{ orgId_userId: {...} }`) is expanded first,
+     * so both spellings are recognized.
+     */
+    whereMatchesAtMostOneRow(where) {
+        if (where === null || typeof where !== 'object' || Array.isArray(where))
+            return false;
+        const expanded = expandCompoundUniqueWhere(this.tableMeta, where);
+        const pinned = new Set();
+        for (const [field, value] of Object.entries(expanded)) {
+            if (value === undefined)
+                continue;
+            // A plain scalar (or a Date) is an equality. `null` is NOT: `col IS NULL`
+            // is not a uniqueness match, since SQL uniqueness permits many nulls.
+            const isScalarEquality = value !== null && (typeof value !== 'object' || value instanceof Date) && typeof value !== 'function';
+            if (!isScalarEquality)
+                return false;
+            const column = ownLookup(this.tableMeta.columnMap, field);
+            if (!column)
+                return false;
+            pinned.add(column);
+        }
+        if (pinned.size === 0)
+            return false;
+        const covers = (columns) => !!columns && columns.length > 0 && columns.every((c) => pinned.has(c));
+        return covers(this.tableMeta.primaryKey) || (this.tableMeta.uniqueColumns ?? []).some(covers);
+    }
     /**
      * Recursively measure the maximum depth of a `with` clause tree.
      * Used by the dev-only deep-with warning guard.
@@ -1783,7 +1826,7 @@ export class QueryInterface {
         }
         return maxDepth;
     }
-    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
+    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause", matches TypedWithClause default
     buildFindMany(args) {
         this.currentSkip = args?.skipGlobalFilters;
         // Stable relation order (opt-in): fill PK-asc orderBy into unordered to-many
@@ -1815,7 +1858,7 @@ export class QueryInterface {
         // path re-orders in an outer wrapper (`... AS "<table>_distinct" ORDER BY
         // <userOrder>`) where a correlated relation subquery (pick-row, `_count`,
         // to-one relation ordering) would reference the parent table name out of
-        // scope — a guaranteed "missing FROM-clause entry" crash on Postgres.
+        // scope, a guaranteed "missing FROM-clause entry" crash on Postgres.
         // Checked BEFORE the SQL cache so build and warm-cache paths throw
         // identically (same rule as the vector guard inside the distinct branch).
         if (args?.distinct && args.distinct.length > 0 && args.orderBy) {
@@ -1874,7 +1917,7 @@ export class QueryInterface {
         // own cache-key segment: a cached no-PII statement must never serve an
         // `includePii` call, nor vice versa.
         // `relationLoadStrategy: 'flatten'` compiles eligible to-one relations to
-        // LEFT JOINs instead of correlated subqueries — a completely different
+        // LEFT JOINs instead of correlated subqueries, a completely different
         // statement for the same `with` shape, which `withFp` (strategy-blind)
         // does not distinguish. So the plan gets its own cache-key segment, exactly
         // like `pii=`: a join-planned template must never serve a flatten-planned
@@ -1925,7 +1968,7 @@ export class QueryInterface {
             // where → cursor order (the collect path mirrors this exactly).
             let tail = freshWhereSql;
             if (args?.cursor) {
-                // Sorted (canonical) order — MUST match cursorFp and the cache-hit collect below.
+                // Sorted (canonical) order, MUST match cursorFp and the cache-hit collect below.
                 const cursorEntries = sortedEntries(args.cursor).filter(([, v]) => v !== undefined);
                 if (cursorEntries.length > 0) {
                     // Resolve the seek direction per cursor field from the flattened
@@ -1975,7 +2018,7 @@ export class QueryInterface {
                     : '';
                 sql = `SELECT ${distinctPrefix}${selectClause} FROM ${qt}${relationJoins.join('')}${lateralJoins.join('')}${tail}${orderBySql}`;
             }
-            // Pagination — push params in the same order the collect path mirrors
+            // Pagination, push params in the same order the collect path mirrors
             // (limit before offset); the SQL TEXT shape is dialect-owned via
             // buildPagination (PG: ` LIMIT $n`/` OFFSET $n`; SQL Server: OFFSET/FETCH).
             let limitPh;
@@ -1999,7 +2042,7 @@ export class QueryInterface {
         if (args?.with) {
             this.collectWithParams(args.with, params, undefined, flattenPlan);
         }
-        // 3. Cursor params — sorted (canonical) order, matching cursorFp and the build path.
+        // 3. Cursor params, sorted (canonical) order, matching cursorFp and the build path.
         if (args?.cursor) {
             const cursorEntries = sortedEntries(args.cursor).filter(([, v]) => v !== undefined);
             for (const [, v] of cursorEntries) {
@@ -2007,11 +2050,11 @@ export class QueryInterface {
             }
         }
         // 4. ORDER BY params (vector KNN ordering binds a `$n::vector` query vector).
-        //    Mirrors buildOrderBy's push order — between cursor and LIMIT.
+        //    Mirrors buildOrderBy's push order, between cursor and LIMIT.
         if (args?.orderBy) {
             this.collectOrderByParams(args.orderBy, params);
         }
-        // 5. LIMIT param — skipped when the dialect inlines pagination (build path
+        // 5. LIMIT param, skipped when the dialect inlines pagination (build path
         //    mirrors via paginationRef → no placeholder, no param).
         if (effectiveLimit !== undefined && !this.dialect.inlineLimitOffset) {
             // Validate here too: on a cache HIT the build path never runs, and a
@@ -2019,7 +2062,7 @@ export class QueryInterface {
             // i.e. no limit at all).
             params.push(this.paginationValue(effectiveLimit, 'limit'));
         }
-        // 6. OFFSET param — same inline gate as LIMIT above.
+        // 6. OFFSET param, same inline gate as LIMIT above.
         if (args?.offset !== undefined && !this.dialect.inlineLimitOffset) {
             params.push(this.paginationValue(args.offset, 'skip/offset'));
         }
@@ -2035,7 +2078,7 @@ export class QueryInterface {
         };
     }
     // -------------------------------------------------------------------------
-    // findManyStream — async iterable using PostgreSQL cursors
+    // findManyStream, async iterable using PostgreSQL cursors
     // -------------------------------------------------------------------------
     /**
      * Stream rows from a findMany query using PostgreSQL cursors.
@@ -2074,8 +2117,8 @@ export class QueryInterface {
         const hasRelations = !!args?.with;
         // Build the positional-aware relation parser once for the whole stream.
         // Same flatten plan buildFindMany compiles below. The plan is a pure
-        // function of the schema, the `with` shape and `includePii` — never of
-        // `limit` — so the batch-size override the speculative fetch applies cannot
+        // function of the schema, the `with` shape and `includePii`, never of
+        // `limit`, so the batch-size override the speculative fetch applies cannot
         // change it, and the stream's parser matches the emitted SQL.
         const streamFlattenPlan = hasRelations ? this.planFlatten(args, args?.includePii === true) : null;
         const parseWith = hasRelations
@@ -2089,7 +2132,7 @@ export class QueryInterface {
         this.currentAction = 'findManyStream';
         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
+            // Small drain, yield all rows and return, no cursor needed
             for (const row of speculativeResult.rows) {
                 yield (parseWith ? parseWith(row) : this.parseRow(row, this.table));
             }
@@ -2129,7 +2172,7 @@ export class QueryInterface {
         }
     }
     // -------------------------------------------------------------------------
-    // findFirst — like findMany but returns a single row or null
+    // findFirst, like findMany but returns a single row or null
     // -------------------------------------------------------------------------
     async findFirst(args) {
         return this.executeWithMiddleware('findFirst', (args ?? {}), async () => {
@@ -2154,7 +2197,7 @@ export class QueryInterface {
             return deferred.transform(result);
         });
     }
-    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
+    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause", matches TypedWithClause default
     buildFindFirst(args) {
         // Reuse findMany's SQL builder but force LIMIT 1
         const findManyArgs = { ...args, limit: 1 };
@@ -2170,7 +2213,7 @@ export class QueryInterface {
         };
     }
     // -------------------------------------------------------------------------
-    // findFirstOrThrow — like findFirst but throws if no record found
+    // findFirstOrThrow, like findFirst but throws if no record found
     // -------------------------------------------------------------------------
     async findFirstOrThrow(args) {
         return this.executeWithMiddleware('findFirstOrThrow', (args ?? {}), async () => {
@@ -2179,7 +2222,7 @@ export class QueryInterface {
             return deferred.transform(result);
         });
     }
-    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
+    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause", matches TypedWithClause default
     buildFindFirstOrThrow(args) {
         const inner = this.buildFindFirst(args);
         return {
@@ -2200,7 +2243,7 @@ export class QueryInterface {
         };
     }
     // -------------------------------------------------------------------------
-    // findUniqueOrThrow — like findUnique but throws if no record found
+    // findUniqueOrThrow, like findUnique but throws if no record found
     // -------------------------------------------------------------------------
     async findUniqueOrThrow(args) {
         return this.executeWithMiddleware('findUniqueOrThrow', args, async () => {
@@ -2209,7 +2252,7 @@ export class QueryInterface {
             return deferred.transform(result);
         });
     }
-    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
+    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause", matches TypedWithClause default
     buildFindUniqueOrThrow(args) {
         const inner = this.buildFindUnique(args);
         return {
@@ -2242,7 +2285,7 @@ export class QueryInterface {
         });
     }
     // -------------------------------------------------------------------------
-    // createMany — uses UNNEST for performance
+    // createMany, uses UNNEST for performance
     // -------------------------------------------------------------------------
     async createMany(args) {
         return this.executeWithMiddleware('createMany', args, async () => {
@@ -2308,7 +2351,7 @@ export class QueryInterface {
             // implicit transaction.
             this.pool);
             // biome-ignore lint/suspicious/noExplicitAny: TransactionClient satisfies NestedWriteContext['tx'] at runtime
-            const ctx = { schema: this.schema, tx: tx };
+            const ctx = { schema: this.schema, tx: tx, scopedConnect: this.scopedConnect };
             const result = await fn(ctx);
             await client.query(this.dialect.commitStatement());
             return result;
@@ -2356,7 +2399,7 @@ export class QueryInterface {
         });
     }
     // -------------------------------------------------------------------------
-    // upsert — INSERT ... ON CONFLICT ... DO UPDATE
+    // upsert, INSERT ... ON CONFLICT ... DO UPDATE
     // -------------------------------------------------------------------------
     async upsert(args) {
         return this.executeWithMiddleware('upsert', args, async () => {
@@ -2365,7 +2408,7 @@ export class QueryInterface {
         });
     }
     // -------------------------------------------------------------------------
-    // updateMany — UPDATE ... WHERE ... returning count
+    // updateMany, UPDATE ... WHERE ... returning count
     // -------------------------------------------------------------------------
     async updateMany(args) {
         return this.executeWithMiddleware('updateMany', args, async () => {
@@ -2375,7 +2418,7 @@ export class QueryInterface {
         });
     }
     // -------------------------------------------------------------------------
-    // deleteMany — DELETE ... WHERE ... returning count
+    // deleteMany, DELETE ... WHERE ... returning count
     // -------------------------------------------------------------------------
     async deleteMany(args) {
         return this.executeWithMiddleware('deleteMany', args, async () => {
@@ -2448,7 +2491,7 @@ export class QueryInterface {
         return aggMod.buildAggregate(this.ctx, args);
     }
     // -------------------------------------------------------------------------
-    // aggregate — standalone aggregation without groupBy
+    // aggregate, standalone aggregation without groupBy
     // -------------------------------------------------------------------------
     async aggregate(args) {
         return this.executeWithMiddleware('aggregate', args, async () => {
@@ -2584,7 +2627,7 @@ export class QueryInterface {
         // 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
+        // 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);
@@ -2594,15 +2637,14 @@ export class QueryInterface {
         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)'}.`);
+        throw new ValidationError(unknownFieldMessage(this.table, field, this.tableMeta));
     }
     /** Convert camelCase field name to a double-quoted SQL identifier */
     toSqlColumn(field) {
         return this.q(this.toColumn(field));
     }
     // =========================================================================
-    // Fingerprinting — value-invariant shape keys for SQL cache lookup
+    // Fingerprinting, value-invariant shape keys for SQL cache lookup
     // =========================================================================
     // ---------------------------------------------------------------------------
     // WHERE-clause compilation (extracted to where.ts).
@@ -2699,7 +2741,7 @@ export class QueryInterface {
         }
     }
     // -------------------------------------------------------------------------
-    // Global filters (soft-delete / multi-tenancy — WS-G)
+    // Global filters (soft-delete / multi-tenancy, WS-G)
     //
     // A configured global filter for a table is AND-merged into the compiled WHERE
     // of every query on that table (via {@link mergeGlobalFilter}, so the merge is
@@ -2707,12 +2749,12 @@ export class QueryInterface {
     // subquery targeting it (rendered at build time against the subquery's alias/
     // table by the `*GlobalFilterAlias`/`*GlobalFilterExists` helpers, with the
     // shape folded into the SQL-cache key via {@link globalFilterCacheSegment}).
-    // Function filters are evaluated per resolve — at query-build time — enabling
+    // Function filters are evaluated per resolve, at query-build time, enabling
     // per-request tenancy via a closure. They must return a STABLE shape (same
     // keys/operators); only values may vary between calls.
     // -------------------------------------------------------------------------
     // -------------------------------------------------------------------------
-    // Scoped (non-top-level) WHERE compilation — relation EXISTS sub-wheres and
+    // Scoped (non-top-level) WHERE compilation, relation EXISTS sub-wheres and
     // relation `with`-clause `where`s. All three consumers below drive the SAME
     // canonical `walkWhere` the top level uses (bound to the SCOPE's target
     // table), so their key order + combinator structure + relation detection can
@@ -2728,12 +2770,12 @@ export class QueryInterface {
     /**
      * Build ORDER BY clause from an object.
      *
-     * Each value is either a plain direction (`'asc'`/`'desc'`) or — for pgvector
-     * columns — a `{ distance: { to, metric, direction? } }` KNN ordering object.
+     * Each value is either a plain direction (`'asc'`/`'desc'`) or, for pgvector
+     * columns, a `{ distance: { to, metric, direction? } }` KNN ordering object.
      * Vector ordering binds the query vector as a `$n::vector` param, so a `params`
      * array MUST be supplied when a vector ordering may be present (top-level
      * findMany path). When `params` is omitted (groupBy / relation path) a vector
-     * ordering throws — KNN ordering is only supported at the top level.
+     * ordering throws, KNN ordering is only supported at the top level.
      */
     // -------------------------------------------------------------------------
     // pgvector helpers (similarity search)
@@ -2766,7 +2808,7 @@ export class QueryInterface {
                 // columns (`date[]`, `timestamp[]`, `timestamptz[]`), for which the
                 // driver already hands back a `Date[]`. Coercing it ran
                 // `new Date(String(theArray))` and replaced the whole array with a
-                // single Invalid Date — the column was unreadable on every strategy.
+                // single Invalid Date, the column was unreadable on every strategy.
                 // The join strategy's string arrays are handled upstream instead, by
                 // the JSON-wire decode in relations.ts.
                 if ((dateCols.has(col) || camelDateFields.has(field)) &&

package/dist/query/compound-unique.d.ts

@@ -1,5 +1,5 @@
 /**
- * turbine-orm — Prisma-style compound-unique `where` selectors.
+ * turbine-orm, Prisma-style compound-unique `where` selectors.
  *
  * Prisma lets a `findUnique`-family `where` address a multi-column unique
  * constraint through a single synthetic key holding the member columns:

package/dist/query/deferred.d.ts

@@ -1,5 +1,5 @@
 /**
- * turbine-orm — Deferred query + QueryInterface option types
+ * turbine-orm, Deferred query + QueryInterface option types
  *
  * Split from builder.ts so the class file focuses on SQL assembly / execution.
  */
@@ -27,7 +27,7 @@ export interface DeferredQuery<T> {
     preparedName?: string;
     /**
      * Execution plan for dialects whose {@link Dialect.resultStrategy} is
-     * `'reselect'` (no RETURNING — e.g. MySQL). Owns the statement ordering: it
+     * `'reselect'` (no RETURNING, e.g. MySQL). Owns the statement ordering: it
      * runs the write and the follow-up row-fetching SELECT(s) via `exec`, and
      * resolves the result whose rows {@link DeferredQuery.transform} consumes.
      * Absent for `'returning'`/`'output'` dialects (the statement returns its own
@@ -35,7 +35,7 @@ export interface DeferredQuery<T> {
      */
     reselect?: (exec: ReselectExecutor) => Promise<pg.QueryResult>;
 }
-/** Middleware function type — imported from client to avoid circular deps */
+/** Middleware function type, imported from client to avoid circular deps */
 export type MiddlewareFn = (params: {
     model: string;
     action: string;
@@ -75,13 +75,19 @@ export interface QueryInterfaceOptions {
      * queries are surfaced loudly during development. Pass `false` to silence
      * the warning entirely (e.g. for CLI tooling that intentionally streams
      * full tables), or a per-table map (`{ userProfiles: false }`) to silence
-     * only the tables that intentionally read full sets — unlisted tables keep
+     * only the tables that intentionally read full sets, unlisted tables keep
      * the default. Map keys accept BOTH the camelCase accessor name
      * (`userProfiles`) and the snake_case table name (`user_profiles`); the
      * snake_case entry wins if both are present. Individual calls can also
      * override via `findMany({ warnOnUnlimited: false })`.
      */
     warnOnUnlimited?: boolean | Record<string, boolean>;
+    /**
+     * Refuse a nested `connect` / `connectOrCreate` that would re-parent a
+     * to-many child already owned by a different parent. Off by default; see
+     * {@link import('../nested-write.js').NestedWriteContext.scopedConnect}.
+     */
+    scopedConnect?: boolean;
     /**
      * Enable prepared statements. When true, queries are submitted with a
      * `{ name, text, values }` object to the pg driver, which caches the
@@ -196,7 +202,7 @@ export interface QueryInterfaceOptions {
     autoRoundTripMs?: number;
     /**
      * How nested-relation subqueries encode each row's JSON: `'object'` (default,
-     * `json_build_object`) or `'positional'` (`json_build_array`, key-less — see
+     * `json_build_object`) or `'positional'` (`json_build_array`, key-less, see
      * {@link Dialect.buildJsonArray}). Positional is Postgres-only in v1; a
      * `with` clause on any other dialect throws `UnsupportedFeatureError` (E017).
      */
@@ -208,7 +214,7 @@ export interface QueryInterfaceOptions {
      * {@link GlobalFilters}.
      */
     globalFilters?: GlobalFilters;
-    /** @internal Set by TransactionClient — signals that this QI runs inside an active transaction. */
+    /** @internal Set by TransactionClient, signals that this QI runs inside an active transaction. */
     _txScoped?: boolean;
     /** @internal Callback from TurbineClient for query event emission. */
     _onQuery?: (event: QueryEvent) => void;

package/dist/query/deferred.js

@@ -1,5 +1,5 @@
 /**
- * turbine-orm — Deferred query + QueryInterface option types
+ * turbine-orm, Deferred query + QueryInterface option types
  *
  * Split from builder.ts so the class file focuses on SQL assembly / execution.
  */