@rvoh/dream 2.18.1 → 2.20.0

package/dist/types/src/dream/DreamClassTransactionBuilder.d.ts

@@ -56,6 +56,25 @@ export default class DreamClassTransactionBuilder<DreamClass extends typeof Drea
      * @returns The number of records corresponding to this model
      */
     count<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>>(this: I): Promise<number>;
+    /**
+     * Retrieves the number of records in each group, keyed by the
+     * value of the provided group column (a SQL `GROUP BY`).
+     *
+     * ```ts
+     * await ApplicationModel.transaction(async txn => {
+     *   await User.txn(txn).countBy('name')
+     *   // Map(2) { 'fred' => 2, 'zed' => 1 }
+     * })
+     * ```
+     *
+     * Only groups with at least one matching row appear in the Map; 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.
+     *
+     * @param groupColumn - the column to group by
+     * @returns A Map from each present group value to the number of records in that group
+     */
+    countBy<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>, T extends DreamColumnNames<DreamInstance>>(this: I, groupColumn: T): Promise<Map<DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]][T & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]]]["coercedType" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]][T & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]]]], number>>;
     /**
      * Returns a new Query instance, specifying a limit
      *
@@ -99,6 +118,27 @@ export default class DreamClassTransactionBuilder<DreamClass extends typeof Drea
      * @returns The max value of the specified column for this model's records
      */
     max<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>, T extends DreamColumnNames<DreamInstance>>(this: I, columnName: T): Promise<DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]][T & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]]]["coercedType" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]][T & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]]]]>;
+    /**
+     * 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 ApplicationModel.transaction(async txn => {
+     *   await CompositionAsset.txn(txn).maxBy('name', 'score')
+     *   // Map(2) { 'primary' => 9, 'secondary' => 4 }
+     * })
+     * ```
+     *
+     * Only groups with at least one matching row appear in the Map. 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
+     * @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
+     */
+    maxBy<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>, GroupColumnName extends DreamColumnNames<DreamInstance>, AggregatedColumnName extends DreamColumnNames<DreamInstance>>(this: I, groupColumn: GroupColumnName, aggregatedColumn: AggregatedColumnName): Promise<Map<DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]][GroupColumnName & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]]]["coercedType" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]][GroupColumnName & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]]]], DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]][AggregatedColumnName & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]]]["coercedType" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]][AggregatedColumnName & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]]]]>>;
     /**
      * Retrieves the min value of the specified column
      * for this model's records.
@@ -114,6 +154,27 @@ export default class DreamClassTransactionBuilder<DreamClass extends typeof Drea
      * @returns The min value of the specified column for this model's records
      */
     min<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>, T extends DreamColumnNames<DreamInstance>>(this: I, columnName: T): Promise<DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]][T & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]]]["coercedType" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]][T & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]]]]>;
+    /**
+     * 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 ApplicationModel.transaction(async txn => {
+     *   await CompositionAsset.txn(txn).minBy('name', 'score')
+     *   // Map(2) { 'primary' => 1, 'secondary' => 4 }
+     * })
+     * ```
+     *
+     * Only groups with at least one matching row appear in the Map. 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
+     * @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
+     */
+    minBy<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>, GroupColumnName extends DreamColumnNames<DreamInstance>, AggregatedColumnName extends DreamColumnNames<DreamInstance>>(this: I, groupColumn: GroupColumnName, aggregatedColumn: AggregatedColumnName): Promise<Map<DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]][GroupColumnName & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]]]["coercedType" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]][GroupColumnName & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]]]], DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]][AggregatedColumnName & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]]]["coercedType" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]][AggregatedColumnName & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]]]]>>;
     /**
      * Retrieves the sum value of the specified column
      * for this Query
@@ -127,6 +188,27 @@ export default class DreamClassTransactionBuilder<DreamClass extends typeof Drea
      * @returns the sum of the values of the specified column for this Query
      */
     sum<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>, T extends DreamColumnNames<DreamInstance>>(this: I, columnName: T): Promise<DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]][T & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]]]["coercedType" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]][T & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]]]]>;
