turbine-orm 0.40.1 → 0.41.0

package/dist/query/aggregates.js

@@ -92,15 +92,37 @@ export function buildGroupBy(qi, args) {
         }
     }
     // _count
-    const countSelected = args._count === true || args._count === undefined;
-    if (countSelected) {
-        // default: always include count
+    //   - `true` / omitted → scalar `_count` column (COUNT(*)), result `_count: number`.
+    //   - record form → one column per selection: `_all` → COUNT(*) AS "_count__all"
+    //     (double underscore, collision-proof against a real column named `all`),
+    //     each field → COUNT(col) AS "_count_<col>", result `_count: { _all, field }`.
+    const countArg = args._count;
+    const countIsRecord = countArg !== true && countArg !== undefined && typeof countArg === 'object';
+    const scalarCount = countArg === true || countArg === undefined;
+    if (scalarCount) {
+        // default: always include the scalar count
         selectExprs.push(`${qi.castAgg('COUNT(*)', 'int')} AS _count`);
     }
+    else if (countIsRecord) {
+        for (const [field, enabled] of Object.entries(countArg)) {
+            if (!enabled)
+                continue;
+            if (field === '_all') {
+                selectExprs.push(`${qi.castAgg('COUNT(*)', 'int')} AS ${qi.q('_count__all')}`);
+            }
+            else {
+                const col = qi.toColumn(field);
+                selectExprs.push(`${qi.castAgg(`COUNT(${qi.q(col)})`, 'int')} AS ${qi.q(`_count_${col}`)}`);
+            }
+        }
+    }
     // ORDER BY aggregate expressions, keyed `${aggKey}:${field}` (plus a bare
     // `_count`). Populated alongside the SELECT list below so `orderBy` can only
     // reference an aggregate that is actually requested. `COUNT(*)` (uncast) is
     // the ordering expression (the SELECT cast is only for the returned value).
+    // COUNT(*) is orderable whenever it is selected: scalar `_count`, OR the
+    // record form containing `_all`.
+    const countSelected = scalarCount || (countIsRecord && countArg._all === true);
     const aggOrderExprs = new Map();
     if (countSelected)
         aggOrderExprs.set('_count', 'COUNT(*)');
@@ -192,12 +214,34 @@ export function buildGroupBy(qi, args) {
                 restructured[reader.resultKey] = reader.raw ? row[reader.rowKey] : parsed[reader.resultKey];
             }
             // _count
+            //   scalar form → the plain `_count` (or driver-lowercased `count`) column.
+            //   record form → assemble `{ _all, field, ... }` from the `_count__all`
+            //   and `_count_<col>` columns. `_count__all` MUST be matched before the
+            //   generic `_count_` prefix (its slice(7) would map through snakeToCamel).
             if ('_count' in row) {
                 restructured._count = row._count;
             }
             else if ('count' in row) {
                 restructured._count = row.count;
             }
+            else {
+                const countObj = {};
+                let hasCount = false;
+                for (const [rawKey, rawValue] of Object.entries(row)) {
+                    if (rawKey === '_count__all') {
+                        countObj._all = rawValue;
+                        hasCount = true;
+                    }
+                    else if (rawKey.startsWith('_count_')) {
+                        const col = rawKey.slice(7);
+                        const field = qi.tableMeta.reverseColumnMap[col] ?? snakeToCamel(col);
+                        countObj[field] = rawValue;
+                        hasCount = true;
+                    }
+                }
+                if (hasCount)
+                    restructured._count = countObj;
+            }
             // Collect aggregates into nested objects
             const sumObj = {};
             const avgObj = {};
@@ -520,6 +564,9 @@ export function buildAggregate(qi, args) {
         }
         if (args._count && typeof args._count === 'object') {
             for (const key of Object.keys(args._count)) {
+                // `_all` is the reserved COUNT(*) selector, not a column.
+                if (key === '_all')
+                    continue;
                 if (!(key in meta.columnMap)) {
                     throw new ValidationError(`Unknown column "${key}" in aggregate for table "${qi.table}"`);
                 }
@@ -527,13 +574,20 @@ export function buildAggregate(qi, args) {
         }
     }
     const selectExprs = [];
-    // _count
+    // _count. `true` → scalar COUNT(*). Record form: reserved `_all` → COUNT(*) AS
+    // "_count__all" (double underscore, collision-proof against a real column named
+    // `all`); each field → COUNT(col) AS "_count_<col>".
     if (args._count === true) {
         selectExprs.push(`${qi.castAgg('COUNT(*)', 'int')} AS _count`);
     }
     else if (args._count && typeof args._count === 'object') {
         for (const [field, enabled] of Object.entries(args._count)) {
-            if (enabled) {
+            if (!enabled)
+                continue;
+            if (field === '_all') {
+                selectExprs.push(`${qi.castAgg('COUNT(*)', 'int')} AS ${qi.q('_count__all')}`);
+            }
+            else {
                 const col = qi.toColumn(field);
                 selectExprs.push(`${qi.castAgg(`COUNT(${qi.q(col)})`, 'int')} AS ${qi.q(`_count_${col}`)}`);
             }
@@ -590,11 +644,17 @@ export function buildAggregate(qi, args) {
                 aggResult._count = row._count;
             }
             else {
-                // Check for per-column counts
+                // Check for per-column counts. `_count__all` MUST be matched before the
+                // generic `_count_` prefix (its slice(7) is `_all`, which snakeToCamel
+                // would mangle to `All`).
                 const countObj = {};
                 let hasCountFields = false;
                 for (const [key, val] of Object.entries(row)) {
-                    if (key.startsWith('_count_')) {
+                    if (key === '_count__all') {
+                        countObj._all = val;
+                        hasCountFields = true;
+                    }
+                    else if (key.startsWith('_count_')) {
                         const col = key.slice(7);
                         const field = qi.tableMeta.reverseColumnMap[col] ?? snakeToCamel(col);
                         countObj[field] = val;

package/dist/query/builder.d.ts

@@ -47,8 +47,16 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      */
     private sqlCacheEnabled;
     private readonly dialect;
-    /** Client-level default relation-loading strategy ('join' unless configured). */
+    /**
+     * Client-level default relation-loading strategy. When nothing is configured
+     * this is `'auto'` (the implicit default): per-relation, keep the single-
+     * statement join unless the introspected metadata proves a probe is unindexed,
+     * in which case that relation falls back to the batched loader. An explicit
+     * `'join'`/`'batched'` (client or query level) always wins.
+     */
     private readonly relationLoadStrategy;
+    /** Client-level default for {@link applyStableRelationOrder} (off unless configured). */
+    private readonly stableRelationOrder;
     /** Nested-relation JSON encoding: 'object' (default) or 'positional'. */
     private readonly jsonEncoding;
     /**
@@ -79,8 +87,6 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * must never receive this schema's `::"enum"` cast (see enumTypeForColumn).
      */
     private readonly crossSchemaTypeColumns;
-    /** Tracks tables that have already triggered a deep-with warning (one-time) */
-    private readonly deepWithWarned;
     /**
      * Per-table memo of date columns keyed by their camelCase FIELD name.
      * `meta.dateColumns` is keyed by raw snake_case column name, which matches
@@ -95,6 +101,15 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly options?;
     /** Set by executeWithMiddleware so queryWithTimeout can include it in events. */
     private currentAction;
+    /**
+     * Tags the query events of an in-flight `relationLoadStrategy: 'auto'` query
+     * that engaged the batched fallback (`'auto-batched'`), so observability sees
+     * which queries the auto default re-planned. Same transient-instance-state
+     * caveat as {@link currentAction}: set for the whole auto-split operation and
+     * cleared afterward; a concurrent unrelated query on the same accessor during
+     * that window could read it (a best-effort diagnostic tag, not load-bearing).
+     */
+    private currentStrategyTag;
     /**
      * 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
@@ -181,10 +196,68 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private inParam;
     /**
      * Resolve the effective relation-loading strategy for a query: the per-query
-     * arg wins, then the client-level default, then `'join'`. Only meaningful when
+     * arg wins, then the client-level default, then `'auto'`. Only meaningful when
      * a `with` clause is present; the callers gate on that.
      */
     private resolveLoadStrategy;
+    /**
+     * The effective {@link QueryInterfaceOptions.stableRelationOrder} for a query:
+     * the per-query arg wins, then the client-level default (off).
+     */
+    private resolveStableOrder;
+    /**
+     * Fill a PK-ascending `orderBy` into every to-many `with` relation that has no
+     * explicit one, recursing into nested `with`. Returns a CLONED clause (user
+     * args are never mutated); when nothing needs filling it returns the input
+     * object unchanged, so the byte-identical fast path stays free. Only called
+     * when {@link resolveStableOrder} is true; runs BEFORE `withFingerprint`, so
+     * the two orderings get distinct SQL-cache entries automatically. To-one
+     * relations are single rows (no array to order) and PK-less targets have
+     * nothing stable to order by, so both are left untouched.
+     */
+    private applyStableRelationOrder;
+    /**
+     * Whether a relation can be served by the batched loader, i.e. all its
+     * correlation keys are single-column (the loader throws E017 on composite
+     * keys). Composite-key relations therefore always stay on the join plan under
+     * `'auto'` (and keep the existing unindexed-probe dev warning).
+     */
+    private relationBatchEligible;
+    /**
+     * The verdict for one relation SUBTREE under `'auto'`: is any probe in the
+     * subtree unindexed, is EVERY relation in the subtree batched-eligible, and
+     * the first unindexed probe found (for the dev note). Subtree-atomic: a whole
+     * top-level relation falls back only when its entire subtree is eligible,
+     * mirroring the batched loader recursing the same tree.
+     */
+    private autoSubtreeVerdict;
+    /** The `_count` verdict under `'auto'`: any counted probe unindexed + all single-key. */
+    private autoCountVerdict;
+    /**
+     * Partition a top-level `with` clause under `'auto'`: each relation whose
+     * subtree has a PROVEN unindexed probe AND is fully batched-eligible routes to
+     * `batchedWith`; everything else (indexed, composite-key, unknown) stays in
+     * `joinWith` (byte-identical join). The reserved `_count` key partitions the
+     * same way. Also returns the engaged relations for the dev note.
+     */
+    private partitionWithForAuto;
+    /**
+     * Plan the `'auto'` split for a query's `with` clause: normalize stable order,
+     * partition, and return the split ONLY when at least one relation falls back
+     * to batched. Returns `null` (→ run the plain join path, byte-identical, same
+     * cache keys) when there is no DB-backed index metadata or nothing qualifies.
+     */
+    private planAuto;
+    /** Dev-only once-per-relation note that `'auto'` engaged the batched fallback. */
+    private emitAutoNotes;
+    /**
+     * Execute a findMany/findUnique `'auto'` split: run the base query with the
+     * residual `joinWith` (plus any parent stitch keys the batched subset needs),
+     * then load `batchedWith` via the batched loader and stitch. `single` returns
+     * the first entity (findUnique) instead of the array. Output is identical in
+     * shape to the pure join plan.
+     */
+    private runAutoSplit;
     /**
      * Build the {@link RelationLoadContext} the batched loader needs, closing over
      * this interface's pool/dialect/executor. Child readers are constructed on the