@rvoh/dream 2.18.1 → 2.19.0

package/dist/esm/src/errors/CannotNamespaceAssociationFilterToAnotherTable.js

@@ -0,0 +1,27 @@
+export default class CannotNamespaceAssociationFilterToAnotherTable extends Error {
+    dreamClass;
+    key;
+    expectedAlias;
+    constructor(dreamClass, key, expectedAlias) {
+        super();
+        this.dreamClass = dreamClass;
+        this.key = key;
+        this.expectedAlias = expectedAlias;
+    }
+    get message() {
+        return `
+Cannot filter on an association via a where-clause key namespaced to another table.
+
+dream class: ${this.dreamClass.sanitizedName}
+where-clause key: ${this.key}
+table alias this where clause applies to: ${this.expectedAlias}
+
+A Dream instance (or array of Dream instances) as a where-clause value resolves
+an association on the model the where clause applies to, so the key may not be
+namespaced to a different table. To filter a joined table by one of its
+associations, pass the filter in the join's on-clause instead, e.g.:
+
+  .innerJoin('association', { and: { myBelongsToAssociation: instances } })
+`;
+    }
+}

package/dist/esm/src/helpers/cli/generateMigrationContent.js

@@ -8,8 +8,13 @@ import globalClassNameFromFullyQualifiedModelName from '../globalClassNameFromFu
 import snakeify from '../snakeify.js';
 import standardizeFullyQualifiedModelName from '../standardizeFullyQualifiedModelName.js';
 const STI_TYPE_COLUMN_NAME = 'type';
