turbine-orm 0.32.1 → 0.32.2

package/dist/cjs/powql.js

@@ -1216,6 +1216,17 @@ class PowqlInterface {
                 proj.push(`${a.alias}: ${a.fn}(${a.field ? this.ref(a.field) : `.${this.meta.primaryKey[0]}`})`);
             }
             const having = this.buildHaving(args.having, params);
+            // groupBy aggregate ordering (`_count` / `_sum` / … keys) has no PowQL
+            // equivalent here: `buildOrder` treats an `orderBy` key as a field ref, so
+            // a bare `_count: 'desc'` would silently emit an invalid `._count` sort.
+            // Refuse those keys explicitly; plain by-field ordering still flows through.
+            if (args.orderBy) {
+                for (const key of Object.keys(args.orderBy)) {
+                    if (key === '_count' || key === '_sum' || key === '_avg' || key === '_min' || key === '_max') {
+                        throw new errors_js_1.UnsupportedFeatureError('groupBy ordering by an aggregate', 'PowDB', `orderBy key "${key}"`);
+                    }
+                }
+            }
             const order = this.buildOrder(args.orderBy);
             const powql = `${this.qt}${filter} group ${groupKeys.join(', ')}${having}${order} { ${proj.join(', ')} }`;
             const { rows } = await this.exec(powql, params, args.timeout);

package/dist/cjs/query/builder.js

