@rvoh/dream 2.35.0 → 2.36.1

package/dist/cjs/src/cli/index.js

@@ -68,44 +68,56 @@ function buildColumnsWithTypesDescription(belongsToDescription) {
     return `${baseColumnsWithTypesDescription}
 ${belongsToDescription}`;
 }
-const columnsWithTypesDescription = buildColumnsWithTypesDescription(`
+/**
+ * The `[columnsWithTypes...]` argument description for `g:model`. Exported so
+ * that spec/unit/cli/generateMigrationContent.spec.ts can run each
+ * `:belongs_to` example in this text through the migration generator and check
+ * the FK column the example's comment names: an example that drifts from what
+ * the generator actually produces then fails the suite instead of shipping.
+ */
+export const columnsWithTypesDescription = buildColumnsWithTypesDescription(`
 ${INDENT}
 ${INDENT}    - belongs_to:
 ${INDENT}        ALWAYS use this instead of adding a raw uuid column for foreign keys. It creates the FK column, adds a database index,
 ${INDENT}        AND generates the @deco.BelongsTo association and typed property on the model. A raw uuid column does none of this.
 ${INDENT}
-${INDENT}        use the fully qualified model name (matching its path under src/app/models/):
+${INDENT}        use the fully qualified model name (matching its path under src/app/models/). The last segment of that
+${INDENT}        path names the FK column, the typed FK property and the association:
 ${INDENT}          User:belongs_to                  # creates user_id column + BelongsTo association
-${INDENT}          Health/Coach:belongs_to           # creates health_coach_id column + BelongsTo association
+${INDENT}          Health/Coach:belongs_to           # creates coach_id column, coachId property, coach association
 ${INDENT}          User:belongs_to:optional          # nullable foreign key (for optional associations)
 ${INDENT}
-${INDENT}        rename the association with Model@alias — the snake_case alias drives the FK column name AND the
-${INDENT}        @deco.BelongsTo association + typed FK property on the generated model:
+${INDENT}        rename the association with Model@alias — the snake_case alias takes the last segment's place, naming the
+${INDENT}        FK column <alias>_id AND the @deco.BelongsTo association + typed FK property on the generated model:
 ${INDENT}          InternalUser@canceled_by:belongs_to:optional       # canceled_by_id column, canceledById property, canceledBy association,
 ${INDENT}                                                             #   @deco.BelongsTo('InternalUser', { on: 'canceledById', optional: true })
-${INDENT}          Messaging/Template@template:belongs_to             # template_id column, templateId property, template association
-${INDENT}                                                             #   (strips the namespace from the property/association names while keeping
-${INDENT}                                                             #   the namespaced model reference intact)
+${INDENT}          Health/Coach@health_coach:belongs_to               # health_coach_id column, healthCoachId property, healthCoach association,
+${INDENT}                                                             #   @deco.BelongsTo('Health/Coach', { on: 'healthCoachId' })
 ${INDENT}        Aliasing also lets you declare multiple FKs to the same model in one generator call without column collisions.`);
 export const columnsWithTypesDescriptionForStiChild = buildColumnsWithTypesDescription(`
 ${INDENT}
 ${INDENT}    - belongs_to:
 ${INDENT}        NOT supported for STI children. STI children cannot declare associations; declare all BelongsTo,
 ${INDENT}        HasOne, and HasMany associations on the STI parent model instead.`);
-const columnsWithTypesDescriptionForMigration = buildColumnsWithTypesDescription(`
+/**
+ * The `[columnsWithTypes...]` argument description for `g:migration`. Exported
+ * for the same `:belongs_to` example check as `columnsWithTypesDescription`.
+ */
+export const columnsWithTypesDescriptionForMigration = buildColumnsWithTypesDescription(`
 ${INDENT}
 ${INDENT}    - belongs_to:
 ${INDENT}        ALWAYS use this instead of adding a raw uuid column for foreign keys. It creates the FK column with an index.
 ${INDENT}        Unlike in g:model/g:resource, this does NOT add a BelongsTo association (no model is generated).
 ${INDENT}
-${INDENT}        use the fully qualified model name (matching its path under src/app/models/):
+${INDENT}        use the fully qualified model name (matching its path under src/app/models/). The last segment of that
+${INDENT}        path names the FK column:
 ${INDENT}          User:belongs_to                  # creates user_id column with index
-${INDENT}          Health/Coach:belongs_to           # creates health_coach_id column with index
+${INDENT}          Health/Coach:belongs_to           # creates coach_id column with index
 ${INDENT}          User:belongs_to:optional          # nullable foreign key
 ${INDENT}
-${INDENT}        rename the FK column with Model@alias (snake_case alias becomes the column name):
+${INDENT}        rename the FK column with Model@alias (the column is <alias>_id, with the alias snake_cased):
 ${INDENT}          InternalUser@canceled_by:belongs_to:optional       # canceled_by_id column with index
-${INDENT}          Messaging/Template@template:belongs_to             # template_id column (strips the namespace from the column name)`);
+${INDENT}          Health/Coach@health_coach:belongs_to               # health_coach_id column with index`);
 /**
  * The `<migrationName>` argument description for `g:migration`. Exported so
  * that spec/unit/helpers/cli/generateMigration.spec.ts can read the example
@@ -217,7 +229,7 @@ ${INDENT}  # STI parent model (use with g:sti-child for children)
 ${INDENT}  pnpm psy g:model --sti-base-serializer Room Place:belongs_to type:enum:room_types:Bathroom,Bedroom deleted_at:datetime:optional`)
             .option('--no-serializer', 'skip serializer generation. Useful for internal models that will never be serialized in an API response (e.g., join tables, audit logs)')
             .option('--connection-name <connectionName>', 'the name of the database connection to use for the model. Only needed for multi-database setups; defaults to "default"', 'default')
-            .option('--sti-base-serializer', `Creates generically typed base serializers (default and summary) that accept a \`StiChildClass\` parameter and include the \`type\` attribute with a per-child enum constraint. This allows consuming applications to determine the response shape based on the STI type discriminator.
+            .option('--sti-base-serializer', `Creates generically typed base serializers (summary and default, plus each Admin and Internal pair requested with --admin-serializers or --internal-serializers) that accept a \`StiChildClass\` parameter. When a \`type\` column is given, each summary serializer renders \`type\` right after \`id\`, with an OpenAPI enum of just the STI child's class name, and the default serializer inherits it from the summary. This allows consuming applications to determine the response shape based on the STI type discriminator.
 ${INDENT}
 ${INDENT}Use this when generating the parent model of an STI hierarchy. After generating the parent, use g:sti-child for each child type.
 ${INDENT}
@@ -255,9 +267,9 @@ ${INDENT}  Settings/CommunicationPreferences   # src/app/models/Settings/Communi
         program
             .command('generate:sti-child')
             .alias('g:sti-child')
-            .description(`Generates an STI (Single Table Inheritance) child model that extends an existing parent model. The child shares the parent's database table (discriminated by the \`type\` column) and can add child-specific columns. Generates a child model decorated with @STI(Parent), child serializers extending the parent's base serializers, a migration that ALTERs the parent table (not a new table), check constraints, a factory, and spec skeleton.
+            .description(`Generates an STI (Single Table Inheritance) child model that extends an existing parent model. The child shares the parent's database table (discriminated by the \`type\` column) and can add child-specific columns. Always generates the child model decorated with @STI(Parent), a factory, and a spec skeleton; unless --no-serializer is passed, also generates child serializers extending the parent's base serializers.
 ${INDENT}
-${INDENT}If the child declares no additional columns, only the model file is generated — no migration is created. STI children share the parent's table, so a no-columns child requires no schema change. Add a migration only by passing positional field:type args, in which case the generator emits one with the appropriate check constraint. STI children cannot declare associations — declare them on the parent model instead. The generator rejects belongs_to columns. STI children never receive @SoftDelete() — soft delete is enforced at the parent level only — and the generator does not accept --no-soft-delete.
+${INDENT}A migration is generated only when positional field:type args are passed. It ALTERs the parent's table (it does not create a new one), adds a check constraint requiring a value on this child's rows for each column that is not :optional, an array or a boolean, and goes in the migrations folder of the parent model's database connection, which the child shares. A child with no additional columns needs no schema change, so no migration is generated for it. STI children cannot declare associations — declare them on the parent model instead. The generator rejects belongs_to columns. STI children never receive @SoftDelete() — soft delete is enforced at the parent level only — and the generator does not accept --no-soft-delete.
 ${INDENT}
 ${INDENT}The parent must already exist (typically generated with g:model --sti-base-serializer or g:resource --sti-base-serializer).
 ${INDENT}
@@ -271,7 +283,6 @@ ${INDENT}
 ${INDENT}  # Child with no additional columns
 ${INDENT}  pnpm psy g:sti-child --model-name=Kitchen Room/Kitchen extends Room`)
             .option('--no-serializer', 'skip serializer generation. Useful if the child uses the parent serializer directly or serialization is handled elsewhere')
-            .option('--connection-name', 'the name of the database connection to use for the model. Only needed for multi-database setups; defaults to "default"', 'default')
             .option('--model-name <modelName>', `Explicit model class name to use instead of the one auto-derived from the model path. Useful when the path segments don't match the desired class name.
 ${INDENT}
 ${INDENT}Example:

package/dist/cjs/src/db/migration-helpers/DreamMigrationHelpers.js

@@ -1,6 +1,8 @@
 import { sql } from 'kysely';
+import defaultEncryptedColumnName from '../../encrypt/defaultEncryptedColumnName.js';
 import InternalEncrypt from '../../encrypt/InternalEncrypt.js';
 import DropEnumValueRetypeFailed, { quotedRelationName, } from '../../errors/DropEnumValueRetypeFailed.js';
+import snakeify from '../../helpers/snakeify.js';
 export default class DreamMigrationHelpers {
     /**
      * Rename a table and its associated primary key index and sequence.
@@ -49,8 +51,8 @@ export default class DreamMigrationHelpers {
         await this.dropConstraint(db, constraintName, { table });
         await sql `
     ALTER TABLE ${sql.table(table)}
-    ADD CONSTRAINT ${sql.table(constraintName)}
-      UNIQUE (${sql.raw(columns.join(', '))})
+    ADD CONSTRAINT ${sql.ref(constraintName)}
+      UNIQUE (${sql.join(columns.map(column => sql.ref(column)))})
       DEFERRABLE INITIALLY DEFERRED;
   `.execute(db);
     }
@@ -65,7 +67,7 @@ export default class DreamMigrationHelpers {
      * @param __namedParameters.value - The name of the value to add to the enum
      */
     static async addEnumValue(db, { enumName, value }) {
-        await sql `ALTER TYPE ${sql.raw(enumName)} ADD VALUE IF NOT EXISTS '${sql.raw(value)}';`.execute(db);
+        await sql `ALTER TYPE ${sql.ref(enumName)} ADD VALUE IF NOT EXISTS ${sql.lit(value)};`.execute(db);
     }
     /**
      * Create a database extension.
@@ -104,7 +106,7 @@ export default class DreamMigrationHelpers {
      */
     static async createGinIndex(db, indexName, { table, column }) {
         await sql `
-    CREATE INDEX IF NOT EXISTS ${sql.raw(indexName)} ON ${sql.raw(table)} USING GIN (${sql.raw(`${column} gin_trgm_ops`)});
+    CREATE INDEX IF NOT EXISTS ${sql.ref(indexName)} ON ${sql.table(table)} USING GIN (${sql.ref(column)} gin_trgm_ops);
   `.execute(db);
     }
     /**
@@ -120,7 +122,7 @@ export default class DreamMigrationHelpers {
      */
     static async dropConstraint(db, constraintName, { table }) {
         await sql `
-    ALTER TABLE ${sql.table(table)} DROP CONSTRAINT IF EXISTS ${sql.table(constraintName)};
+    ALTER TABLE ${sql.table(table)} DROP CONSTRAINT IF EXISTS ${sql.ref(constraintName)};
   `.execute(db);
     }
     /**
@@ -262,11 +264,11 @@ export default class DreamMigrationHelpers {
      * @param options - Configuration options
      * @param options.table - The name of the table
      * @param options.column - The current (plaintext) column name
-     * @param options.encryptedColumnName - The target encrypted column name. Defaults to `encrypted_<column>`, matching the `@Encrypted` decorator's default; pass this when the decorator was given a custom encrypted column name.
+     * @param options.encryptedColumnName - The target encrypted column name. Defaults to the column the `@Encrypted` decorator reads for a property named after `column` (`encrypted_phone` for `phone`); pass this when the decorator was given a custom encrypted column name.
      * @param options.primaryKey - The primary key column used to keyset-paginate and target each row's update. Defaults to `id`.
      * @param options.batchSize - How many rows to read per batch. Defaults to `1000`.
      */
-    static async encryptColumn(db, { table, column, encryptedColumnName = `encrypted_${column}`, primaryKey = 'id', batchSize = 1000, }) {
+    static async encryptColumn(db, { table, column, encryptedColumnName = snakeify(defaultEncryptedColumnName(column)), primaryKey = 'id', batchSize = 1000, }) {
         await db.schema.alterTable(table).renameColumn(column, encryptedColumnName).execute();
         await db.schema
             .alterTable(table)
@@ -301,12 +303,12 @@ export default class DreamMigrationHelpers {
      * @param options - Configuration options
      * @param options.table - The name of the table
      * @param options.column - The target (plaintext) column name to rename back to
-     * @param options.encryptedColumnName - The current encrypted column name. Defaults to `encrypted_<column>`.
+     * @param options.encryptedColumnName - The current encrypted column name. Defaults to the column the `@Encrypted` decorator reads for a property named after `column` (`encrypted_phone` for `phone`).
      * @param options.primaryKey - The primary key column used to keyset-paginate and target each row's update. Defaults to `id`.
      * @param options.batchSize - How many rows to read per batch. Defaults to `1000`.
      * @param options.columnType - When provided, the restored column is converted to this type. When omitted, the column is left as `text`.
      */
-    static async decryptColumn(db, { table, column, encryptedColumnName = `encrypted_${column}`, primaryKey = 'id', batchSize = 1000, columnType, }) {
+    static async decryptColumn(db, { table, column, encryptedColumnName = snakeify(defaultEncryptedColumnName(column)), primaryKey = 'id', batchSize = 1000, columnType, }) {
         await this.transformColumnInBatches(db, { table, column: encryptedColumnName, primaryKey, batchSize }, value => InternalEncrypt.decryptColumn(value));
         await db.schema.alterTable(table).renameColumn(encryptedColumnName, column).execute();
         if (columnType !== undefined) {
@@ -452,7 +454,7 @@ function constraintContextFor(byPosition, position) {
     return byPosition[position] ?? { relationResolved: false, checkConstraints: [] };
 }
 async function getEnumValues(db, enumName) {
-    const response = await sql `SELECT unnest(enum_range(NULL::${sql.raw(enumName)}))`.execute(db);
+    const response = await sql `SELECT unnest(enum_range(NULL::${sql.ref(enumName)}))`.execute(db);
     return response.rows.map(row => row.unnest);
 }
 // finds any records in the specified table
@@ -466,10 +468,10 @@ async function replaceArrayValues(db, value, tableAndColumnToChange) {
         .updateTable(table)
         .set({
         [column]: tableAndColumnToChange.behavior === 'remove'
-            ? sql.raw(`array_remove(${column}, '${value}')`)
-            : sql.raw(`array_replace(${column}, '${value}', '${tableAndColumnToChange.replaceWith}')`),
+            ? sql `array_remove(${sql.ref(column)}, ${value})`
+            : sql `array_replace(${sql.ref(column)}, ${value}, ${tableAndColumnToChange.replaceWith})`,
     })
-        .where(sql.raw(`'${value}'`), '=', sql.raw(`ANY(${column})`))
+        .where(sql `${value} = ANY(${sql.ref(column)})`)
         .execute();
 }
 // finds any records in the specified table
@@ -489,20 +491,20 @@ async function replaceNonArrayValues(db, value, tableAndColumnToChange) {
 async function updateTableColumnToNewEnumArrayType(db, enumName, tableAndColumnToChange) {
     const { table, column } = tableAndColumnToChange;
     await sql `
-    ALTER TABLE ${sql.raw(table)}
-    ALTER ${sql.raw(column)}
-    TYPE ${sql.raw(enumName)}[]
-    USING ${sql.raw(column)}::${sql.raw(enumName)}[];
+    ALTER TABLE ${sql.table(table)}
+    ALTER COLUMN ${sql.ref(column)}
+    TYPE ${sql.ref(enumName)}[]
+    USING ${sql.ref(column)}::${sql.ref(enumName)}[];
   `.execute(db);
 }
 // updates the table's targeted column to the newly-created enum
 async function updateTableColumnToNewEnumType(db, enumName, tableAndColumnToChange) {
     const { table, column } = tableAndColumnToChange;
     await sql `
-    ALTER TABLE ${sql.raw(table)}
-    ALTER ${sql.raw(column)}
-    TYPE ${sql.raw(enumName)}
-    USING ${sql.raw(column)}::${sql.raw(enumName)};
+    ALTER TABLE ${sql.table(table)}
+    ALTER COLUMN ${sql.ref(column)}
+    TYPE ${sql.ref(enumName)}
+    USING ${sql.ref(column)}::${sql.ref(enumName)};
   `.execute(db);
 }
 function computedTemporaryType(array) {

package/dist/cjs/src/decorators/Decorators.js

@@ -115,16 +115,38 @@ export default class Decorators {
      *
      *   // automatically sets `myEncryptedPhone` to the encrypted value that
      *   // `phone` is set to new/create/update, e.g., `await user.update({ phone })`
-     *   @deco.Encrypted('myEncryptedPhone)
+     *   @deco.Encrypted('myEncryptedPhone')
      *   public phone: string
+     *
+     *   // automatically sets `myEncryptedMfaSettings` to the encrypted value that
+     *   // `mfaSettings` is set to in new/create/update, and declares the
+     *   // value's OpenAPI shape, since it is not a string
+     *   @deco.Encrypted({
+     *     column: 'myEncryptedMfaSettings',
+     *     openapi: { type: ['object', 'null'], properties: { token: 'string' } },
+     *   })
+     *   public mfaSettings: { token: string } | null
      * }
      * ```
      *
-     * @param column — if omitted, then 'encrypted' is prepended to the Pascal cased version of the decorated field
+     * The decorated property may hold any JSON-serializable value. Its OpenAPI
+     * shape is what Psychic uses to cast the property in params and to render
+     * it in request body and serializer OpenAPI. Without an `openapi` option,
+     * that shape is `'string'`, or `['string', 'null']` when the backing column
+     * allows null. Pass `openapi` when the property holds a non-string value,
+     * such as an object, a number, or an array; it accepts any shape
+     * `@deco.Virtual` accepts. The declared shape is used exactly as given and
+     * replaces the nullability inferred from the backing column, so when the
+     * backing column allows null, include `'null'` in the shape, e.g.
+     * `type: ['object', 'null']`.
+     *
+     * @param columnOrOptions - Either the backing column's name, or an options object:
+     * - `column` — the backing column's name; if omitted, then 'encrypted' is prepended to the Pascal cased version of the decorated field
+     * - `openapi` — the OpenAPI shape of the decorated property's value; if omitted, the property's shape is a string (see above)
      * @returns An Encrypted decorator
      */
-    Encrypted(column) {
-        return Encrypted(column);
+    Encrypted(columnOrOptions) {
+        return Encrypted(columnOrOptions);
     }
     /**
      * The Scope decorator decorates a static method that accepts

package/dist/cjs/src/decorators/field/Encrypted.js

@@ -1,11 +1,18 @@
+import DreamApp from '../../dream-app/index.js';
+import defaultEncryptedColumnName from '../../encrypt/defaultEncryptedColumnName.js';
 import InternalEncrypt from '../../encrypt/InternalEncrypt.js';
 import DoNotSetEncryptedFieldsDirectly from '../../errors/DoNotSetEncryptedFieldsDirectly.js';
 import columnAllowsNull from '../../helpers/db/columnAllowsNull.js';
-import pascalize from '../../helpers/pascalize.js';
-export default function Encrypted(encryptedColumnName) {
+export default function Encrypted(columnOrOptions) {
+    const { column, openapi } = typeof columnOrOptions === 'string' ? { column: columnOrOptions } : (columnOrOptions ?? {});
     return function (_, context) {
         const key = context.name;
-        const encryptedKey = encryptedColumnName || `encrypted${pascalize(key)}`;
+        const encryptedKey = column || defaultEncryptedColumnName(key);
+        // records whose legacy-key listeners for this property are running; a
+        // read of the property on one of them returns its value without
+        // dispatching the event again, so a listener that reads the property
+        // does not recurse
+        const recordsDispatchingLegacyKeyUsed = new WeakSet();
         context.addInitializer(function () {
             const dreamClass = this.constructor;
             if (!dreamClass['globallyInitializingDecorators']) {
@@ -30,7 +37,7 @@ export default function Encrypted(encryptedColumnName) {
             ;
             dreamClass['virtualAttributes'].push({
                 property: key,
-                type: columnAllowsNull(dreamClass, encryptedKey) ? ['string', 'null'] : 'string',
+                type: openapi ?? (columnAllowsNull(dreamClass, encryptedKey) ? ['string', 'null'] : 'string'),
             });
             if (!Object.getOwnPropertyDescriptor(dreamClass, 'explicitUnsafeParamColumns')) {
                 // This pattern allows `explicitUnsafeParamColumns` on a base STI class and on
@@ -56,7 +63,22 @@ export default function Encrypted(encryptedColumnName) {
             const dreamPrototype = Object.getPrototypeOf(this);
             Object.defineProperty(dreamPrototype, key, {
                 get() {
-                    return InternalEncrypt.decryptColumn(this.getAttribute(encryptedKey));
+                    const dream = this;
+                    return InternalEncrypt.decryptColumn(this.getAttribute(encryptedKey), {
+                        onLegacyKeyUsed: () => {
+                            if (recordsDispatchingLegacyKeyUsed.has(dream))
+                                return;
+                            recordsDispatchingLegacyKeyUsed.add(dream);
+                            try {
+                                DreamApp.getOrFail().specialHooks.encryptionLegacyKeyUsed.forEach(fn => {
+                                    fn({ dream, property: key, encryptedColumnName: encryptedKey });
+                                });
+                            }
+                            finally {
+                                recordsDispatchingLegacyKeyUsed.delete(dream);
+                            }
+                        },
+                    });
                 },
                 set(val) {
                     /**
@@ -74,7 +96,14 @@ export default function Encrypted(encryptedColumnName) {
                      */
                     if (this.columnSetterGuardActivated)
                         return;
-                    this.setAttribute(encryptedKey, InternalEncrypt.encryptColumn(val));
+                    // On a persisted record, the ciphertext as loaded or last saved is
+                    // kept when the current key opens it to the assigned value, so
+                    // assigning a property the plaintext it already holds leaves the
+                    // record clean; any other value is encrypted fresh. Either way the
+                    // value is ciphertext Dream produced, so it bypasses setAttribute's
+                    // check that a backing column receives only decryptable ciphertext
+                    const dream = this;
+                    this.setAttributeUnchecked(encryptedKey, InternalEncrypt.reuseOrEncryptColumn(val, dream.isPersisted ? dream['frozenAttributes'][encryptedKey] : undefined));
                 },
                 configurable: false,
             });

package/dist/cjs/src/dream/DreamClassTransactionBuilder.js

@@ -498,12 +498,12 @@ export default class DreamClassTransactionBuilder {
      * 5. associations loading associations loading associations could result in exponential amounts of data; in those cases, `.preload(...).findEach(...)` avoids instantiating massive amounts of data at once
      *
      * ```ts
-     * const user = await User.txn(txn).leftJoinPreload('posts', 'comments', { visibilty: 'public' }, 'replies').first()
+     * const user = await User.txn(txn).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
      */
     leftJoinPreload(...args) {
@@ -521,13 +521,13 @@ export default class DreamClassTransactionBuilder {
      *
      * ```ts
      * await ApplicationModel.transaction(async txn => {
-     *   const user = await User.txn(txn).preload('posts', 'comments', { visibilty: 'public' }, 'replies').first()
+     *   const user = await User.txn(txn).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
      */
     preload(...args) {
@@ -591,7 +591,7 @@ export default class DreamClassTransactionBuilder {
      * })
      * ```
      *
-     * @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) {
@@ -607,7 +607,7 @@ export default class DreamClassTransactionBuilder {
      * })
      * ```
      *
-     * @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) {

package/dist/cjs/src/dream/DreamInstanceTransactionBuilder.js

@@ -3,6 +3,7 @@ import CannotCreateAssociationOnUnpersistedDream from '../errors/associations/Ca
 import CannotDestroyAssociationOnUnpersistedDream from '../errors/associations/CannotDestroyAssociationOnUnpersistedDream.js';
 import CannotUpdateAssociationOnUnpersistedDream from '../errors/associations/CannotUpdateAssociationOnUnpersistedDream.js';
 import RecordNotFound from '../errors/RecordNotFound.js';
+import assertRecognizedAssociationConditionKeys, { DESTROY_ASSOCIATION_OPTION_KEYS, UPDATE_ASSOCIATION_OPTION_KEYS, } from './internal/associations/assertRecognizedAssociationConditionKeys.js';
 import associationQuery from './internal/associations/associationQuery.js';
 import associationUpdateQuery from './internal/associations/associationUpdateQuery.js';
 import createAssociation from './internal/associations/createAssociation.js';
@@ -33,26 +34,29 @@ export default class DreamInstanceTransactionBuilder {
     /**
      * Loads the requested associations upon execution
      *
+     * **IMPORTANT:** `load().execute()` returns a **new clone** of the model with the
+     * associations loaded. It does NOT modify the original instance.
+     *
      * NOTE: {@link Dream#preload} is often a preferrable way of achieving the
      * same goal.
      *
      * ```ts
      * await ApplicationModel.transaction(async txn => {
-     *   await user
+     *   const loadedUser = await user
      *    .txn(txn)
-     *    .load('posts', { body: ops.ilike('%hello world%') }, 'comments', 'replies')
+     *    .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
      */
     load(...args) {
@@ -112,32 +116,34 @@ export default class DreamInstanceTransactionBuilder {
      * Load each specified association using a single SQL query.
      * See {@link #load} for loading in separate queries.
      *
-     * Note: since leftJoinPreload loads via single query, it has
-     * some downsides and that may be avoided using {@link #load}:
+     * **IMPORTANT:** Like `load()`, `leftJoinLoad().execute()` returns a **new clone** of the
+     * model with associations loaded. It does NOT modify the original instance.
+     *
+     * Note: since leftJoinLoad loads via single query, it has
+     * some downsides that may be avoided using {@link #load}:
      * 1. `limit` and `offset` will be automatically removed
      * 2. `through` associations will bring additional namespaces into the query that can conflict with through associations from other associations, creating an invalid query
-     * 3. each nested association will result in an additional record which duplicates data from the outer record. E.g., given `.leftJoinPreload('a', 'b', 'c')`, if each `a` has 10 `b` and each `b` has 10 `c`, then for one `a`, 100 records will be returned, each of which has all of the columns of `a`. `.load('a', 'b', 'c')` would perform three separate SQL queries, but the data for a single `a` would only be returned once.
+     * 3. each nested association will result in an additional record which duplicates data from the outer record. E.g., given `.leftJoinLoad('a', 'b', 'c')`, if each `a` has 10 `b` and each `b` has 10 `c`, then for one `a`, 100 records will be returned, each of which has all of the columns of `a`. `.load('a', 'b', 'c')` would perform three separate SQL queries, but the data for a single `a` would only be returned once.
      * 4. the individual query becomes more complex the more associations are included
      * 5. associations loading associations loading associations could result in exponential amounts of data; in those cases, `.load(...).findEach(...)` avoids instantiating massive amounts of data at once
-     * Loads the requested associations upon execution
-     *
-     * NOTE: {@link Dream#leftJoinPreload} is often a preferrable way of achieving the
-     * same goal.
      *
      * ```ts
-     * await user.txn(txn)
-     *  .leftJoinLoad('posts', { body: ops.ilike('%hello world%') }, 'comments', 'replies')
-     *  .leftJoinLoad('images')
-     *  .execute()
+     * await ApplicationModel.transaction(async txn => {
+     *   const loadedUser = await user
+     *    .txn(txn)
+     *    .leftJoinLoad('posts', { and: { body: ops.ilike('%hello world%') } }, 'comments', 'replies')
+     *    .leftJoinLoad('images')
+     *    .execute()
      *
-     * user.posts[0].comments[0].replies[0]
-     * // Reply{}
+     *   loadedUser.posts[0].comments[0].replies[0]
+     *   // Reply{}
      *
-     * user.images[0]
-     * // Image{}
+     *   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
      */
     leftJoinLoad(...args) {
@@ -153,7 +159,7 @@ export default class DreamInstanceTransactionBuilder {
      * })
      * ```
      *
-     * @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) {
@@ -169,7 +175,7 @@ export default class DreamInstanceTransactionBuilder {
      * })
      * ```
      *
-     * @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) {
@@ -252,6 +258,12 @@ export default class DreamInstanceTransactionBuilder {
      * 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.
      *
@@ -279,6 +291,18 @@ export default class DreamInstanceTransactionBuilder {
      * 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.
@@ -329,6 +353,10 @@ export default class DreamInstanceTransactionBuilder {
      * 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' })
      *
@@ -386,8 +414,8 @@ export default class DreamInstanceTransactionBuilder {
     }
     /**
      * Updates all records matching the association with
-     * the provided attributes. If a where statement is passed,
-     * The where 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
@@ -402,13 +430,16 @@ export default class DreamInstanceTransactionBuilder {
      * @param associationName - The name of the association to update
      * @param attributes - The attributes to update on the association
      * @param updateAssociationOptions - Options for updating the association
-     * @param updateAssociationOptions.where - Optional where statement to apply to query before updating
+     * @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.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
      * @param updateAssociationOptions.skipHooks - If true, skips applying model hooks during the update operation. Defaults to false
      * @returns The number of updated records
      */
     async updateAssociation(associationName, attributes, updateAssociationOptions) {
+        assertRecognizedAssociationConditionKeys(updateAssociationOptions, UPDATE_ASSOCIATION_OPTION_KEYS, associationName, 'updateAssociation');
         if (this.dreamInstance.isNewRecord)
             throw new CannotUpdateAssociationOnUnpersistedDream(this.dreamInstance, associationName);
         return await associationUpdateQuery(this.dreamInstance, this.dreamTransaction, associationName, {
@@ -465,6 +496,7 @@ export default class DreamInstanceTransactionBuilder {
      * @returns The number of records deleted
      */
     async destroyAssociation(associationName, options) {
+        assertRecognizedAssociationConditionKeys(options, DESTROY_ASSOCIATION_OPTION_KEYS, associationName, 'destroyAssociation');
         if (this.dreamInstance.isNewRecord)
             throw new CannotDestroyAssociationOnUnpersistedDream(this.dreamInstance, associationName);
         return await destroyAssociation(this.dreamInstance, this.dreamTransaction, associationName, {
@@ -503,6 +535,7 @@ export default class DreamInstanceTransactionBuilder {
      * @returns The number of records deleted
      */
     async reallyDestroyAssociation(associationName, options) {
+        assertRecognizedAssociationConditionKeys(options, DESTROY_ASSOCIATION_OPTION_KEYS, associationName, 'reallyDestroyAssociation');
         if (this.dreamInstance.isNewRecord)
             throw new CannotDestroyAssociationOnUnpersistedDream(this.dreamInstance, associationName);
         return await destroyAssociation(this.dreamInstance, this.dreamTransaction, associationName, {
@@ -521,7 +554,9 @@ export default class DreamInstanceTransactionBuilder {
      * will also be undeleted.
      *
      * ```ts
-     * await user.undestroyAssociation('posts', { and: { body: 'hello world' } })
+     * await ApplicationModel.transaction(async txn => {
+     *   await user.txn(txn).undestroyAssociation('posts', { and: { body: 'hello world' } })
+     * })
      * ```
      *
      * @param associationName - The name of the association to undestroy
@@ -536,6 +571,7 @@ export default class DreamInstanceTransactionBuilder {
      * @returns The number of records undestroyed
      */
     async undestroyAssociation(associationName, options) {
+        assertRecognizedAssociationConditionKeys(options, DESTROY_ASSOCIATION_OPTION_KEYS, associationName, 'undestroyAssociation');
         return await undestroyAssociation(this.dreamInstance, this.dreamTransaction, associationName, {
             ...undestroyOptions(options),
             joinAndStatements: {

package/dist/cjs/src/dream/LeftJoinLoadBuilder.js

@@ -28,13 +28,13 @@ export default class LeftJoinLoadBuilder {
         return this;
     }
     /**
-     * Attaches a load statement to the load builder
+     * Attaches a leftJoinLoad statement to the load builder
      *
      * ```ts
      * const user = await User.firstOrFail()
      * await user
-     *   .load('settings')
-     *   .load('posts', 'comments', 'replies', ['image', 'localizedText'])
+     *   .leftJoinLoad('settings')
+     *   .leftJoinLoad('posts', 'comments', 'replies', ['image', 'localizedText'])
      *   .execute()
      * ```
      */