+    /**
+     * 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 ApplicationModel.transaction(async txn => {
+     *   await CompositionAsset.txn(txn).sumBy('name', 'score')
+     *   // Map(2) { 'primary' => 10, 'secondary' => 4 }
+     * })
+     * ```
+     *
+     * Only groups with at least one matching row appear in the Map. 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
+     * @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
+     */
+    sumBy<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>, GroupColumnName extends DreamColumnNames<DreamInstance>, AggregatedColumnName extends DreamColumnNames<DreamInstance>>(this: I, groupColumn: GroupColumnName, aggregatedColumn: AggregatedColumnName): Promise<Map<DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]][GroupColumnName & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]]]["coercedType" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]][GroupColumnName & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]]]], DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]][AggregatedColumnName & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]]]["coercedType" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]][AggregatedColumnName & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]]]]>>;
     /**
      * Retrieves the average value of the specified column
      * for this Query
@@ -140,6 +222,27 @@ export default class DreamClassTransactionBuilder<DreamClass extends typeof Drea
      * @returns the average of the values of the specified column for this Query
      */
     avg<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>, T extends DreamColumnNames<DreamInstance>>(this: I, columnName: T): Promise<DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]][T & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]]]["coercedType" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]][T & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]]]]>;
+    /**
+     * 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 ApplicationModel.transaction(async txn => {
+     *   await CompositionAsset.txn(txn).avgBy('name', 'score')
+     *   // Map(2) { 'primary' => 5, 'secondary' => 4 }
+     * })
+     * ```
+     *
+     * Only groups with at least one matching row appear in the Map. 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
+     * @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
+     */
+    avgBy<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>, GroupColumnName extends DreamColumnNames<DreamInstance>, AggregatedColumnName extends DreamColumnNames<DreamInstance>>(this: I, groupColumn: GroupColumnName, aggregatedColumn: AggregatedColumnName): Promise<Map<DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]][GroupColumnName & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]]]["coercedType" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]][GroupColumnName & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]]]], DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]][AggregatedColumnName & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]]]["coercedType" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]][AggregatedColumnName & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]["columns" & keyof DreamInstance["schema"][DreamInstance["table"] & keyof DreamInstance["schema"]]]]]>>;
     /**
      * Persists a new record, setting the provided attributes.
      * Automatically sets createdAt and updatedAt timestamps.

package/dist/types/src/dream/Query.d.ts

@@ -308,6 +308,17 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * 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
@@ -697,6 +708,37 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * @returns The number of records matching the Query
      */
     count(): Promise<number>;
+    /**
+     * 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
+     */
+    countBy<Q extends Query<DreamInstance, QueryTypeOpts>, DB extends DreamInstance['DB'], GroupColumnName extends ColumnNamesAccountingForJoinedAssociations<Q['queryTypeOpts']['joinedAssociations'], DB, QueryTypeOpts['rootTableName'], QueryTypeOpts['rootTableAlias']>, GroupKey extends NamespacedOrBaseModelColumnTypes<[GroupColumnName], Q, DreamInstance>[0]>(groupColumn: GroupColumnName): Promise<Map<GroupKey, number>>;
     /**
      * Returns new Query with distinct clause applied.
      * If no column is specified, applies distinct to the primary key.
@@ -739,6 +781,30 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      *
      */
     max<Q extends Query<DreamInstance, QueryTypeOpts>, DB extends DreamInstance['DB'], ColumnName extends ColumnNamesAccountingForJoinedAssociations<Q['queryTypeOpts']['joinedAssociations'], DB, QueryTypeOpts['rootTableName'], QueryTypeOpts['rootTableAlias']>, ReturnType extends NamespacedOrBaseModelColumnTypes<[ColumnName], Q, DreamInstance>[0]>(columnName: ColumnName): Promise<ReturnType>;
