@rvoh/dream 2.35.0 → 2.36.1

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;
@@ -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,41 @@ 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
+     * writes (freshly encrypted, or the ciphertext as loaded or last saved,
+     * which it keeps when that already holds the assigned plaintext). Every
+     * caller-supplied value goes through setAttribute.
+     */
+    private setAttributeUnchecked;
     /**
      * Returns the value for a columnName provided,
      * bypassing the getters.
@@ -2336,43 +2416,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
@@ -2382,8 +2474,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' })
@@ -2414,7 +2520,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
@@ -2642,19 +2779,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>;
@@ -2855,19 +2992,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>;
@@ -2929,6 +3066,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.
      *
@@ -2959,6 +3103,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'
@@ -3004,6 +3152,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.
      *
@@ -3027,6 +3181,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;

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

@@ -16,7 +16,20 @@ export type SpawnOptions = Omit<NodeSpawnOptions, 'shell'> & {
 };
 export declare const CLI_INDENT = "                  ";
 export declare const baseColumnsWithTypesDescription = "space separated snake-case properties like this:\n                      title:citext subtitle:string body_markdown:text style:enum:post_styles:formal,informal\n                  \n                  all properties default to not nullable; null can be allowed by appending ':optional':\n                      subtitle:string:optional\n                  \n                  supported types:\n                      - uuid:\n                      - uuid[]:\n                          a column optimized for storing UUIDs\n                  \n                      - citext:\n                      - citext[]:\n                          case insensitive text (indexes and queries are automatically case insensitive)\n                  \n                      - encrypted:\n                          encrypted text (used in conjunction with the @deco.Encrypted decorator)\n                  \n                      - string:\n                      - string[]:\n                          varchar; allowed length defaults to 255, but may be customized, e.g.: subtitle:string:128 or subtitle:string:128:optional\n                  \n                      - text\n                      - text[]\n                      - date\n                      - date[]\n                      - datetime\n                      - datetime[]\n                      - time\n                      - time[]\n                      - timetz\n                      - timetz[]\n                      - integer\n                      - integer[]\n                      - boolean\n                      - boolean[]\n                  \n                      - decimal:\n                      - decimal[]:\n                          precision,scale is required, e.g.: volume:decimal:3,2 or volume:decimal:3,2:optional\n                  \n                          leveraging arrays, add the \"[]\" suffix, e.g.: volume:decimal[]:3,2\n                  \n                      - enum:\n                      - enum[]:\n                          include the enum name to automatically create the enum:\n                            type:enum:room_types:bathroom,kitchen,bedroom or type:enum:room_types:bathroom,kitchen,bedroom:optional\n                  \n                          omit the enum values to leverage an existing enum (omits the enum type creation):\n                            type:enum:room_types or type:enum:room_types:optional\n                  \n                          leveraging arrays, add the \"[]\" suffix, e.g.: type:enum[]:room_types:bathroom,kitchen,bedroom";
+/**
+ * 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 declare const columnsWithTypesDescription: string;
 export declare const columnsWithTypesDescriptionForStiChild: string;
+/**
+ * The `[columnsWithTypes...]` argument description for `g:migration`. Exported
+ * for the same `:belongs_to` example check as `columnsWithTypesDescription`.
+ */
+export declare const columnsWithTypesDescriptionForMigration: string;
 /**
  * The `<migrationName>` argument description for `g:migration`. Exported so
  * that spec/unit/helpers/cli/generateMigration.spec.ts can read the example

package/dist/types/src/db/migration-helpers/DreamMigrationHelpers.d.ts

@@ -183,7 +183,7 @@ 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`.
      */