@@ -1854,6 +1854,15 @@ class QueryInterface {
         const selectExprs = [];
         /** by entries in order: how to read each group key off the result row. */
         const byReaders = [];
+        // ORDER BY registries: map each key the groupBy RESULT actually contains to
+        // the exact SELECT expression that produced it, so `orderBy` re-emits that
+        // expression (never a SELECT alias, since not every dialect accepts alias
+        // references in ORDER BY, and re-emitting mirrors HAVING's `jsonAggExprs`).
+        // `byOrderExprs`: plain by-field name / JSON group-key alias → column or
+        // extract expression. `aggOrderExprs`: `${aggKey}:${field}` → aggregate
+        // expression (including any already-bound JSON-path placeholder, reused
+        // exactly like HAVING since ORDER BY is appended after all other params).
+        const byOrderExprs = new Map();
         const usedResultKeys = new Set();
         const claimResultKey = (key, what) => {
             if (key === '_count' || usedResultKeys.has(key)) {
@@ -1874,6 +1883,7 @@ class QueryInterface {
                 groupExprs.push(this.q(col));
                 selectExprs.push(this.q(col));
                 byReaders.push({ resultKey: entry, rowKey: col, raw: false });
+                byOrderExprs.set(entry, this.q(col));
             }
             else {
                 const col = this.resolveJsonPathTarget('group key', entry.field, entry.path);
@@ -1885,13 +1895,24 @@ class QueryInterface {
                 selectExprs.push(`(${extract}) AS ${this.q(alias)}`);
                 groupExprs.push(extract);
                 byReaders.push({ resultKey: alias, rowKey: alias, raw: true });
+                // ORDER BY by this JSON alias re-emits the extract expression (with its
+                // already-bound $n): the same reuse HAVING does for JSON aggregates.
+                byOrderExprs.set(alias, extract);
             }
         }
         // _count
-        if (args._count === true || args._count === undefined) {
+        const countSelected = args._count === true || args._count === undefined;
+        if (countSelected) {
             // default: always include count
             selectExprs.push(`${this.castAgg('COUNT(*)', 'int')} AS _count`);
         }
+        // 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).
+        const aggOrderExprs = new Map();
+        if (countSelected)
+            aggOrderExprs.set('_count', 'COUNT(*)');
         // _sum / _avg / _min / _max: `true` keeps the plain-column behavior; a
         // {@link JsonPathAggregateTarget} aggregates a JSON path under the arg key
         // as alias. `jsonAggFields` routes each JSON-aggregate row key back to its
@@ -1914,6 +1935,7 @@ class QueryInterface {
                     const inner = `${sqlFn}(${this.q(col)})`;
                     const expr = aggKey === '_avg' ? this.castAgg(inner, 'float') : inner;
                     selectExprs.push(`${expr} AS ${this.q(`${aggKey}_${col}`)}`);
+                    aggOrderExprs.set(`${aggKey}:${key}`, expr);
                     continue;
                 }
                 const col = this.resolveJsonPathTarget(`${aggKey} target "${key}"`, target.field, target.path);
@@ -1931,6 +1953,7 @@ class QueryInterface {
                 selectExprs.push(`${expr} AS ${this.q(`${aggKey}_${key}`)}`);
                 jsonAggFields.set(`${aggKey}_${key}`, { field: key, numeric });
                 jsonAggExprs.set(`${key}:${aggKey}`, expr);
+                aggOrderExprs.set(`${aggKey}:${key}`, expr);
             }
         };
         buildAggregates('_sum', 'SUM', args._sum);
@@ -1947,9 +1970,12 @@ class QueryInterface {
                 sql += ` HAVING ${havingClauses.join(' AND ')}`;
             }
         }
-        // ORDER BY
+        // ORDER BY, over the groupBy RESULT columns (by-fields, JSON aliases, and
+        // requested aggregates), not the table's physical columns.
         if (args.orderBy) {
-            sql += ` ORDER BY ${this.buildOrderBy(args.orderBy)}`;
+            const orderSql = this.buildGroupByOrderBy(args.orderBy, byOrderExprs, aggOrderExprs);
+            if (orderSql)
+                sql += ` ORDER BY ${orderSql}`;
         }
         return {
             sql,
@@ -2014,6 +2040,74 @@ class QueryInterface {
             tag: `${this.table}.groupBy`,
         };
     }
+    /**
+     * Compile a groupBy `orderBy` into an ORDER BY body. Unlike findMany ORDER BY
+     * ({@link buildOrderBy}, which validates keys against the table's physical
+     * columns), groupBy ordering targets the columns the RESULT actually
+     * contains: plain by-fields, JSON group-key aliases, and requested aggregates
+     * (`_count` / `_sum` / `_avg` / `_min` / `_max`). Each key re-emits the exact
+     * SELECT expression that produced it (`byOrderExprs` / `aggOrderExprs`),
+     * mirroring how HAVING re-emits aggregate expressions, so no dialect ever has
+     * to accept a SELECT-alias reference in ORDER BY, and any already-bound
+     * JSON-path placeholder is reused verbatim (ORDER BY is the last clause, so
+     * no `$n` renumbering). An aggregate key that was not requested, or an unknown
+     * by-key, throws {@link ValidationError} E003 listing the valid keys.
+     */
+    buildGroupByOrderBy(orderBy, byOrderExprs, aggOrderExprs) {
+        const aggBlocks = new Set(['_count', '_sum', '_avg', '_min', '_max']);
+        /** Human-readable list of every key this call can order by (for E003). */
+        const validKeys = () => {
+            const keys = [...byOrderExprs.keys()];
+            for (const k of aggOrderExprs.keys()) {
+                keys.push(k.includes(':') ? k.replace(':', '.') : k);
+            }
+            return keys.join(', ') || '(none)';
+        };
+        const parts = [];
+        for (const [key, value] of Object.entries(orderBy)) {
+            if (value === undefined)
+                continue;
+            // Aggregate ordering blocks.
+            if (aggBlocks.has(key)) {
+                if (key === '_count') {
+                    const expr = aggOrderExprs.get('_count');
+                    if (!expr) {
+                        throw new errors_js_1.ValidationError(`[turbine] Cannot order groupBy by "_count" on table "${this.table}": _count is not selected. ` +
+                            `Orderable keys: ${validKeys()}.`);
+                    }
+                    const { dir, nulls } = (0, filters_js_1.normalizeOrderBy)(value);
+                    parts.push(`${expr} ${dir}${this.nullsSuffix(nulls)}`);
+                    continue;
+                }
+                // `_sum` / `_avg` / `_min` / `_max`: an object of field → direction/spec.
+                if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+                    throw new errors_js_1.ValidationError(`[turbine] Invalid groupBy orderBy for "${key}" on table "${this.table}": ` +
+                        `expected a field map like { ${key}: { amount: 'desc' } }.`);
+                }
+                for (const [field, dirSpec] of Object.entries(value)) {
+                    if (dirSpec === undefined)
+                        continue;
+                    const expr = aggOrderExprs.get(`${key}:${field}`);
+                    if (!expr) {
+                        throw new errors_js_1.ValidationError(`[turbine] Cannot order groupBy by "${key}.${field}" on table "${this.table}": ` +
+                            `that aggregate is not requested in this call. Orderable keys: ${validKeys()}.`);
+                    }
+                    const { dir, nulls } = (0, filters_js_1.normalizeOrderBy)(dirSpec);
+                    parts.push(`${expr} ${dir}${this.nullsSuffix(nulls)}`);
+                }
+                continue;
+            }
+            // Plain by-field name or JSON group-key alias.
+            const expr = byOrderExprs.get(key);
+            if (!expr) {
+                throw new errors_js_1.ValidationError(`[turbine] Unknown field "${key}" in groupBy orderBy on table "${this.table}". ` +
+                    `Orderable keys: ${validKeys()}.`);
+            }
+            const { dir, nulls } = (0, filters_js_1.normalizeOrderBy)(value);
+            parts.push(`${expr} ${dir}${this.nullsSuffix(nulls)}`);
+        }
+        return parts.join(', ');
+    }
     /**
      * Validate a JSON-path target (group key or aggregate target) in groupBy:
      * the field must resolve to a real json/jsonb column and the path must be a

package/dist/powql.js

@@ -1180,6 +1180,17 @@ export class PowqlInterface {
                 proj.push(`${a.alias}: ${a.fn}(${a.field ? this.ref(a.field) : `.${this.meta.primaryKey[0]}`})`);
             }
             const having = this.buildHaving(args.having, params);
+            // groupBy aggregate ordering (`_count` / `_sum` / … keys) has no PowQL
+            // equivalent here: `buildOrder` treats an `orderBy` key as a field ref, so
+            // a bare `_count: 'desc'` would silently emit an invalid `._count` sort.
+            // Refuse those keys explicitly; plain by-field ordering still flows through.
+            if (args.orderBy) {
+                for (const key of Object.keys(args.orderBy)) {
+                    if (key === '_count' || key === '_sum' || key === '_avg' || key === '_min' || key === '_max') {
+                        throw new UnsupportedFeatureError('groupBy ordering by an aggregate', 'PowDB', `orderBy key "${key}"`);
+                    }
+                }
+            }
             const order = this.buildOrder(args.orderBy);
             const powql = `${this.qt}${filter} group ${groupKeys.join(', ')}${having}${order} { ${proj.join(', ')} }`;
             const { rows } = await this.exec(powql, params, args.timeout);

package/dist/query/builder.d.ts

@@ -382,6 +382,20 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     buildCount(args?: CountArgs<T>): DeferredQuery<number>;
     groupBy(args: GroupByArgs<T>): Promise<Record<string, unknown>[]>;
     buildGroupBy(args: GroupByArgs<T>): DeferredQuery<Record<string, unknown>[]>;
+    /**
+     * Compile a groupBy `orderBy` into an ORDER BY body. Unlike findMany ORDER BY
+     * ({@link buildOrderBy}, which validates keys against the table's physical
+     * columns), groupBy ordering targets the columns the RESULT actually
+     * contains: plain by-fields, JSON group-key aliases, and requested aggregates
+     * (`_count` / `_sum` / `_avg` / `_min` / `_max`). Each key re-emits the exact
+     * SELECT expression that produced it (`byOrderExprs` / `aggOrderExprs`),
+     * mirroring how HAVING re-emits aggregate expressions, so no dialect ever has
+     * to accept a SELECT-alias reference in ORDER BY, and any already-bound
+     * JSON-path placeholder is reused verbatim (ORDER BY is the last clause, so
+     * no `$n` renumbering). An aggregate key that was not requested, or an unknown
+     * by-key, throws {@link ValidationError} E003 listing the valid keys.
+     */
+    private buildGroupByOrderBy;
     /**
      * Validate a JSON-path target (group key or aggregate target) in groupBy:
      * the field must resolve to a real json/jsonb column and the path must be a

package/dist/query/builder.js

@@ -1818,6 +1818,15 @@ export class QueryInterface {
         const selectExprs = [];
         /** by entries in order: how to read each group key off the result row. */
         const byReaders = [];
+        // ORDER BY registries: map each key the groupBy RESULT actually contains to
+        // the exact SELECT expression that produced it, so `orderBy` re-emits that
+        // expression (never a SELECT alias, since not every dialect accepts alias
+        // references in ORDER BY, and re-emitting mirrors HAVING's `jsonAggExprs`).
+        // `byOrderExprs`: plain by-field name / JSON group-key alias → column or
+        // extract expression. `aggOrderExprs`: `${aggKey}:${field}` → aggregate
+        // expression (including any already-bound JSON-path placeholder, reused
+        // exactly like HAVING since ORDER BY is appended after all other params).
+        const byOrderExprs = new Map();
         const usedResultKeys = new Set();
         const claimResultKey = (key, what) => {
             if (key === '_count' || usedResultKeys.has(key)) {
@@ -1838,6 +1847,7 @@ export class QueryInterface {
                 groupExprs.push(this.q(col));
                 selectExprs.push(this.q(col));
                 byReaders.push({ resultKey: entry, rowKey: col, raw: false });
+                byOrderExprs.set(entry, this.q(col));
             }
             else {
                 const col = this.resolveJsonPathTarget('group key', entry.field, entry.path);
@@ -1849,13 +1859,24 @@ export class QueryInterface {
                 selectExprs.push(`(${extract}) AS ${this.q(alias)}`);
                 groupExprs.push(extract);
                 byReaders.push({ resultKey: alias, rowKey: alias, raw: true });
+                // ORDER BY by this JSON alias re-emits the extract expression (with its
+                // already-bound $n): the same reuse HAVING does for JSON aggregates.
+                byOrderExprs.set(alias, extract);
             }
         }
         // _count
-        if (args._count === true || args._count === undefined) {
+        const countSelected = args._count === true || args._count === undefined;
+        if (countSelected) {
             // default: always include count
             selectExprs.push(`${this.castAgg('COUNT(*)', 'int')} AS _count`);
         }
+        // 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).
+        const aggOrderExprs = new Map();
+        if (countSelected)
+            aggOrderExprs.set('_count', 'COUNT(*)');
         // _sum / _avg / _min / _max: `true` keeps the plain-column behavior; a
         // {@link JsonPathAggregateTarget} aggregates a JSON path under the arg key
         // as alias. `jsonAggFields` routes each JSON-aggregate row key back to its
@@ -1878,6 +1899,7 @@ export class QueryInterface {
                     const inner = `${sqlFn}(${this.q(col)})`;
                     const expr = aggKey === '_avg' ? this.castAgg(inner, 'float') : inner;
                     selectExprs.push(`${expr} AS ${this.q(`${aggKey}_${col}`)}`);
+                    aggOrderExprs.set(`${aggKey}:${key}`, expr);
                     continue;
                 }
                 const col = this.resolveJsonPathTarget(`${aggKey} target "${key}"`, target.field, target.path);
@@ -1895,6 +1917,7 @@ export class QueryInterface {
                 selectExprs.push(`${expr} AS ${this.q(`${aggKey}_${key}`)}`);
                 jsonAggFields.set(`${aggKey}_${key}`, { field: key, numeric });
                 jsonAggExprs.set(`${key}:${aggKey}`, expr);
+                aggOrderExprs.set(`${aggKey}:${key}`, expr);
             }
         };
         buildAggregates('_sum', 'SUM', args._sum);
@@ -1911,9 +1934,12 @@ export class QueryInterface {
                 sql += ` HAVING ${havingClauses.join(' AND ')}`;
             }
         }
-        // ORDER BY
+        // ORDER BY, over the groupBy RESULT columns (by-fields, JSON aliases, and
+        // requested aggregates), not the table's physical columns.
         if (args.orderBy) {
-            sql += ` ORDER BY ${this.buildOrderBy(args.orderBy)}`;
+            const orderSql = this.buildGroupByOrderBy(args.orderBy, byOrderExprs, aggOrderExprs);
+            if (orderSql)
+                sql += ` ORDER BY ${orderSql}`;
         }
         return {
             sql,
@@ -1978,6 +2004,74 @@ export class QueryInterface {
             tag: `${this.table}.groupBy`,
         };
     }
+    /**
+     * Compile a groupBy `orderBy` into an ORDER BY body. Unlike findMany ORDER BY
+     * ({@link buildOrderBy}, which validates keys against the table's physical
+     * columns), groupBy ordering targets the columns the RESULT actually
+     * contains: plain by-fields, JSON group-key aliases, and requested aggregates
+     * (`_count` / `_sum` / `_avg` / `_min` / `_max`). Each key re-emits the exact
+     * SELECT expression that produced it (`byOrderExprs` / `aggOrderExprs`),
+     * mirroring how HAVING re-emits aggregate expressions, so no dialect ever has
+     * to accept a SELECT-alias reference in ORDER BY, and any already-bound
+     * JSON-path placeholder is reused verbatim (ORDER BY is the last clause, so
+     * no `$n` renumbering). An aggregate key that was not requested, or an unknown
+     * by-key, throws {@link ValidationError} E003 listing the valid keys.
+     */
+    buildGroupByOrderBy(orderBy, byOrderExprs, aggOrderExprs) {
+        const aggBlocks = new Set(['_count', '_sum', '_avg', '_min', '_max']);
+        /** Human-readable list of every key this call can order by (for E003). */
+        const validKeys = () => {
+            const keys = [...byOrderExprs.keys()];
+            for (const k of aggOrderExprs.keys()) {
+                keys.push(k.includes(':') ? k.replace(':', '.') : k);
+            }
+            return keys.join(', ') || '(none)';
+        };
+        const parts = [];
+        for (const [key, value] of Object.entries(orderBy)) {
+            if (value === undefined)
+                continue;
+            // Aggregate ordering blocks.
+            if (aggBlocks.has(key)) {
+                if (key === '_count') {
+                    const expr = aggOrderExprs.get('_count');
+                    if (!expr) {
+                        throw new ValidationError(`[turbine] Cannot order groupBy by "_count" on table "${this.table}": _count is not selected. ` +
+                            `Orderable keys: ${validKeys()}.`);
+                    }
+                    const { dir, nulls } = normalizeOrderBy(value);
+                    parts.push(`${expr} ${dir}${this.nullsSuffix(nulls)}`);
+                    continue;
+                }
+                // `_sum` / `_avg` / `_min` / `_max`: an object of field → direction/spec.
+                if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+                    throw new ValidationError(`[turbine] Invalid groupBy orderBy for "${key}" on table "${this.table}": ` +
+                        `expected a field map like { ${key}: { amount: 'desc' } }.`);
+                }
+                for (const [field, dirSpec] of Object.entries(value)) {
+                    if (dirSpec === undefined)
+                        continue;
+                    const expr = aggOrderExprs.get(`${key}:${field}`);
+                    if (!expr) {
+                        throw new ValidationError(`[turbine] Cannot order groupBy by "${key}.${field}" on table "${this.table}": ` +
+                            `that aggregate is not requested in this call. Orderable keys: ${validKeys()}.`);
+                    }
+                    const { dir, nulls } = normalizeOrderBy(dirSpec);
+                    parts.push(`${expr} ${dir}${this.nullsSuffix(nulls)}`);
+                }
+                continue;
+            }
+            // Plain by-field name or JSON group-key alias.
+            const expr = byOrderExprs.get(key);
+            if (!expr) {
+                throw new ValidationError(`[turbine] Unknown field "${key}" in groupBy orderBy on table "${this.table}". ` +
+                    `Orderable keys: ${validKeys()}.`);
+            }
+            const { dir, nulls } = normalizeOrderBy(value);
+            parts.push(`${expr} ${dir}${this.nullsSuffix(nulls)}`);
+        }
+        return parts.join(', ');
+    }
     /**
      * Validate a JSON-path target (group key or aggregate target) in groupBy:
      * the field must resolve to a real json/jsonb column and the path must be a

package/dist/query/types.d.ts

@@ -657,6 +657,37 @@ export interface GroupByDistinctOn<T> {
     /** Which row survives per combination (required for determinism). */
     orderBy: Record<string, OrderDirection | OrderBySpec | JsonPathOrderBy>;
 }
