@rvoh/dream 2.28.3 → 2.30.1

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

@@ -21,6 +21,7 @@ import DreamApp from '../../dream-app/index.js';
 import Dream from '../../Dream.js';
 import ArrayTargetIncompatibleWithThroughAssociation from '../../errors/associations/ArrayTargetIncompatibleWithThroughAssociation.js';
 import CannotJoinPolymorphicBelongsToError from '../../errors/associations/CannotJoinPolymorphicBelongsToError.js';
+import IncompatibleThroughAssociationTarget from '../../errors/associations/IncompatibleThroughAssociationTarget.js';
 import JoinAttemptedOnMissingAssociation from '../../errors/associations/JoinAttemptedOnMissingAssociation.js';
 import MissingRequiredAssociationAndClause from '../../errors/associations/MissingRequiredAssociationAndClause.js';
 import MissingRequiredPassthroughForAssociationAndClause from '../../errors/associations/MissingRequiredPassthroughForAssociationAndClause.js';
@@ -1547,7 +1548,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                 joinAndStatement,
                 joinType,
                 previousThroughAssociations: [],
-                dreamClassThroughAssociationWantsToHydrate: undefined,
+                polymorphicSourceTargetModelClass: undefined,
             });
             query = results.query;
             /**
@@ -1976,7 +1977,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                 joinAndStatement: {},
                 previousThroughAssociations: [],
                 joinType,
-                dreamClassThroughAssociationWantsToHydrate: undefined,
+                polymorphicSourceTargetModelClass: undefined,
             });
         }
         const associatedDreamClass = associationReferencedByThroughAssociation.modelCB();
@@ -1992,12 +1993,24 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                 association: throughAssociation,
                 throughClass: associatedDreamClass,
             });
+        const outermostThroughAssociation = previousThroughAssociations[0]?.association ?? throughAssociation;
+        const outermostTargetModelClass = outermostThroughAssociation.modelCB();
+        const sourceTargetModelClassOrClasses = sourceAssociation.modelCB();
+        const sourceTargetModelClasses = Array.isArray(sourceTargetModelClassOrClasses)
+            ? sourceTargetModelClassOrClasses
+            : [sourceTargetModelClassOrClasses];
+        if (!sourceTargetModelClasses.some(sourceTargetModelClass => outermostTargetModelClass.typeof(sourceTargetModelClass)))
+            throw new IncompatibleThroughAssociationTarget({
+                outermostAssociation: outermostThroughAssociation,
+                outermostTargetModelClass,
+                sourceAssociation,
+            });
         /**
-         * When the source is a polymorphic BelongsTo association, use the target of the through
-         * association to determine which class to target.
+         * A polymorphic source can accept several model classes. The outermost
+         * association target selects the one this through chain is following.
          */
-        const dreamClassThroughAssociationWantsToHydrate = Array.isArray(sourceAssociation.modelCB())
-            ? throughAssociation.modelCB()
+        const polymorphicSourceTargetModelClass = Array.isArray(sourceTargetModelClassOrClasses)
+            ? outermostTargetModelClass
             : undefined;
         /**
          * Add the source that `sourceAssociation` points to. Note that since joinsBridgeThroughAssociations
@@ -2031,7 +2044,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                 { association: throughAssociation, selfTableAlias: previousTableAlias },
             ],
             joinType,
-            dreamClassThroughAssociationWantsToHydrate,
+            polymorphicSourceTargetModelClass,
         });
     }
     applyOneJoin({ query, dreamClass, association, 
@@ -2054,7 +2067,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
     /**
      * previousTableAlias is always set
      */
