@rvoh/dream 2.18.1 → 2.20.0

package/dist/esm/src/dream/Query.js

@@ -442,6 +442,17 @@ export default class Query {
      * 3. each nested association will result in an additional record which duplicates data from the outer record. E.g., given `.leftJoinPreload('a', 'b', 'c')`, if each `a` has 10 `b` and each `b` has 10 `c`, then for one `a`, 100 records will be returned, each of which has all of the columns of `a`. `.preload('a', 'b', 'c')` would perform three separate SQL queries, but the data for a single `a` would only be returned once.
      * 4. the individual query becomes more complex the more associations are included
      * 5. associations loading associations loading associations could result in exponential amounts of data; in those cases, `.preload(...).findEach(...)` avoids instantiating massive amounts of data at once
+     * 6. unlike base-model reads, `preload`/`load`, and saves — which tolerate
+     * schema/image skew (e.g. a rolling deploy dropping a column while
+     * containers compiled against the previous schema are still draining) —
+     * leftJoinPreload must enumerate every compiled column of every joined
+     * model under per-alias names (per-alias `*` is not expressible in a
+     * single flat row), so an **unplanned** column drop breaks
+     * leftJoinPreload queries for the duration of the rollout window. A
+     * **planned** drop is safe when performed via the two-deploy process
+     * documented on the `ignoredColumns` getter of Dream: declaring the
+     * column ignored removes it from the generated schema, so leftJoinPreload
+     * stops naming it a full deploy before the column is actually dropped.
      *
      *
      * ```ts
@@ -980,6 +991,39 @@ export default class Query {
     async count() {
         return await this.dbDriverInstance().count();
     }
+    /**
+     * Retrieves the number of records in each group, keyed by the
+     * value of the provided group column (a SQL `GROUP BY`).
+     *
+     * ```ts
+     * await User.query().countBy('name')
+     * // Map(2) { 'fred' => 2, 'zed' => 1 }
+     *
+     * await User.where({ email: ops.ilike('%gmail.com') }).countBy('name')
+     * // Map(1) { 'fred' => 3 }
+     * ```
+     *
+     * Any `where` clauses, base scopes (soft-delete / STI), and joined-association
+     * `and` clauses on the Query carry through automatically. A joined-association
+     * column may be grouped on by passing its namespaced name (e.g.
+     * `'compositionAssets.name'`).
+     *
+     * Only groups with at least one matching row appear in the Map (inherent to
+     * `GROUP BY`); seed absent groups yourself with `map.get(key) ?? 0`. When the
+     * group column is nullable, records with a `null` value are grouped under a real
+     * `null` key.
+     *
+     * ```ts
+     * await Composition.query().innerJoin('compositionAssets').countBy('compositionAssets.name')
+     * // Map(2) { 'primary' => 3, null => 1 }
+     * ```
+     *
+     * @param groupColumn - the column to group by (base or joined-association-namespaced)
+     * @returns A Map from each present group value to the number of records in that group
+     */
+    async countBy(groupColumn) {
+        return await this.dbDriverInstance().countBy(groupColumn);
+    }
     /**
      * Returns new Query with distinct clause applied.
      * If no column is specified, applies distinct to the primary key.
@@ -1038,6 +1082,32 @@ export default class Query {
     async max(columnName) {
         return await this.dbDriverInstance().max(columnName);
     }
+    /**
+     * Retrieves the max value of the specified column within each group, keyed by
+     * the value of the provided group column (a SQL `GROUP BY`).
+     *
+     * ```ts
+     * await CompositionAsset.query().maxBy('name', 'score')
+     * // Map(2) { 'primary' => 9, 'secondary' => 4 }
+     * ```
+     *
+     * Any `where` clauses, base scopes (soft-delete / STI), and joined-association
+     * `and` clauses on the Query carry through automatically. A joined-association
+     * column may be grouped on or aggregated by passing its namespaced name (e.g.
+     * `'compositionAssets.name'`).
+     *
+     * Only groups with at least one matching row appear in the Map (inherent to
+     * `GROUP BY`). When the group column is nullable, records with a `null` value
+     * are grouped under a real `null` key; a group whose aggregated values are all
+     * `null` yields a `null` value.
+     *
+     * @param groupColumn - the column to group by (base or joined-association-namespaced)
+     * @param aggregatedColumn - the column to take the max of within each group
+     * @returns A Map from each present group value to the max of the aggregated column in that group
+     */
+    async maxBy(groupColumn, aggregatedColumn) {
+        return await this.dbDriverInstance().maxBy(groupColumn, aggregatedColumn);
+    }
     /**
      * Retrieves the min value of the specified column
      * for this Query
@@ -1053,6 +1123,32 @@ export default class Query {
     async min(columnName) {
         return await this.dbDriverInstance().min(columnName);
     }
+    /**
+     * Retrieves the min value of the specified column within each group, keyed by
+     * the value of the provided group column (a SQL `GROUP BY`).
+     *
+     * ```ts
+     * await CompositionAsset.query().minBy('name', 'score')
+     * // Map(2) { 'primary' => 1, 'secondary' => 4 }
+     * ```
+     *
+     * Any `where` clauses, base scopes (soft-delete / STI), and joined-association
+     * `and` clauses on the Query carry through automatically. A joined-association
+     * column may be grouped on or aggregated by passing its namespaced name (e.g.
+     * `'compositionAssets.name'`).
+     *
+     * Only groups with at least one matching row appear in the Map (inherent to
+     * `GROUP BY`). When the group column is nullable, records with a `null` value
+     * are grouped under a real `null` key; a group whose aggregated values are all
+     * `null` yields a `null` value.
+     *
+     * @param groupColumn - the column to group by (base or joined-association-namespaced)
+     * @param aggregatedColumn - the column to take the min of within each group
+     * @returns A Map from each present group value to the min of the aggregated column in that group
+     */
+    async minBy(groupColumn, aggregatedColumn) {
+        return await this.dbDriverInstance().minBy(groupColumn, aggregatedColumn);
+    }
     /**
      * Retrieves the sum value of the specified column
      * for this Query
@@ -1068,6 +1164,32 @@ export default class Query {
     async sum(columnName) {
         return await this.dbDriverInstance().sum(columnName);
     }
+    /**
+     * Retrieves the sum of the specified column within each group, keyed by
+     * the value of the provided group column (a SQL `GROUP BY`).
+     *
+     * ```ts
+     * await CompositionAsset.query().sumBy('name', 'score')
+     * // Map(2) { 'primary' => 10, 'secondary' => 4 }
+     * ```
+     *
+     * Any `where` clauses, base scopes (soft-delete / STI), and joined-association
+     * `and` clauses on the Query carry through automatically. A joined-association
+     * column may be grouped on or aggregated by passing its namespaced name (e.g.
+     * `'compositionAssets.name'`).
+     *
+     * Only groups with at least one matching row appear in the Map (inherent to
+     * `GROUP BY`). When the group column is nullable, records with a `null` value
+     * are grouped under a real `null` key; a group whose aggregated values are all
+     * `null` yields a `null` value.
+     *
+     * @param groupColumn - the column to group by (base or joined-association-namespaced)
+     * @param aggregatedColumn - the column to sum within each group
+     * @returns A Map from each present group value to the sum of the aggregated column in that group
+     */
+    async sumBy(groupColumn, aggregatedColumn) {
+        return await this.dbDriverInstance().sumBy(groupColumn, aggregatedColumn);
+    }
     /**
      * Retrieves the average value of the specified column
      * for this Query
@@ -1083,6 +1205,32 @@ export default class Query {
     async avg(columnName) {
         return await this.dbDriverInstance().avg(columnName);
     }
+    /**
+     * Retrieves the average of the specified column within each group, keyed by
+     * the value of the provided group column (a SQL `GROUP BY`).
+     *
+     * ```ts
+     * await CompositionAsset.query().avgBy('name', 'score')
+     * // Map(2) { 'primary' => 5, 'secondary' => 4 }
+     * ```
+     *
+     * Any `where` clauses, base scopes (soft-delete / STI), and joined-association
+     * `and` clauses on the Query carry through automatically. A joined-association
+     * column may be grouped on or aggregated by passing its namespaced name (e.g.
+     * `'compositionAssets.name'`).
+     *
+     * Only groups with at least one matching row appear in the Map (inherent to
+     * `GROUP BY`). When the group column is nullable, records with a `null` value
+     * are grouped under a real `null` key; a group whose aggregated values are all
+     * `null` yields a `null` value.
+     *
+     * @param groupColumn - the column to group by (base or joined-association-namespaced)
+     * @param aggregatedColumn - the column to average within each group
+     * @returns A Map from each present group value to the average of the aggregated column in that group
+     */
+    async avgBy(groupColumn, aggregatedColumn) {
+        return await this.dbDriverInstance().avgBy(groupColumn, aggregatedColumn);
+    }
     /**
      * Plucks the provided fields from the given dream class table
      *

package/dist/esm/src/dream/QueryDriver/Base.js

@@ -273,6 +273,23 @@ export default class QueryDriverBase {
     async max(columnName) {
         throw new Error('implement max in child class');
     }
+    /**
+     * Retrieves the max value of the specified column within each group,
+     * keyed by the value of the provided group column.
+     *
+     * ```ts
+     * await CompositionAsset.query().maxBy('name', 'score')
+     * // Map(2) { 'primary' => 9, 'secondary' => 4 }
+     * ```
+     *
+     * @param groupColumn - the column to group by
+     * @param aggregatedColumn - the column to take the max of within each group
+     * @returns A Map from each present group value to the max of the aggregated column in that group
+     */
+    // eslint-disable-next-line @typescript-eslint/require-await, @typescript-eslint/no-unused-vars
+    async maxBy(groupColumn, aggregatedColumn) {
+        throw new Error('implement maxBy in child class');
+    }
     /**
      * Retrieves the min value of the specified column
      * for this Query
@@ -289,6 +306,23 @@ export default class QueryDriverBase {
     async min(columnName) {
         throw new Error('implement min in child class');
     }
+    /**
+     * Retrieves the min value of the specified column within each group,
+     * keyed by the value of the provided group column.
+     *
+     * ```ts
+     * await CompositionAsset.query().minBy('name', 'score')
+     * // Map(2) { 'primary' => 1, 'secondary' => 4 }
+     * ```
+     *
+     * @param groupColumn - the column to group by
+     * @param aggregatedColumn - the column to take the min of within each group
+     * @returns A Map from each present group value to the min of the aggregated column in that group
+     */
+    // eslint-disable-next-line @typescript-eslint/require-await, @typescript-eslint/no-unused-vars
+    async minBy(groupColumn, aggregatedColumn) {
+        throw new Error('implement minBy in child class');
+    }
     /**
      * Retrieves the sum value of the specified column
      * for this Query
@@ -305,6 +339,23 @@ export default class QueryDriverBase {
     async sum(columnName) {
         throw new Error('implement sum in child class');
     }
+    /**
+     * Retrieves the sum of the specified column within each group,
+     * keyed by the value of the provided group column.
+     *
+     * ```ts
+     * await CompositionAsset.query().sumBy('name', 'score')
+     * // Map(2) { 'primary' => 10, 'secondary' => 4 }
+     * ```
+     *
+     * @param groupColumn - the column to group by
+     * @param aggregatedColumn - the column to sum within each group
+     * @returns A Map from each present group value to the sum of the aggregated column in that group
+     */
+    // eslint-disable-next-line @typescript-eslint/require-await, @typescript-eslint/no-unused-vars
+    async sumBy(groupColumn, aggregatedColumn) {
+        throw new Error('implement sumBy in child class');
+    }
     /**
      * Retrieves the average value of the specified column
      * for this Query
@@ -321,6 +372,23 @@ export default class QueryDriverBase {
     async avg(columnName) {
         throw new Error('implement avg in child class');
     }
+    /**
+     * Retrieves the average of the specified column within each group,
+     * keyed by the value of the provided group column.
+     *
+     * ```ts
+     * await CompositionAsset.query().avgBy('name', 'score')
+     * // Map(2) { 'primary' => 5, 'secondary' => 4 }
+     * ```
+     *
+     * @param groupColumn - the column to group by
+     * @param aggregatedColumn - the column to average within each group
+     * @returns A Map from each present group value to the average of the aggregated column in that group
+     */
+    // eslint-disable-next-line @typescript-eslint/require-await, @typescript-eslint/no-unused-vars
+    async avgBy(groupColumn, aggregatedColumn) {
+        throw new Error('implement avgBy in child class');
+    }
     /**
      * Retrieves the number of records in the database
      *
@@ -334,6 +402,22 @@ export default class QueryDriverBase {
     async count() {
         throw new Error('implement count in child class');
     }
+    /**
+     * Retrieves the number of records in each group, keyed by the
+     * value of the provided group column.
+     *
+     * ```ts
+     * await User.query().countBy('name')
+     * // Map(2) { 'fred' => 2, 'zed' => 1 }
+     * ```
+     *
+     * @param groupColumn - the column to group by
+     * @returns A Map from each present group value to the number of records in that group
+     */
+    // eslint-disable-next-line @typescript-eslint/require-await, @typescript-eslint/no-unused-vars
+    async countBy(groupColumn) {
+        throw new Error('implement countBy in child class');
+    }
     /**
      * @internal
      *