@rvoh/dream 2.18.1 → 2.20.0

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

@@ -0,0 +1,198 @@
+import scopeArray from '../../decorators/field/sortable/helpers/scopeArray.js';
+import CannotIgnoreAssociationColumn from '../../errors/schema-builder/CannotIgnoreAssociationColumn.js';
+import CannotIgnoreEncryptedColumn from '../../errors/schema-builder/CannotIgnoreEncryptedColumn.js';
+import CannotIgnorePrimaryKey from '../../errors/schema-builder/CannotIgnorePrimaryKey.js';
+import CannotIgnoreSoftDeleteColumn from '../../errors/schema-builder/CannotIgnoreSoftDeleteColumn.js';
+import CannotIgnoreSortablePositionColumn from '../../errors/schema-builder/CannotIgnoreSortablePositionColumn.js';
+import CannotIgnoreSortableScopeColumn from '../../errors/schema-builder/CannotIgnoreSortableScopeColumn.js';
+import CannotIgnoreStiTypeColumn from '../../errors/schema-builder/CannotIgnoreStiTypeColumn.js';
+import ConflictingIgnoredColumns from '../../errors/schema-builder/ConflictingIgnoredColumns.js';
+import IgnoredColumnMustBeCamelCase from '../../errors/schema-builder/IgnoredColumnMustBeCamelCase.js';
+import camelize from '../camelize.js';
+import uniq from '../uniq.js';
+/**
+ * @internal
+ *
+ * Resolves the set of ignored columns for a table from the `ignoredColumns`
+ * declarations of every model backed by that table, validating the
+ * declarations along the way. Called while `sync` builds the generated types
+ * files (the declarations have no runtime behavior; see the `ignoredColumns`
+ * getter on Dream), so each of these guards fails the sync command loudly
+ * rather than surfacing as broken behavior at runtime:
+ *
+ * - ignored columns must be declared in camelCase, since generated column
+ *   names are camelized, so any other shape can never match a generated
+ *   column and would be silently inert
+ * - a model may never ignore its primary key
+ * - an STI model may never ignore the STI "type" column
+ * - a model may never ignore an @Sortable position field or a plain-column
+ *   @Sortable scope, the backing column of an @Encrypted property, or (on a
+ *   SoftDelete model) its deletedAtField — the framework reads and writes
+ *   those columns by name
+ * - models sharing a table must agree on their ignored columns, since there
+ *   is only one generated schema per table (STI children inherit the base
+ *   model's getter, so agreement is automatic unless a child overrides it)
+ * - no association anywhere in the app may name an ignored column as the
+ *   foreign key (or polymorphic type field) it reads and writes on this
+ *   table — a BelongsTo on a model backed by this table names a foreign key
+ *   on this table, and so does a HasMany/HasOne on any other model that
+ *   points at a model backed by this table
+ * - no association anywhere in the app may name an ignored column as its
+ *   primaryKeyOverride — the column the association's foreign key points
+ *   at, which lives on the associated model's table for a BelongsTo and on
+ *   the declaring model's own table for a HasMany/HasOne
+ *
+ * @param models - every model backed by the table
+ * @param tableName - the table whose ignored columns are being resolved
+ * @param allModels - every model in the app (on the table's connection);
+ *   required because associations declared on other models can name foreign
+ *   keys on this table
+ * @returns the set of column names to omit from the table's generated types
+ */
+export default function resolveIgnoredColumns(models, tableName, allModels) {
+    models.forEach(modelClass => {
+        const ignoredColumns = modelClass.prototype.ignoredColumns;
+        ignoredColumns.forEach(columnName => {
+            if (camelize(columnName) !== columnName)
+                throw new IgnoredColumnMustBeCamelCase(modelClass, columnName);
+        });
+        if (ignoredColumns.includes(modelClass.primaryKey))
+            throw new CannotIgnorePrimaryKey(modelClass);
+        if (ignoredColumns.includes('type') && (modelClass['isSTIBase'] || modelClass['isSTIChild']))
+            throw new CannotIgnoreStiTypeColumn(modelClass);
+        modelClass['sortableFields'].forEach(sortableFieldConfig => {
+            if (ignoredColumns.includes(sortableFieldConfig.positionField))
+                throw new CannotIgnoreSortablePositionColumn(modelClass, sortableFieldConfig.positionField);
+            // a Sortable scope entry names either a column or a BelongsTo
+            // association on the model (getColumnForSortableScope resolves columns
+            // first, then falls back to association metadata), so an ignored scope
+            // entry only breaks @Sortable when no association answers to the name
+            scopeArray(sortableFieldConfig.scope).forEach(scopeEntry => {
+                if (ignoredColumns.includes(scopeEntry) &&
+                    modelClass['associationMetadataMap']()[scopeEntry] === undefined)
+                    throw new CannotIgnoreSortableScopeColumn(modelClass, scopeEntry, sortableFieldConfig.positionField);
+            });
+        });
+        // the Encrypted decorator records each backing column it manages in
+        // explicitUnsafeParamColumns (which nothing else populates)
+        modelClass['explicitUnsafeParamColumns'].forEach(columnName => {
+            if (ignoredColumns.includes(columnName))
+                throw new CannotIgnoreEncryptedColumn(modelClass, columnName);
+        });
+        if (modelClass['softDelete']) {
+            const deletedAtField = modelClass.prototype['_deletedAtField'];
+            if (ignoredColumns.includes(deletedAtField))
+                throw new CannotIgnoreSoftDeleteColumn(modelClass, deletedAtField);
+        }
+    });
+    const distinctDeclarations = uniq(models.map(modelClass => JSON.stringify(uniq([...modelClass.prototype.ignoredColumns]).sort())));
+    if (distinctDeclarations.length > 1)
+        throw new ConflictingIgnoredColumns(tableName, models);
+    const ignoredColumns = new Set(models.flatMap(modelClass => [...modelClass.prototype.ignoredColumns]));
+    if (ignoredColumns.size)
+        guardAssociationColumns(ignoredColumns, tableName, allModels);
+    return ignoredColumns;
+}
+/**
+ * @internal
+ *
+ * fails the sync when an ignored column of the table is the foreign key (or
+ * polymorphic type field) that any association in the app reads and writes
+ * on this table, or the primaryKeyOverride column that any association's
+ * foreign key points at on this table. A BelongsTo association names a
+ * foreign key on the declaring model's own table and a primaryKeyOverride
+ * on the associated model's table; a HasMany/HasOne association names a
+ * foreign key on the associated model's table and a primaryKeyOverride on
+ * the declaring model's own table — so the load-bearing association may be
+ * declared on any model in the app, not just the models backed by this
+ * table.
+ */
+function guardAssociationColumns(ignoredColumns, tableName, allModels) {
+    for (const modelClass of allModels) {
+        for (const associationName of modelClass.associationNames) {
+            const associationMetaData = modelClass['associationMetadataMap']()[associationName];
+            if (associationMetaData === undefined)
+                continue;
+            // a through association names no foreign key of its own; the source
+            // association it travels through is guarded directly
+            if (associationMetaData.through)
+                continue;
+            // unlike foreignKey(), primaryKeyOverride is a plain string on the
+            // association statement, so it can be guarded without consulting the
+            // generated schema — before the foreignKey-specific short-circuits below
+            const primaryKeyOverride = associationMetaData.primaryKeyOverride;
+            if (primaryKeyOverride &&
+                ignoredColumns.has(primaryKeyOverride) &&
+                primaryKeyOverrideTableForAssociationMatches(associationMetaData, modelClass, tableName))
+                throw new CannotIgnoreAssociationColumn(tableName, primaryKeyOverride, modelClass, associationMetaData, 'primary key override');
+            if (!foreignKeyTableForAssociationMatches(associationMetaData, modelClass, tableName))
+                continue;
+            // NOTE
+            // this try-catch mirrors getAssociationData in ASTConnectionBuilder:
+            // computing foreignKey() introspects columns via the generated schema
+            // file, so it may throw — on the first sync pass because the schema
+            // file has not been regenerated yet, and on the second pass because
+            // the regenerated schema omits the ignored column. So in orderings
+            // where foreignKey() throws on the first pass, it throws on the second
+            // pass too, and these guards never see the association's foreign key;
+            // the InvalidComputedForeignKey / ExplicitForeignKeyRequired errors
+            // swallowed here resurface at runtime as the backstop.
+            let foreignKey = null;
+            let foreignKeyTypeColumn = null;
+            try {
+                foreignKey = associationMetaData.foreignKey();
+                foreignKeyTypeColumn = associationMetaData.polymorphic
+                    ? associationMetaData.foreignKeyTypeField()
+                    : null;
+            }
+            catch {
+                continue;
+            }
+            if (ignoredColumns.has(foreignKey))
+                throw new CannotIgnoreAssociationColumn(tableName, foreignKey, modelClass, associationMetaData, 'foreign key');
+            if (foreignKeyTypeColumn && ignoredColumns.has(foreignKeyTypeColumn))
+                throw new CannotIgnoreAssociationColumn(tableName, foreignKeyTypeColumn, modelClass, associationMetaData, 'polymorphic type field');
+        }
+    }
+}
+/**
+ * @internal
+ *
+ * returns whether the given association's foreign key physically lives on
+ * the given table: on the declaring model's own table for a BelongsTo, and
+ * on the associated model's table for a HasMany/HasOne
+ */
+function foreignKeyTableForAssociationMatches(associationMetaData, modelClass, tableName) {
+    if (associationMetaData.type === 'BelongsTo')
+        return modelClass.table === tableName;
+    const dreamClassOrClasses = associationMetaData.modelCB();
+    // a missing associated class raises FailedToIdentifyAssociation while the
+    // builder gathers association data; it is not this guard's concern
+    if (!dreamClassOrClasses)
+        return false;
+    return Array.isArray(dreamClassOrClasses)
+        ? dreamClassOrClasses.some(dreamClass => dreamClass.table === tableName)
+        : dreamClassOrClasses.table === tableName;
+}
+/**
+ * @internal
+ *
+ * returns whether the given association's primaryKeyOverride column
+ * physically lives on the given table — the opposite side from the foreign
+ * key (see associationPrimaryKeyAccessors in
+ * decorators/field/association/shared.ts): on the associated model's table
+ * for a BelongsTo, and on the declaring model's own table for a
+ * HasMany/HasOne
+ */
+function primaryKeyOverrideTableForAssociationMatches(associationMetaData, modelClass, tableName) {
+    if (associationMetaData.type !== 'BelongsTo')
+        return modelClass.table === tableName;
+    const dreamClassOrClasses = associationMetaData.modelCB();
+    // a missing associated class raises FailedToIdentifyAssociation while the
+    // builder gathers association data; it is not this guard's concern
+    if (!dreamClassOrClasses)
+        return false;
+    return Array.isArray(dreamClassOrClasses)
+        ? dreamClassOrClasses.some(dreamClass => dreamClass.table === tableName)
+        : dreamClassOrClasses.table === tableName;
+}

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.
@@ -1027,6 +1120,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()
@@ -1856,6 +1955,81 @@ export default class Dream {
      * @returns The table name for this model
      */
     get table(): AssociationTableNames<any, any>;
+    /**
+     * 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(): readonly string[];
     /**
      * @internal
      *
@@ -2651,9 +2825,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 +2844,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;