@rvoh/dream 2.34.0 → 2.36.0

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

@@ -4,6 +4,7 @@ import Query from '../dream/Query.js';
 import DBClassDeprecation from '../helpers/cli/DBClassDeprecation.js';
 import generateDream from '../helpers/cli/generateDream.js';
 import EnvInternal from '../helpers/EnvInternal.js';
+import standardizeFullyQualifiedModelName from '../helpers/standardizeFullyQualifiedModelName.js';
 export default class DreamBin {
     static async sync(onSync, options) {
         if (!EnvInternal.isTest) {
@@ -58,6 +59,7 @@ export default class DreamBin {
         });
     }
     static async generateStiChild(fullyQualifiedModelName, fullyQualifiedParentName, columnsWithTypes, options) {
+        const connectionName = options.connectionName ?? stiParentConnectionName(fullyQualifiedModelName, fullyQualifiedParentName);
         await generateDream({
             fullyQualifiedModelName,
             columnsWithTypes,
@@ -65,6 +67,7 @@ export default class DreamBin {
                 includeAdminSerializers: options.adminSerializers ?? false,
                 includeInternalSerializers: options.internalSerializers ?? false,
                 ...options,
+                connectionName,
                 stiBaseSerializer: false,
                 // `@SoftDelete()` is incompatible with STI children — never auto-apply.
                 softDelete: false,
@@ -95,3 +98,13 @@ export default class DreamBin {
         DreamCLI.logger.logEndProgress();
     }
 }
+/**
+ * An STI child shares its parent's table, so its migration belongs to the
+ * parent model's connection.
+ */
+function stiParentConnectionName(fullyQualifiedModelName, fullyQualifiedParentName) {
+    const parentModel = DreamApp.getOrFail().models[standardizeFullyQualifiedModelName(fullyQualifiedParentName)];
+    if (!parentModel)
+        throw new Error(`Cannot generate the STI child ${fullyQualifiedModelName}: its parent, ${fullyQualifiedParentName}, is not one of the app models. The parent must already exist, and its name must match its path under the models directory (e.g. Health/Coach for Health/Coach.ts).`);
+    return parentModel.prototype.connectionName;
+}

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

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

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

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

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

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

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

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

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

@@ -498,12 +498,12 @@ export default class DreamClassTransactionBuilder {
      * 5. associations loading associations loading associations could result in exponential amounts of data; in those cases, `.preload(...).findEach(...)` avoids instantiating massive amounts of data at once
      *
      * ```ts
-     * const user = await User.txn(txn).leftJoinPreload('posts', 'comments', { visibilty: 'public' }, 'replies').first()
+     * const user = await User.txn(txn).leftJoinPreload('posts', 'comments', { and: { visibility: 'public' } }, 'replies').first()
      * console.log(user.posts[0].comments[0].replies)
      * // [Reply{id: 1}, Reply{id: 2}]
      * ```
      *
-     * @param args - A chain of association names and where clauses
+     * @param args - A chain of association names and and/andNot/andAny clauses
      * @returns A query for this model with the include statement applied
      */
     leftJoinPreload(...args) {
@@ -521,13 +521,13 @@ export default class DreamClassTransactionBuilder {
      *
      * ```ts
      * await ApplicationModel.transaction(async txn => {
-     *   const user = await User.txn(txn).preload('posts', 'comments', { visibilty: 'public' }, 'replies').first()
+     *   const user = await User.txn(txn).preload('posts', 'comments', { and: { visibility: 'public' } }, 'replies').first()
      *   console.log(user.posts[0].comments[0].replies)
      *   // [Reply{id: 1}, Reply{id: 2}]
      * })
      * ```
      *
-     * @param args - A chain of association names and where clauses
+     * @param args - A chain of association names and and/andNot/andAny clauses
      * @returns A query for this model with the preload statement applied
      */
     preload(...args) {
@@ -591,7 +591,7 @@ export default class DreamClassTransactionBuilder {
      * })
      * ```
      *
-     * @param args - A chain of association names and where clauses
+     * @param args - A chain of association names and and/andNot/andAny clauses
      * @returns A Query for this model with the inner join clause applied
      */
     innerJoin(...args) {
@@ -607,7 +607,7 @@ export default class DreamClassTransactionBuilder {
      * })
      * ```
      *
-     * @param args - A chain of association names and where clauses
+     * @param args - A chain of association names and and/andNot/andAny clauses
      * @returns A Query for this model with the left join clause applied
      */
     leftJoin(...args) {