-const DELETED_AT_COLUMN_NAME = 'deleted_at';
-const COLUMNS_TO_INDEX = [STI_TYPE_COLUMN_NAME, DELETED_AT_COLUMN_NAME];
+// deleted_at is deliberately NOT in this list: the SoftDelete default scope's
+// `WHERE deleted_at IS NULL` is unselective on healthy tables, Dream internals
+// never issue a query a deleted_at index could serve, and the useful partial
+// index alternatives are dialect-specific SQL the generator must not emit by
+// default. See spec/unit/cli/generateMigrationContent.spec.ts
+// ("deleted_at is deliberately NOT indexed") and the CHANGELOG.
+const COLUMNS_TO_INDEX = [STI_TYPE_COLUMN_NAME];
 export default function generateMigrationContent({ connectionName = 'default', table, columnsWithTypes = [], primaryKeyType = 'bigserial', createOrAlter = 'create', stiChildClassName, softDelete = false, } = {}) {
     const altering = createOrAlter === 'alter';
     let requireCitextExtension = false;
@@ -43,13 +48,18 @@ export default function generateMigrationContent({ connectionName = 'default', t
             return acc;
         /**
          * Automatically set email columns to citext since different casings of
-         * email address are the same email address
+         * email address are the same email address. Skip this when the user
+         * explicitly asked for an encrypted column, since encrypted columns
+         * are always stored as encrypted text and must not be overridden by
+         * the name-based heuristic.
          */
-        const attributeType = /email$/.test(nonStandardAttributeName)
-            ? 'citext'
-            : /uuid$/.test(nonStandardAttributeName)
-                ? 'uuid'
-                : _attributeType;
+        const attributeType = _attributeType === 'encrypted' || _attributeType === 'encrypted[]'
+            ? _attributeType
+            : /email$/.test(nonStandardAttributeName)
+                ? 'citext'
+                : /uuid$/.test(nonStandardAttributeName)
+                    ? 'uuid'
+                    : _attributeType;
         const processedAttrType = camelize(attributeType)?.toLowerCase();
         const userWantsThisOptional = optionalFromDescriptors(descriptors);
         // when creating a migration for an STI child, we don't want to include notNull;
@@ -115,6 +125,7 @@ export default function generateMigrationContent({ connectionName = 'default', t
                 attributeName = `encrypted_${attributeName}`;
                 columnDefs.push(generateColumnStr(attributeName, 'text', descriptors, {
                     omitInlineNonNull,
+                    skipUniqueHeuristic: true,
                 }));
                 break;
             // TODO: determine if we need to support encrypted[] in the future
@@ -145,9 +156,6 @@ export default function generateMigrationContent({ connectionName = 'default', t
         }
         return acc;
     }, { columnDefs: [], columnDrops: [], indexDefs: [] });
-    if (emitDeletedAtColumn) {
-        indexDefs.push(columnIndexStatement(table, DELETED_AT_COLUMN_NAME));
-    }
     if (!table) {
         return `\
 import { Kysely, sql } from 'kysely'
@@ -274,12 +282,12 @@ function generateDecimalStr(attributeName, { descriptors, omitInlineNonNull: opt
         : `'decimal(${scale}, ${precision})'`;
     return `.addColumn('${attributeName}', ${decimalStatement}${optional ? '' : `, col => ${columnModifiers}`})`;
 }
-function generateColumnStr(attributeName, attributeType, descriptors, { omitInlineNonNull: optional }) {
+function generateColumnStr(attributeName, attributeType, descriptors, { omitInlineNonNull: optional, skipUniqueHeuristic = false, }) {
     let returnStr = `.addColumn('${attributeName}', ${attributeTypeString(attributeType)}`;
     const providedDefaultArg = descriptors.find(d => /^default\(/.test(d));
     const providedDefault = providedDefaultArg?.replace(/^default\(/, '')?.replace(/\)$/, '');
     const notNull = !optional;
-    const isUnique = /(email|token|uuid)$/.test(attributeName);
+    const isUnique = !skipUniqueHeuristic && /(email|token|uuid)$/.test(attributeName);
     const hasExtraValues = providedDefault || notNull || isUnique;
     const isArray = /\[\]$/.test(attributeType);
     const needsJsonDefault = notNull && !isArray && (attributeType === 'jsonb' || attributeType === 'json');

package/dist/types/src/Dream.d.ts

@@ -716,6 +716,23 @@ export default class Dream {
      * @returns The number of records corresponding to this model
      */
     static count<T extends typeof Dream>(this: T): 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.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 countBy<T extends typeof Dream, GroupColumnName extends DreamColumnNames<InstanceType<T>>>(this: T, groupColumn: GroupColumnName): Promise<Map<InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]][GroupColumnName & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]]]["coercedType" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]][GroupColumnName & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]]]], number>>;
     /**
      * Retrieves the max value of the specified column
      * for this model's records.
@@ -729,6 +746,25 @@ export default class Dream {
      * @returns the max value of the specified column for this model's records
      */
     static max<T extends typeof Dream, ColumnName extends DreamColumnNames<InstanceType<T>>>(this: T, columnName: ColumnName): Promise<InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]][ColumnName & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]]]["coercedType" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]][ColumnName & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["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 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 maxBy<T extends typeof Dream, GroupColumnName extends DreamColumnNames<InstanceType<T>>, AggregatedColumnName extends DreamColumnNames<InstanceType<T>>>(this: T, groupColumn: GroupColumnName, aggregatedColumn: AggregatedColumnName): Promise<Map<InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]][GroupColumnName & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]]]["coercedType" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]][GroupColumnName & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]]]], InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]][AggregatedColumnName & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]]]["coercedType" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]][AggregatedColumnName & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]]]]>>;
     /**
      * Retrieves the min value of the specified column
      * for this model's records.
@@ -743,6 +779,25 @@ export default class Dream {
      * @returns the min value of the specified column for this model's records
      */
     static min<T extends typeof Dream, ColumnName extends DreamColumnNames<InstanceType<T>>>(this: T, columnName: ColumnName): Promise<InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]][ColumnName & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]]]["coercedType" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]][ColumnName & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["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 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 minBy<T extends typeof Dream, GroupColumnName extends DreamColumnNames<InstanceType<T>>, AggregatedColumnName extends DreamColumnNames<InstanceType<T>>>(this: T, groupColumn: GroupColumnName, aggregatedColumn: AggregatedColumnName): Promise<Map<InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]][GroupColumnName & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]]]["coercedType" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]][GroupColumnName & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]]]], InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]][AggregatedColumnName & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]]]["coercedType" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]][AggregatedColumnName & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]]]]>>;
     /**
      * Retrieves the sum for all values of the specified column
      * for this model's records.
@@ -757,6 +812,25 @@ export default class Dream {
      * @returns the sum for all values of the specified column for this model's records
      */
     static sum<T extends typeof Dream, ColumnName extends DreamColumnNames<InstanceType<T>>>(this: T, columnName: ColumnName): Promise<InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]][ColumnName & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]]]["coercedType" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]][ColumnName & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["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 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 sumBy<T extends typeof Dream, GroupColumnName extends DreamColumnNames<InstanceType<T>>, AggregatedColumnName extends DreamColumnNames<InstanceType<T>>>(this: T, groupColumn: GroupColumnName, aggregatedColumn: AggregatedColumnName): Promise<Map<InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]][GroupColumnName & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]]]["coercedType" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]][GroupColumnName & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]]]], InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]][AggregatedColumnName & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]]]["coercedType" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]][AggregatedColumnName & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]]]]>>;
     /**
      * Retrieves the average for all values of the specified column
      * for this model's records.
@@ -771,6 +845,25 @@ export default class Dream {
      * @returns the average for all values of the specified column for this model's records
      */
     static avg<T extends typeof Dream, ColumnName extends DreamColumnNames<InstanceType<T>>>(this: T, columnName: ColumnName): Promise<InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]][ColumnName & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]]]["coercedType" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]][ColumnName & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["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 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 avgBy<T extends typeof Dream, GroupColumnName extends DreamColumnNames<InstanceType<T>>, AggregatedColumnName extends DreamColumnNames<InstanceType<T>>>(this: T, groupColumn: GroupColumnName, aggregatedColumn: AggregatedColumnName): Promise<Map<InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]][GroupColumnName & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]]]["coercedType" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]][GroupColumnName & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]]]], InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]][AggregatedColumnName & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]]]["coercedType" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]][AggregatedColumnName & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]["columns" & keyof InstanceType<T>["schema"][InstanceType<T>["table"] & keyof InstanceType<T>["schema"]]]]]>>;
     /**
      * Persists a new record, setting the provided attributes.
      * Automatically sets createdAt and updatedAt timestamps.
@@ -2651,9 +2744,9 @@ export default class Dream {
         [x: string]: any;
     } | Partial<{
         [x: string]: any;
-    }> | Partial<{
+    }> | {
         [x: string]: any;
-    }>>>;
+    }>>;
     /**
      * Takes the attributes passed in and sets their values internally,
      * bypassing any custom setters defined for these attributes.
@@ -2670,9 +2763,9 @@ export default class Dream {
         [x: string]: any;
     } | Partial<{
         [x: string]: any;
-    }> | Partial<{
+    }> | {
         [x: string]: any;
-    }>>>;
+    }>>;
     private _setAttributes;
     /**
      * Saves the state of the current instance to the

package/dist/types/src/decorators/class/SoftDelete.d.ts

@@ -34,5 +34,17 @@ export declare 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(): (target: typeof Dream) => void;

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

@@ -697,6 +697,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 +770,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 +807,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 +844,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 +881,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
      *