@@ -215,7 +215,7 @@ 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`.

package/dist/types/src/decorators/Decorators.d.ts

@@ -6,6 +6,7 @@ import { DreamColumnNames, GlobalModelNameTableMap, SortableOptions } from '../t
 import { AfterHookOpts, BeforeHookOpts } from '../types/lifecycle.js';
 import { OpenapiSchemaBodyShorthand, OpenapiShorthandPrimitiveTypes } from '../types/openapi.js';
 import { ValidationType } from '../types/validation.js';
+import { EncryptedOptions } from './field/Encrypted.js';
 export default class Decorators<TD extends typeof Dream, T extends Dream = InstanceType<TD>> {
     BelongsTo<const AssociationGlobalNameOrNames extends keyof GlobalModelNameTableMap<T> | (keyof GlobalModelNameTableMap<T>)[]>(this: Decorators<TD>, globalAssociationNameOrNames: AssociationGlobalNameOrNames, options?: NonPolymorphicBelongsToOptions<T, AssociationGlobalNameOrNames>): any;
     BelongsTo<const AssociationGlobalNameOrNames extends keyof GlobalModelNameTableMap<T> | (keyof GlobalModelNameTableMap<T>)[]>(this: Decorators<TD>, globalAssociationNameOrNames: AssociationGlobalNameOrNames, options?: PolymorphicBelongsToOptions<T, AssociationGlobalNameOrNames>): any;
@@ -29,15 +30,37 @@ export default class Decorators<TD extends typeof Dream, T extends Dream = Insta
      *
      *   // 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(this: Decorators<TD>, column?: DreamColumnNames<T>): any;
+    Encrypted(this: Decorators<TD>, columnOrOptions?: DreamColumnNames<T> | EncryptedOptions<DreamColumnNames<T>>): any;
     /**
      * The Scope decorator decorates a static method that accepts
      * and returns a Dream Query.

package/dist/types/src/decorators/field/Encrypted.d.ts

@@ -1,4 +1,9 @@
-export default function Encrypted(encryptedColumnName?: string): any;
+import { OpenapiSchemaBodyShorthand, OpenapiShorthandPrimitiveTypes } from '../../types/openapi.js';
+export default function Encrypted(columnOrOptions?: string | EncryptedOptions): any;
+export interface EncryptedOptions<ColumnName extends string = string> {
+    column?: ColumnName;
+    openapi?: OpenapiShorthandPrimitiveTypes | OpenapiSchemaBodyShorthand;
+}
 export interface EncryptedAttributeStatement {
     property: string;
     encryptedColumnName: string;

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

@@ -453,15 +453,15 @@ export default class DreamClassTransactionBuilder<DreamClass extends typeof Drea
      * 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<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], const Arr extends readonly unknown[], const LastArg extends VariadicLeftJoinLoadArgs<DreamInstance, DB, Schema, TableName, Arr>, const JoinedAssociationsCandidate = JoinedAssociationsTypeFromAssociations<DB, Schema, TableName, [
+    leftJoinPreload<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], const Arr extends readonly unknown[], const LastArg extends VariadicLeftJoinLoadArgs<DreamInstance, 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<DreamInstance>, JoinedAssociations>>(this: I, ...args: [...Arr, LastArg]): RetQuery;
@@ -477,13 +477,13 @@ export default class DreamClassTransactionBuilder<DreamClass extends typeof Drea
      *
      * ```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<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], const Arr extends readonly unknown[]>(this: I, ...args: [...Arr, VariadicLoadArgs<DreamInstance, DB, Schema, TableName, Arr>]): Query<DreamInstance, Readonly<{
@@ -561,10 +561,10 @@ export default class DreamClassTransactionBuilder<DreamClass extends typeof Drea
      * })
      * ```
      *
-     * @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 DreamClassTransactionBuilder<DreamClass, DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], const Arr extends readonly unknown[], const LastArg extends VariadicJoinsArgs<DreamInstance, DB, Schema, TableName, Arr>, const JoinedAssociationsCandidate = JoinedAssociationsTypeFromAssociations<DB, Schema, TableName, [
+    innerJoin<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], const Arr extends readonly unknown[], const LastArg extends VariadicJoinsArgs<DreamInstance, 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<DreamInstance>, JoinedAssociations>>(this: I, ...args: [...Arr, LastArg]): RetQuery;
@@ -578,10 +578,10 @@ export default class DreamClassTransactionBuilder<DreamClass extends typeof Drea
      * })
      * ```
      *
-     * @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 DreamClassTransactionBuilder<DreamClass, DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], const Arr extends readonly unknown[], const LastArg extends VariadicJoinsArgs<DreamInstance, DB, Schema, TableName, Arr>, const JoinedAssociationsCandidate = JoinedAssociationsTypeFromAssociations<DB, Schema, TableName, [
+    leftJoin<I extends DreamClassTransactionBuilder<DreamClass, DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], const Arr extends readonly unknown[], const LastArg extends VariadicJoinsArgs<DreamInstance, 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<DreamInstance>, JoinedAssociations>>(this: I, ...args: [...Arr, LastArg]): RetQuery;