@rvoh/dream 2.34.0 → 2.36.0

package/dist/esm/src/serializer/builders/ObjectSerializerBuilder.js

@@ -92,9 +92,10 @@ export default class ObjectSerializerBuilder {
      *     (e.g., delegating `'profile', 'avatarUrl'` with `as: 'avatar'` outputs the value
      *     under `avatar`)
      *   - `default` - Value to use when the target object or its attribute is null/undefined
-     *   - `optional` - Set to `true` to mark the value as nullable in the OpenAPI schema
-     *     (wraps the type in `anyOf: [schema, { type: 'null' }]`). OpenAPI-only — the
-     *     key is still rendered (as `null`)
+     *   - `optional` - Set to `true` to mark the value as nullable in the OpenAPI schema:
+     *     Psychic adds `null` to the rendered schema (e.g., `type: 'string'` becomes
+     *     `type: ['string', 'null']`, and a `$ref` becomes `anyOf: [{ $ref }, { type: 'null' }]`).
+     *     OpenAPI-only — the key is still rendered (as `null`)
      *   - `precision` - Round decimal values to the specified number of decimal places (0–9)
      *     during rendering; does not affect the OpenAPI shape
      *   - `required` - Set to `false` to omit the key from the rendered output when the
@@ -137,17 +138,23 @@ export default class ObjectSerializerBuilder {
      * Executes a callback function to generate a custom attribute value.
      * The `openapi` option is always required since the return type cannot be inferred.
      *
-     * Unlike DreamSerializerBuilder's `customAttribute`, this version does not support `as`
-     * or `precision`.
+     * The callback's return value renders as is, so any fallback belongs in the callback.
      *
      * @param name - The attribute name for the computed value
      * @param fn - Callback function that returns the computed value
      * @param options - Configuration options:
      *   - `openapi` - (required) OpenAPI schema definition for the computed value
-     *   - `default` - Value to use when the callback returns undefined
      *   - `flatten` - When `true`, spreads the returned object's properties directly into the
-     *     parent serialized output instead of nesting them under `name`; the `openapi` option
-     *     should then define each flattened property individually
+     *     parent serialized output instead of nesting them under `name`. The `openapi` option
+     *     then describes the whole returned object, not each property, because Psychic adds it
+     *     to the parent's schema as an `allOf` branch: either an object schema with full
+     *     property bodies (`type: 'object'`, `properties`, and `required` listing the keys that
+     *     are always present), or `{ $serializer: SomeSerializer }` when the callback returns
+     *     what that serializer renders. A serializer ref with `many: true` does not type-check
+     *     here, since a list has no properties to spread. A `null` or `undefined` return adds no
+     *     keys. Attributes render in declaration order, so a key the returned object shares with
+     *     another attribute takes the value of whichever is declared later; under the `allOf`,
+     *     that value must match both schemas
      *   - `required` - Set to `false` to mark the attribute as optional in the OpenAPI schema;
      *     when omitted, attributes are required by default
      * @returns The serializer builder for method chaining
@@ -160,12 +167,16 @@ export default class ObjectSerializerBuilder {
      *   { openapi: { type: 'string' } }
      * )
      *
-     * // Flattened object properties
+     * // Flattened object properties: `openapi` describes the whole returned object
      * .customAttribute('coordinates', () => ({ lat: 40.7, lng: -74.0 }), {
      *   flatten: true,
      *   openapi: {
-     *     lat: { type: 'number' },
-     *     lng: { type: 'number' }
+     *     type: 'object',
+     *     required: ['lat', 'lng'],
+     *     properties: {
+     *       lat: { type: 'number' },
+     *       lng: { type: 'number' }
+     *     }
      *   }
      * })
      * ```
@@ -189,9 +200,18 @@ export default class ObjectSerializerBuilder {
      * @param options - Configuration options:
      *   - `as` - Rename the association key in the serialized output
      *   - `flatten` - When `true`, spreads the rendered association's attributes directly into
-     *     the parent serialized output instead of nesting them under `name`. Be aware of
-     *     attribute shadowing: if the parent and flattened association share attribute names
-     *     (e.g., `id`), the flattened association's values overwrite the parent's
+     *     the parent serialized output instead of nesting them under `name`. Attributes render in
+     *     declaration order, so when the parent and the association share a key (e.g., `id`),
+     *     whichever is declared later wins: the association's value replaces an attribute declared
+     *     before the `rendersOne`, and an attribute declared after it replaces the association's.
+     *     When the association is `null`, every key its serializer declares renders as `null`
+     *     (for a polymorphic `BelongsTo`, every key the serializer of any of its target classes
+     *     declares, and for an association to an STI base, every key the serializer of any of its
+     *     STI children declares), in the same order (so an `id` declared before the `rendersOne` becomes
+     *     `null`); nothing in that serializer is rendered, so its custom attribute callbacks do
+     *     not run, and a flattened `customAttribute` in it adds no keys. Psychic adds the association's OpenAPI
+     *     schema to the parent's as an `allOf` branch, so a shared key's value must match both
+     *     schemas, whichever declaration wins
      *   - `optional` - When `true`, allows the association to be null/missing without causing
      *     an `OpenapiResponseValidationFailure` during Psychic controller unit specs. By default,
      *     `rendersOne` expects the association to be present (mirroring the `optional` option on

package/dist/esm/src/serializer/helpers/serializersForAssociatedClass.js

@@ -0,0 +1,43 @@
+import uniq from '../../helpers/uniq.js';
+import { inferSerializersFromDreamClassOrViewModelClass } from './inferSerializerFromDreamOrViewModel.js';
+/**
+ * Only used when flatten: true, and the associated object is null, in which case there is no
+ * object to resolve a serializer from, but the renderer still needs the serializers whose keys it
+ * renders as null in the parent's payload.
+ *
+ * Resolves, in order, to the `serializer` option, the serializers of the `dreamClass` or
+ * `viewModelClass` option, or the serializers of each class `parentClass` declares the association
+ * to: the one class of most associations, or every target class of a polymorphic BelongsTo. A
+ * class that is an STI base contributes the serializer of every one of its children, since the
+ * association renders with whichever child it holds when present. The renderer renders the union
+ * of all their keys, each key once. Returns no serializers when none applies, e.g. a
+ * non-association property without a `serializer` option, so the flattened association adds no
+ * keys.
+ */
+export function serializersForAssociatedClass(parentClass, associationName, options) {
+    if (options.serializer)
+        return [options.serializer];
+    const optionClass = options.dreamClass ?? options.viewModelClass;
+    let associatedClasses;
+    if (optionClass) {
+        associatedClasses = [optionClass];
+    }
+    else {
+        const association = parentClass?.['getAssociationMetadata'](associationName);
+        if (!association)
+            return [];
+        const modelClassOrClasses = association.modelCB();
+        associatedClasses = Array.isArray(modelClassOrClasses) ? modelClassOrClasses : [modelClassOrClasses];
+    }
+    // Every serializer of every class: one for a plain class, and one per child (sorted by
+    // sanitizedName) for an STI base, so the parent JSON carries the flattened keys of every child
+    // as nulls, as it carries those of every target class of a polymorphic BelongsTo. Several classes
+    // may resolve to the same serializer; the renderer walks each serializer once either way.
+    // (rendersMany never reaches here and does not accept `flatten`.)
+    return uniq(associatedClasses.flatMap(associatedClass => inferSerializersFromDreamClassOrViewModelClass(associatedClass, options.serializerKey, {
+        // Reached only from SerializerRenderer's rendersOne branch, so the edge type is fixed. No
+        // declaring serializer: the renderer holds the rendered attribute, not the serializer that
+        // declared it.
+        edge: { type: 'rendersOne', associationName },
+    })));
+}

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

@@ -1063,6 +1063,47 @@ export default class Dream {
      * @returns void
      */
     static findEach<T extends typeof Dream>(this: T, cb: (instance: InstanceType<T>) => void | Promise<void>, opts?: FindEachOpts): Promise<void>;
+    /**
+     * 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 reencryptEncryptedColumns<T extends typeof Dream>(this: T, opts?: FindEachOpts): Promise<void>;
     /**
      * Returns a new instance of Query scoped to the given
      * model class. Especially useful with {@link Query#toKysely}.
@@ -1174,15 +1215,15 @@ 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<T extends typeof Dream, I extends InstanceType<T>, DB extends I['DB'], TableName extends InstanceType<T>['table'], Schema extends I['schema'], const Arr extends readonly unknown[], const LastArg extends VariadicLeftJoinLoadArgs<I, DB, Schema, TableName, Arr>, const JoinedAssociationsCandidate = JoinedAssociationsTypeFromAssociations<DB, Schema, TableName, [
+    static leftJoinPreload<T extends typeof Dream, I extends InstanceType<T>, DB extends I['DB'], TableName extends InstanceType<T>['table'], Schema extends I['schema'], const Arr extends readonly unknown[], const LastArg extends VariadicLeftJoinLoadArgs<I, DB, Schema, TableName, Arr, LastArg>, const JoinedAssociationsCandidate = JoinedAssociationsTypeFromAssociations<DB, Schema, TableName, [
         ...Arr,
         LastArg
     ]>, const JoinedAssociations extends readonly JoinedAssociation[] = JoinedAssociationsCandidate extends readonly JoinedAssociation[] ? JoinedAssociationsCandidate : never, RetQuery = QueryWithJoinedAssociationsTypeAndNoPreload<Query<I>, JoinedAssociations>>(this: T, ...args: [...Arr, LastArg]): RetQuery;
@@ -1197,12 +1238,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<T extends typeof Dream, I extends InstanceType<T>, DB extends I['DB'], TableName extends InstanceType<T>['table'], Schema extends I['schema'], const Arr extends readonly unknown[]>(this: T, ...args: [...Arr, VariadicLoadArgs<I, DB, Schema, TableName, Arr>]): Query<InstanceType<T>, Readonly<{
@@ -1276,10 +1317,10 @@ 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<T extends typeof Dream, I extends InstanceType<T>, DB extends I['DB'], Schema extends I['schema'], TableName extends I['table'] & keyof Schema, const Arr extends readonly unknown[], const LastArg extends VariadicJoinsArgs<I, DB, Schema, TableName, Arr>, const JoinedAssociationsCandidate = JoinedAssociationsTypeFromAssociations<DB, Schema, TableName, [
+    static innerJoin<T extends typeof Dream, I extends InstanceType<T>, DB extends I['DB'], Schema extends I['schema'], TableName extends I['table'] & keyof Schema, const Arr extends readonly unknown[], const LastArg extends VariadicJoinsArgs<I, DB, Schema, TableName, Arr, LastArg>, const JoinedAssociationsCandidate = JoinedAssociationsTypeFromAssociations<DB, Schema, TableName, [
         ...Arr,
         LastArg
     ]>, const JoinedAssociations extends readonly JoinedAssociation[] = JoinedAssociationsCandidate extends readonly JoinedAssociation[] ? JoinedAssociationsCandidate : never, RetQuery = QueryWithJoinedAssociationsType<Query<I>, JoinedAssociations>>(this: T, ...args: [...Arr, LastArg]): RetQuery;
@@ -1291,10 +1332,10 @@ 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<I extends Dream, DB extends I['DB'], Schema extends I['schema'], TableName extends I['table'] & keyof Schema, const Arr extends readonly unknown[], const LastArg extends VariadicJoinsArgs<I, DB, Schema, TableName, Arr>, const JoinedAssociationsCandidate = JoinedAssociationsTypeFromAssociations<DB, Schema, TableName, [
+    innerJoin<I extends Dream, DB extends I['DB'], Schema extends I['schema'], TableName extends I['table'] & keyof Schema, const Arr extends readonly unknown[], const LastArg extends VariadicJoinsArgs<I, DB, Schema, TableName, Arr, LastArg>, const JoinedAssociationsCandidate = JoinedAssociationsTypeFromAssociations<DB, Schema, TableName, [
         ...Arr,
         LastArg
     ]>, const JoinedAssociations extends readonly JoinedAssociation[] = JoinedAssociationsCandidate extends readonly JoinedAssociation[] ? JoinedAssociationsCandidate : never, RetQuery = QueryWithJoinedAssociationsType<Query<I>, JoinedAssociations>>(this: I, ...args: [...Arr, LastArg]): RetQuery;
@@ -1306,10 +1347,10 @@ 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<T extends typeof Dream, I extends InstanceType<T>, DB extends I['DB'], Schema extends I['schema'], TableName extends I['table'] & keyof Schema, const Arr extends readonly unknown[], const LastArg extends VariadicJoinsArgs<I, DB, Schema, TableName, Arr>, const JoinedAssociationsCandidate = JoinedAssociationsTypeFromAssociations<DB, Schema, TableName, [
+    static leftJoin<T extends typeof Dream, I extends InstanceType<T>, DB extends I['DB'], Schema extends I['schema'], TableName extends I['table'] & keyof Schema, const Arr extends readonly unknown[], const LastArg extends VariadicJoinsArgs<I, DB, Schema, TableName, Arr, LastArg>, const JoinedAssociationsCandidate = JoinedAssociationsTypeFromAssociations<DB, Schema, TableName, [
         ...Arr,
         LastArg
     ]>, const JoinedAssociations extends readonly JoinedAssociation[] = JoinedAssociationsCandidate extends readonly JoinedAssociation[] ? JoinedAssociationsCandidate : never, RetQuery = QueryWithJoinedAssociationsType<Query<I>, JoinedAssociations>>(this: T, ...args: [...Arr, LastArg]): RetQuery;
@@ -1321,10 +1362,10 @@ 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<I extends Dream, DB extends I['DB'], Schema extends I['schema'], TableName extends I['table'] & keyof Schema, const Arr extends readonly unknown[], const LastArg extends VariadicJoinsArgs<I, DB, Schema, TableName, Arr>, const JoinedAssociationsCandidate = JoinedAssociationsTypeFromAssociations<DB, Schema, TableName, [
+    leftJoin<I extends Dream, DB extends I['DB'], Schema extends I['schema'], TableName extends I['table'] & keyof Schema, const Arr extends readonly unknown[], const LastArg extends VariadicJoinsArgs<I, DB, Schema, TableName, Arr, LastArg>, const JoinedAssociationsCandidate = JoinedAssociationsTypeFromAssociations<DB, Schema, TableName, [
         ...Arr,
         LastArg
     ]>, const JoinedAssociations extends readonly JoinedAssociation[] = JoinedAssociationsCandidate extends readonly JoinedAssociation[] ? JoinedAssociationsCandidate : never, RetQuery = QueryWithJoinedAssociationsType<Query<I>, JoinedAssociations>>(this: I, ...args: [...Arr, LastArg]): RetQuery;
@@ -1900,8 +1941,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' })
@@ -2165,6 +2206,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<T extends typeof Dream>(this: T, opts?: UpdateablePropertiesForClass<T>, additionalOpts?: {
@@ -2189,6 +2239,7 @@ export default class Dream {
      */
     constructor(opts: any, additionalOpts: {
         bypassUserDefinedSetters?: boolean;
+        fromDatabase?: boolean;
         isPersisted?: boolean;
         _internalUseOnly: true;
     });
@@ -2276,12 +2327,39 @@ 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<I extends Dream, Key extends AttributeKeys<I>>(this: I, column: Key & string, val: any): void;
+    /**
+     * @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.
+     */
+    private setAttributeUnchecked;
     /**
      * Returns the value for a columnName provided,
      * bypassing the getters.
@@ -2312,9 +2390,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' })
@@ -2337,43 +2414,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
@@ -2383,8 +2472,22 @@ export default class Dream {
         now: Selectable<Table>[DreamColumnNames<I>];
     }>>>(this: I): RetType;
     /**
-     * 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' })
@@ -2415,7 +2518,38 @@ 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
@@ -2425,9 +2559,9 @@ export default class Dream {
      * 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
@@ -2444,15 +2578,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()
      *
@@ -2644,19 +2777,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<I extends Dream, DB extends I['DB'], TableName extends I['table'], Schema extends I['schema'], const Arr extends readonly unknown[]>(this: I, ...args: [...Arr, VariadicLoadArgs<I, DB, Schema, TableName, Arr>]): LoadBuilder<I>;
@@ -2857,19 +2990,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<I extends Dream, DB extends I['DB'], TableName extends I['table'], Schema extends I['schema'], const Arr extends readonly unknown[]>(this: I, ...args: [...Arr, VariadicLeftJoinLoadArgs<I, DB, Schema, TableName, Arr>]): LeftJoinLoadBuilder<I>;
@@ -2931,6 +3064,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.
      *
@@ -2961,6 +3101,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'
@@ -3006,6 +3150,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.
      *
@@ -3029,6 +3179,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.

package/dist/types/src/bin/index.d.ts

@@ -21,7 +21,13 @@ export default class DreamBin {
     }): Promise<void>;
     static generateStiChild(fullyQualifiedModelName: string, fullyQualifiedParentName: string, columnsWithTypes: string[], options: {
         serializer: boolean;
-        connectionName: string;
+        /**
+         * The connection whose migrations folder receives the child's
+         * migration. Defaults to the parent model's connection, which is the
+         * connection the child uses; the parent must then be one of the app's
+         * models, or this throws before any file is written.
+         */
+        connectionName?: string;
         adminSerializers?: boolean;
         internalSerializers?: boolean;
         modelName?: string;