+    /**
+     * 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
+     */
+    maxBy<Q extends Query<DreamInstance, QueryTypeOpts>, DB extends DreamInstance['DB'], GroupColumnName extends ColumnNamesAccountingForJoinedAssociations<Q['queryTypeOpts']['joinedAssociations'], DB, QueryTypeOpts['rootTableName'], QueryTypeOpts['rootTableAlias']>, AggregatedColumnName extends ColumnNamesAccountingForJoinedAssociations<Q['queryTypeOpts']['joinedAssociations'], DB, QueryTypeOpts['rootTableName'], QueryTypeOpts['rootTableAlias']>, GroupKey extends NamespacedOrBaseModelColumnTypes<[GroupColumnName], Q, DreamInstance>[0], AggregatedType extends NamespacedOrBaseModelColumnTypes<[AggregatedColumnName], Q, DreamInstance>[0]>(groupColumn: GroupColumnName, aggregatedColumn: AggregatedColumnName): Promise<Map<GroupKey, AggregatedType>>;
     /**
      * Retrieves the min value of the specified column
      * for this Query
@@ -752,6 +818,30 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * @returns the min value of the specified column for this Query
      */
     min<Q extends Query<DreamInstance, QueryTypeOpts>, DB extends DreamInstance['DB'], ColumnName extends ColumnNamesAccountingForJoinedAssociations<Q['queryTypeOpts']['joinedAssociations'], DB, QueryTypeOpts['rootTableName'], QueryTypeOpts['rootTableAlias']>, ReturnType extends NamespacedOrBaseModelColumnTypes<[ColumnName], Q, DreamInstance>[0]>(columnName: ColumnName): Promise<ReturnType>;
+    /**
+     * 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
+     */
+    minBy<Q extends Query<DreamInstance, QueryTypeOpts>, DB extends DreamInstance['DB'], GroupColumnName extends ColumnNamesAccountingForJoinedAssociations<Q['queryTypeOpts']['joinedAssociations'], DB, QueryTypeOpts['rootTableName'], QueryTypeOpts['rootTableAlias']>, AggregatedColumnName extends ColumnNamesAccountingForJoinedAssociations<Q['queryTypeOpts']['joinedAssociations'], DB, QueryTypeOpts['rootTableName'], QueryTypeOpts['rootTableAlias']>, GroupKey extends NamespacedOrBaseModelColumnTypes<[GroupColumnName], Q, DreamInstance>[0], AggregatedType extends NamespacedOrBaseModelColumnTypes<[AggregatedColumnName], Q, DreamInstance>[0]>(groupColumn: GroupColumnName, aggregatedColumn: AggregatedColumnName): Promise<Map<GroupKey, AggregatedType>>;
     /**
      * Retrieves the sum value of the specified column
      * for this Query
@@ -765,6 +855,30 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * @returns the sum of the values of the specified column for this Query
      */
     sum<Q extends Query<DreamInstance, QueryTypeOpts>, DB extends DreamInstance['DB'], ColumnName extends ColumnNamesAccountingForJoinedAssociations<Q['queryTypeOpts']['joinedAssociations'], DB, QueryTypeOpts['rootTableName'], QueryTypeOpts['rootTableAlias']>, ReturnType extends NamespacedOrBaseModelColumnTypes<[ColumnName], Q, DreamInstance>[0]>(columnName: ColumnName): Promise<ReturnType>;
