turbine-orm 0.50.0 → 0.51.0

package/dist/powql.js

@@ -1,8 +1,8 @@
 /**
- * PowqlInterface — Turbine's PowQL query generator (the PowDB analogue of
+ * PowqlInterface, Turbine's PowQL query generator (the PowDB analogue of
  * {@link QueryInterface}). It exposes the same public method surface as the SQL
- * `QueryInterface` (`findMany`, `create`, `update`, …) but emits **PowQL** — a
- * pipeline language, not SQL — executed through {@link PowdbPool}.
+ * `QueryInterface` (`findMany`, `create`, `update`, …) but emits **PowQL**, a
+ * pipeline language, not SQL, executed through {@link PowdbPool}.
  *
  * It is a *parallel* implementation rather than a `Dialect` of the SQL builder:
  * PowQL's grammar (`T filter <e> order <k> { .col }`) shares no surface with
@@ -14,14 +14,14 @@
  * server):
  *   - `create`/`createMany`/`update`/`delete` use PowDB 0.7.0's trailing
  *     `returning` keyword (`RETURNING *`, all columns) to surface affected rows
- *     in one round-trip. `upsert` is the lone exception — its statement does not
+ *     in one round-trip. `upsert` is the lone exception, its statement does not
  *     accept `returning`, so it reselects the row by PK (a composite-PK upsert
  *     reselects-or-writes inside one flat transaction).
  *   - The PK is server-assigned when the column is `isGenerated` (PowDB's `auto`
- *     int — read back via `returning`); otherwise a defaulted **string** PK is
+ *     int, read back via `returning`); otherwise a defaulted **string** PK is
  *     generated client-side (UUID).
- *   - `with` (nested relations) uses **batched N+1 loaders** — D round-trips for
- *     depth D, not one query — including manyToMany (junction → targets).
+ *   - `with` (nested relations) uses **batched N+1 loaders**, D round-trips for
+ *     depth D, not one query, including manyToMany (junction → targets).
  *   - **Relation filters** (`some`/`none`/`every`, all cardinalities incl. m2m)
  *     are resolved client-side to a literal `in (…)` list, never an IN-subquery:
  *     PowDB's executor caches a subquery's result by plan shape and would return
@@ -30,7 +30,7 @@
  *     shared nested-write engine as one flat top-level transaction (PowDB is
  *     single-writer, no savepoints).
  *   - pgvector / JSON / array filters and cursor streaming throw
- *     {@link UnsupportedFeatureError} (E017) — they have no PowDB equivalent.
+ *     {@link UnsupportedFeatureError} (E017), they have no PowDB equivalent.
  *
  * @module
  */
@@ -42,6 +42,7 @@ import { assertAggregatePiiOptIn } from './query/aggregates.js';
 import { expandCompoundUniqueWhere } from './query/compound-unique.js';
 import { isJsonFilter, isRelationPickOrderBy, orderByEntries } from './query/filters.js';
 import { escapeLike } from './query/utils.js';
+import { assertJsonFilterKeys, jsonStringEntries } from './query/where.js';
 import { normalizeKeyColumns, snakeToCamel, } from './schema.js';
 /**
  * Max parent keys per relation-loader `in (…)` query. A `with` over a large
@@ -88,7 +89,7 @@ const POWQL_WRITE_ACTIONS = new Set([
  * relation before compiling to it. Keyed on the pool object identity so every
  * table interface over the same connection shares one snapshot; a WeakMap lets a
  * discarded pool's snapshot be collected. A fetch failure caches `[]` (a missing
- * listing means "no verifiable links" — a silent fallback to loaders, never an
+ * listing means "no verifiable links", a silent fallback to loaders, never an
  * error).
  */
 const LINK_SNAPSHOT_CACHE = new WeakMap();
