@rvoh/dream 2.34.0 → 2.36.0

package/README.md

@@ -261,11 +261,11 @@ const userIds = await User.where({ name: ops.similarity('steeven hawkins') }).pl
 const min = await User.where({ name: ops.similarity('steeven hawkins') }).min('id')
 const max = await User.where({ name: ops.similarity('steeven hawkins') }).max('id')
 const count = await User.where({ name: ops.similarity('steeven hawkins') }).count()
-const petIds = await User.innerJoin('pets', { name: ops.similarity('fido') }).pluck('pets.id')
+const petIds = await User.innerJoin('pets', { and: { name: ops.similarity('fido') } }).pluck('pets.id')
 const numUpdatedRecords = await User.where({ name: ops.similarity('steeven hawkins') }).update({
   name: 'Stephen Hawking',
 })
-const users = await User.innerJoin('pets', { name: ops.similarity('fido') }).all()
+const users = await User.innerJoin('pets', { and: { name: ops.similarity('fido') } }).all()
 
 const user = await User.first()
 const pets = await user

package/dist/cjs/src/Dream.js

@@ -8,6 +8,7 @@ import DreamApp from './dream-app/index.js';
 import { RECURSIVE_SERIALIZATION_MAX_REPEATS } from './dream/constants.js';
 import DreamClassTransactionBuilder from './dream/DreamClassTransactionBuilder.js';
 import DreamInstanceTransactionBuilder from './dream/DreamInstanceTransactionBuilder.js';
+import assertRecognizedAssociationConditionKeys, { DESTROY_ASSOCIATION_OPTION_KEYS, UPDATE_ASSOCIATION_OPTION_KEYS, } from './dream/internal/associations/assertRecognizedAssociationConditionKeys.js';
 import associationQuery from './dream/internal/associations/associationQuery.js';
 import associationUpdateQuery from './dream/internal/associations/associationUpdateQuery.js';
 import createAssociation from './dream/internal/associations/createAssociation.js';
@@ -30,6 +31,7 @@ import updateOrCreateBy from './dream/internal/updateOrCreateBy.js';
 import LeftJoinLoadBuilder from './dream/LeftJoinLoadBuilder.js';
 import LoadBuilder from './dream/LoadBuilder.js';
 import Query from './dream/Query.js';
+import InternalEncrypt from './encrypt/InternalEncrypt.js';
 import CannotAssociationQueryOnUnpersistedDream from './errors/associations/CannotAssociationQueryOnUnpersistedDream.js';
 import CannotCreateAssociationOnUnpersistedDream from './errors/associations/CannotCreateAssociationOnUnpersistedDream.js';
 import CannotDestroyAssociationOnUnpersistedDream from './errors/associations/CannotDestroyAssociationOnUnpersistedDream.js';
@@ -40,6 +42,7 @@ import CannotCallUndestroyOnANonSoftDeleteModel from './errors/CannotCallUndestr
 import ConstructorOnlyForInternalUse from './errors/ConstructorOnlyForInternalUse.js';
 import CreateOrFindByFailedToCreateAndFind from './errors/CreateOrFindByFailedToCreateAndFind.js';
 import CreateOrUpdateByFailedToCreateAndUpdate from './errors/CreateOrUpdateByFailedToCreateAndUpdate.js';
+import DoNotSetEncryptedFieldsDirectly from './errors/DoNotSetEncryptedFieldsDirectly.js';
 import GlobalNameNotSet from './errors/dream-app/GlobalNameNotSet.js';
 import DreamMissingRequiredOverride from './errors/DreamMissingRequiredOverride.js';
 import NonExistentScopeProvidedToResort from './errors/NonExistentScopeProvidedToResort.js';