-    previousTableAlias, selfTableAlias = previousTableAlias, joinAndStatement = {}, previousThroughAssociations, joinType, dreamClassThroughAssociationWantsToHydrate, }) {
+    previousTableAlias, selfTableAlias = previousTableAlias, joinAndStatement = {}, previousThroughAssociations, joinType, polymorphicSourceTargetModelClass, }) {
         if (association.type !== 'BelongsTo' && association.through) {
             return this.joinsBridgeThroughAssociations({
                 query,
@@ -2077,7 +2090,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             joinAndStatement,
             previousThroughAssociations,
             joinType,
-            dreamClassThroughAssociationWantsToHydrate,
+            polymorphicSourceTargetModelClass,
         });
     }
     addAssociationJoinStatementToQuery({ query, dreamClass, association, 
@@ -2100,12 +2113,38 @@ export default class KyselyQueryDriver extends QueryDriverBase {
     /**
      * previousTableAlias is always set
      */
-    previousTableAlias, selfTableAlias, joinAndStatement, previousThroughAssociations, joinType, dreamClassThroughAssociationWantsToHydrate, }) {
+    previousTableAlias, selfTableAlias, joinAndStatement, previousThroughAssociations, joinType, polymorphicSourceTargetModelClass, }) {
         const currentTableAlias = explicitAlias ?? association.as;
-        const _associatedDreamClass = association.modelCB();
-        const associatedDreamClass = Array.isArray(_associatedDreamClass)
-            ? _associatedDreamClass[0]
-            : _associatedDreamClass;
+        const associationModelClassOrPolymorphicModelClasses = association.modelCB();
+        const modelClassUsedForJoinConditions = Array.isArray(associationModelClassOrPolymorphicModelClasses)
+            ? associationModelClassOrPolymorphicModelClasses[0]
+            : associationModelClassOrPolymorphicModelClasses;
+        /**
+         * The outermost through association defines what callers expect this join to
+         * return, so its target is the single owner of the target table's default
+         * scopes. Inner associations describe how to reach that table; the
+         * compatibility check in `joinsBridgeThroughAssociations` ensures they can
+         * actually return the outer target.
+         *
+         * For example, BearBnB already defines `Host.places` and `Place.rooms`. It
+         * could expose only bedrooms from a host without adding `Place.bedrooms`:
+         *
+         *   // Place.ts
+         *   @deco.HasMany('Room')
+         *   public rooms: Room[]
+         *
+         *   // Host.ts
+         *   @deco.HasMany('Room/Bedroom', { through: 'places', source: 'rooms' })
+         *   public bedrooms: Bedroom[]
+         *
+         * `Host.bedrooms` is the outermost association, so Bedroom's `dream:STI`
+         * scope is applied once to the final rooms join. Bedroom is a subclass of
+         * Room, so `Place.rooms` is a compatible path. Reversing those targets, or
+         * mixing sibling STI children, raises instead of silently changing meaning.
+         */
+        const modelClassWhoseDefaultScopesApplyToJoin = previousThroughAssociations[0]?.association.modelCB() ??
+            polymorphicSourceTargetModelClass ??
+            modelClassUsedForJoinConditions;
         /**
          * Stacked order/distinct clauses are applied in join order: the options of
          * the through association whose bridging joins were added to the query
@@ -2131,22 +2170,22 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             }
         }
         if (association.type === 'BelongsTo') {
-            if (!dreamClassThroughAssociationWantsToHydrate && Array.isArray(association.modelCB()))
+            if (!polymorphicSourceTargetModelClass && Array.isArray(association.modelCB()))
                 throw new CannotJoinPolymorphicBelongsToError({
                     dreamClass,
                     association,
                     innerJoinStatements: this.query['innerJoinStatements'],
                     leftJoinStatements: this.query['leftJoinStatements'],
                 });
-            const to = (dreamClassThroughAssociationWantsToHydrate ?? association.modelCB()).table;
+            const to = (polymorphicSourceTargetModelClass ?? association.modelCB()).table;
             const joinTableExpression = this.aliasedJoinTableExpression(to, currentTableAlias);
             query = query[(joinType === 'inner' ? 'innerJoin' : 'leftJoin')](joinTableExpression, (join) => {
                 join = join.onRef(this.namespaceColumn(association.foreignKey(), previousTableAlias), '=', this.namespaceColumn(association.primaryKey(undefined, {
-                    associatedClassOverride: dreamClassThroughAssociationWantsToHydrate,
+                    associatedClassOverride: polymorphicSourceTargetModelClass,
                 }), currentTableAlias));
-                if (dreamClassThroughAssociationWantsToHydrate) {
+                if (polymorphicSourceTargetModelClass) {
                     join = join.on((eb) => this.whereStatementToExpressionWrapper(dreamClass, eb, this.aliasWhereStatement({
-                        [association.foreignKeyTypeField()]: dreamClassThroughAssociationWantsToHydrate.sanitizedName,
+                        [association.foreignKeyTypeField()]: polymorphicSourceTargetModelClass.sanitizedName,
                     }, previousTableAlias)));
                 }
                 join = this.applyPreviousThroughAssociationAndStatementsToJoinStatement({
@@ -2156,14 +2195,14 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                     currentTableAlias,
                     joinAndStatement,
                 });
-                join = this.conditionallyApplyDefaultScopesDependentOnAssociation({
+                join = this.applyAssociationDefaultScopesToJoin({
                     dreamClass,
                     join,
                     tableNameOrAlias: currentTableAlias,
                     association,
-                    throughAssociatedClassOverride: dreamClassThroughAssociationWantsToHydrate,
+                    modelClassWhoseDefaultScopesApply: modelClassWhoseDefaultScopesApplyToJoin,
                 });
-                join = this.applyJoinAndStatement(associatedDreamClass, join, joinAndStatement, currentTableAlias);
+                join = this.applyJoinAndStatement(modelClassUsedForJoinConditions, join, joinAndStatement, currentTableAlias);
                 return join;
             });
         }
@@ -2174,8 +2213,8 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                 join = join.onRef(this.namespaceColumn(association.primaryKey(), previousTableAlias), '=', this.namespaceColumn(association.foreignKey(), currentTableAlias));
                 if (association.polymorphic) {
                     join = join.on((eb) => this.whereStatementToExpressionWrapper(dreamClass, eb, this.aliasWhereStatement({
-                        [association.foreignKeyTypeField()]: dreamClassThroughAssociationWantsToHydrate
-                            ? dreamClassThroughAssociationWantsToHydrate.referenceTypeString
+                        [association.foreignKeyTypeField()]: polymorphicSourceTargetModelClass
+                            ? polymorphicSourceTargetModelClass.referenceTypeString
                             : dreamClass.referenceTypeString,
                     }, currentTableAlias)));
                 }
@@ -2194,14 +2233,14 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                     selfTableAlias,
                     joinAndStatement,
                 });
-                join = this.conditionallyApplyDefaultScopesDependentOnAssociation({
+                join = this.applyAssociationDefaultScopesToJoin({
                     dreamClass,
                     join,
                     tableNameOrAlias: currentTableAlias,
                     association,
-                    throughAssociatedClassOverride: dreamClassThroughAssociationWantsToHydrate,
+                    modelClassWhoseDefaultScopesApply: modelClassWhoseDefaultScopesApplyToJoin,
                 });
-                join = this.applyJoinAndStatement(associatedDreamClass, join, joinAndStatement, currentTableAlias);
+                join = this.applyJoinAndStatement(modelClassUsedForJoinConditions, join, joinAndStatement, currentTableAlias);
                 return join;
             });
             if (association.type === 'HasMany') {
@@ -2312,11 +2351,9 @@ export default class KyselyQueryDriver extends QueryDriverBase {
         if (missingRequiredWhereStatements.length)
             throw new MissingRequiredAssociationAndClause(association, missingRequiredWhereStatements[0]);
     }
-    conditionallyApplyDefaultScopesDependentOnAssociation({ dreamClass, join, tableNameOrAlias, association, throughAssociatedClassOverride, }) {
+    applyAssociationDefaultScopesToJoin({ dreamClass, join, tableNameOrAlias, association, modelClassWhoseDefaultScopesApply, }) {
         let scopesQuery = new Query(this.dreamInstance);
-        const associationClass = throughAssociatedClassOverride ?? association.modelCB();
-        const associationScopes = associationClass['scopes'].default;
-        for (const scope of associationScopes) {
+        for (const scope of modelClassWhoseDefaultScopesApply['scopes'].default) {
             if (!shouldBypassDefaultScope(scope.method, {
                 bypassAllDefaultScopes: this.query['bypassAllDefaultScopes'],
                 defaultScopesToBypass: [
@@ -2324,7 +2361,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                     ...(association.withoutDefaultScopes || []),
                 ],
             })) {
-                const tempQuery = associationClass[scope.method](scopesQuery);
+                const tempQuery = modelClassWhoseDefaultScopesApply[scope.method](scopesQuery);
                 // The scope method on a Dream model should return a clone of the Query it receives
                 // (e.g. by returning `scope.where(...)`), but in case the function doesn't return,
                 // or returns the wrong thing, we check before overriding `scopesQuery` with what the

package/dist/esm/src/dream/internal/applyScopeBypassingSettingsToQuery.js

@@ -1,6 +1,6 @@
 export default function applyScopeBypassingSettingsToQuery(query, { bypassAllDefaultScopes, defaultScopesToBypass, }) {
     if (bypassAllDefaultScopes)
-        query = query.removeAllDefaultScopes();
+        query = query['removeAllDefaultScopes']();
     defaultScopesToBypass.forEach(defaultScopeToBypass => {
         query = query.removeDefaultScope(defaultScopeToBypass);
     });

package/dist/esm/src/dream/internal/associations/loadedOrLoadAssociation.js

@@ -5,6 +5,8 @@ export default async function loadedOrLoadAssociation(dream, dreamOrTransactionB
         let scope = dreamOrTransactionBuilder.associationQuery(associationName, associationQueryOptions);
         if (options?.passthrough)
             scope = scope.passthrough(options.passthrough);
+        if (options?.connection)
+            scope = scope.connection(options.connection);
         if (association?.type === 'HasMany') {
             dream[associationName] = (await scope.all());
         }

package/dist/esm/src/dream/internal/installPersistedAttribute.js

@@ -0,0 +1,9 @@
+/**
+ * Installs one database-sourced scalar as the persisted value without
+ * replacing the saved-change history established by the current save.
+ */
+export default function installPersistedAttribute(dream, column, val) {
+    dream['currentAttributes'][column] = val;
+    dream['frozenAttributes'][column] = val;
+    dream['originalAttributes'][column] = val;
+}

package/dist/esm/src/dream/internal/instanceMutationOptions.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/src/dream/internal/loadDependentDestroyTree.js

@@ -21,7 +21,7 @@ export default async function loadDependentDestroyTree(dream, txn, { reallyDestr
         loadBuilder = loadBuilder.load(...args);
     }
     if (bypassAllDefaultScopes) {
-        loadBuilder = loadBuilder.removeAllDefaultScopes();
+        loadBuilder = loadBuilder['removeAllDefaultScopes']();
     }
     else {
         for (const scopeName of defaultScopesToBypass) {

package/dist/esm/src/dream/internal/reload.js

@@ -10,7 +10,9 @@ export default async function reload(dream, txn = null) {
     // we have persisted are not yet propagated
     else
         query = query.connection('primary');
-    query = query.removeAllDefaultScopes().where({ [dream['_primaryKey']]: dream.primaryKeyValue() });
+    query = query['removeAllDefaultScopes']().where({
+        [dream['_primaryKey']]: dream.primaryKeyValue(),
+    });
     const reloadedRecord = await query.firstOrFail();
     dream.setAttributes(reloadedRecord.getAttributes());
     dream['freezeAttributes']();

package/dist/esm/src/errors/associations/IncompatibleThroughAssociationTarget.js

@@ -0,0 +1,11 @@
+export default class IncompatibleThroughAssociationTarget extends Error {
+    constructor({ outermostAssociation, outermostTargetModelClass, sourceAssociation, }) {
+        super(`Through association \`${outermostAssociation.as}\` targets \`${outermostTargetModelClass.sanitizedName}\`, but source association \`${sourceAssociation.as}\` targets ${targetDescription(sourceAssociation)}. ` +
+            `The through association's target must be the same as or a subclass of a source target.`);
+    }
+}
+function targetDescription(association) {
+    const targetModelClassOrClasses = association.modelCB();
+    const targetNames = (Array.isArray(targetModelClassOrClasses) ? targetModelClassOrClasses : [targetModelClassOrClasses]).map(targetModelClass => `\`${targetModelClass.sanitizedName}\``);
+    return targetNames.join(', ');
+}

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

@@ -2,7 +2,7 @@ import { CompiledQuery, Selectable } from 'kysely';
 import DreamClassTransactionBuilder from './dream/DreamClassTransactionBuilder.js';
 import DreamInstanceTransactionBuilder from './dream/DreamInstanceTransactionBuilder.js';
 import DreamTransaction from './dream/DreamTransaction.js';
-import { DestroyOptions } from './dream/internal/destroyOptions.js';
+import type { InstanceDestroyOptions, InstanceUpdateOptions } from './dream/internal/instanceMutationOptions.js';
 import LeftJoinLoadBuilder from './dream/LeftJoinLoadBuilder.js';
 import LoadBuilder from './dream/LoadBuilder.js';
 import Query from './dream/Query.js';
@@ -594,6 +594,8 @@ export default class Dream {
      */
     static get associationNames(): string[];
     /**
+     * @deprecated Use {@link removeDefaultScope} instead. This method will become private in v3.
+     *
      * Returns a query which bypasses user-removable default scopes, including on
      * association loads. An STI child's reserved type discriminator remains
      * enforced; query the STI base model to span its registered children.
@@ -2476,7 +2478,7 @@ export default class Dream {
      * @param options.defaultScopesToBypass - An array of default scope names to bypass when cascade destroying. Defaults to an empty array
      * @returns The instance that was destroyed
      */
-    destroy<I extends Dream>(this: I, options?: DestroyOptions<I>): Promise<I>;
+    destroy<I extends Dream>(this: I, options?: InstanceDestroyOptions<I>): Promise<I>;
     /**
      * Deletes the record represented by this instance
      * from the database, calling any destroy
@@ -2499,7 +2501,7 @@ export default class Dream {
      * @param options.defaultScopesToBypass - An array of default scope names to bypass when cascade destroying. Defaults to an empty array
      * @returns The instance that was destroyed
      */
-    reallyDestroy<I extends Dream>(this: I, options?: DestroyOptions<I>): Promise<I>;
+    reallyDestroy<I extends Dream>(this: I, options?: InstanceDestroyOptions<I>): Promise<I>;
     /**
      * Undestroys a SoftDelete model, unsetting
      * the `deletedAt` field in the database.
@@ -2508,7 +2510,7 @@ export default class Dream {
      * this will raise an exception.
      *
      * ```ts
-     * const user = await User.removeAllDefaultScopes().last()
+     * const user = await User.removeDefaultScope('dream:SoftDelete').last()
      * await user.undestroy()
      * ```
      *
@@ -2519,7 +2521,7 @@ export default class Dream {
      * @param options.defaultScopesToBypass - An array of default scope names to bypass when cascade undestroying (soft delete is always bypassed). Defaults to an empty array
      * @returns The undestroyed record
      */
-    undestroy<I extends Dream>(this: I, options?: DestroyOptions<I>): Promise<I>;
+    undestroy<I extends Dream>(this: I, options?: InstanceDestroyOptions<I>): Promise<I>;
     /**
      * Returns true if the argument is the same Dream class
      * with the same primary key value.
@@ -2563,23 +2565,21 @@ export default class Dream {
      * @returns The created association
      */
     createAssociation<I extends Dream, AssociationName extends DreamAssociationNames<I>, PossibleArrayAssociationType extends I[AssociationName & keyof I], AssociationType extends PossibleArrayAssociationType extends (infer ElementType)[] ? ElementType : PossibleArrayAssociationType, RestrictedAssociationType extends AssociationType extends Dream ? AssociationType : never>(this: I, associationName: AssociationName, attributes?: UpdateableAssociationProperties<I, RestrictedAssociationType>): Promise<NonNullable<AssociationType>>;
-    destroyAssociation<I extends Dream, DB extends I['DB'], TableName extends I['table'], Schema extends I['schema'], AssociationName extends DreamAssociationNamesWithRequiredOnClauses<I>, RequiredOnClauseKeysForThisAssociation extends RequiredOnClauseKeys<Schema, TableName, AssociationName>, AssociationDream extends AssociationNameToDream<I, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, options: DestroyOptions<I> & JoinAndStatements<I, DB, Schema, AssociationTableName, RequiredOnClauseKeysForThisAssociation>): Promise<number>;
-    destroyAssociation<I extends Dream, DB extends I['DB'], Schema extends I['schema'], AssociationName extends DreamAssociationNamesWithoutRequiredOnClauses<I>, AssociationDream extends AssociationNameToDream<I, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, options?: DestroyOptions<I> & JoinAndStatements<I, DB, Schema, AssociationTableName, null>): Promise<number>;
-    reallyDestroyAssociation<I extends Dream, DB extends I['DB'], TableName extends I['table'], Schema extends I['schema'], AssociationName extends DreamAssociationNamesWithRequiredOnClauses<I>, RequiredOnClauseKeysForThisAssociation extends RequiredOnClauseKeys<Schema, TableName, AssociationName>, AssociationDream extends AssociationNameToDream<I, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, options: DestroyOptions<I> & JoinAndStatements<I, DB, Schema, AssociationTableName, RequiredOnClauseKeysForThisAssociation>): Promise<number>;
-    reallyDestroyAssociation<I extends Dream, DB extends I['DB'], Schema extends I['schema'], AssociationName extends DreamAssociationNamesWithoutRequiredOnClauses<I>, AssociationDream extends AssociationNameToDream<I, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, options?: DestroyOptions<I> & JoinAndStatements<I, DB, Schema, AssociationTableName, null>): Promise<number>;
-    undestroyAssociation<I extends Dream, DB extends I['DB'], TableName extends I['table'], Schema extends I['schema'], AssociationName extends DreamAssociationNamesWithRequiredOnClauses<I>, RequiredOnClauseKeysForThisAssociation extends RequiredOnClauseKeys<Schema, TableName, AssociationName>, AssociationDream extends AssociationNameToDream<I, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, options: DestroyOptions<I> & JoinAndStatements<I, DB, Schema, AssociationTableName, RequiredOnClauseKeysForThisAssociation>): Promise<number>;
-    undestroyAssociation<I extends Dream, DB extends I['DB'], Schema extends I['schema'], AssociationName extends DreamAssociationNamesWithoutRequiredOnClauses<I>, AssociationDream extends AssociationNameToDream<I, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, options?: DestroyOptions<I> & JoinAndStatements<I, DB, Schema, AssociationTableName, null>): Promise<number>;
+    destroyAssociation<I extends Dream, DB extends I['DB'], TableName extends I['table'], Schema extends I['schema'], AssociationName extends DreamAssociationNamesWithRequiredOnClauses<I>, RequiredOnClauseKeysForThisAssociation extends RequiredOnClauseKeys<Schema, TableName, AssociationName>, AssociationDream extends AssociationNameToDream<I, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, options: InstanceDestroyOptions<I> & JoinAndStatements<I, DB, Schema, AssociationTableName, RequiredOnClauseKeysForThisAssociation>): Promise<number>;
+    destroyAssociation<I extends Dream, DB extends I['DB'], Schema extends I['schema'], AssociationName extends DreamAssociationNamesWithoutRequiredOnClauses<I>, AssociationDream extends AssociationNameToDream<I, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, options?: InstanceDestroyOptions<I> & JoinAndStatements<I, DB, Schema, AssociationTableName, null>): Promise<number>;
+    reallyDestroyAssociation<I extends Dream, DB extends I['DB'], TableName extends I['table'], Schema extends I['schema'], AssociationName extends DreamAssociationNamesWithRequiredOnClauses<I>, RequiredOnClauseKeysForThisAssociation extends RequiredOnClauseKeys<Schema, TableName, AssociationName>, AssociationDream extends AssociationNameToDream<I, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, options: InstanceDestroyOptions<I> & JoinAndStatements<I, DB, Schema, AssociationTableName, RequiredOnClauseKeysForThisAssociation>): Promise<number>;
+    reallyDestroyAssociation<I extends Dream, DB extends I['DB'], Schema extends I['schema'], AssociationName extends DreamAssociationNamesWithoutRequiredOnClauses<I>, AssociationDream extends AssociationNameToDream<I, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, options?: InstanceDestroyOptions<I> & JoinAndStatements<I, DB, Schema, AssociationTableName, null>): Promise<number>;
+    undestroyAssociation<I extends Dream, DB extends I['DB'], TableName extends I['table'], Schema extends I['schema'], AssociationName extends DreamAssociationNamesWithRequiredOnClauses<I>, RequiredOnClauseKeysForThisAssociation extends RequiredOnClauseKeys<Schema, TableName, AssociationName>, AssociationDream extends AssociationNameToDream<I, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, options: InstanceDestroyOptions<I> & JoinAndStatements<I, DB, Schema, AssociationTableName, RequiredOnClauseKeysForThisAssociation>): Promise<number>;
+    undestroyAssociation<I extends Dream, DB extends I['DB'], Schema extends I['schema'], AssociationName extends DreamAssociationNamesWithoutRequiredOnClauses<I>, AssociationDream extends AssociationNameToDream<I, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, options?: InstanceDestroyOptions<I> & JoinAndStatements<I, DB, Schema, AssociationTableName, null>): Promise<number>;
     associationQuery<I extends Dream, DB extends I['DB'], TableName extends I['table'], Schema extends I['schema'], AssociationName extends DreamAssociationNamesWithRequiredOnClauses<I>, RequiredOnClauseKeysForThisAssociation extends RequiredOnClauseKeys<Schema, TableName, AssociationName>, AssociationDream extends AssociationNameToDream<I, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, joinAndStatements: JoinAndStatements<AssociationDream, DB, Schema, AssociationTableName, RequiredOnClauseKeysForThisAssociation>): Query<AssociationDream, DefaultQueryTypeOptions<AssociationDream, AssociationName & string>>;
     associationQuery<I extends Dream, DB extends I['DB'], Schema extends I['schema'], AssociationName extends DreamAssociationNamesWithoutRequiredOnClauses<I>, AssociationDream extends AssociationNameToDream<I, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, joinAndStatements?: JoinAndStatements<AssociationDream, DB, Schema, AssociationTableName, null>): Query<AssociationDream, DefaultQueryTypeOptions<AssociationDream, AssociationName & string>>;