@@ -227,8 +228,8 @@ export class PowqlInterface {
         return `$${params.length}`;
     }
     /**
-     * Render a value for a write *assignment* (`col := …`). Every value — float
-     * columns included — is sent as a positional `$N` param. PowDB ≥ 0.7.0 fixed
+     * Render a value for a write *assignment* (`col := …`). Every value, float
+     * columns included, is sent as a positional `$N` param. PowDB ≥ 0.7.0 fixed
      * the int→float UPDATE coercion bug (`score := $n` with an integer param now
      * reads back the integer value, not the raw i64 bits), so the float-literal
      * inlining workaround Turbine carried for ≤ 0.6.2 is gone. Marks the column as
@@ -259,7 +260,7 @@ export class PowqlInterface {
     get capabilities() {
         return this.pool.capabilities ?? ALL_POWDB_CAPABILITIES;
     }
-    /** A predicate that is always false — the empty-`in` / contradiction sentinel. */
+    /** A predicate that is always false, the empty-`in` / contradiction sentinel. */
     alwaysFalse() {
         const pk = this.meta.primaryKey[0] ?? this.meta.columns[0]?.name;
         return `(.${pk} is null and .${pk} is not null)`;
@@ -302,7 +303,7 @@ export class PowqlInterface {
             }
             else if (this.meta.relations[key]) {
                 // Relation filters are pre-resolved to scalar in/notIn by
-                // resolveRelationFilters() before buildWhere runs — reaching here means
+                // resolveRelationFilters() before buildWhere runs, reaching here means
                 // a caller skipped that step (an internal bug, not user error).
                 throw new ValidationError(`[turbine] internal: relation filter "${key}" reached buildWhere unresolved (missing resolveRelationFilters()).`);
             }
@@ -336,7 +337,7 @@ export class PowqlInterface {
         }
         rejectUnsupportedFilter(op, field);
         if (!Object.keys(op).some((k) => OPERATOR_KEYS.has(k))) {
-            // A bare object that is not an operator set — equality by value.
+            // A bare object that is not an operator set, equality by value.
             return `${ref} = ${this.param(value, params)}`;
         }
         const insensitive = op.mode === 'insensitive';
@@ -434,6 +435,10 @@ export class PowqlInterface {
      * by the empty-where guard.
      */
     buildJsonPathCondition(col, filter, params, alias) {
+        // Same strict-key check as the SQL path. Without it an unrecognized
+        // operator compiled to zero conditions and the predicate silently
+        // disappeared, returning every row (see assertJsonFilterKeys).
+        assertJsonFilterKeys(filter, col.name);
         const conds = [];
         // Bind the path segments at most once and reuse the expression string across
         // equals + range comparisons (they share the same `path`).
@@ -479,8 +484,20 @@ export class PowqlInterface {
             }
             conds.push(`${pathP()} ${powOp} ${this.param(v, params)}`);
         }
-        if (!conds.length)
-            return '';
+        // Substring comparisons against the text at `path`, in the same fixed
+        // order as the SQL path. PowQL has `like`, so these compile natively.
+        for (const { pattern, value } of jsonStringEntries(filter, col.name)) {
+            const insensitive = filter.mode === 'insensitive';
+            const lhs = insensitive ? `lower(${pathP()})` : pathP();
+            conds.push(`${lhs} like ${this.bindLike(pattern(escapeLike(value)), params, insensitive)}`);
+        }
+        // Every reachable shape now emits a condition or throws: assertJsonFilterKeys
+        // rejects a filter that compares nothing, so an empty list here would be a
+        // generator bug rather than a user error, and must not silently widen the
+        // query the way it used to.
+        if (!conds.length) {
+            throw new ValidationError(`[turbine] internal: JSON filter on "${col.name}" compiled to no condition. This is a bug in turbine-orm.`);
+        }
         return conds.length > 1 ? `(${conds.join(' and ')})` : conds[0];
     }
     /** Bind a value, lowercasing for case-insensitive comparisons. */
@@ -493,7 +510,7 @@ export class PowqlInterface {
         const ph = this.param(pattern, params);
         return insensitive ? `lower(${ph})` : ph;
     }
-    /** `lhs [not] in ($1, $2, …)` — empty list collapses to a constant. */
+    /** `lhs [not] in ($1, $2, …)`, empty list collapses to a constant. */
     buildInList(lhs, values, params, insensitive, negate) {
         if (!Array.isArray(values) || values.length === 0) {
             // `in []` matches nothing; `not in []` matches everything (SQL parity requires a
@@ -520,7 +537,7 @@ export class PowqlInterface {
      * so a second subquery of the same shape with a different value returns the
      * first one's stale rows (reproduced live on the embedded engine; the
      * single-statement literal `in (list)` form is always correct). Resolving
-     * client-side trades extra round-trips for correctness, and recurses — nested
+     * client-side trades extra round-trips for correctness, and recurses, nested
      * relation filters in the inner predicate resolve when the target query runs.
      */
     async resolveRelationFilters(where, timeout) {
@@ -562,7 +579,7 @@ export class PowqlInterface {
         const fk = normalizeKeyColumns(rel.foreignKey);
         const rk = normalizeKeyColumns(rel.referenceKey);
         if (fk.length > 1 || rk.length > 1) {
-            throw new UnsupportedFeatureError('composite-key relation filters', 'PowDB', `relation "${rel.name}" uses a composite key — PowQL has no tuple-\`in\` to express it`);
+            throw new UnsupportedFeatureError('composite-key relation filters', 'PowDB', `relation "${rel.name}" uses a composite key, PowQL has no tuple-\`in\` to express it`);
         }
         const targetMeta = this.schema.tables[rel.to];
         if (!targetMeta)
@@ -603,7 +620,7 @@ export class PowqlInterface {
         if (!targetMeta)
             throw new ValidationError(`[turbine] Relation "${rel.name}" targets unknown table "${rel.to}".`);
         if (sourceJ.length > 1 || targetJ.length > 1 || sourceRef.length > 1 || targetMeta.primaryKey.length > 1) {
-            throw new UnsupportedFeatureError('composite-key manyToMany filters', 'PowDB', `relation "${rel.name}" — PowQL has no tuple-\`in\` for composite junction/target keys`);
+            throw new UnsupportedFeatureError('composite-key manyToMany filters', 'PowDB', `relation "${rel.name}", PowQL has no tuple-\`in\` for composite junction/target keys`);
         }
         const sourceJCol = sourceJ[0];
         const targetJCol = targetJ[0];
@@ -621,7 +638,7 @@ export class PowqlInterface {
             });
             return [...new Set(rows.map((r) => r[targetPkField]).filter((v) => v != null))];
         };
-        // Junction source keys linking any of `targetPks` (literal IN-list — never a subquery).
+        // Junction source keys linking any of `targetPks` (literal IN-list, never a subquery).
         const sourcesForTargets = async (targetPks) => {
             if (!targetPks.length)
                 return [];
@@ -769,7 +786,7 @@ export class PowqlInterface {
                     }
                     return `${this.ref(field, alias)} ${spec.sort === 'desc' ? 'desc' : 'asc'}`;
                 }
-                // Name the actual feature in the refusal — a pick-row ordering
+                // Name the actual feature in the refusal, a pick-row ordering
                 // reported as "vector / distance ordering" sends users hunting for
                 // pgvector docs. Everything else stays E017 on PowDB.
                 const feature = isRelationPickOrderBy(dir)
@@ -951,8 +968,8 @@ export class PowqlInterface {
      *
      * When the engine supports nested projections (>= 0.18) and the strategy
      * does not opt out, eligible `with` relations compile INTO this statement as
-     * nested-projection blocks (`nestedPlans`) — one round-trip for the whole
-     * shape — and only the ineligible remainder (`residualWith`) goes to the
+     * nested-projection blocks (`nestedPlans`), one round-trip for the whole
+     * shape, and only the ineligible remainder (`residualWith`) goes to the
      * post-execution loaders. Without nesting the emitted PowQL is byte-identical
      * to the pre-0.18 output (no alias, `.col` refs).
      */
@@ -1110,7 +1127,7 @@ export class PowqlInterface {
         return row;
     }
     // -------------------------------------------------------------------------
-    // Nested relations — batched N+1 loaders (hasMany / hasOne / belongsTo)
+    // Nested relations, batched N+1 loaders (hasMany / hasOne / belongsTo)
     // -------------------------------------------------------------------------
     /**
      * Load each requested relation for `parents` and attach it onto each row.
@@ -1242,7 +1259,7 @@ export class PowqlInterface {
         }
     }
     /**
-     * manyToMany nested read — a three-hop batched loader (no `json_agg`/join
+     * manyToMany nested read, a three-hop batched loader (no `json_agg`/join
      * pushdown): (1) read the junction rows for all parents in `sourceKey in (…)`
      * chunks, (2) read the target rows for the collected `targetKey`s, (3) stitch
      * each parent → its junction rows → its targets in memory. Mirrors the
@@ -1260,7 +1277,7 @@ export class PowqlInterface {
         if (!targetMeta)
             throw new ValidationError(`[turbine] Relation "${relName}" targets unknown table "${rel.to}".`);
         if (sourceJ.length > 1 || targetJ.length > 1 || sourceRef.length > 1 || targetMeta.primaryKey.length > 1) {
-            throw new UnsupportedFeatureError('composite-key manyToMany', 'PowDB', `relation "${relName}" — PowQL has no tuple-\`in\`, so composite junction/target keys can't be loaded`);
+            throw new UnsupportedFeatureError('composite-key manyToMany', 'PowDB', `relation "${relName}", PowQL has no tuple-\`in\`, so composite junction/target keys can't be loaded`);
         }
         const sourceJCol = sourceJ[0];
         const targetJCol = targetJ[0];
@@ -1706,7 +1723,7 @@ export class PowqlInterface {
     /**
      * Shape the nested JSON children back into typed entities on every parent
      * row. The nested field arrives as a decoded JSON array on the native wire
-     * (or JSON text on the legacy wire — parsed here); its values are real JSON
+     * (or JSON text on the legacy wire, parsed here); its values are real JSON
      * types, so each child object goes through the NATIVE coercion policy
      * (`rowToEntity(…, true)`: a date column's micros number becomes a `Date`, a
      * json column's document passes through, a str `"null"` stays a string).
@@ -1803,7 +1820,7 @@ export class PowqlInterface {
      * must stay on the loaders (ALWAYS a silent fallback with identical output).
      *
      * SCOPED TIGHT: this fires ONLY for a to-one relation whose child projection
-     * includes a bigint/bytes column — exactly the case a JSON nested block cannot
+     * includes a bigint/bytes column, exactly the case a JSON nested block cannot
      * carry, so nested projections have already fallen back to a per-relation loader
      * (`planNestedRelation` returned `null` for the same shape). Cases nested
      * projections DO serve keep nested projections: link-bearing statements are
@@ -1811,9 +1828,9 @@ export class PowqlInterface {
      * link path would regress a hot path for no gain. Requires: single-column
      * belongsTo; no relation `with` / `where` / `distinct` / `orderBy` /
      * `limit` / `offset` (a scalar path has no per-hop filter/order and cannot
-     * reproduce those — such inputs stay on the loader for exact parity); a link
+     * reproduce those, such inputs stay on the loader for exact parity); a link
      * name and all projected columns that are bare identifiers (a quoted segment in
-     * a dotted link path is outside the verified spelling — fall back); and a
+     * a dotted link path is outside the verified spelling, fall back); and a
      * DECLARED link that verifiably matches (`findMatchingLink`).
      */
     async planLinkPathRelation(relName, rel, opt, includePii, parentCols, index) {
@@ -1844,7 +1861,7 @@ export class PowqlInterface {
         });
         if (!hasCarrierBlockedCol)
             return null;
-        // All cheap checks passed: NOW fetch (and cache) the link snapshot — never
+        // All cheap checks passed: NOW fetch (and cache) the link snapshot, never
         // before, so a query with no link-path candidate issues no `schema links`.
         const link = this.findMatchingLink(await this.linksSnapshot(), rel);
         if (!link)
@@ -1875,7 +1892,7 @@ export class PowqlInterface {
     }
     /**
      * Reconstruct each link-path relation's child entity from its flat hop fields
-     * and attach it under the relation name — output indistinguishable from the
+     * and attach it under the relation name, output indistinguishable from the
      * loader (same keys, same coercions). Presence: the target PK cell arriving
      * Empty (a null/dangling FK at the hop) means no linked row → `null`, matching
      * the loader's `matches[0] ?? null`. Otherwise the gathered snake cells go
@@ -1905,7 +1922,7 @@ export class PowqlInterface {
         }
     }
     // -------------------------------------------------------------------------
-    // Writes (reselect — PowDB has no RETURNING)
+    // Writes (reselect, PowDB has no RETURNING)
     // -------------------------------------------------------------------------
     /** Split `data` into scalar assignments; reject relation (nested-write) keys. */
     scalarData(data) {
@@ -1914,7 +1931,7 @@ export class PowqlInterface {
             if (value === undefined)
                 continue;
             if (this.meta.relations[field]) {
-                throw new UnsupportedFeatureError('nested writes', 'PowDB', `relation "${field}" — nested writes need create()/update(), not createMany()/upsert()`);
+                throw new UnsupportedFeatureError('nested writes', 'PowDB', `relation "${field}", nested writes need create()/update(), not createMany()/upsert()`);
             }
             out.push({ col: this.column(field), value });
         }
@@ -1923,8 +1940,8 @@ export class PowqlInterface {
     /**
      * Fill in a client-generated UUID for a defaulted **string** PK that wasn't
      * supplied. A server-generated PK ({@link ColumnMetadata.isGenerated}, e.g. an
-     * `int` column with PowDB's `auto` modifier) is left untouched — PowDB assigns
-     * it and the trailing `returning` reads it back — as is any non-string PK.
+     * `int` column with PowDB's `auto` modifier) is left untouched, PowDB assigns
+     * it and the trailing `returning` reads it back, as is any non-string PK.
      */
     applyPkDefault(data) {
         const out = { ...data };
@@ -1941,7 +1958,7 @@ export class PowqlInterface {
         return out;
     }
     /**
-     * The table name as a PowQL type reference — backtick-quoted when it is a
+     * The table name as a PowQL type reference, backtick-quoted when it is a
      * reserved word (e.g. a table named `order`). Used in every emitted
      * statement; plain `this.table` stays in error messages.
      */
@@ -2024,7 +2041,7 @@ export class PowqlInterface {
             if (value === undefined)
                 continue;
             if (this.meta.relations[field]) {
-                throw new UnsupportedFeatureError('nested writes', 'PowDB', `relation "${field}" — nested writes need create()/update(), not updateMany()/upsert()`);
+                throw new UnsupportedFeatureError('nested writes', 'PowDB', `relation "${field}", nested writes need create()/update(), not updateMany()/upsert()`);
             }
             const colMeta = this.column(field);
             const ref = this.ref(field);
@@ -2053,11 +2070,11 @@ export class PowqlInterface {
         return parts.join(', ');
     }
     // -------------------------------------------------------------------------
-    // Nested writes — create/update whose `data` carries relation ops (create,
+    // Nested writes, create/update whose `data` carries relation ops (create,
     // connect, connectOrCreate, disconnect, set, delete, update, upsert). Reuses
     // the engine-agnostic nested-write engine (it only needs ctx.schema + the
     // table accessors PowqlInterface already provides). Runs as ONE flat top-level
-    // PowDB transaction — single global write lock, no savepoints, so the whole
+    // PowDB transaction, single global write lock, no savepoints, so the whole
     // tree commits or rolls back together (mirrors the SQL path's coverage:
     // hasMany / hasOne / belongsTo; manyToMany nested writes are not handled by
     // the shared engine on any backend).
@@ -2100,9 +2117,13 @@ export class PowqlInterface {
             // Pass the PowDB pool so its read-only guard + capabilities carry into
             // the transaction-scoped proxy pool (see createTxPool).
             this.pool);
-            const ctx = { schema: this.schema, tx: tx };
+            const ctx = {
+                schema: this.schema,
+                tx: tx,
+                scopedConnect: this.options?.scopedConnect === true,
+            };
             // Plant the single-writer re-entrancy marker for the implicit tx's
-            // subtree (same seam TurbineClient.$transaction uses) — user code that
+            // subtree (same seam TurbineClient.$transaction uses), user code that
             // fires db.$transaction from inside (e.g. $use middleware around a
             // nested-write child op) must fast-fail E017, not queue into deadlock.
             const wrap = client
@@ -2112,7 +2133,7 @@ export class PowqlInterface {
             return result;
         }
         catch (err) {
-            // Only roll back a transaction we actually opened — a failed BEGIN
+            // Only roll back a transaction we actually opened, a failed BEGIN
             // (queue timeout, re-entrancy E017) must not emit a stray ROLLBACK that
             // could land inside another transaction on a shared engine handle.
             if (began) {
@@ -2120,7 +2141,7 @@ export class PowqlInterface {
                     await client.query(d?.rollbackStatement?.() ?? 'rollback');
                 }
                 catch {
-                    /* best-effort — the connection may be gone */
+                    /* best-effort, the connection may be gone */
                 }
             }
             throw err;
@@ -2143,7 +2164,7 @@ export class PowqlInterface {
             const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
             const where = this.buildWhere(resolvedWhere, params);
             this.assertCompiledWhere(where, false, 'delete');
-            // `returning` hands back the deleted row(s) — no separate pre-image reselect needed.
+            // `returning` hands back the deleted row(s), no separate pre-image reselect needed.
             const { rows, native } = await this.exec(`${this.qt} filter ${where} delete returning`, params, args.timeout, 'delete');
             const row = rows.length ? this.stripWritePii(this.shape(rows, native)[0]) : null;
             if (!row)
@@ -2231,7 +2252,7 @@ export class PowqlInterface {
     }
     async aggregate(args) {
         return this.withMiddleware('aggregate', args, async () => {
-            // One scalar query per aggregate — PowDB's bare-projection aggregate is broken.
+            // One scalar query per aggregate, PowDB's bare-projection aggregate is broken.
             const result = {};
             const filterParams = [];
             const resolvedWhere = await this.resolveRelationFilters(args.where, args.timeout);
@@ -2600,12 +2621,12 @@ export class PowqlInterface {
     // -------------------------------------------------------------------------
     // Streaming / unsupported
     // -------------------------------------------------------------------------
-    // biome-ignore lint/correctness/useYield: intentionally throws before yielding — PowDB has no server cursor.
+    // biome-ignore lint/correctness/useYield: intentionally throws before yielding, PowDB has no server cursor.
     async *findManyStream() {
         throw new UnsupportedFeatureError('cursor streaming (findManyStream)', 'PowDB', 'PowDB has no server-side cursor; page with findMany({ limit, offset }) instead');
     }
     // -------------------------------------------------------------------------
-    // Reselect helper (upsert only — PowDB's upsert has no `returning`)
+    // Reselect helper (upsert only, PowDB's upsert has no `returning`)
     // -------------------------------------------------------------------------
     /** Reselect a single row by its single-column primary key value. */
     async reselectByPk(pkValue, timeout) {
@@ -2618,12 +2639,12 @@ export class PowqlInterface {
         return rows.length ? this.shape(rows, native)[0] : null;
     }
     /**
-     * Empty-where guard — blocks accidental whole-table writes. Mirrors the SQL
+     * Empty-where guard, blocks accidental whole-table writes. Mirrors the SQL
      * path's `assertMutationHasPredicate` (query/builder.ts): it gates on the
      * *compiled* PowQL filter fragment, NOT the shape of the `where` object. A
-     * `where` whose conditions all evaporate during compilation — `{}`,
+     * `where` whose conditions all evaporate during compilation, `{}`,
      * `{ id: undefined }`, `{ OR: [] }`, `{ AND: [] }`, `{ NOT: {} }`,
-     * `{ OR: [{ f: undefined }] }` — compiles to the empty string and is refused,
+     * `{ OR: [{ f: undefined }] }`, compiles to the empty string and is refused,
      * because emitting a filter-less write would hit every row.
      */
     assertCompiledWhere(compiledWhere, allow, action) {

package/dist/query/aggregates.d.ts

@@ -73,7 +73,7 @@ export declare function buildDistinctOnSource<T extends object>(qi: BuilderCtx,
  * throws {@link ValidationError} for unknown fields and `qi.q()` quotes via
  * the dialect, so no unvalidated identifier ever reaches the SQL string. Every
  * comparison value is pushed onto the shared `params` array and referenced by
- * a `$N` placeholder via {@link buildHavingNumericClauses} — there is no string
+ * a `$N` placeholder via {@link buildHavingNumericClauses}, there is no string
  * interpolation of user values.
  *
  * `jsonAggExprs` (from {@link buildGroupBy}) maps `alias:aggKey` to the

package/dist/query/aggregates.js

@@ -64,7 +64,7 @@ export function buildGroupBy(qi, args) {
         ? buildDistinctOnSource(qi, args.distinctOn, whereSql, params)
         : `${qi.q(qi.table)}${whereSql}`;
     // Group keys: plain columns and/or JSON-path keys. Output-name collisions
-    // are rejected up front — and the check runs over the EMITTED SQL output
+    // are rejected up front, and the check runs over the EMITTED SQL output
     // column names (snake_case column / JSON alias / `_agg_key` aggregate
     // alias), not just the given arg keys: the driver keeps only the LAST
     // duplicate field per row object, so a JSON alias equal to another key's
@@ -211,7 +211,7 @@ export function buildGroupBy(qi, args) {
     buildAggregates('_min', 'MIN', args._min);
     buildAggregates('_max', 'MAX', args._max);
     let sql = `SELECT ${selectExprs.join(', ')} FROM ${fromSql} GROUP BY ${groupExprs.join(', ')}`;
-    // HAVING — filter whole groups by their aggregate values.
+    // HAVING, filter whole groups by their aggregate values.
     // Appends to the same `params` array, so placeholders continue from the
     // WHERE clause's parameter positions (qi.p(params.length) below).
     if (args.having) {
@@ -467,7 +467,7 @@ export function buildDistinctOnSource(qi, distinctOn, whereSql, params) {
  * throws {@link ValidationError} for unknown fields and `qi.q()` quotes via
  * the dialect, so no unvalidated identifier ever reaches the SQL string. Every
  * comparison value is pushed onto the shared `params` array and referenced by
- * a `$N` placeholder via {@link buildHavingNumericClauses} — there is no string
+ * a `$N` placeholder via {@link buildHavingNumericClauses}, there is no string
  * interpolation of user values.
  *
  * `jsonAggExprs` (from {@link buildGroupBy}) maps `alias:aggKey` to the
@@ -479,7 +479,7 @@ export function buildDistinctOnSource(qi, distinctOn, whereSql, params) {
 export function buildHavingClauses(qi, having, params, jsonAggExprs) {
     const clauses = [];
     // Maps the per-field aggregate key to its SQL function name. The set of
-    // allowed keys is fixed here — any other key on a field's filter object is
+    // allowed keys is fixed here, any other key on a field's filter object is
     // rejected by ValidationError below (never interpolated).
     const aggFnByKey = {
         _sum: 'SUM',
@@ -502,7 +502,7 @@ export function buildHavingClauses(qi, having, params, jsonAggExprs) {
                 `expected an aggregate object like { _sum: { gt: 100 } }.`);
         }
         // toColumn validates the field against schema metadata (throws
-        // ValidationError on unknown columns) and q() quotes the identifier — no
+        // ValidationError on unknown columns) and q() quotes the identifier, no
         // unvalidated identifier ever reaches the SQL string. Resolution is lazy:
         // a JSON-path aggregate alias is not a column, so it must not hit
         // toColumn when every aggregate under it resolves via `jsonAggExprs`.

package/dist/query/batched-loader.d.ts

@@ -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
@@ -132,7 +132,7 @@ export declare function defaultProjectionFields(meta: TableMetadata, 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 declare function includeKeysForBatching(select: Record<string, boolean> | undefined, omit: Record<string, boolean> | undefined, fields: string[], 
 /**
@@ -173,13 +173,13 @@ export declare function neededParentKeyFields(parentMeta: TableMetadata, withCla
  */
 export declare function resolveCountRelations(parentMeta: TableMetadata, countSpec: WithCount): RelationDef[];
 /**
- * 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).
  */