turbine-orm 0.50.0 → 0.51.0

package/dist/query/batched-loader.js

@@ -1,19 +1,19 @@
 /**
- * turbine-orm — Batched relation loader (the `relationLoadStrategy: 'batched'` path)
+ * turbine-orm, Batched relation loader (the `relationLoadStrategy: 'batched'` path)
  *
  * ## Why this exists
  *
  * Turbine's default `with`-clause strategy resolves nested relations in ONE SQL
- * statement using correlated `json_agg(json_build_object(...))` subqueries — one
+ * statement using correlated `json_agg(json_build_object(...))` subqueries, one
  * probe per parent row (see `buildRelationSubquery` in builder.ts). That is the
  * right default: a single round-trip, and when the child FK columns are indexed
  * each probe is an index seek. But it degrades in two situations:
  *
- *   1. **Missing FK index** — a correlated probe per parent row becomes
+ *   1. **Missing FK index**, a correlated probe per parent row becomes
  *      N-parents × full-table-scan. A batched-loader ORM pays that missing index
  *      only ONCE (a single `WHERE fk = ANY($1)` seq-scan), which is why schemas
  *      migrated from those ORMs often lack the index the json_agg path needs.
- *   2. **Huge unpaginated result sets** — the JSON wire format
+ *   2. **Huge unpaginated result sets**, the JSON wire format
  *      (`json_build_object` per row, re-serialized inside `json_agg`) is heavy to
  *      encode/decode compared with flat rows.
  *
@@ -29,19 +29,19 @@
  *   - **Same executor / connection path.** Every follow-up query runs through the
  *     caller's own executor ({@link RelationLoadContext.exec}) and child query
  *     interfaces built on the caller's pool. Inside a `$transaction` that pool is
- *     the pinned-connection `txPool`, so batched loads join the transaction — no
+ *     the pinned-connection `txPool`, so batched loads join the transaction, no
  *     separate pool checkout per query.
  *   - **Identical output shape.** The stitched result is byte-for-byte the same
  *     shape the join strategy produces: relation arrays for hasMany/manyToMany
  *     (`[]` when empty), single-or-null for hasOne/belongsTo, with the same
- *     camelCase keys and Date coercion — because the child rows are parsed by the
+ *     camelCase keys and Date coercion, because the child rows are parsed by the
  *     very same `parseRow`/`buildFindMany` machinery via a child QueryInterface.
  *   - **Stitch keys never leak.** To stitch, the follow-up query must select the
  *     FK/PK it joins on even when the caller's `select`/`omit` excluded it; the
  *     loader adds those columns for the query and strips them from the returned
  *     entities afterwards ({@link includeKeysForBatching}).
  *
- * PowDB (powql.ts) has its own batched loaders for the same reasons — this is the
+ * PowDB (powql.ts) has its own batched loaders for the same reasons, this is the
  * clean Postgres/SQL implementation, deliberately NOT shared with PowQL.
  *
  * @module
@@ -52,14 +52,14 @@ import { isRelationPickOrderBy } from './filters.js';
 import { ownLookup } from './utils.js';
 /**
  * Max parent keys per follow-up query. On Postgres the whole key set travels as
- * ONE array parameter (`= ANY($1)`), so this is not a bind-parameter limit — it
+ * ONE array parameter (`= ANY($1)`), so this is not a bind-parameter limit, it
  * only bounds planner/memory cost per statement. Keep it large: every extra
  * chunk is an extra network round-trip, and round-trips are exactly what the
  * batched strategy exists to minimize (a 9-chunk load was measured 2× slower
  * than a single-statement one over a WAN link).
  */
 const MAX_RELATION_KEYS = 32_000;
