@rvoh/dream 2.35.0 → 2.36.0

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;

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

@@ -21,26 +21,29 @@ export default class DreamInstanceTransactionBuilder<DreamInstance extends Dream
     /**
      * 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<I extends DreamInstanceTransactionBuilder<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>]): LoadBuilder<DreamInstance>;
@@ -96,32 +99,34 @@ export default class DreamInstanceTransactionBuilder<DreamInstance extends Dream
      * 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<I extends DreamInstanceTransactionBuilder<DreamInstance>, DB extends DreamInstance['DB'], TableName extends DreamInstance['table'], Schema extends DreamInstance['schema'], const Arr extends readonly unknown[]>(this: I, ...args: [...Arr, VariadicLeftJoinLoadArgs<DreamInstance, DB, Schema, TableName, Arr>]): LeftJoinLoadBuilder<DreamInstance>;
@@ -135,10 +140,10 @@ export default class DreamInstanceTransactionBuilder<DreamInstance extends Dream
      * })
      * ```
      *
-     * @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 DreamInstanceTransactionBuilder<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 DreamInstanceTransactionBuilder<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;
@@ -152,10 +157,10 @@ export default class DreamInstanceTransactionBuilder<DreamInstance extends Dream
      * })
      * ```
      *
-     * @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 DreamInstanceTransactionBuilder<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 DreamInstanceTransactionBuilder<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;
@@ -228,6 +233,12 @@ export default class DreamInstanceTransactionBuilder<DreamInstance extends 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.
      *
@@ -252,6 +263,18 @@ export default class DreamInstanceTransactionBuilder<DreamInstance extends 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.
@@ -297,6 +320,10 @@ export default class DreamInstanceTransactionBuilder<DreamInstance extends 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' })
      *

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

@@ -23,17 +23,17 @@ export default class LeftJoinLoadBuilder<DreamInstance extends Dream> {
     constructor(dream: Dream, dreamTransaction?: (DreamTransaction<any> | null) | undefined);
     passthrough<I extends LeftJoinLoadBuilder<DreamInstance>, PassthroughColumns extends PassthroughColumnNames<DreamInstance>>(this: I, passthroughWhereStatement: PassthroughOnClause<PassthroughColumns>): I;
     /**
-     * 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()
      * ```
      */
-    leftJoinLoad<I extends LeftJoinLoadBuilder<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>>(this: I, ...args: [...Arr, LastArg]): I;
+    leftJoinLoad<I extends LeftJoinLoadBuilder<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>>(this: I, ...args: [...Arr, LastArg]): I;
     /**
      * Executes the left-join load query, returning a **clone** of the original model
      * with all requested associations loaded. The original instance is not modified.

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

@@ -84,7 +84,7 @@ export default class LoadBuilder<DreamInstance extends Dream> {
      *   .execute()
      * ```
      *
-     * @param args - A list of associations (and optional where clauses) to load
+     * @param args - A chain of association names and and/andNot/andAny clauses to load
      * @returns A chainable LoadBuilder instance
      */
     load<I extends LoadBuilder<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>]): I;