+    /**
+     * 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
+     */
+    sumBy<Q extends Query<DreamInstance, QueryTypeOpts>, DB extends DreamInstance['DB'], GroupColumnName extends ColumnNamesAccountingForJoinedAssociations<Q['queryTypeOpts']['joinedAssociations'], DB, QueryTypeOpts['rootTableName'], QueryTypeOpts['rootTableAlias']>, AggregatedColumnName extends ColumnNamesAccountingForJoinedAssociations<Q['queryTypeOpts']['joinedAssociations'], DB, QueryTypeOpts['rootTableName'], QueryTypeOpts['rootTableAlias']>, GroupKey extends NamespacedOrBaseModelColumnTypes<[GroupColumnName], Q, DreamInstance>[0], AggregatedType extends NamespacedOrBaseModelColumnTypes<[AggregatedColumnName], Q, DreamInstance>[0]>(groupColumn: GroupColumnName, aggregatedColumn: AggregatedColumnName): Promise<Map<GroupKey, AggregatedType>>;
     /**
      * Retrieves the average value of the specified column
      * for this Query
@@ -778,6 +892,30 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * @returns the average of the values of the specified column for this Query
      */
     avg<Q extends Query<DreamInstance, QueryTypeOpts>, DB extends DreamInstance['DB'], ColumnName extends ColumnNamesAccountingForJoinedAssociations<Q['queryTypeOpts']['joinedAssociations'], DB, QueryTypeOpts['rootTableName'], QueryTypeOpts['rootTableAlias']>, ReturnType extends NamespacedOrBaseModelColumnTypes<[ColumnName], Q, DreamInstance>[0]>(columnName: ColumnName): Promise<ReturnType>;
+    /**
+     * 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
+     */
+    avgBy<Q extends Query<DreamInstance, QueryTypeOpts>, DB extends DreamInstance['DB'], GroupColumnName extends ColumnNamesAccountingForJoinedAssociations<Q['queryTypeOpts']['joinedAssociations'], DB, QueryTypeOpts['rootTableName'], QueryTypeOpts['rootTableAlias']>, AggregatedColumnName extends ColumnNamesAccountingForJoinedAssociations<Q['queryTypeOpts']['joinedAssociations'], DB, QueryTypeOpts['rootTableName'], QueryTypeOpts['rootTableAlias']>, GroupKey extends NamespacedOrBaseModelColumnTypes<[GroupColumnName], Q, DreamInstance>[0], AggregatedType extends NamespacedOrBaseModelColumnTypes<[AggregatedColumnName], Q, DreamInstance>[0]>(groupColumn: GroupColumnName, aggregatedColumn: AggregatedColumnName): Promise<Map<GroupKey, AggregatedType>>;
     /**
      * Plucks the provided fields from the given dream class table
      *

package/dist/types/src/dream/QueryDriver/Base.d.ts

@@ -205,6 +205,20 @@ export default class QueryDriverBase<DreamInstance extends Dream> {
      *
      */
     max(columnName: string): Promise<any>;
+    /**
+     * 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
+     */
+    maxBy(groupColumn: string, aggregatedColumn: string): Promise<Map<any, any>>;
     /**
      * Retrieves the min value of the specified column
      * for this Query
@@ -218,6 +232,20 @@ export default class QueryDriverBase<DreamInstance extends Dream> {
      * @returns the min value of the specified column for this Query
      */
     min(columnName: string): Promise<any>;
+    /**
+     * 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
+     */
+    minBy(groupColumn: string, aggregatedColumn: string): Promise<Map<any, any>>;
     /**
      * Retrieves the sum value of the specified column
      * for this Query
@@ -231,6 +259,20 @@ export default class QueryDriverBase<DreamInstance extends Dream> {
      * @returns the sum of the values of the specified column for this Query
      */
     sum(columnName: string): Promise<any>;
+    /**
+     * 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
+     */
+    sumBy(groupColumn: string, aggregatedColumn: string): Promise<Map<any, any>>;
     /**
      * Retrieves the average value of the specified column
      * for this Query
@@ -244,6 +286,20 @@ export default class QueryDriverBase<DreamInstance extends Dream> {
      * @returns the average of the values of the specified column for this Query
      */
     avg(columnName: string): Promise<any>;
+    /**
+     * 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
+     */
+    avgBy(groupColumn: string, aggregatedColumn: string): Promise<Map<any, any>>;
     /**
      * Retrieves the number of records in the database
      *
@@ -254,6 +310,19 @@ export default class QueryDriverBase<DreamInstance extends Dream> {
      * @returns The number of records in the database
      */
     count(): Promise<number>;
+    /**
+     * 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
+     */
+    countBy(groupColumn: string): Promise<Map<any, number>>;
     /**
      * @internal
      *