@rvoh/dream 2.29.0 → 2.31.0

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

@@ -3,6 +3,7 @@ import { clearSortableSaveState } from '../../decorators/field/sortable/helpers/
 import performSortablePositionWork from '../../decorators/field/sortable/helpers/performSortablePositionWork.js';
 import prepareSortableFieldsForSave from '../../decorators/field/sortable/helpers/prepareSortableFieldsForSave.js';
 import { cacheSortableSnapshots } from '../../decorators/field/sortable/helpers/sortableSnapshot.js';
+import CannotSaveMissingDream from '../../errors/CannotSaveMissingDream.js';
 import ValidationError from '../../errors/ValidationError.js';
 import sqlAttributes from '../../helpers/sqlAttributes.js';
 import { DateTime } from '../../utils/datetime/DateTime.js';
@@ -114,6 +115,14 @@ async function writeDream(dream, txn, { alreadyPersisted, sortableFieldConfigs,
         dream.createdAt = now;
     if (!dream.dirtyAttributes().updatedAt && dream.columns().has('updatedAt'))
         dream.updatedAt = now;
+    // The scope-lock read above positively found the row gone, so there is
+    // nothing to update. Raised here rather than after the write because the
+    // write below would not reach the database at all on a position-only save,
+    // whose attributes Sortable has already cleared; a save that does carry data
+    // raises the equivalent diagnostic from the driver, which sees the update
+    // match no row.
+    if (alreadyPersisted && !rowFoundBeforeWrite)
+        throw new CannotSaveMissingDream(dream);
     const hasUnsavedData = !!Object.keys(sqlAttributes(dream)).length;
     // BeforeSave/Update actions may clear all the data that we intended to save, leaving us with
     // an invalid update command. The Sortable decorator is an example of this.

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

@@ -0,0 +1,24 @@
+/**
+ * Raised when saving a persisted instance whose database row no longer exists —
+ * the row was deleted between the moment the instance was loaded and the moment
+ * the save reached the database.
+ *
+ * This is the write-side counterpart of `RecordNotFound`, and applications catch
+ * it for the same reasons: a request updating a record another request has since
+ * deleted should answer 404 or 409 rather than 500, and a background job holding
+ * a stale instance should usually drop the work rather than fail loudly. Nothing
+ * is written when it is raised.
+ *
+ * It does not mean the save was rejected — a save that fails validation raises
+ * `ValidationError`, and a constraint violation raises its own error. It means
+ * the row that the instance stands for is gone.
+ *
+ * Dream raises it from the query driver, so a custom driver overriding
+ * `saveDream` translates its own adapter's empty-result error the same way, as
+ * the test-app MySQL driver does.
+ */
+export default class CannotSaveMissingDream extends Error {
+    constructor(dream) {
+        super(`Cannot save ${dream.sanitizedConstructorName} with primary key ${String(dream.primaryKeyValue())} because its persisted database row no longer exists.`);
+    }
+}

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

@@ -1,4 +1,6 @@
 /**
+ * @internal
+ *
  * Raised when a batch of a locked `Query#destroy` or `Query#update` on a
  * sortable model would carry its transaction past the number of advisory
  * sort-scope locks Dream is willing to hold at once.
@@ -27,6 +29,11 @@
  * — a long multi-batch run inside a transaction you opened — either let Dream
  * open a transaction per batch (do not pass a transaction of your own) or
  * commit between runs, which is what releases the locks as it goes.
+ *
+ * Not exported from `@rvoh/dream/errors`. Exceeding the bound is a sizing
+ * mistake in the calling code, not a runtime condition an application can
+ * recover from, so there is nothing for a consumer to catch: the fix is a
+ * smaller batch or a narrower transaction, never a retry.
  */
 export default class SortableBatchRequiresTooManyScopeLocks extends Error {
     dreamClassName;

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/esm/src/errors/associations/MissingRequiredBelongsToAssociation.js

@@ -48,10 +48,15 @@ export default class MissingRequiredBelongsToAssociation extends Error {
 Attempting to access required BelongsTo association \`${this.associationName}\` on an instance of \`${this.dreamClass.sanitizedName}\`,
 but the loaded association is null.
 
-${this.foreignKeyMessage}
-
-If the associated record was deleted, check whether the inverse HasOne/HasMany association should specify dependent: 'destroy'.
+${this.foreignKeyMessage}${this.populatedForeignKeyDiagnosticMessage}
 `;
+    }
+    get populatedForeignKeyDiagnosticMessage() {
+        if (this.foreignKeyValue === null || this.foreignKeyValue === undefined)
+            return '';
+        return `
+
+The associated record may have been deleted (including soft-deleted), or it may not match this association’s target—for example, its STI type may differ from the targeted STI child. If the record was deleted unexpectedly, check whether the inverse HasOne/HasMany association should specify \`dependent: 'destroy'\`.`;
     }
     get foreignKeyMessage() {
         if (this.foreignKeyValue === null || this.foreignKeyValue === undefined) {

package/dist/esm/src/package-exports/errors.js

@@ -1,18 +1,27 @@
 export { pgErrorType } from '../db/errors.js';
 export { default as NonLoadedAssociation } from '../errors/associations/NonLoadedAssociation.js';
+export { default as CannotSaveMissingDream } from '../errors/CannotSaveMissingDream.js';
 export { default as CreateOrFindByFailedToCreateAndFind } from '../errors/CreateOrFindByFailedToCreateAndFind.js';
 export { default as CheckConstraintViolation } from '../errors/db/CheckConstraintViolation.js';
 export { default as ColumnOverflow } from '../errors/db/ColumnOverflow.js';
 export { default as DataIncompatibleWithDatabaseField } from '../errors/db/DataIncompatibleWithDatabaseField.js';
 export { default as DataTypeColumnTypeMismatch } from '../errors/db/DataTypeColumnTypeMismatch.js';
 export { default as NotNullViolation } from '../errors/db/NotNullViolation.js';
+// Raised by the framework packages layered on Dream, not only by Dream: psychic
+// (`src/controller/index.ts`) raises it for a controller's global name, and
+// psychic-workers (`src/background/BaseBackgroundedService.ts`,
+// `src/background/BaseScheduledService.ts`) for service global names. Both reach it
+// through this entry point, so unexporting it breaks the build of every application
+// that installs either package.
 export { default as GlobalNameNotSet } from '../errors/dream-app/GlobalNameNotSet.js';
 export { default as DecryptionError } from '../errors/encrypt/DecryptionError.js';
 export { default as DecryptionParseError } from '../errors/encrypt/DecryptionParseError.js';
 export { default as DecryptionRotationError } from '../errors/encrypt/DecryptionRotationError.js';
 export { default as RecordNotFound } from '../errors/RecordNotFound.js';
+// Caught through this entry point by psychic
+// (`test-app/src/app/controllers/SerializerTestsController.ts`), which distinguishes it
+// to prove a controller can render a missing-serializers failure as a response.
 export { default as MissingSerializersDefinition } from '../errors/serializers/MissingSerializersDefinition.js';
-export { default as SortableBatchRequiresTooManyScopeLocks } from '../errors/SortableBatchRequiresTooManyScopeLocks.js';
 export { default as SortableScopeDidNotStabilize } from '../errors/SortableScopeDidNotStabilize.js';
 export { default as SortableScopeLockWaitTimedOut } from '../errors/SortableScopeLockWaitTimedOut.js';
 export { default as ValidationError } from '../errors/ValidationError.js';

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';
@@ -2478,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
@@ -2501,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.
@@ -2521,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.
@@ -2565,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
@@ -2683,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,
@@ -2744,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
@@ -2986,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,
@@ -3012,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/decorators/Decorators.d.ts

@@ -63,18 +63,93 @@ export default class Decorators<TD extends typeof Dream, T extends Dream = Insta
         default?: boolean;
     }): any;
     /**
-     * The Sortable decorator automatically adjusts the value of the columns
-     * corresponding to the decorated field.
-     *
-     * NOTE: the Sortable decorator may not be used in STI child models (it may be used in the STI base class)
+     * Marks an integer column as a sortable position: Dream keeps the positions of
+     * every record in a sort scope contiguous, starting at 1, as records are
+     * created, moved, destroyed and undestroyed.
      *
      * ```ts
-     * class Balloon {
+     * class Post extends ApplicationModel {
      *   @deco.Sortable({ scope: 'user' })
-     *   public position: DreamColumn<Balloon, 'position'>
+     *   public position: number
+     * }
+     *
+     * await post.update({ position: 2 }) // the records at 2 and above shift up
+     * ```
+     *
+     * A position past the end of the scope is clamped to the end, and a position
+     * below 1 — or none at all — lands the record at the end.
+     *
+     * **A save that changes the sort scope ignores a position given alongside it.**
+     * The record lands at the end of the scope it moves into, whatever position the
+     * same `update` supplied:
+     *
+     * ```ts
+     * await post.update({ user: otherUser, position: 1 })
+     * // post is now the last record in otherUser's scope, not the first
+     * ```
+     *
+     * Move it in two saves to place it: `await post.update({ user: otherUser })`,
+     * then `await post.update({ position: 1 })`.
+     *
+     * Sortable requires a query driver that supports advisory transaction locks —
+     * the `PostgresQueryDriver` does — since every position write serializes the
+     * writers of its sort scope on one. This concurrency guarantee first shipped
+     * in Dream 2.28.0 and begins only after every writer is running a lock-aware
+     * release. During the first rolling deployment, older processes take no
+     * advisory locks and can still race the upgraded processes.
+     *
+     * All participating Dream writers of one hot scope serialize. Ordinary saves
+     * and destroys with `skipHooks`, direct query writes, raw SQL, and older
+     * pre-lock Dream processes bypass Sortable maintenance and do not participate
+     * in its locking protocol. Undestroy still performs stabilized Sortable
+     * maintenance and acquires scope locks with `skipHooks: true`; locked query
+     * batches likewise acquire their scope locks during preflight, before any
+     * per-record callbacks, even when those callbacks skip hooks. A waiter that
+     * enters the protocol holds a pooled connection until the holder finishes or
+     * `sortableScopeLockTimeout` expires; sustained contention can therefore
+     * produce latency waves, timeouts, and pool starvation. Keep database work
+     * inside the lock window short, and avoid cross-region database latency for
+     * hot scopes.
+     *
+     * `SortableScopeDidNotStabilize` and `SortableScopeLockWaitTimedOut` are the
+     * expected Dream errors an application may choose to retry. Database deadlocks
+     * remain native adapter errors (for example PostgreSQL code `40P01` or MySQL
+     * errno `1213`) so their driver fields and stacks remain intact. A database
+     * deadlock aborts the whole transaction: retry by starting the transaction
+     * again from the beginning, never by continuing it or retrying only the failed
+     * statement. Recurrent deadlocks call for shorter transactions or a consistent
+     * multi-resource acquisition order; they do not by themselves prove Sortable
+     * caused the cycle.
+     *
+     * ```ts
+     * import {
+     *   SortableScopeDidNotStabilize,
+     *   SortableScopeLockWaitTimedOut,
+     * } from '@rvoh/dream/errors'
+     *
+     * const runTransaction = async () =>
+     *   await ApplicationModel.transaction(async txn => {
+     *     // bind every operation in the attempt to txn
+     *   })
+     *
+     * try {
+     *   await runTransaction()
+     * } catch (error) {
+     *   const adapterDeadlock =
+     *     (error as { code?: string }).code === '40P01' ||
+     *     (error as { errno?: number }).errno === 1213
+     *   const retryable =
+     *     error instanceof SortableScopeDidNotStabilize ||
+     *     error instanceof SortableScopeLockWaitTimedOut ||
+     *     adapterDeadlock
+     *   if (!retryable) throw error
+     *
+     *   await runTransaction() // one whole-transaction retry
      * }
      * ```
      *
+     * NOTE: the Sortable decorator may not be used in STI child models (it may be used in the STI base class)
+     *
      * @param opts - Configuration options for the sortable decorator
      * @param opts.scope - The column, association, or combination thereof which you would like to restrict the incrementing logic to. Can be a single column name, a single belongs-to association name, or an array of column/association names
      * @returns A Sortable decorator

package/dist/types/src/decorators/field/sortable/Sortable.d.ts

@@ -1,35 +1,8 @@
 /**
- * Marks an integer column as a sortable position: Dream keeps the positions of
- * every record in a sort scope contiguous, starting at 1, as records are
- * created, moved, destroyed and undestroyed.
- *
- * ```ts
- * class Post extends ApplicationModel {
- *   @deco.Sortable({ scope: 'user' })
- *   public position: number
- * }
- *
- * await post.update({ position: 2 }) // the records at 2 and above shift up
- * ```
- *
- * A position past the end of the scope is clamped to the end, and a position
- * below 1 — or none at all — lands the record at the end.
- *
- * **A save that changes the sort scope ignores a position given alongside it.**
- * The record lands at the end of the scope it moves into, whatever position the
- * same `update` supplied:
- *
- * ```ts
- * await post.update({ user: otherUser, position: 1 })
- * // post is now the last record in otherUser's scope, not the first
- * ```
- *
- * Move it in two saves to place it: `await post.update({ user: otherUser })`,
- * then `await post.update({ position: 1 })`.
- *
- * Sortable requires a query driver that supports advisory transaction locks —
- * the `PostgresQueryDriver` does — since every position write serializes the
- * writers of its sort scope on one.
+ * The implementation behind `@deco.Sortable`. The decorator's semantics —
+ * position clamping, what a scope-changing save does with a position given
+ * alongside it, and the advisory-lock concurrency protocol — are documented on
+ * `Decorators#Sortable`, which is where a consumer reads them.
  */
 export default function Sortable(opts?: SortableOpts): any;
 interface SortableOpts {

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

@@ -4,7 +4,7 @@ import { AllDefaultScopeNames, AssociationNameToDream, DreamAssociationNames, Dr
 import { DefaultQueryTypeOptions, LoadForModifierFn, QueryWithJoinedAssociationsType } from '../types/query.js';
 import { JoinedAssociation, JoinedAssociationsTypeFromAssociations, VariadicJoinsArgs, VariadicLeftJoinLoadArgs, VariadicLoadArgs } from '../types/variadic.js';
 import DreamTransaction from './DreamTransaction.js';
-import { DestroyOptions } from './internal/destroyOptions.js';
+import type { InstanceDestroyOptions, InstanceUpdateOptions } from './internal/instanceMutationOptions.js';
 import LeftJoinLoadBuilder from './LeftJoinLoadBuilder.js';
 import LoadBuilder from './LoadBuilder.js';
 import Query from './Query.js';
@@ -178,7 +178,7 @@ export default class DreamInstanceTransactionBuilder<DreamInstance extends 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 DreamInstanceTransactionBuilder<DreamInstance>>(this: I, options?: DestroyOptions<DreamInstance>): Promise<DreamInstance>;
+    destroy<I extends DreamInstanceTransactionBuilder<DreamInstance>>(this: I, options?: InstanceDestroyOptions<DreamInstance>): Promise<DreamInstance>;
     /**
      * Deletes the record represented by this instance
      * from the database, calling any destroy
@@ -198,7 +198,7 @@ export default class DreamInstanceTransactionBuilder<DreamInstance extends 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 DreamInstanceTransactionBuilder<DreamInstance>>(this: I, options?: DestroyOptions<DreamInstance>): Promise<DreamInstance>;
+    reallyDestroy<I extends DreamInstanceTransactionBuilder<DreamInstance>>(this: I, options?: InstanceDestroyOptions<DreamInstance>): Promise<DreamInstance>;
     /**
      * Undestroys a SoftDelete model, unsetting
      * the `deletedAt` field in the database.
@@ -218,7 +218,7 @@ export default class DreamInstanceTransactionBuilder<DreamInstance extends 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 instance
      */
-    undestroy<I extends DreamInstanceTransactionBuilder<DreamInstance>>(this: I, options?: DestroyOptions<DreamInstance>): Promise<DreamInstance>;
+    undestroy<I extends DreamInstanceTransactionBuilder<DreamInstance>>(this: I, options?: InstanceDestroyOptions<DreamInstance>): Promise<DreamInstance>;
     /**
      * Applies all attribute changes passed to the Dream
      * instance, leveraging any custom-defined setters,
@@ -242,9 +242,7 @@ export default class DreamInstanceTransactionBuilder<DreamInstance extends Dream
      * @param opts.skipHooks - if true, will skip applying model hooks. Defaults to false
      * @returns void
      */
-    update<I extends DreamInstanceTransactionBuilder<DreamInstance>>(this: I, attributes: UpdateableProperties<DreamInstance>, { skipHooks }?: {
-        skipHooks?: boolean;
-    }): Promise<void>;
+    update<I extends DreamInstanceTransactionBuilder<DreamInstance>>(this: I, attributes: UpdateableProperties<DreamInstance>, { skipHooks }?: InstanceUpdateOptions): Promise<void>;
     /**
      * Applies all attribute changes passed to the dream,
      * bypassing any custom-defined setters,
@@ -269,9 +267,7 @@ export default class DreamInstanceTransactionBuilder<DreamInstance extends Dream
      * @param opts.skipHooks - if true, will skip applying model hooks. Defaults to false
      * @returns - void
      */
-    updateAttributes<I extends DreamInstanceTransactionBuilder<DreamInstance>>(this: I, attributes: UpdateableProperties<DreamInstance>, { skipHooks }?: {
-        skipHooks?: boolean;
-    }): Promise<void>;
+    updateAttributes<I extends DreamInstanceTransactionBuilder<DreamInstance>>(this: I, attributes: UpdateableProperties<DreamInstance>, { skipHooks }?: InstanceUpdateOptions): Promise<void>;
     /**
      * Reloads an instance, refreshing all it's attribute values
      * to those in the database.
@@ -432,15 +428,13 @@ export default class DreamInstanceTransactionBuilder<DreamInstance extends Dream
     associationOrFail<I extends DreamInstanceTransactionBuilder<DreamInstance>, MaybeAssociationName extends DreamBelongsToAssociationNames<DreamInstance> | DreamHasOneAssociationNames<DreamInstance> | DreamHasManyAssociationNames<DreamInstance>, AssociationName extends MaybeAssociationName extends DreamAssociationNamesWithPassthroughOnClauses<DreamInstance> | DreamAssociationNamesWithRequiredOnClauses<DreamInstance> ? never : MaybeAssociationName, ReturnType extends AssociationName extends DreamHasManyAssociationNames<DreamInstance> ? AssociationNameToDream<DreamInstance, AssociationName>[] : AssociationNameToDream<DreamInstance, AssociationName>>(this: I, associationName: AssociationName): Promise<ReturnType>;
     associationQuery<I extends DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], AssociationName extends DreamAssociationNamesWithRequiredOnClauses<DreamInstance>, RequiredOnClauseKeysForThisAssociation extends RequiredOnClauseKeys<Schema, TableName, AssociationName>, AssociationDream extends AssociationNameToDream<DreamInstance, 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 DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], Schema extends DreamInstance['schema'], AssociationName extends DreamAssociationNamesWithoutRequiredOnClauses<DreamInstance>, AssociationDream extends AssociationNameToDream<DreamInstance, 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 DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], AssociationName extends DreamAssociationNamesWithRequiredOnClauses<DreamInstance>, RequiredOnClauseKeysForThisAssociation extends RequiredOnClauseKeys<Schema, TableName, AssociationName>, AssociationDream extends AssociationNameToDream<DreamInstance, AssociationName>, AssociationTableName extends AssociationDream['table'], PossibleArrayAssociationType = DreamInstance[AssociationName & keyof DreamInstance], AssociationType = PossibleArrayAssociationType extends (infer ElementType)[] ? ElementType : PossibleArrayAssociationType, RestrictedAssociationType extends AssociationType extends Dream ? AssociationType : never = AssociationType extends Dream ? AssociationType : never>(this: I, associationName: AssociationName, attributes: UpdateableAssociationProperties<DreamInstance, RestrictedAssociationType>, updateAssociationOptions: {
+    updateAssociation<I extends DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], AssociationName extends DreamAssociationNamesWithRequiredOnClauses<DreamInstance>, RequiredOnClauseKeysForThisAssociation extends RequiredOnClauseKeys<Schema, TableName, AssociationName>, AssociationDream extends AssociationNameToDream<DreamInstance, AssociationName>, AssociationTableName extends AssociationDream['table'], PossibleArrayAssociationType = DreamInstance[AssociationName & keyof DreamInstance], AssociationType = PossibleArrayAssociationType extends (infer ElementType)[] ? ElementType : PossibleArrayAssociationType, RestrictedAssociationType extends AssociationType extends Dream ? AssociationType : never = AssociationType extends Dream ? AssociationType : never>(this: I, associationName: AssociationName, attributes: UpdateableAssociationProperties<DreamInstance, RestrictedAssociationType>, updateAssociationOptions: InstanceUpdateOptions & {
         bypassAllDefaultScopes?: boolean;
         defaultScopesToBypass?: AllDefaultScopeNames<DreamInstance>[];
-        skipHooks?: boolean;
     } & JoinAndStatements<AssociationDream, DB, Schema, AssociationTableName, RequiredOnClauseKeysForThisAssociation>): Promise<number>;
-    updateAssociation<I extends DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], Schema extends DreamInstance['schema'], AssociationName extends DreamAssociationNamesWithoutRequiredOnClauses<DreamInstance>, AssociationDream extends AssociationNameToDream<DreamInstance, AssociationName>, AssociationTableName extends AssociationDream['table'], PossibleArrayAssociationType = DreamInstance[AssociationName & keyof DreamInstance], AssociationType = PossibleArrayAssociationType extends (infer ElementType)[] ? ElementType : PossibleArrayAssociationType, RestrictedAssociationType extends AssociationType extends Dream ? AssociationType : never = AssociationType extends Dream ? AssociationType : never>(this: I, associationName: AssociationName, attributes: UpdateableAssociationProperties<DreamInstance, RestrictedAssociationType>, updateAssociationOptions?: {
+    updateAssociation<I extends DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], Schema extends DreamInstance['schema'], AssociationName extends DreamAssociationNamesWithoutRequiredOnClauses<DreamInstance>, AssociationDream extends AssociationNameToDream<DreamInstance, AssociationName>, AssociationTableName extends AssociationDream['table'], PossibleArrayAssociationType = DreamInstance[AssociationName & keyof DreamInstance], AssociationType = PossibleArrayAssociationType extends (infer ElementType)[] ? ElementType : PossibleArrayAssociationType, RestrictedAssociationType extends AssociationType extends Dream ? AssociationType : never = AssociationType extends Dream ? AssociationType : never>(this: I, associationName: AssociationName, attributes: UpdateableAssociationProperties<DreamInstance, RestrictedAssociationType>, updateAssociationOptions?: InstanceUpdateOptions & {
         bypassAllDefaultScopes?: boolean;
         defaultScopesToBypass?: AllDefaultScopeNames<DreamInstance>[];
-        skipHooks?: boolean;
     } & JoinAndStatements<DreamInstance, DB, Schema, AssociationTableName, null>): Promise<number>;
     /**
      * Creates an association for an instance. Automatically
@@ -458,12 +452,12 @@ export default class DreamInstanceTransactionBuilder<DreamInstance extends Dream
      * @returns The created association
      */
     createAssociation<I extends DreamInstanceTransactionBuilder<DreamInstance>, AssociationName extends DreamAssociationNames<DreamInstance>, PossibleArrayAssociationType = DreamInstance[AssociationName & keyof DreamInstance], AssociationType = PossibleArrayAssociationType extends (infer ElementType)[] ? ElementType : PossibleArrayAssociationType, RestrictedAssociationType extends AssociationType extends Dream ? AssociationType : never = AssociationType extends Dream ? AssociationType : never>(this: I, associationName: AssociationName, opts?: UpdateableAssociationProperties<DreamInstance, RestrictedAssociationType>): Promise<NonNullable<AssociationType>>;
-    destroyAssociation<I extends DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], AssociationName extends DreamAssociationNamesWithRequiredOnClauses<DreamInstance>, RequiredOnClauseKeysForThisAssociation extends RequiredOnClauseKeys<Schema, TableName, AssociationName>, AssociationDream extends AssociationNameToDream<DreamInstance, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, options: DestroyOptions<DreamInstance> & JoinAndStatements<AssociationDream, DB, Schema, AssociationTableName, RequiredOnClauseKeysForThisAssociation>): Promise<number>;
-    destroyAssociation<I extends DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], Schema extends DreamInstance['schema'], AssociationName extends DreamAssociationNamesWithoutRequiredOnClauses<DreamInstance>, AssociationDream extends AssociationNameToDream<DreamInstance, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, options?: DestroyOptions<DreamInstance> & JoinAndStatements<DreamInstance, DB, Schema, AssociationTableName, null>): Promise<number>;
-    reallyDestroyAssociation<I extends DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], AssociationName extends DreamAssociationNamesWithRequiredOnClauses<DreamInstance>, RequiredOnClauseKeysForThisAssociation extends RequiredOnClauseKeys<Schema, TableName, AssociationName>, AssociationDream extends AssociationNameToDream<DreamInstance, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, options: DestroyOptions<DreamInstance> & JoinAndStatements<AssociationDream, DB, Schema, AssociationTableName, RequiredOnClauseKeysForThisAssociation>): Promise<number>;
-    reallyDestroyAssociation<I extends DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], Schema extends DreamInstance['schema'], AssociationName extends DreamAssociationNamesWithoutRequiredOnClauses<DreamInstance>, AssociationDream extends AssociationNameToDream<DreamInstance, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, options?: DestroyOptions<DreamInstance> & JoinAndStatements<AssociationDream, DB, Schema, AssociationTableName, null>): Promise<number>;
-    undestroyAssociation<I extends DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], AssociationName extends DreamAssociationNamesWithRequiredOnClauses<DreamInstance>, RequiredOnClauseKeysForThisAssociation extends RequiredOnClauseKeys<Schema, TableName, AssociationName>, AssociationDream extends AssociationNameToDream<DreamInstance, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, options: DestroyOptions<DreamInstance> & JoinAndStatements<AssociationDream, DB, Schema, AssociationTableName, RequiredOnClauseKeysForThisAssociation>): Promise<number>;
-    undestroyAssociation<I extends DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], Schema extends DreamInstance['schema'], AssociationName extends DreamAssociationNamesWithoutRequiredOnClauses<DreamInstance>, AssociationDream extends AssociationNameToDream<DreamInstance, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, options?: DestroyOptions<DreamInstance> & JoinAndStatements<AssociationDream, DB, Schema, AssociationTableName, null>): Promise<number>;
+    destroyAssociation<I extends DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], AssociationName extends DreamAssociationNamesWithRequiredOnClauses<DreamInstance>, RequiredOnClauseKeysForThisAssociation extends RequiredOnClauseKeys<Schema, TableName, AssociationName>, AssociationDream extends AssociationNameToDream<DreamInstance, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, options: InstanceDestroyOptions<DreamInstance> & JoinAndStatements<AssociationDream, DB, Schema, AssociationTableName, RequiredOnClauseKeysForThisAssociation>): Promise<number>;
+    destroyAssociation<I extends DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], Schema extends DreamInstance['schema'], AssociationName extends DreamAssociationNamesWithoutRequiredOnClauses<DreamInstance>, AssociationDream extends AssociationNameToDream<DreamInstance, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, options?: InstanceDestroyOptions<DreamInstance> & JoinAndStatements<DreamInstance, DB, Schema, AssociationTableName, null>): Promise<number>;
+    reallyDestroyAssociation<I extends DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], AssociationName extends DreamAssociationNamesWithRequiredOnClauses<DreamInstance>, RequiredOnClauseKeysForThisAssociation extends RequiredOnClauseKeys<Schema, TableName, AssociationName>, AssociationDream extends AssociationNameToDream<DreamInstance, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, options: InstanceDestroyOptions<DreamInstance> & JoinAndStatements<AssociationDream, DB, Schema, AssociationTableName, RequiredOnClauseKeysForThisAssociation>): Promise<number>;
+    reallyDestroyAssociation<I extends DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], Schema extends DreamInstance['schema'], AssociationName extends DreamAssociationNamesWithoutRequiredOnClauses<DreamInstance>, AssociationDream extends AssociationNameToDream<DreamInstance, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, options?: InstanceDestroyOptions<DreamInstance> & JoinAndStatements<AssociationDream, DB, Schema, AssociationTableName, null>): Promise<number>;
+    undestroyAssociation<I extends DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], AssociationName extends DreamAssociationNamesWithRequiredOnClauses<DreamInstance>, RequiredOnClauseKeysForThisAssociation extends RequiredOnClauseKeys<Schema, TableName, AssociationName>, AssociationDream extends AssociationNameToDream<DreamInstance, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, options: InstanceDestroyOptions<DreamInstance> & JoinAndStatements<AssociationDream, DB, Schema, AssociationTableName, RequiredOnClauseKeysForThisAssociation>): Promise<number>;
+    undestroyAssociation<I extends DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], Schema extends DreamInstance['schema'], AssociationName extends DreamAssociationNamesWithoutRequiredOnClauses<DreamInstance>, AssociationDream extends AssociationNameToDream<DreamInstance, AssociationName>, AssociationTableName extends AssociationDream['table']>(this: I, associationName: AssociationName, options?: InstanceDestroyOptions<DreamInstance> & JoinAndStatements<AssociationDream, DB, Schema, AssociationTableName, null>): Promise<number>;
     /**
      * @internal
      *