@@ -1429,6 +1432,67 @@ export default class Dream {
     static async findEach(cb, opts) {
         await this.query().findEach(cb, opts);
     }
+    /**
+     * Encrypts every value of the model's `@deco.Encrypted` properties again
+     * with the current column encryption key, so that reading them no longer
+     * needs the `legacy` key. It is a step of a key rotation (see
+     * `Encrypt.generateKey`): run it in each environment, once that
+     * environment has deployed its rotated keys, from a console or a script,
+     * not from a migration, whose result would then depend on the keys a given
+     * environment has configured when the migration runs.
+     *
+     * ```ts
+     * await User.reencryptEncryptedColumns()
+     * ```
+     *
+     * It walks every row of the model's table, including rows its default
+     * scopes (such as soft delete) hide and an STI model's siblings, in batches in primary key order, and opens
+     * each non-null value with the current key or, failing that, the legacy
+     * one (see `Encrypt.reencrypt`). Each row is written on its own, with
+     * no model hooks and without changing `updatedAt`, and only while the
+     * column still holds the value read, so a row an app saves in between
+     * keeps the newer value. Reading values here does not fire
+     * `dreamApp.on('encryption:legacy-key-used', ...)`.
+     *
+     * **Run it only once every server encrypts with the new key.** It walks
+     * the table once, so a row a server still configured with the old
+     * `current` writes behind it stays encrypted with the old key, and so does
+     * old-key ciphertext later written straight into a backing column
+     * (`setAttribute`, `setAttributes` and `updateAttributes` accept, for a
+     * backing column, ciphertext that either key opens). Once no writer uses
+     * the old key and this has run for every model with encrypted properties,
+     * `legacy` is safe to drop.
+     *
+     * **A value neither key opens stops it**, throwing as reading the property
+     * would (`DecryptionRotationError` while a `legacy` key is configured,
+     * `DecryptionError` without one). The rows rewritten before it stay
+     * rewritten; running it again once the value is fixed rewrites them again
+     * harmlessly.
+     *
+     * @param opts - Optional parameters
+     * @param opts.batchSize - how many rows to read per batch. Defaults to 1000
+     */
+    static async reencryptEncryptedColumns(opts) {
+        const encryptedColumnNames = this.encryptedAttributes.map(attribute => attribute.encryptedColumnName);
+        if (!encryptedColumnNames.length)
+            return;
+        const tableClass = this.stiBaseClassOrOwnClass;
+        await tableClass.removeAllDefaultScopes().findEach(async (record) => {
+            for (const columnName of encryptedColumnNames) {
+                const ciphertext = record.getAttribute(columnName);
+                if (ciphertext === null || ciphertext === undefined)
+                    continue;
+                // written through Kysely, since Query#update refuses any value for a
+                // backing column, ciphertext included
+                await tableClass
+                    .removeAllDefaultScopes()
+                    .where({ [tableClass.primaryKey]: record.primaryKeyValue(), [columnName]: ciphertext })
+                    .toKysely('update')
+                    .set({ [columnName]: InternalEncrypt.reencryptColumn(ciphertext) })
+                    .execute();
+            }
+        }, opts);
+    }
     /**
      * Returns a new instance of Query scoped to the given
      * model class. Especially useful with {@link Query#toKysely}.
@@ -1560,12 +1624,12 @@ export default class Dream {
      * planned drop safe.
      *
      * ```ts
-     * const user = await User.leftJoinPreload('posts', 'comments', { visibilty: 'public' }, 'replies').first()
+     * const user = await User.leftJoinPreload('posts', 'comments', { and: { visibility: 'public' } }, 'replies').first()
      * console.log(user.posts[0].comments[0].replies)
      * // [Reply{id: 1}, Reply{id: 2}]
      * ```
      *
-     * @param args - A chain of association names and where clauses
+     * @param args - A chain of association names and and/andNot/andAny clauses
      * @returns A query for this model with the include statement applied
      */
     static leftJoinPreload(...args) {
@@ -1582,12 +1646,12 @@ export default class Dream {
      * Preload is useful for avoiding the N+1 query problem
      *
      * ```ts
-     * const user = await User.preload('posts', 'comments', { visibilty: 'public' }, 'replies').first()
+     * const user = await User.preload('posts', 'comments', { and: { visibility: 'public' } }, 'replies').first()
      * console.log(user.posts[0].comments[0].replies)
      * // [Reply{id: 1}, Reply{id: 2}]
      * ```
      *
-     * @param args - A chain of association names and where clauses
+     * @param args - A chain of association names and and/andNot/andAny clauses
      * @returns A query for this model with the preload statement applied
      */
     static preload(...args) {
@@ -1647,7 +1711,7 @@ export default class Dream {
      * await User.innerJoin('posts').first()
      * ```
      *
-     * @param args - A chain of association names and where clauses
+     * @param args - A chain of association names and and/andNot/andAny clauses
      * @returns A Query for this model with the inner join clause applied
      */
     static innerJoin(...args) {
@@ -1661,7 +1725,7 @@ export default class Dream {
      * await user.innerJoin('posts').first()
      * ```
      *
-     * @param args - A chain of association names and where clauses
+     * @param args - A chain of association names and and/andNot/andAny clauses
      * @returns A Query for this model with the inner join clause applied
      */
     innerJoin(...args) {
@@ -1675,7 +1739,7 @@ export default class Dream {
      * await User.leftJoin('posts').first()
      * ```
      *
-     * @param args - A chain of association names and where clauses
+     * @param args - A chain of association names and and/andNot/andAny clauses
      * @returns A Query for this model with the left join clause applied
      */
     static leftJoin(...args) {
@@ -1689,7 +1753,7 @@ export default class Dream {
      * await user.leftJoin('posts').first()
      * ```
      *
-     * @param args - A chain of association names and where clauses
+     * @param args - A chain of association names and and/andNot/andAny clauses
      * @returns A Query for this model with the left join clause applied
      */
     leftJoin(...args) {
@@ -2302,8 +2366,8 @@ export default class Dream {
     /**
      * Returns true if any of the attributes on the instance
      * have changed since it was last pulled from the database.
-     * It will also return true if the instance is not yet
-     * persisted.
+     * On an unpersisted instance, it returns true when at least
+     * one column has a value other than `undefined`.
      *
      * ```ts
      * const post = Post.new({ body: 'howyadoin' })
@@ -2589,6 +2653,15 @@ export default class Dream {
      * const user = User.new({ email: 'how@yadoin' })
      * ```
      *
+     * @param opts - the attributes to set on the new instance
+     * @param additionalOpts - optional parameters
+     * @param additionalOpts.bypassUserDefinedSetters - if true, sets the attributes
+     * as {@link Dream.setAttributes | setAttributes} does, bypassing any
+     * custom-defined setters. An encrypted property (e.g. `secret`) is still
+     * encrypted, and an `@Encrypted` backing column (e.g. `encryptedSecret`)
+     * accepts only ciphertext that decrypts with this app's column encryption
+     * keys, or `null`; anything else throws (see
+     * {@link Dream.setAttribute | setAttribute}). Defaults to false
      * @returns A new (unpersisted) instance of the provided dream class
      */
     static new(opts, additionalOpts = {}) {
@@ -2658,7 +2731,7 @@ export default class Dream {
      *
      * Used for determining which attributes to update
      */
-    static extractAttributesFromUpdateableProperties(attributes, dreamInstance, { bypassUserDefinedSetters = false } = {}) {
+    static extractAttributesFromUpdateableProperties(attributes, dreamInstance, { bypassUserDefinedSetters = false, fromDatabase = false } = {}) {
         const returnValues = {};
         const setAttributeOnDreamInstance = (attr, value) => {
             if (!dreamInstance)
@@ -2672,8 +2745,13 @@ export default class Dream {
             }
             else if (bypassUserDefinedSetters && !isJsonColumn(this, attr)) {
                 // bypass user defined setters, and this field is not json, so set
-                // the attribute directly and return the attribute
-                dreamInstance.setAttribute(attr, value);
+                // the attribute directly and return the attribute. A row read from
+                // the database already holds the ciphertext Dream stored, so it skips
+                // setAttribute's check of @Encrypted backing columns
+                if (fromDatabase)
+                    dreamInstance['setAttributeUnchecked'](attr, value);
+                else
+                    dreamInstance.setAttribute(attr, value);
                 return dreamInstance.getAttribute(attr);
             }
             else {
@@ -2903,13 +2981,47 @@ export default class Dream {
      * bypassing any custom-defined setters. If you would like to set attributes
      * without bypassing custom-defined setters, use #assignAttribute instead
      *
+     * An `@Encrypted` backing column (e.g. `encryptedSecret`) accepts only
+     * a string of ciphertext that decrypts with this app's column encryption
+     * keys (current or legacy), or `null`, which clears it. Anything else,
+     * including plaintext, `undefined`, a non-string value, and ciphertext
+     * made with a key this app does not hold, throws and leaves the column
+     * unchanged. The check covers the backing columns of this model's class,
+     * including those it inherits from an STI parent; a backing column
+     * declared only by another class in the same STI hierarchy is not
+     * checked.
+     *
+     * Given the name of an encrypted property (e.g. `secret`), setAttribute
+     * neither encrypts the value nor stores it: it keeps the value,
+     * unencrypted, under that name in this instance's attributes, which a
+     * save does not write, while the backing column and the property keep
+     * the value they had. To store a new value, assign the property
+     * (`user.secret = 'new secret'`) or pass it to
+     * {@link Dream.setAttributes | setAttributes}, each of which encrypts it.
+     *
      * ```ts
      *  const user = new User()
      *  user.setAttribute('email', 'sally@gmail.com')
      * ```
      */
     setAttribute(column, val) {
-        ;
+        const dreamClass = this.constructor;
+        const encryptedAttribute = dreamClass.encryptedAttributes.find(({ encryptedColumnName }) => encryptedColumnName === column);
+        if (encryptedAttribute &&
+            val !== null &&
+            !(typeof val === 'string' && InternalEncrypt.isDecryptableColumnCiphertext(val)))
+            throw new DoNotSetEncryptedFieldsDirectly(dreamClass, column, encryptedAttribute.property);
+        this.setAttributeUnchecked(column, val);
+    }
+    /**
+     * @internal
+     *
+     * Writes the value into the current attributes as given, with none of
+     * setAttribute's checks. Only for values Dream already trusts: a row read
+     * from the database, and the ciphertext the @Encrypted property setter
+     * has just produced. Every caller-supplied value goes through setAttribute.
+     */
+    setAttributeUnchecked(column, val) {
         this.currentAttributes[column] = val;
     }
     /**
@@ -2946,9 +3058,8 @@ export default class Dream {
      * being persisted to the database, with the values
      * that were last persisted to the database.
      *
-     * On a record that has not been persisted, every
-     * column counts as changed: the object has a key
-     * for every column.
+     * On a record that has not been persisted, only columns
+     * with values other than `undefined` count as changed.
      *
      * ```ts
      *  const user = User.new({ email: 'original@email', password: 'howyadoin' })
@@ -2978,43 +3089,55 @@ export default class Dream {
      * changed since last persisting, along with their current
      * and previously persisted values.
      *
+     * For a column with an unsaved change, `was` is its value
+     * as of the most recent save. For every other column, `was`
+     * is its value from before that save, so the changes the
+     * save made keep appearing, beside any later unsaved change,
+     * until the next save.
+     *
+     * On a create, that earlier value is `undefined` for every
+     * column of an instance from `new` or `create`, assigned or
+     * not, and the copied value for an instance from
+     * {@link Dream.dup | dup}. So after a create from `new` or
+     * `create`, every column the insert returned counts as
+     * changed: the primary key, timestamps, database defaults,
+     * and `null` for each nullable column nobody assigned. After
+     * a create from `dup`, the columns `dup` cleared (the primary
+     * key, timestamps and sortable positions) count, and a copied
+     * column counts only if the insert returned a different value.
+     *
      * ```ts
      * const pet = Pet.new({ species: 'dog' })
      * pet.changes()
      * // {
-     * //   species: {
-     * //     was: undefined,
-     * //     now: 'dog',
-     * //   }
+     * //   species: { was: undefined, now: 'dog' },
      * // }
      *
      * await pet.save()
      * pet.changes()
      * // {
-     * //   species: {
-     * //     was: undefined,
-     * //     now: 'dog',
-     * //   }
+     * //   id: { was: undefined, now: 1 },
+     * //   species: { was: undefined, now: 'dog' },
+     * //   name: { was: undefined, now: null },
+     * //   ...every other column the insert returned
      * // }
      *
      * pet.species = 'cat'
      * pet.species = 'frog'
      * pet.changes()
      * // {
-     * //   species: {
-     * //     was: 'dog',
-     * //     now: 'frog',
-     * //   }
+     * //   id: { was: undefined, now: 1 },
+     * //   species: { was: 'dog', now: 'frog' },
+     * //   name: { was: undefined, now: null },
+     * //   ...every other change the create made
      * // }
      *
      * await pet.save()
      * pet.changes()
      * // {
-     * //   species: {
-     * //     was: 'dog',
-     * //     now: 'frog',
-     * //   }
+     * //   species: { was: 'dog', now: 'frog' },
      * // }
+     * // (and `updatedAt`, on a model with that column)
      * ```
      *
      * @returns An object containing changed attributes
@@ -3030,8 +3153,22 @@ export default class Dream {
         return obj;
     }
     /**
-     * Returns the value most recently persisted
-     * to the database.
+     * Returns the value the column held before the most
+     * recent save. For a column with an unsaved change, it
+     * returns the column's value as of that save instead.
+     *
+     * On a create, the value before the save is `undefined`
+     * for every column of an instance from `new` or `create`,
+     * assigned or not, and the copied value for an instance
+     * from {@link Dream.dup | dup} (`undefined` for the
+     * columns `dup` cleared). So after a create from `new` or
+     * `create`, this returns `undefined` for every column
+     * without an unsaved change, not the value the insert
+     * wrote. After an update, it returns the column's value
+     * from before that update, which for a column the update
+     * did not change is its current value. On a record loaded
+     * from the database and not saved since, it returns the
+     * loaded value.
      *
      * ```ts
      * const pet = Pet.new({ species: 'cat' })
@@ -3066,24 +3203,54 @@ export default class Dream {
     /**
      * Returns true if the columnName provided has
      * changes that were persisted during the most
-     * recent save.
+     * recent save. An unsaved change does not count,
+     * and an unsaved edit made after that save does
+     * not undo a change the save made. On a record
+     * that has not been persisted, this returns false.
+     *
+     * A create compares the value the insert returned
+     * with `undefined` for every column of an instance
+     * from `new` or `create`, assigned or not, and with
+     * the copied value for an instance from
+     * {@link Dream.dup | dup}. So after a create from
+     * `new` or `create`, this returns true for every
+     * column the insert returned: the primary key,
+     * timestamps, database defaults, and a nullable
+     * column nobody assigned, which comes back `null`.
+     * To react only to the columns a create assigned,
+     * use the `ifChanged` option of an after hook.
+     *
+     * ```ts
+     * const pet = await Pet.create({ species: 'cat' })
+     * pet.savedChangeToAttribute('species')
+     * // true
+     * pet.savedChangeToAttribute('name')
+     * // true (unassigned, so the insert returned null)
+     *
+     * await pet.update({ name: 'Snoopy' })
+     * pet.savedChangeToAttribute('species')
+     * // false
+     *
+     * pet.species = 'dog'
+     * pet.savedChangeToAttribute('species')
+     * // false (not saved yet)
+     * ```
      *
      * @param columnName - the column name to check
      * @returns A boolean
      */
     savedChangeToAttribute(columnName) {
-        const changes = this.changes();
-        const was = changes?.[columnName]?.was;
-        const now = changes?.[columnName]?.now;
-        return this.isPersisted && notEqual(now, was);
+        if (!this.isPersisted)
+            return false;
+        return notEqual(this.attributesFromBeforeLastSave[columnName], this.frozenAttributes[columnName]);
     }
     /**
      * Returns true if the columnName provided has
      * changes that have not yet been persisted.
      *
-     * On a record that has not been persisted, every
-     * column counts as changed, so this returns true
-     * for every column, whether or not it was assigned.
+     * On a record that has not been persisted, this returns
+     * true only for a column with a value other than `undefined`.
+     * An explicit `null` counts as a change.
      *
      * @param attribute - the column name to check
      * @returns A boolean
@@ -3104,15 +3271,14 @@ export default class Dream {
      * of columns that have changed since last persist,
      * and their current values.
      *
-     * On a record that has not been persisted, every
-     * column counts as changed: the object has a key
-     * for every column, including those never assigned,
-     * whose value is `undefined`.
+     * On a record that has not been persisted, the object
+     * contains only columns with values other than `undefined`.
+     * An explicit `null` is included.
      *
      * ```ts
      *  const user = User.new({ email: 'hello@world' })
      *  user.dirtyAttributes()
-     *  // { id: undefined, email: 'hello@world', name: undefined, ...every other column: undefined }
+     *  // { email: 'hello@world' }
      *
      *  await user.save()
      *
@@ -3146,7 +3312,7 @@ export default class Dream {
      */
     attributeIsDirty(attribute) {
         if (this.isNewRecord)
-            return true;
+            return this.getAttribute(attribute) !== undefined;
         return !areEqual(this.frozenAttributes[attribute], this.getAttribute(attribute));
     }
     /**
@@ -3308,7 +3474,7 @@ export default class Dream {
      * deleting their corresponding records within the database.
      *
      * ```ts
-     * await user.destroyAssociation('posts', { body: 'hello world' })
+     * await user.destroyAssociation('posts', { and: { body: 'hello world' } })
      * ```
      *
      * @param associationName - The name of the association to destroy
@@ -3323,6 +3489,7 @@ export default class Dream {
      * @returns The number of records deleted
      */
     async destroyAssociation(associationName, options) {
+        assertRecognizedAssociationConditionKeys(options, DESTROY_ASSOCIATION_OPTION_KEYS, associationName, 'destroyAssociation');
         if (this.isNewRecord)
             throw new CannotDestroyAssociationOnUnpersistedDream(this, associationName);
         return await destroyAssociation(this, null, associationName, {
@@ -3344,7 +3511,7 @@ export default class Dream {
      * causing those records to be deleted from the database.
      *
      * ```ts
-     * await user.reallyDestroyAssociation('posts', { body: 'hello world' })
+     * await user.reallyDestroyAssociation('posts', { and: { body: 'hello world' } })
      * ```
      *
      * @param associationName - The name of the association to destroy
@@ -3359,6 +3526,7 @@ export default class Dream {
      * @returns The number of records deleted
      */
     async reallyDestroyAssociation(associationName, options) {
+        assertRecognizedAssociationConditionKeys(options, DESTROY_ASSOCIATION_OPTION_KEYS, associationName, 'reallyDestroyAssociation');
         if (this.isNewRecord)
             throw new CannotDestroyAssociationOnUnpersistedDream(this, associationName);
         return await destroyAssociation(this, null, associationName, {
@@ -3377,7 +3545,7 @@ export default class Dream {
      * will also be undeleted.
      *
      * ```ts
-     * await user.undestroyAssociation('posts', { body: 'hello world' })
+     * await user.undestroyAssociation('posts', { and: { body: 'hello world' } })
      * ```
      *
      * @param associationName - The name of the association to undestroy
@@ -3392,6 +3560,7 @@ export default class Dream {
      * @returns The number of records undestroyed
      */
     async undestroyAssociation(associationName, options) {
+        assertRecognizedAssociationConditionKeys(options, DESTROY_ASSOCIATION_OPTION_KEYS, associationName, 'undestroyAssociation');
         return await undestroyAssociation(this, null, associationName, {
             ...undestroyOptions(options),
             joinAndStatements: {
@@ -3424,8 +3593,8 @@ export default class Dream {
     }
     /**
      * Updates all records matching the association with
-     * the provided attributes. If a where statement is passed,
-     * The on statement will be applied to the query
+     * the provided attributes. If an and, andNot or andAny
+     * statement is passed, it will be applied to the query
      * before updating.
      *
      * ```ts
@@ -3437,14 +3606,17 @@ export default class Dream {
      *
      * @param associationName - The name of the association to update
      * @param attributes - The attributes to update on the association
-     * @param options - Options for updating the association
-     * @param options.and - Optional on statement to apply to query before updating
-     * @param options.skipHooks - If true, skips applying model hooks during the update operation. Defaults to false
-     * @param options.bypassAllDefaultScopes - If true, bypasses user-removable default scopes when updating the association; an STI child's reserved discriminator remains enforced, including when associations are loaded. Defaults to false
-     * @param options.defaultScopesToBypass - An array of default scope names to bypass when updating the association. Defaults to an empty array
+     * @param updateAssociationOptions - Options for updating the association
+     * @param updateAssociationOptions.and - Optional and statement to apply to query before updating
+     * @param updateAssociationOptions.andNot - Optional andNot statement to apply to query before updating
+     * @param updateAssociationOptions.andAny - Optional andAny statement to apply to query before updating
+     * @param updateAssociationOptions.skipHooks - If true, skips applying model hooks during the update operation. Defaults to false
+     * @param updateAssociationOptions.bypassAllDefaultScopes - If true, bypasses user-removable default scopes when updating the association; an STI child's reserved discriminator remains enforced, including when associations are loaded. Defaults to false
+     * @param updateAssociationOptions.defaultScopesToBypass - An array of default scope names to bypass when updating the association. Defaults to an empty array
      * @returns The number of updated records
      */
     async updateAssociation(associationName, attributes, updateAssociationOptions) {
+        assertRecognizedAssociationConditionKeys(updateAssociationOptions, UPDATE_ASSOCIATION_OPTION_KEYS, associationName, 'updateAssociation');
         if (this.isNewRecord)
             throw new CannotUpdateAssociationOnUnpersistedDream(this, associationName);
         return associationUpdateQuery(this, null, associationName, {
@@ -3510,19 +3682,19 @@ export default class Dream {
      * if the association is not already loaded.
      *
      * ```ts
-     * const user = await user
-     *  .load('posts', { body: ops.ilike('%hello world%') }, 'comments', 'replies')
+     * const loadedUser = await user
+     *  .load('posts', { and: { body: ops.ilike('%hello world%') } }, 'comments', 'replies')
      *  .load('images')
      *  .execute()
      *
-     * user.posts[0].comments[0].replies[0]
+     * loadedUser.posts[0].comments[0].replies[0]
      * // Reply{}
      *
-     * user.images[0]
+     * loadedUser.images[0]
      * // Image{}
      * ```
      *
-     * @param args - A list of associations (and optional where clauses) to load
+     * @param args - A chain of association names and and/andNot/andAny clauses
      * @returns A chainable LoadBuilder instance. Call `.execute()` to get the cloned model with associations loaded.
      */
     load(...args) {
@@ -3604,19 +3776,19 @@ export default class Dream {
      * 5. associations loading associations loading associations could result in exponential amounts of data; in those cases, `.load(...).findEach(...)` avoids instantiating massive amounts of data at once
      *
      * ```ts
-     * const user = await user
-     *  .leftJoinLoad('posts', { body: ops.ilike('%hello world%') }, 'comments', 'replies')
+     * const loadedUser = await user
+     *  .leftJoinLoad('posts', { and: { body: ops.ilike('%hello world%') } }, 'comments', 'replies')
      *  .leftJoinLoad('images')
      *  .execute()
      *
-     * user.posts[0].comments[0].replies[0]
+     * loadedUser.posts[0].comments[0].replies[0]
      * // Reply{}
      *
-     * user.images[0]
+     * loadedUser.images[0]
      * // Image{}
      * ```
      *
-     * @param args - A list of associations (and optional where clauses) to load
+     * @param args - A chain of association names and and/andNot/andAny clauses
      * @returns A chainable LeftJoinLoadBuilder instance. Call `.execute()` to get the cloned model with associations loaded.
      */
     leftJoinLoad(...args) {
@@ -3683,6 +3855,13 @@ export default class Dream {
      * Takes the attributes passed in and sets their values internally,
      * bypassing any custom setters defined for these attributes.
      *
+     * An encrypted property (e.g. `secret`) is still encrypted. Its
+     * `@Encrypted` backing column (e.g. `encryptedSecret`) accepts only
+     * ciphertext that decrypts with this app's column encryption keys, or
+     * `null`; anything else throws (see {@link Dream.setAttribute | setAttribute}).
+     * Attributes are set in order, so those before the rejected one have
+     * already been set when it throws.
+     *
      * NOTE:
      * To leverage custom-defined setters, use `#assignAttributes` instead.
      *
@@ -3713,6 +3892,10 @@ export default class Dream {
      * Upon updating an instance, the update timestamp (if defined)
      * will be updated on the model.
      *
+     * A column whose value is `undefined` is skipped, not written: a new
+     * record gets the column's database default, and a persisted record
+     * keeps the value stored for it. Set a column to `null` to clear it.
+     *
      * ```ts
      * const user = User.new({ email: 'how@yadoin' })
      * user.name = 'fred'
@@ -3760,6 +3943,12 @@ export default class Dream {
      * See {@link Dream.save | save} for details on
      * the side effects of saving.
      *
+     * A column whose value is still `undefined` after setters run is
+     * skipped, not written (see {@link Dream.save | save}), with two
+     * `@Encrypted` exceptions: `undefined` for an encrypted property (e.g.
+     * `secret`) is encrypted to `null`, so it clears the column, and
+     * `undefined` for its backing column (e.g. `encryptedSecret`) throws.
+     *
      * NOTE:
      * To bypass custom-defined setters, use {@link Dream.updateAttributes | updateAttributes} instead.
      *
@@ -3787,6 +3976,18 @@ export default class Dream {
      * See {@link Dream.save | save} for details on
      * the side effects of saving.
      *
+     * An encrypted property (e.g. `secret`) is still encrypted. Its
+     * `@Encrypted` backing column (e.g. `encryptedSecret`) accepts only
+     * ciphertext that decrypts with this app's column encryption keys, or
+     * `null`; anything else throws before anything is saved (see
+     * {@link Dream.setAttribute | setAttribute}).
+     *
+     * A column whose value is still `undefined` after setters run is
+     * skipped, not written (see {@link Dream.save | save}), with two
+     * `@Encrypted` exceptions: `undefined` for an encrypted property (e.g.
+     * `secret`) is encrypted to `null`, so it clears the column, and
+     * `undefined` for its backing column (e.g. `encryptedSecret`) throws.
+     *
      * NOTE:
      * To update the values without bypassing any custom-defined
      * setters, use {@link Dream.update | update} instead.