-/** Nesting cap — parity with the join strategy's depth-10 guard. */
+/** Nesting cap, parity with the join strategy's depth-10 guard. */
 const MAX_DEPTH = 10;
 /**
  * The default projection of `meta` expressed in FIELD names: which fields the
@@ -91,7 +91,7 @@ export function defaultProjectionFields(meta, includePii) {
  *
  * Used both for the base query (parent keys) and each follow-up query (child
  * keys) so a caller's `select: { title: true }` on a relation still stitches even
- * though the FK was not requested — and the FK never appears in the output.
+ * though the FK was not requested, and the FK never appears in the output.
  */
 export function includeKeysForBatching(select, omit, fields, 
 /**
@@ -113,7 +113,7 @@ defaultProjection) {
         for (const f of unique) {
             if (!next[f]) {
                 next[f] = true;
-                strip.push(f); // not requested by the caller — added only to stitch
+                strip.push(f); // not requested by the caller, added only to stitch
             }
         }
         return { select: next, omit, strip };
@@ -173,7 +173,7 @@ export function neededParentKeyFields(parentMeta, withClause) {
         }
         const rel = ownLookup(parentMeta.relations, relName);
         if (!rel)
-            continue; // unknown relation — the join path throws; let the loader surface it
+            continue; // unknown relation, the join path throws; let the loader surface it
         for (const col of localKeyColumns(rel)) {
             fields.add(parentMeta.reverseColumnMap[col] ?? col);
         }
@@ -222,18 +222,18 @@ export function resolveCountRelations(parentMeta, countSpec) {
     }
     return out;
 }
-/** Stringified stitch key — robust to number/uuid/bigint type drift across a join. */
+/** Stringified stitch key, robust to number/uuid/bigint type drift across a join. */
 function keyOf(value) {
     return String(value);
 }
 /**
- * Reject pick-row relation ordering anywhere inside a `with` tree's orderBy —
+ * Reject pick-row relation ordering anywhere inside a `with` tree's orderBy -
  * strategy parity with the join path, which throws this exact E003 at SQL
  * build time (`pickOrderNestedError` in builder.ts). Without this guard the
  * loaders would forward `options.orderBy` as the child reader's TOP-LEVEL
- * findMany orderBy, where the pick shape compiles fine — so the same query
+ * findMany orderBy, where the pick shape compiles fine, so the same query
  * would execute on 'batched' but throw on 'join'. Walks the whole tree up
- * front so acceptance never depends on which levels have rows — the batched
+ * front so acceptance never depends on which levels have rows, the batched
  * runners in builder.ts call this BEFORE the base query (a zero-row base
  * result must still reject, exactly like the join strategy's build-time throw).
  */
@@ -269,13 +269,13 @@ export async function loadRelationsBatched(ctx, parents, withClause, timeout, de
     if (parents.length === 0)
         return;
     // Sibling relations are independent (each writes only its own parent[relName]
-    // and reads only parent keys), so load them concurrently — on a pool that's
+    // and reads only parent keys), so load them concurrently, on a pool that's
     // real parallelism, inside a transaction pg queues them on the one connection.
     const loads = [];
     for (const [relName, spec] of Object.entries(withClause)) {
         if (!spec)
             continue;
-        // Reserved `_count` key — one grouped COUNT(*) follow-up per counted relation.
+        // Reserved `_count` key, one grouped COUNT(*) follow-up per counted relation.
         if (relName === '_count') {
             loads.push(loadCounts(ctx, parents, spec));
             continue;
@@ -300,7 +300,7 @@ async function loadToOneOrMany(ctx, parents, rel, relName, options, timeout, dep
     const fk = normalizeKeyColumns(rel.foreignKey);
     const rk = normalizeKeyColumns(rel.referenceKey);
     if (fk.length > 1 || rk.length > 1) {
-        throw new UnsupportedFeatureError('composite-key batched relation loading', 'relationLoadStrategy: "batched"', `relation "${relName}" — use the default 'join' strategy for composite-key relations`);
+        throw new UnsupportedFeatureError('composite-key batched relation loading', 'relationLoadStrategy: "batched"', `relation "${relName}", use the default 'join' strategy for composite-key relations`);
     }
     const targetMeta = requireTable(ctx.schema, rel.to, relName);
     // Local key lives on the parent; the correlating key lives on the child.
@@ -375,7 +375,7 @@ async function loadManyToMany(ctx, parents, rel, relName, options, timeout, dept
     const sourceRef = normalizeKeyColumns(rel.referenceKey);
     const targetMeta = requireTable(ctx.schema, rel.to, relName);
     if (sourceJ.length > 1 || targetJ.length > 1 || sourceRef.length > 1 || targetMeta.primaryKey.length !== 1) {
-        throw new UnsupportedFeatureError('composite-key batched manyToMany loading', 'relationLoadStrategy: "batched"', `relation "${relName}" — use the default 'join' strategy for composite-key m2m relations`);
+        throw new UnsupportedFeatureError('composite-key batched manyToMany loading', 'relationLoadStrategy: "batched"', `relation "${relName}", use the default 'join' strategy for composite-key m2m relations`);
     }
     const sourceJCol = sourceJ[0];
     const targetJCol = targetJ[0];
@@ -474,7 +474,7 @@ async function loadManyToMany(ctx, parents, rel, relName, options, timeout, dept
  * Load correlated `_count` values for the counted relations. One grouped
  * follow-up per relation (`SELECT key, COUNT(*) … WHERE key = ANY($1) GROUP BY
  * key`), attached onto each parent's `_count` object (0 when a parent has no
- * matching rows) — byte-identical to the join strategy's `_count` output.
+ * matching rows), byte-identical to the join strategy's `_count` output.
  */
 async function loadCounts(ctx, parents, countSpec) {
     const rels = resolveCountRelations(ctx.parentMeta, countSpec);
@@ -499,7 +499,7 @@ async function loadOneCount(ctx, parents, rel) {
         const sourceRef = normalizeKeyColumns(rel.referenceKey);
         const sourceJ = normalizeKeyColumns(through.sourceKey);
         if (sourceRef.length > 1 || sourceJ.length > 1) {
-            throw new UnsupportedFeatureError('composite-key batched _count', 'relationLoadStrategy: "batched"', `relation "${rel.name}" — use the default 'join' strategy for composite-key m2m _count`);
+            throw new UnsupportedFeatureError('composite-key batched _count', 'relationLoadStrategy: "batched"', `relation "${rel.name}", use the default 'join' strategy for composite-key m2m _count`);
         }
         parentKeyCol = sourceRef[0];
         childTable = through.table;
@@ -510,7 +510,7 @@ async function loadOneCount(ctx, parents, rel) {
         const fk = normalizeKeyColumns(rel.foreignKey);
         const rk = normalizeKeyColumns(rel.referenceKey);
         if (fk.length > 1 || rk.length > 1) {
-            throw new UnsupportedFeatureError('composite-key batched _count', 'relationLoadStrategy: "batched"', `relation "${rel.name}" — use the default 'join' strategy for composite-key _count`);
+            throw new UnsupportedFeatureError('composite-key batched _count', 'relationLoadStrategy: "batched"', `relation "${rel.name}", use the default 'join' strategy for composite-key _count`);
         }
         parentKeyCol = rk[0];
         childTable = rel.to;
@@ -529,7 +529,7 @@ async function loadOneCount(ctx, parents, rel) {
         // two strategies return identical counts under a filter. hasMany filters
         // the counted table directly; m2m counts junction rows but restricts them
         // to junction rows whose TARGET survives the target table's filter via
-        // EXISTS — mirroring buildRelationCountExpr's EXISTS-on-target (which also
+        // EXISTS, mirroring buildRelationCountExpr's EXISTS-on-target (which also
         // skips the filter when the junction targetKey arity doesn't match the
         // target PK). Rendered after the $1 key array.
         let gf = null;

package/dist/query/builder.d.ts

@@ -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 type pg from 'pg';
 import type { SchemaMetadata } from '../schema.js';
@@ -103,6 +103,7 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly middlewares;
     private readonly defaultLimit?;
     private readonly warnOnUnlimited;
+    private readonly scopedConnect;
     private readonly utcTimestamps;
     private readonly preparedStatementsEnabled;
     /**
@@ -150,7 +151,7 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly 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
@@ -165,7 +166,7 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly 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).
      */
     private readonly crossSchemaTypeColumns;
@@ -179,7 +180,7 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly camelDateFieldCache;
     /** True when this QI runs inside an active transaction (set via _txScoped option). */
     private readonly txScoped;
-    /** Original options reference — forwarded to child QIs in nested writes. */
+    /** Original options reference, forwarded to child QIs in nested writes. */
     private readonly options?;
     /** Set by executeWithMiddleware so queryWithTimeout can include it in events. */
     private currentAction;
@@ -195,7 +196,7 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     /**
      * 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.
@@ -240,7 +241,7 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * 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.
      */
     private buildPagination;
@@ -431,7 +432,7 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * 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
@@ -445,7 +446,7 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * 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.
      *
@@ -492,7 +493,7 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * 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.
      */
     private batchedContext;
@@ -582,7 +583,7 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      *
      *   - `'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
@@ -612,7 +613,7 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      *
      * 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.
@@ -626,7 +627,7 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * strategy's shape for the one row.
      */
     private runFindUniqueBatched;
-    buildFindUnique<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W, Record<string, boolean> | undefined, Record<string, boolean> | undefined>): DeferredQuery<T | null>;
+    buildFindUnique<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: FindUniqueArgs<T, R, W, S, O>): DeferredQuery<QueryResult<T, R, W, S, O> | null>;
     findMany<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args?: FindManyArgs<T, R, W, S, O>): Promise<QueryResult<T, R, W, S, O>[]>;
     /**
      * Return the engine's query plan for a {@link findMany}-shaped query as plain
@@ -672,12 +673,29 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * disabled in config).
      */
     private maybeWarnUnlimited;
+    /**
+     * 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.
+     */
+    private whereMatchesAtMostOneRow;
     /**
      * Recursively measure the maximum depth of a `with` clause tree.
      * Used by the dev-only deep-with warning guard.
      */
     private measureWithDepth;
-    buildFindMany<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W, Record<string, boolean> | undefined, Record<string, boolean> | undefined>): DeferredQuery<T[]>;
+    buildFindMany<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args?: FindManyArgs<T, R, W, S, O>): DeferredQuery<QueryResult<T, R, W, S, O>[]>;
     /**
      * Stream rows from a findMany query using PostgreSQL cursors.
      * Returns an AsyncIterable that yields individual rows, fetching in batches internally.
@@ -712,11 +730,11 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      */
     findManyStream<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args?: FindManyStreamArgs<T, R, W, S, O>): AsyncGenerator<QueryResult<T, R, W, S, O>, void, undefined>;
     findFirst<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args?: FindManyArgs<T, R, W, S, O>): Promise<QueryResult<T, R, W, S, O> | null>;
-    buildFindFirst<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W, Record<string, boolean> | undefined, Record<string, boolean> | undefined>): DeferredQuery<T | null>;
+    buildFindFirst<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args?: FindManyArgs<T, R, W, S, O>): DeferredQuery<QueryResult<T, R, W, S, O> | null>;
     findFirstOrThrow<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args?: FindManyArgs<T, R, W, S, O>): Promise<QueryResult<T, R, W, S, O>>;
-    buildFindFirstOrThrow<W extends TypedWithClause<R> = {}>(args?: FindManyArgs<T, R, W, Record<string, boolean> | undefined, Record<string, boolean> | undefined>): DeferredQuery<T>;
+    buildFindFirstOrThrow<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args?: FindManyArgs<T, R, W, S, O>): DeferredQuery<QueryResult<T, R, W, S, O>>;
     findUniqueOrThrow<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: FindUniqueArgs<T, R, W, S, O>): Promise<QueryResult<T, R, W, S, O>>;
-    buildFindUniqueOrThrow<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W, Record<string, boolean> | undefined, Record<string, boolean> | undefined>): DeferredQuery<T>;
+    buildFindUniqueOrThrow<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: FindUniqueArgs<T, R, W, S, O>): DeferredQuery<QueryResult<T, R, W, S, O>>;
     create(args: CreateArgs<T, R>): Promise<T>;
     createMany(args: CreateManyArgs<T>): Promise<T[]>;
     update(args: UpdateArgs<T, R>): Promise<T>;
@@ -831,12 +849,12 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     /**
      * 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.
      */
     /** Parse a flat row: convert snake_case to camelCase + Date coercion */
     /**