+/** A per-field aggregate ordering block: field/alias → direction or sort spec. */
+export type GroupByAggregateOrderBy = Record<string, OrderDirection | OrderBySpec>;
+/**
+ * {@link GroupByArgs.orderBy}: order the result groups by any column the
+ * groupBy result contains.
+ *
+ * - A plain **by-column** field name, or a **JSON group-key alias** (explicit
+ *   `alias`, else the last path segment): `{ region: 'asc' }`.
+ * - An **aggregate block**: `_count` takes a direction/spec directly
+ *   (`{ _count: 'desc' }`); `_sum`/`_avg`/`_min`/`_max` take a field map keyed
+ *   by a requested aggregate field/alias (`{ _sum: { amount: 'desc' } }`).
+ *
+ * An aggregate ordering that references an aggregate not requested in the same
+ * call (or an unknown by-key) throws {@link ValidationError} (E003). Every
+ * value accepts an {@link OrderBySpec} for `NULLS FIRST/LAST` placement
+ * (PostgreSQL / SQLite only).
+ */
+export interface GroupByOrderBy {
+    /** Order by the group's row count (requires `_count` to be selected). */
+    _count?: OrderDirection | OrderBySpec;
+    /** Order by a requested `_sum` aggregate, keyed by its field/alias. */
+    _sum?: GroupByAggregateOrderBy;
+    /** Order by a requested `_avg` aggregate, keyed by its field/alias. */
+    _avg?: GroupByAggregateOrderBy;
+    /** Order by a requested `_min` aggregate, keyed by its field/alias. */
+    _min?: GroupByAggregateOrderBy;
+    /** Order by a requested `_max` aggregate, keyed by its field/alias. */
+    _max?: GroupByAggregateOrderBy;
+    /** A by-column field name or JSON group-key alias → direction or sort spec. */
+    [key: string]: OrderDirection | OrderBySpec | GroupByAggregateOrderBy | undefined;
+}
 export interface GroupByArgs<T> {
     /** Group keys: plain column field names and/or JSON-path keys ({@link JsonPathGroupKey}). */
     by: ((keyof T & string) | JsonPathGroupKey)[];
@@ -678,8 +709,15 @@ export interface GroupByArgs<T> {
     _max?: GroupByAggregateSpec<T>;
     /** Filter whole groups by their aggregate values (SQL HAVING). JSON-path aggregates key by their alias. */
     having?: HavingClause<T>;
-    /** Order groups (supports {@link OrderBySpec} for NULLS placement). */
-    orderBy?: Record<string, OrderDirection | OrderBySpec>;
+    /**
+     * Order the result groups. Keys may be any column the groupBy result actually
+     * contains: a plain by-column field name, a JSON group-key alias (explicit
+     * `alias`, or the last path segment when unaliased), or an aggregate block
+     * (`_count`, or `_sum`/`_avg`/`_min`/`_max` mapping a requested field/alias to
+     * its direction). Every value supports {@link OrderBySpec} for NULLS
+     * placement. See {@link GroupByOrderBy}.
+     */
+    orderBy?: GroupByOrderBy;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
     /** Opt out of configured {@link GlobalFilters}. See {@link SkipGlobalFilters}. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.32.1",
+  "version": "0.32.2",
   "description": "Postgres-native TypeScript ORM — runs on Neon, Vercel Postgres, Cloudflare, Supabase. Streaming cursors, typed errors, single-query nested relations. One dependency, no WASM engine",
   "type": "module",
   "exports": {