-    updateAssociation<I extends Dream, DB extends I['DB'], TableName extends I['table'], Schema extends I['schema'], AssociationName extends DreamAssociationNamesWithRequiredOnClauses<I>, RequiredOnClauseKeysForThisAssociation extends RequiredOnClauseKeys<Schema, TableName, AssociationName>, AssociationDream extends AssociationNameToDream<I, AssociationName>, AssociationTableName extends AssociationDream['table'], PossibleArrayAssociationType extends I[AssociationName & keyof I], AssociationType extends PossibleArrayAssociationType extends (infer ElementType)[] ? ElementType : PossibleArrayAssociationType, RestrictedAssociationType extends AssociationType extends Dream ? AssociationType : never>(this: I, associationName: AssociationName, attributes: UpdateableAssociationProperties<I, RestrictedAssociationType>, updateAssociationOptions: {
+    updateAssociation<I extends Dream, DB extends I['DB'], TableName extends I['table'], Schema extends I['schema'], AssociationName extends DreamAssociationNamesWithRequiredOnClauses<I>, RequiredOnClauseKeysForThisAssociation extends RequiredOnClauseKeys<Schema, TableName, AssociationName>, AssociationDream extends AssociationNameToDream<I, AssociationName>, AssociationTableName extends AssociationDream['table'], PossibleArrayAssociationType extends I[AssociationName & keyof I], AssociationType extends PossibleArrayAssociationType extends (infer ElementType)[] ? ElementType : PossibleArrayAssociationType, RestrictedAssociationType extends AssociationType extends Dream ? AssociationType : never>(this: I, associationName: AssociationName, attributes: UpdateableAssociationProperties<I, RestrictedAssociationType>, updateAssociationOptions: InstanceUpdateOptions & {
         bypassAllDefaultScopes?: boolean;
         defaultScopesToBypass?: AllDefaultScopeNames<I>[];
-        skipHooks?: boolean;
     } & JoinAndStatements<I, DB, Schema, AssociationTableName, RequiredOnClauseKeysForThisAssociation>): Promise<number>;
-    updateAssociation<I extends Dream, DB extends I['DB'], Schema extends I['schema'], AssociationName extends DreamAssociationNamesWithoutRequiredOnClauses<I>, AssociationDream extends AssociationNameToDream<I, AssociationName>, AssociationTableName extends AssociationDream['table'], PossibleArrayAssociationType extends I[AssociationName & keyof I], AssociationType extends PossibleArrayAssociationType extends (infer ElementType)[] ? ElementType : PossibleArrayAssociationType, RestrictedAssociationType extends AssociationType extends Dream ? AssociationType : never>(this: I, associationName: AssociationName, attributes: UpdateableAssociationProperties<I, RestrictedAssociationType>, updateAssociationOptions?: {
+    updateAssociation<I extends Dream, DB extends I['DB'], Schema extends I['schema'], AssociationName extends DreamAssociationNamesWithoutRequiredOnClauses<I>, AssociationDream extends AssociationNameToDream<I, AssociationName>, AssociationTableName extends AssociationDream['table'], PossibleArrayAssociationType extends I[AssociationName & keyof I], AssociationType extends PossibleArrayAssociationType extends (infer ElementType)[] ? ElementType : PossibleArrayAssociationType, RestrictedAssociationType extends AssociationType extends Dream ? AssociationType : never>(this: I, associationName: AssociationName, attributes: UpdateableAssociationProperties<I, RestrictedAssociationType>, updateAssociationOptions?: InstanceUpdateOptions & {
         bypassAllDefaultScopes?: boolean;
         defaultScopesToBypass?: AllDefaultScopeNames<I>[];
-        skipHooks?: boolean;
     } & JoinAndStatements<I, DB, Schema, AssociationTableName, null>): Promise<number>;
     /**
      * Sends data through for use as passthrough data
@@ -2681,23 +2681,32 @@ export default class Dream {
      *   passthrough: { name: 'My Composition' },
      *   required: { locale: 'de-DE' }
      * })
+     *
+     * // With a specific database connection
+     * const comments = await post.association('comments', { connection: 'replica' })
      * ```
      *
      * @param associationName - The name of the BelongsTo, HasOne, or HasMany association
-     * @param options - Optional configuration for required and passthrough clauses
+     * @param options - Optional configuration for required and passthrough clauses and the database connection
      * @param options.required - for associations with DreamConst.required `and` clauses
      * @param options.passthrough - for associations with DreamConst.passthrough `and` clauses
+     * @param options.connection - the database connection to use when loading the association ('primary' or 'replica')
      * @returns The associated model instance(s) or null/empty array if not found
      */
     association<I extends Dream, MaybeAssociationName extends DreamBelongsToAssociationNames<I> | DreamHasOneAssociationNames<I> | DreamHasManyAssociationNames<I>, AssociationName extends MaybeAssociationName extends DreamAssociationNamesWithPassthroughOnClauses<I> | DreamAssociationNamesWithRequiredOnClauses<I> ? MaybeAssociationName : never, AssociationDream extends AssociationNameToDream<I, AssociationName>, AssociationTableName extends AssociationDream['table'], DB extends I['DB'], TableName extends I['table'], Schema extends I['schema'], PassthroughOnStatement extends Required<OnStatementForSpecificColumns<I, DB, Schema, AssociationTableName, PassthroughOnClauseKeys<Schema, TableName, AssociationName> & string[]>>, RequiredOnStatement extends Required<OnStatementForSpecificColumns<I, DB, Schema, AssociationTableName, RequiredOnClauseKeys<Schema, TableName, AssociationName> & string[]>>, Opts extends AssociationName extends DreamAssociationNamesWithPassthroughOnClauses<I> & DreamAssociationNamesWithRequiredOnClauses<I> ? {
         passthrough: PassthroughOnStatement;
         required: RequiredOnStatement;
+        connection?: DbConnectionType;
     } : AssociationName extends DreamAssociationNamesWithPassthroughOnClauses<I> ? {
         passthrough: PassthroughOnStatement;
+        connection?: DbConnectionType;
     } : AssociationName extends DreamAssociationNamesWithRequiredOnClauses<I> ? {
         required: RequiredOnStatement;
+        connection?: DbConnectionType;
     } : never, ReturnType extends AssociationName extends DreamHasManyAssociationNames<I> ? AssociationNameToDream<I, AssociationName>[] : AssociationNameToDream<I, AssociationName> | null>(this: I, associationName: AssociationName, options: Opts): Promise<ReturnType>;
-    association<I extends Dream, MaybeAssociationName extends DreamBelongsToAssociationNames<I> | DreamHasOneAssociationNames<I> | DreamHasManyAssociationNames<I>, AssociationName extends MaybeAssociationName extends DreamAssociationNamesWithPassthroughOnClauses<I> | DreamAssociationNamesWithRequiredOnClauses<I> ? never : MaybeAssociationName, ReturnType extends AssociationName extends DreamHasManyAssociationNames<I> ? AssociationNameToDream<I, AssociationName>[] : AssociationNameToDream<I, AssociationName> | null>(this: I, associationName: AssociationName): Promise<ReturnType>;
+    association<I extends Dream, MaybeAssociationName extends DreamBelongsToAssociationNames<I> | DreamHasOneAssociationNames<I> | DreamHasManyAssociationNames<I>, AssociationName extends MaybeAssociationName extends DreamAssociationNamesWithPassthroughOnClauses<I> | DreamAssociationNamesWithRequiredOnClauses<I> ? never : MaybeAssociationName, ReturnType extends AssociationName extends DreamHasManyAssociationNames<I> ? AssociationNameToDream<I, AssociationName>[] : AssociationNameToDream<I, AssociationName> | null>(this: I, associationName: AssociationName, options?: {
+        connection?: DbConnectionType;
+    }): Promise<ReturnType>;
     /**
      * If the association is already loaded on the instance, it returns the loaded value
      * immediately without making a database query. If the association is not loaded,
@@ -2742,24 +2751,33 @@ export default class Dream {
      *   passthrough: { name: 'My Composition' },
      *   required: { locale: 'de-DE' }
      * })
+     *
+     * // With a specific database connection
+     * const comments = await post.associationOrFail('comments', { connection: 'replica' })
      * ```
      *
      * @param associationName - The name of the BelongsTo, HasOne, or HasMany association
-     * @param options - Optional configuration for required and passthrough clauses
+     * @param options - Optional configuration for required and passthrough clauses and the database connection
      * @param options.required - for associations with DreamConst.required `and` clauses
      * @param options.passthrough - for associations with DreamConst.passthrough `and` clauses
+     * @param options.connection - the database connection to use when loading the association ('primary' or 'replica')
      * @returns The associated model instance(s) (never null for BelongsTo/HasOne)
      * @throws RecordNotFound if no associated record exists (BelongsTo/HasOne only)
      */
     associationOrFail<I extends Dream, MaybeAssociationName extends DreamBelongsToAssociationNames<I> | DreamHasOneAssociationNames<I> | DreamHasManyAssociationNames<I>, AssociationName extends MaybeAssociationName extends DreamAssociationNamesWithPassthroughOnClauses<I> | DreamAssociationNamesWithRequiredOnClauses<I> ? MaybeAssociationName : never, AssociationDream extends AssociationNameToDream<I, AssociationName>, AssociationTableName extends AssociationDream['table'], DB extends I['DB'], TableName extends I['table'], Schema extends I['schema'], PassthroughOnStatement extends Required<OnStatementForSpecificColumns<I, DB, Schema, AssociationTableName, PassthroughOnClauseKeys<Schema, TableName, AssociationName> & string[]>>, RequiredOnStatement extends Required<OnStatementForSpecificColumns<I, DB, Schema, AssociationTableName, RequiredOnClauseKeys<Schema, TableName, AssociationName> & string[]>>, Opts extends AssociationName extends DreamAssociationNamesWithPassthroughOnClauses<I> & DreamAssociationNamesWithRequiredOnClauses<I> ? {
         passthrough: PassthroughOnStatement;
         required: RequiredOnStatement;
+        connection?: DbConnectionType;
     } : AssociationName extends DreamAssociationNamesWithPassthroughOnClauses<I> ? {
         passthrough: PassthroughOnStatement;
+        connection?: DbConnectionType;
     } : AssociationName extends DreamAssociationNamesWithRequiredOnClauses<I> ? {
         required: RequiredOnStatement;
+        connection?: DbConnectionType;
     } : never, ReturnType extends AssociationName extends DreamHasManyAssociationNames<I> ? AssociationNameToDream<I, AssociationName>[] : AssociationNameToDream<I, AssociationName>>(this: I, associationName: AssociationName, options: Opts): Promise<ReturnType>;
-    associationOrFail<I extends Dream, MaybeAssociationName extends DreamBelongsToAssociationNames<I> | DreamHasOneAssociationNames<I> | DreamHasManyAssociationNames<I>, AssociationName extends MaybeAssociationName extends DreamAssociationNamesWithPassthroughOnClauses<I> | DreamAssociationNamesWithRequiredOnClauses<I> ? never : MaybeAssociationName, ReturnType extends AssociationName extends DreamHasManyAssociationNames<I> ? AssociationNameToDream<I, AssociationName>[] : AssociationNameToDream<I, AssociationName>>(this: I, associationName: AssociationName): Promise<ReturnType>;
+    associationOrFail<I extends Dream, MaybeAssociationName extends DreamBelongsToAssociationNames<I> | DreamHasOneAssociationNames<I> | DreamHasManyAssociationNames<I>, AssociationName extends MaybeAssociationName extends DreamAssociationNamesWithPassthroughOnClauses<I> | DreamAssociationNamesWithRequiredOnClauses<I> ? never : MaybeAssociationName, ReturnType extends AssociationName extends DreamHasManyAssociationNames<I> ? AssociationNameToDream<I, AssociationName>[] : AssociationNameToDream<I, AssociationName>>(this: I, associationName: AssociationName, options?: {
+        connection?: DbConnectionType;
+    }): Promise<ReturnType>;
     /**
      * Recursively loads all Dream associations referenced by `rendersOne` and `rendersMany`
      * in a DreamSerializer. This traverses the entire content tree of serializers to automatically
@@ -2984,9 +3002,7 @@ export default class Dream {
      * @param __namedParameters.skipHooks - if true, will skip applying model hooks. Defaults to false
      * @returns void
      */
-    update<I extends Dream>(this: I, attributes: UpdateableProperties<I>, { skipHooks }?: {
-        skipHooks?: boolean;
-    }): Promise<void>;
+    update<I extends Dream>(this: I, attributes: UpdateableProperties<I>, { skipHooks }?: InstanceUpdateOptions): Promise<void>;
     /**
      * Applies all attribute changes passed to the dream,
      * bypassing any custom-defined setters,
@@ -3010,9 +3026,7 @@ export default class Dream {
      * @param __namedParameters.skipHooks - if true, will skip applying model hooks. Defaults to false
      * @returns - void
      */
-    updateAttributes<I extends Dream>(this: I, attributes: UpdateableProperties<I>, { skipHooks }?: {
-        skipHooks?: boolean;
-    }): Promise<void>;
+    updateAttributes<I extends Dream>(this: I, attributes: UpdateableProperties<I>, { skipHooks }?: InstanceUpdateOptions): Promise<void>;
     /**
      * Flags a dream model so that it does not
      * actually destroy when in a destroy phase.

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

@@ -1,7 +1,7 @@
 import { SelectArg, SelectExpression } from 'kysely';
 import Dream from '../Dream.js';
 import { PassthroughOnClause, WhereStatement } from '../types/associations/shared.js';
-import { CreateOrFindByExtraOpts, DefaultScopeName, DreamColumnNames, DreamSerializerKey, FindablePropertiesForClass, OrderDir, PassthroughColumnNames, PluckEachArgs, PrimaryKeyForFind, TableColumnNames, UpdateableProperties, UpdateOrCreateByExtraOpts, ValidatedPluckEachColumnNames } from '../types/dream.js';
+import { AllDefaultScopeNames, CreateOrFindByExtraOpts, DreamColumnNames, DreamSerializerKey, FindablePropertiesForClass, OrderDir, PassthroughColumnNames, PluckEachArgs, PrimaryKeyForFind, TableColumnNames, UpdateableProperties, UpdateOrCreateByExtraOpts, ValidatedPluckEachColumnNames } from '../types/dream.js';
 import { BaseModelColumnTypes, FindEachOpts, LoadForModifierFn, QueryWithJoinedAssociationsType, QueryWithJoinedAssociationsTypeAndNoPreload } from '../types/query.js';
 import { JoinedAssociation, JoinedAssociationsTypeFromAssociations, VariadicJoinsArgs, VariadicLeftJoinLoadArgs, VariadicLoadArgs } from '../types/variadic.js';
 import DreamTransaction from './DreamTransaction.js';
@@ -599,6 +599,8 @@ export default class DreamClassTransactionBuilder<DreamClass extends typeof Drea
      */
     queryInstance<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>>(this: I): Query<DreamInstance>;
     /**
+     * @deprecated Use {@link removeDefaultScope} instead. This method will become private in v3.
+     *
      * Returns a query which bypasses user-removable default scopes, including on
      * association loads. An STI child's reserved type discriminator remains
      * enforced; query the STI base model to span its registered children.
@@ -612,7 +614,7 @@ export default class DreamClassTransactionBuilder<DreamClass extends typeof Drea
      *
      * @returns A new Query which will prevent a specific default scope from applying
      */
-    removeDefaultScope<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>>(this: I, scopeName: DefaultScopeName<DreamInstance>): Query<DreamInstance>;
+    removeDefaultScope<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>>(this: I, scopeName: AllDefaultScopeNames<DreamInstance>): Query<DreamInstance>;
     /**
      * Returns the last record corresponding to the
      * model, ordered by primary key.