@rvoh/dream 2.18.1 → 2.20.0

package/dist/cjs/src/Dream.js

@@ -976,6 +976,25 @@ export default class Dream {
     static async count() {
         return await this.query().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.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
+     */
+    static async countBy(groupColumn) {
+        return await this.query().countBy(groupColumn);
+    }
     /**
      * Retrieves the max value of the specified column
      * for this model's records.
@@ -991,6 +1010,27 @@ export default class Dream {
     static async max(columnName) {
         return await this.query().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.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
+     */
+    static async maxBy(groupColumn, aggregatedColumn) {
+        return await this.query().maxBy(groupColumn, aggregatedColumn);
+    }
     /**
      * Retrieves the min value of the specified column
      * for this model's records.
@@ -1007,6 +1047,27 @@ export default class Dream {
     static async min(columnName) {
         return await this.query().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.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
+     */
+    static async minBy(groupColumn, aggregatedColumn) {
+        return await this.query().minBy(groupColumn, aggregatedColumn);
+    }
     /**
      * Retrieves the sum for all values of the specified column
      * for this model's records.
@@ -1023,6 +1084,27 @@ export default class Dream {
     static async sum(columnName) {
         return await this.query().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.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
+     */
+    static async sumBy(groupColumn, aggregatedColumn) {
+        return await this.query().sumBy(groupColumn, aggregatedColumn);
+    }
     /**
      * Retrieves the average for all values of the specified column
      * for this model's records.
@@ -1039,6 +1121,27 @@ export default class Dream {
     static async avg(columnName) {
         return await this.query().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.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
+     */
+    static async avgBy(groupColumn, aggregatedColumn) {
+        return await this.query().avgBy(groupColumn, aggregatedColumn);
+    }
     /**
      * Persists a new record, setting the provided attributes.
      * Automatically sets createdAt and updatedAt timestamps.
@@ -1358,6 +1461,12 @@ export default class Dream {
      * 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. leftJoinPreload must enumerate every compiled column of every joined
+     * model, so unlike base-model reads, `preload`/`load`, and saves, it does
+     * not tolerate schema/image skew from an unplanned column drop during a
+     * rolling deploy; see {@link Query.leftJoinPreload} and the
+     * `ignoredColumns` getter for the two-deploy process that makes a
+     * planned drop safe.
      *
      * ```ts
      * const user = await User.leftJoinPreload('posts', 'comments', { visibilty: 'public' }, 'replies').first()
@@ -2237,6 +2346,83 @@ export default class Dream {
     get table() {
         throw new DreamMissingRequiredOverride(this.constructor, 'table');
     }
+    /**
+     * Columns that Dream should behave as though they do not exist.
+     *
+     * Declaring a column ignored removes it from the generated types the next
+     * time `sync` runs: it is omitted from both the db types file (the Kysely
+     * `DB` interface) and the dream schema file, so it disappears from
+     * `columns()` and from every place that flows from `columns()` — select
+     * lists built for `preload`/`load` and `leftJoinPreload`, save hydration,
+     * attribute definition, and param safety. References to the column in
+     * application code become type errors, which is the point: they must be
+     * removed before the column can be dropped.
+     *
+     * This enables safely dropping a column under rolling deploys — the same
+     * problem Rails solves with `ignored_columns`. The safety requirement is
+     * that no image that can run against the post-drop schema names the
+     * column in any SQL it generates. To satisfy it: remove all application
+     * code that uses the column, declare it here, and run `sync`; then let
+     * the drop migration run only once no image lacking the declaration can
+     * run against the database — whether the migration ships in a later
+     * deploy of its own, or together with the declaration in a pipeline that
+     * runs migrations only after the new images have rolled out. Once the
+     * column is dropped, remove this declaration and resync.
+     *
+     * Precondition: as soon as an image built with this declaration runs,
+     * the column is never placed in INSERT column lists, so before that
+     * image can run, the column must be nullable or carry a database
+     * default — a live `NOT NULL` column without a default fails every
+     * create against the table.
+     *
+     * Dropping the column while an image that names it can still run leaves
+     * a window during which those containers (including a rolled-back image)
+     * fail with `42703 column does not exist` — `leftJoinPreload` in
+     * particular has no runtime tolerance for this, since it must enumerate
+     * aliased columns.
+     *
+     * This is a mechanism for the drop window, not for permanently hiding
+     * wide columns: the ignored column is still transferred from the
+     * database on every `RETURNING *` / `select *` until it is actually
+     * dropped.
+     *
+     * The declaration is read only while `sync` generates the types files; it
+     * has no runtime behavior of its own. A declared-but-not-synced model is
+     * therefore not yet protected — CI should verify that `sync` produces no
+     * diff. `sync` will fail loudly if a declared name is not camelCase
+     * (generated column names are camelized, so any other shape could never
+     * match and would be silently inert), if models sharing a table declare
+     * different ignored columns, or if a model attempts to ignore a column
+     * the framework itself reads and writes by name: its primary key, an STI
+     * model's `type` column, any association's foreign key, polymorphic type
+     * field, or `primaryKeyOverride` column, an `@Sortable` position field or
+     * plain-column `@Sortable` scope, an `@Encrypted` backing column, or a
+     * SoftDelete model's `deletedAt` column.
+     *
+     * Because an ignored column vanishes from `columns()`, runtime access via
+     * type escape hatches behaves exactly like any unknown attribute: reads
+     * return `undefined`, and writes assign a plain instance property that is
+     * never persisted.
+     *
+     * ```ts
+     * class User extends ApplicationModel {
+     *   public override get ignoredColumns() {
+     *     return ['legacyEmail'] as const
+     *   }
+     * }
+     * ```
+     *
+     * NOTE: this getter is intentionally typed as `readonly string[]` rather
+     * than as a union of known column names: during the deploy that declares
+     * a column ignored, the regenerated types no longer contain the column,
+     * so a column-name-derived type would reject the very declaration that
+     * removed it.
+     *
+     * @returns The list of column names this model should ignore
+     */
+    get ignoredColumns() {
+        return [];
+    }
     /**
      * @internal
      *

package/dist/cjs/src/db/DreamDbConnection.js

@@ -103,6 +103,12 @@ async function destroyConnectionWithinTimeout(conn, label) {
             reportLeakedDbConnections(label);
         }
     }
+    catch (error) {
+        // teardown is best-effort (the registry entry has already been removed,
+        // so a subsequent getConnection() builds a fresh pool), but a rejected
+        // destroy() must not vanish silently
+        DreamApp.logWithLevel('error', `[dream] failed to close db connection "${label}"`, error);
+    }
     finally {
         if (timer)
             clearTimeout(timer);

package/dist/cjs/src/decorators/class/SoftDelete.js

@@ -35,6 +35,18 @@ export const SOFT_DELETE_SCOPE_NAME = 'dream:SoftDelete';
  *     return 'customDatetimeField' as const
  *   }
  * }
+ *
+ * Note on indexing: Dream deliberately does not index `deleted_at`.
+ * The default scope's `WHERE deleted_at IS NULL` matches nearly every
+ * row on a healthy table, so a plain b-tree on the column is rarely
+ * chosen by the planner while still costing index size and write
+ * amplification, and Dream itself never issues a query such an index
+ * could serve. If your app needs one, add it yourself based on your
+ * own access patterns — on Postgres, the two useful shapes are a
+ * composite partial index on your hot lookup columns with
+ * `WHERE deleted_at IS NULL` (fast scoped reads), or a partial index
+ * `WHERE deleted_at IS NOT NULL` (purge/GC sweeps over soft-deleted
+ * rows). Both are Postgres-specific syntax.
  */
 export default function SoftDelete() {
     return function (target) {

package/dist/cjs/src/dream/DreamClassTransactionBuilder.js

@@ -58,6 +58,27 @@ export default class DreamClassTransactionBuilder {
     async count() {
         return this.queryInstance().count();
     }
+    /**
+     * 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
+     */
+    async countBy(groupColumn) {
+        return this.queryInstance().countBy(groupColumn);
+    }
     /**
      * Returns a new Query instance, specifying a limit
      *
@@ -107,6 +128,29 @@ export default class DreamClassTransactionBuilder {
     async max(columnName) {
         return this.queryInstance().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 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
+     */
+    async maxBy(groupColumn, aggregatedColumn) {
+        return this.queryInstance().maxBy(groupColumn, aggregatedColumn);
+    }
     /**
      * Retrieves the min value of the specified column
      * for this model's records.
@@ -124,6 +168,29 @@ export default class DreamClassTransactionBuilder {
     async min(columnName) {
         return this.queryInstance().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 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
+     */
+    async minBy(groupColumn, aggregatedColumn) {
+        return this.queryInstance().minBy(groupColumn, aggregatedColumn);
+    }
     /**
      * Retrieves the sum value of the specified column
      * for this Query
@@ -139,6 +206,29 @@ export default class DreamClassTransactionBuilder {
     async sum(columnName) {
         return this.queryInstance().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 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
+     */
+    async sumBy(groupColumn, aggregatedColumn) {
+        return this.queryInstance().sumBy(groupColumn, aggregatedColumn);
+    }
     /**
      * Retrieves the average value of the specified column
      * for this Query
@@ -154,6 +244,29 @@ export default class DreamClassTransactionBuilder {
     async avg(columnName) {
         return this.queryInstance().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 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
+     */
+    async avgBy(groupColumn, aggregatedColumn) {
+        return this.queryInstance().avgBy(groupColumn, aggregatedColumn);
+    }
     /**
      * Persists a new record, setting the provided attributes.
      * Automatically sets createdAt and updatedAt timestamps.

package/dist/cjs/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
      *