@rvoh/dream 2.28.0 → 2.28.2

package/dist/cjs/src/Dream.js

@@ -273,6 +273,15 @@ export default class Dream {
      * assignment simply ensures that it is always an array rather than undefined)
      */
     static explicitUnsafeParamColumns = Object.freeze([]);
+    /**
+     * @internal
+     *
+     * Model storage for encrypted attribute metadata, set on the inheriting class when
+     * using the Encrypted decorator (this default assignment simply ensures that it is
+     * always an array rather than undefined,
+     * freezing ensures that we never modify the static array on the inherited Dream class)
+     */
+    static encryptedAttributes = Object.freeze([]);
     /**
      * @internal
      *
@@ -367,6 +376,23 @@ export default class Dream {
     static get isSTIBase() {
         return !!this.extendedBy?.length && !this.isSTIChild;
     }
+    /**
+     * @internal
+     *
+     * This class together with every STI class below it, however deeply nested. These
+     * are the classes whose rows a query rooted at this class can reach, since an STI
+     * child's rows are a subset of its base's.
+     *
+     * The classes *above* this one are deliberately excluded, as are its siblings: a
+     * column that only a sibling declares is meaningless for the rows this class
+     * matches, so treating it as this class's business protects nothing and costs a
+     * wider walk on every call.
+     *
+     * @returns An array of Dream classes
+     */
+    static selfAndStiDescendants() {
+        return [this, ...(this.extendedBy ?? []).flatMap(dreamClass => dreamClass.selfAndStiDescendants())];
+    }
     static stiSiblings() {
         const stiBase = this.stiBaseClassOrOwnClass;
         if (!stiBase.isSTIBase)
@@ -691,6 +717,10 @@ export default class Dream {
         return defaultParams;
     }
     static defaultParamSafeColumns() {
+        // `columns()` is table scoped, so it offers this class every column of the shared
+        // STI table, including those an STI child marks unsafe. A column unsafe for a child
+        // is unsafe here, because a query rooted at this class reaches that child's rows.
+        const explicitUnsafeParamColumns = new Set(this.selfAndStiDescendants().flatMap(dreamClass => [...dreamClass.explicitUnsafeParamColumns]));
         const columns = [...this.columns()].filter(column => {
             if (this.prototype._primaryKey === column)
                 return false;
@@ -700,7 +730,7 @@ export default class Dream {
                 return false;
             if (this.prototype._deletedAtField === column)
                 return false;
-            if (this.explicitUnsafeParamColumns.includes(column))
+            if (explicitUnsafeParamColumns.has(column))
                 return false;
             if (this.isBelongsToAssociationForeignKey(column, { includeStiSiblings: true }))
                 return false;

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

@@ -41,6 +41,18 @@ export default function Encrypted(encryptedColumnName) {
             }
             ;
             dreamClass['explicitUnsafeParamColumns'].push(encryptedKey);
+            if (!Object.getOwnPropertyDescriptor(dreamClass, 'encryptedAttributes')) {
+                // This pattern allows `encryptedAttributes` on a base STI class and on
+                // child STI classes. The new `encryptedAttributes` property will be created
+                // on the child STI class, but it will include all the `encryptedAttributes`
+                // already declared on the base STI class.
+                dreamClass['encryptedAttributes'] = [...dreamClass['encryptedAttributes']];
+            }
+            ;
+            dreamClass['encryptedAttributes'].push({
+                property: key,
+                encryptedColumnName: encryptedKey,
+            });
             const dreamPrototype = Object.getPrototypeOf(this);
             Object.defineProperty(dreamPrototype, key, {
                 get() {

package/dist/cjs/src/decorators/field/sortable/Sortable.js

@@ -47,6 +47,16 @@ export default function Sortable(opts = {}) {
                 // already declared on the base STI class.
                 dreamClass['sortableFields'] = [...dreamClass['sortableFields']];
             }
+            // an STI child inherits its base's sortable fields via the copy above, and
+            // the base's field initializers run again while the child is globally
+            // initialized, so without this guard the child registers a second config
+            // for the same position field whenever the base is initialized first
+            // (models are globally initialized in filesystem order). Every duplicate
+            // config repeats the child's position work on each save, so positions
+            // advance by the number of duplicates instead of by 1
+            if (dreamClass['sortableFields'].some(conf => conf.positionField === key)) {
+                return;
+            }
             // the decorator registers nothing but this metadata: none of a sortable
             // field's runtime work runs as hooks. A save's preparation and position
             // write run as phases in `saveDream` (`prepareSortableFieldsForSave`,

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

@@ -2,6 +2,7 @@ import { SOFT_DELETE_SCOPE_NAME } from '../decorators/class/SoftDelete.js';
 import acquireStabilizedSortableBatchLocks from '../decorators/field/sortable/helpers/acquireStabilizedSortableBatchLocks.js';
 import { invalidateSortableRowCache } from '../decorators/field/sortable/helpers/sortableRowCache.js';
 import DreamApp from '../dream-app/index.js';
+import assertNoEncryptedColumnWrites from '../encrypt/assertNoEncryptedColumnWrites.js';
 import AssociationDeclaredWithoutAssociatedDreamClass from '../errors/associations/AssociationDeclaredWithoutAssociatedDreamClass.js';
 import CannotCallUndestroyOnANonSoftDeleteModel from '../errors/CannotCallUndestroyOnANonSoftDeleteModel.js';
 import CannotPassAdditionalFieldsToPluckEachAfterCallback from '../errors/CannotPassAdditionalFieldsToPluckEachAfterCallback.js';
@@ -2056,7 +2057,7 @@ export default class Query {
         // truthiness, since a primary key of 0 is a legitimate cursor value that
         // would otherwise reset the window to the start of the set
         let lastId = undefined;
-        let attemptedCount = 0;
+        let attemptedCount;
         do {
             const batchQuery = lastId === undefined
                 ? orderedQuery
@@ -2188,7 +2189,7 @@ export default class Query {
      * use {@link Query.destroy} instead.
      *
      * ```ts
-     * await User.where({ email: ops.ilike('%burpcollaborator%').delete() })
+     * await User.where({ email: ops.ilike('%burpcollaborator%') }).delete()
      * // 12
      * ```
      *
@@ -2316,7 +2317,13 @@ export default class Query {
         }, sortableIncomingAttributes);
     }
     async updateWithoutCallingModelHooks(attributes) {
-        return await this.dbDriverInstance().update(attributes);
+        // the guard and the driver must read the same values, so the caller's object
+        // is materialized once here and both read the snapshot
+        const snapshot = { ...attributes };
+        // this path compiles to a single UPDATE statement and never instantiates a
+        // model, so the setter that encrypts an @Encrypted property never runs
+        assertNoEncryptedColumnWrites(this.dreamClass, snapshot);
+        return await this.dbDriverInstance().update(snapshot);
     }
     invertOrder() {
         let query = this.clone({ order: null });

package/dist/cjs/src/encrypt/assertNoEncryptedColumnWrites.js

@@ -0,0 +1,62 @@
+import CannotSetEncryptedColumnInQueryUpdate from '../errors/encrypt/CannotSetEncryptedColumnInQueryUpdate.js';
+import { snakeifyString } from '../helpers/snakeify.js';
+/**
+ * @internal
+ *
+ * Throws when `attributes` names an @Encrypted backing column with anything other
+ * than null. Guards the write paths that never instantiate a model, and so never
+ * reach the throwing setter the Encrypted decorator installs for that column.
+ *
+ * `encryptedAttributes` is class-scoped, but a query rooted at an STI base reaches
+ * every one of its children's rows on the shared table, so `dreamClass` and every STI
+ * class below it are searched for backing columns.
+ *
+ * The search deliberately stops there rather than covering the whole hierarchy. A query
+ * rooted at an STI child matches only that child's rows, and a backing column only a
+ * sibling declares holds nothing meaningful for them: writing plaintext into it corrupts
+ * no ciphertext, because there is none to corrupt. Converting such a row to the sibling
+ * type is what has to clear that column, and it has to clear it whatever this guard did.
+ * Widening the walk to the siblings therefore buys no protection, and this guard runs on
+ * every single-statement update, so keep it narrow.
+ *
+ * Keys are matched in their snakeified form, since Kysely's CamelCasePlugin
+ * resolves both the camelCase and the snake_case spelling of a key to the same
+ * physical column.
+ *
+ * null is permitted: it clears the column, and there is no plaintext to mangle.
+ */
+export default function assertNoEncryptedColumnWrites(dreamClass, attributes) {
+    const encryptedAttributes = encryptedAttributesInStiDescendants(dreamClass);
+    if (encryptedAttributes.size === 0)
+        return;
+    Object.keys(attributes).forEach(key => {
+        const encryptedAttribute = encryptedAttributes.get(snakeifyString(key));
+        if (encryptedAttribute === undefined)
+            return;
+        if (attributes[key] === null)
+            return;
+        throw new CannotSetEncryptedColumnInQueryUpdate(encryptedAttribute.declaringClass, encryptedAttribute.encryptedColumnName, encryptedAttribute.property);
+    });
+}
+/**
+ * @internal
+ *
+ * Every @Encrypted backing column declared on `dreamClass` or on an STI class below it,
+ * keyed by the snakeified backing column name.
+ */
+function encryptedAttributesInStiDescendants(dreamClass) {
+    const encryptedAttributes = new Map();
+    dreamClass['selfAndStiDescendants']().forEach(stiClass => {
+        stiClass['encryptedAttributes'].forEach(({ property, encryptedColumnName }) => {
+            const snakeifiedColumnName = snakeifyString(encryptedColumnName);
+            if (encryptedAttributes.has(snakeifiedColumnName))
+                return;
+            encryptedAttributes.set(snakeifiedColumnName, {
+                property,
+                encryptedColumnName,
+                declaringClass: stiClass,
+            });
+        });
+    });
+    return encryptedAttributes;
+}

package/dist/cjs/src/errors/encrypt/CannotSetEncryptedColumnInQueryUpdate.js

@@ -0,0 +1,31 @@
+export default class CannotSetEncryptedColumnInQueryUpdate extends Error {
+    dreamClass;
+    encryptedColumnName;
+    encryptedProperty;
+    constructor(dreamClass, encryptedColumnName, encryptedProperty) {
+        super();
+        this.dreamClass = dreamClass;
+        this.encryptedColumnName = encryptedColumnName;
+        this.encryptedProperty = encryptedProperty;
+    }
+    get message() {
+        return `
+Cannot write a non-null value to an @Encrypted backing column from a query-level update.
+
+Dream class: ${this.dreamClass.sanitizedName}
+Encrypted backing column: ${this.encryptedColumnName}
+Property to write instead: ${this.encryptedProperty}
+
+\`update(attributes, { skipHooks: true })\` compiles to a single UPDATE statement and
+never instantiates a model, so nothing encrypts the value on its way to the column:
+"${this.encryptedColumnName}" would be written as plaintext, exactly as passed.
+
+Write through the property instead, so that Dream encrypts the value:
+
+  await ${this.dreamClass.sanitizedName}.where({ ... }).update({ ${this.encryptedProperty}: 'value' })
+  await ${this.dreamClass.sanitizedName}.where({ ... }).update({ ${this.encryptedProperty}: 'value' }, { lock: true, skipHooks: true })
+
+Setting "${this.encryptedColumnName}" to null is permitted, and is how this path clears the column.
+`;
+    }
+}

package/dist/cjs/src/helpers/cli/generateMigration.js

@@ -52,7 +52,7 @@ export default async function generateMigration({ migrationName, columnsWithType
         : path.join(dreamPath('db'), 'migrations', connectionName);
     const fileName = `${migrationVersion()}-${hyphenize(migrationName).replace(/\//g, '-')}.ts`;
     const isSTI = !!fullyQualifiedParentName;
-    let content = '';
+    let content;
     if (isSTI) {
         content = generateStiMigrationContent({
             table: validTableNameOrThrow(migrationName, snakeify(pluralize(pascalizePath(fullyQualifiedParentName)))),

package/dist/cjs/src/helpers/cli/resolveIgnoredColumns.js

@@ -137,8 +137,8 @@ function guardAssociationColumns(ignoredColumns, tableName, allModels) {
             // pass too, and these guards never see the association's foreign key;
             // the InvalidComputedForeignKey / ExplicitForeignKeyRequired errors
             // swallowed here resurface at runtime as the backstop.
-            let foreignKey = null;
-            let foreignKeyTypeColumn = null;
+            let foreignKey;
+            let foreignKeyTypeColumn;
             try {
                 foreignKey = associationMetaData.foreignKey();
                 foreignKeyTypeColumn = associationMetaData.polymorphic

package/dist/cjs/src/helpers/cli/writeGeneratedFile.js

@@ -21,6 +21,6 @@ export default async function writeGeneratedFile({ dreamPathKey, basePath, fileN
 
       Does this file already exist? Here is the error that was raised:
         ${error.message}
-    `);
+    `, { cause: error });
     }
 }

package/dist/esm/src/Dream.js

@@ -273,6 +273,15 @@ export default class Dream {
      * assignment simply ensures that it is always an array rather than undefined)
      */
     static explicitUnsafeParamColumns = Object.freeze([]);
+    /**
+     * @internal
+     *
+     * Model storage for encrypted attribute metadata, set on the inheriting class when
+     * using the Encrypted decorator (this default assignment simply ensures that it is
+     * always an array rather than undefined,
+     * freezing ensures that we never modify the static array on the inherited Dream class)
+     */
+    static encryptedAttributes = Object.freeze([]);
     /**
      * @internal
      *
@@ -367,6 +376,23 @@ export default class Dream {
     static get isSTIBase() {
         return !!this.extendedBy?.length && !this.isSTIChild;
     }
+    /**
+     * @internal
+     *
+     * This class together with every STI class below it, however deeply nested. These
+     * are the classes whose rows a query rooted at this class can reach, since an STI
+     * child's rows are a subset of its base's.
+     *
+     * The classes *above* this one are deliberately excluded, as are its siblings: a
+     * column that only a sibling declares is meaningless for the rows this class
+     * matches, so treating it as this class's business protects nothing and costs a
+     * wider walk on every call.
+     *
+     * @returns An array of Dream classes
+     */
+    static selfAndStiDescendants() {
+        return [this, ...(this.extendedBy ?? []).flatMap(dreamClass => dreamClass.selfAndStiDescendants())];
+    }
     static stiSiblings() {
         const stiBase = this.stiBaseClassOrOwnClass;
         if (!stiBase.isSTIBase)
@@ -691,6 +717,10 @@ export default class Dream {
         return defaultParams;
     }
     static defaultParamSafeColumns() {
+        // `columns()` is table scoped, so it offers this class every column of the shared
+        // STI table, including those an STI child marks unsafe. A column unsafe for a child
+        // is unsafe here, because a query rooted at this class reaches that child's rows.
+        const explicitUnsafeParamColumns = new Set(this.selfAndStiDescendants().flatMap(dreamClass => [...dreamClass.explicitUnsafeParamColumns]));
         const columns = [...this.columns()].filter(column => {
             if (this.prototype._primaryKey === column)
                 return false;
@@ -700,7 +730,7 @@ export default class Dream {
                 return false;
             if (this.prototype._deletedAtField === column)
                 return false;
-            if (this.explicitUnsafeParamColumns.includes(column))
+            if (explicitUnsafeParamColumns.has(column))
                 return false;
             if (this.isBelongsToAssociationForeignKey(column, { includeStiSiblings: true }))
                 return false;

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

@@ -41,6 +41,18 @@ export default function Encrypted(encryptedColumnName) {
             }
             ;
             dreamClass['explicitUnsafeParamColumns'].push(encryptedKey);
+            if (!Object.getOwnPropertyDescriptor(dreamClass, 'encryptedAttributes')) {
+                // This pattern allows `encryptedAttributes` on a base STI class and on
+                // child STI classes. The new `encryptedAttributes` property will be created
+                // on the child STI class, but it will include all the `encryptedAttributes`
+                // already declared on the base STI class.
+                dreamClass['encryptedAttributes'] = [...dreamClass['encryptedAttributes']];
+            }
+            ;
+            dreamClass['encryptedAttributes'].push({
+                property: key,
+                encryptedColumnName: encryptedKey,
+            });
             const dreamPrototype = Object.getPrototypeOf(this);
             Object.defineProperty(dreamPrototype, key, {
                 get() {

package/dist/esm/src/decorators/field/sortable/Sortable.js

@@ -47,6 +47,16 @@ export default function Sortable(opts = {}) {
                 // already declared on the base STI class.
                 dreamClass['sortableFields'] = [...dreamClass['sortableFields']];
             }
+            // an STI child inherits its base's sortable fields via the copy above, and
+            // the base's field initializers run again while the child is globally
+            // initialized, so without this guard the child registers a second config
+            // for the same position field whenever the base is initialized first
+            // (models are globally initialized in filesystem order). Every duplicate
+            // config repeats the child's position work on each save, so positions
+            // advance by the number of duplicates instead of by 1
+            if (dreamClass['sortableFields'].some(conf => conf.positionField === key)) {
+                return;
+            }
             // the decorator registers nothing but this metadata: none of a sortable
             // field's runtime work runs as hooks. A save's preparation and position
             // write run as phases in `saveDream` (`prepareSortableFieldsForSave`,

package/dist/esm/src/dream/Query.js

@@ -2,6 +2,7 @@ import { SOFT_DELETE_SCOPE_NAME } from '../decorators/class/SoftDelete.js';
 import acquireStabilizedSortableBatchLocks from '../decorators/field/sortable/helpers/acquireStabilizedSortableBatchLocks.js';
 import { invalidateSortableRowCache } from '../decorators/field/sortable/helpers/sortableRowCache.js';
 import DreamApp from '../dream-app/index.js';
+import assertNoEncryptedColumnWrites from '../encrypt/assertNoEncryptedColumnWrites.js';
 import AssociationDeclaredWithoutAssociatedDreamClass from '../errors/associations/AssociationDeclaredWithoutAssociatedDreamClass.js';
 import CannotCallUndestroyOnANonSoftDeleteModel from '../errors/CannotCallUndestroyOnANonSoftDeleteModel.js';
 import CannotPassAdditionalFieldsToPluckEachAfterCallback from '../errors/CannotPassAdditionalFieldsToPluckEachAfterCallback.js';
@@ -2056,7 +2057,7 @@ export default class Query {
         // truthiness, since a primary key of 0 is a legitimate cursor value that
         // would otherwise reset the window to the start of the set
         let lastId = undefined;
-        let attemptedCount = 0;
+        let attemptedCount;
         do {
             const batchQuery = lastId === undefined
                 ? orderedQuery
@@ -2188,7 +2189,7 @@ export default class Query {
      * use {@link Query.destroy} instead.
      *
      * ```ts
-     * await User.where({ email: ops.ilike('%burpcollaborator%').delete() })
+     * await User.where({ email: ops.ilike('%burpcollaborator%') }).delete()
      * // 12
      * ```
      *
@@ -2316,7 +2317,13 @@ export default class Query {
         }, sortableIncomingAttributes);
     }
     async updateWithoutCallingModelHooks(attributes) {
-        return await this.dbDriverInstance().update(attributes);
+        // the guard and the driver must read the same values, so the caller's object
+        // is materialized once here and both read the snapshot
+        const snapshot = { ...attributes };
+        // this path compiles to a single UPDATE statement and never instantiates a
+        // model, so the setter that encrypts an @Encrypted property never runs
+        assertNoEncryptedColumnWrites(this.dreamClass, snapshot);
+        return await this.dbDriverInstance().update(snapshot);
     }
     invertOrder() {
         let query = this.clone({ order: null });

package/dist/esm/src/encrypt/assertNoEncryptedColumnWrites.js

@@ -0,0 +1,62 @@
+import CannotSetEncryptedColumnInQueryUpdate from '../errors/encrypt/CannotSetEncryptedColumnInQueryUpdate.js';
+import { snakeifyString } from '../helpers/snakeify.js';
+/**
+ * @internal
+ *
+ * Throws when `attributes` names an @Encrypted backing column with anything other
+ * than null. Guards the write paths that never instantiate a model, and so never
+ * reach the throwing setter the Encrypted decorator installs for that column.
+ *
+ * `encryptedAttributes` is class-scoped, but a query rooted at an STI base reaches
+ * every one of its children's rows on the shared table, so `dreamClass` and every STI
+ * class below it are searched for backing columns.
+ *
+ * The search deliberately stops there rather than covering the whole hierarchy. A query
+ * rooted at an STI child matches only that child's rows, and a backing column only a
+ * sibling declares holds nothing meaningful for them: writing plaintext into it corrupts
+ * no ciphertext, because there is none to corrupt. Converting such a row to the sibling
+ * type is what has to clear that column, and it has to clear it whatever this guard did.
+ * Widening the walk to the siblings therefore buys no protection, and this guard runs on
+ * every single-statement update, so keep it narrow.
+ *
+ * Keys are matched in their snakeified form, since Kysely's CamelCasePlugin
+ * resolves both the camelCase and the snake_case spelling of a key to the same
+ * physical column.
+ *
+ * null is permitted: it clears the column, and there is no plaintext to mangle.
+ */
+export default function assertNoEncryptedColumnWrites(dreamClass, attributes) {
+    const encryptedAttributes = encryptedAttributesInStiDescendants(dreamClass);
+    if (encryptedAttributes.size === 0)
+        return;
+    Object.keys(attributes).forEach(key => {
+        const encryptedAttribute = encryptedAttributes.get(snakeifyString(key));
+        if (encryptedAttribute === undefined)
+            return;
+        if (attributes[key] === null)
+            return;
+        throw new CannotSetEncryptedColumnInQueryUpdate(encryptedAttribute.declaringClass, encryptedAttribute.encryptedColumnName, encryptedAttribute.property);
+    });
+}
+/**
+ * @internal
+ *
+ * Every @Encrypted backing column declared on `dreamClass` or on an STI class below it,
+ * keyed by the snakeified backing column name.
+ */
+function encryptedAttributesInStiDescendants(dreamClass) {
+    const encryptedAttributes = new Map();
+    dreamClass['selfAndStiDescendants']().forEach(stiClass => {
+        stiClass['encryptedAttributes'].forEach(({ property, encryptedColumnName }) => {
+            const snakeifiedColumnName = snakeifyString(encryptedColumnName);
+            if (encryptedAttributes.has(snakeifiedColumnName))
+                return;
+            encryptedAttributes.set(snakeifiedColumnName, {
+                property,
+                encryptedColumnName,
+                declaringClass: stiClass,
+            });
+        });
+    });
+    return encryptedAttributes;
+}

package/dist/esm/src/errors/encrypt/CannotSetEncryptedColumnInQueryUpdate.js

@@ -0,0 +1,31 @@
+export default class CannotSetEncryptedColumnInQueryUpdate extends Error {
+    dreamClass;
+    encryptedColumnName;
+    encryptedProperty;
+    constructor(dreamClass, encryptedColumnName, encryptedProperty) {
+        super();
+        this.dreamClass = dreamClass;
+        this.encryptedColumnName = encryptedColumnName;
+        this.encryptedProperty = encryptedProperty;
+    }
+    get message() {
+        return `
+Cannot write a non-null value to an @Encrypted backing column from a query-level update.
+
+Dream class: ${this.dreamClass.sanitizedName}
+Encrypted backing column: ${this.encryptedColumnName}
+Property to write instead: ${this.encryptedProperty}
+
+\`update(attributes, { skipHooks: true })\` compiles to a single UPDATE statement and
+never instantiates a model, so nothing encrypts the value on its way to the column:
+"${this.encryptedColumnName}" would be written as plaintext, exactly as passed.
+
+Write through the property instead, so that Dream encrypts the value:
+
+  await ${this.dreamClass.sanitizedName}.where({ ... }).update({ ${this.encryptedProperty}: 'value' })
+  await ${this.dreamClass.sanitizedName}.where({ ... }).update({ ${this.encryptedProperty}: 'value' }, { lock: true, skipHooks: true })
+
+Setting "${this.encryptedColumnName}" to null is permitted, and is how this path clears the column.
+`;
+    }
+}

package/dist/esm/src/helpers/cli/generateMigration.js

@@ -52,7 +52,7 @@ export default async function generateMigration({ migrationName, columnsWithType
         : path.join(dreamPath('db'), 'migrations', connectionName);
     const fileName = `${migrationVersion()}-${hyphenize(migrationName).replace(/\//g, '-')}.ts`;
     const isSTI = !!fullyQualifiedParentName;
-    let content = '';
+    let content;
     if (isSTI) {
         content = generateStiMigrationContent({
             table: validTableNameOrThrow(migrationName, snakeify(pluralize(pascalizePath(fullyQualifiedParentName)))),

package/dist/esm/src/helpers/cli/resolveIgnoredColumns.js

@@ -137,8 +137,8 @@ function guardAssociationColumns(ignoredColumns, tableName, allModels) {
             // pass too, and these guards never see the association's foreign key;
             // the InvalidComputedForeignKey / ExplicitForeignKeyRequired errors
             // swallowed here resurface at runtime as the backstop.
-            let foreignKey = null;
-            let foreignKeyTypeColumn = null;
+            let foreignKey;
+            let foreignKeyTypeColumn;
             try {
                 foreignKey = associationMetaData.foreignKey();
                 foreignKeyTypeColumn = associationMetaData.polymorphic

package/dist/esm/src/helpers/cli/writeGeneratedFile.js

@@ -21,6 +21,6 @@ export default async function writeGeneratedFile({ dreamPathKey, basePath, fileN
 
       Does this file already exist? Here is the error that was raised:
         ${error.message}
-    `);
+    `, { cause: error });
     }
 }

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

@@ -197,6 +197,15 @@ export default class Dream {
      * assignment simply ensures that it is always an array rather than undefined)
      */
     private static explicitUnsafeParamColumns;
+    /**
+     * @internal
+     *
+     * Model storage for encrypted attribute metadata, set on the inheriting class when
+     * using the Encrypted decorator (this default assignment simply ensures that it is
+     * always an array rather than undefined,
+     * freezing ensures that we never modify the static array on the inherited Dream class)
+     */
+    private static encryptedAttributes;
     /**
      * @internal
      *
@@ -283,6 +292,21 @@ export default class Dream {
      * @returns boolean
      */
     private static get isSTIBase();
+    /**
+     * @internal
+     *
+     * This class together with every STI class below it, however deeply nested. These
+     * are the classes whose rows a query rooted at this class can reach, since an STI
+     * child's rows are a subset of its base's.
+     *
+     * The classes *above* this one are deliberately excluded, as are its siblings: a
+     * column that only a sibling declares is meaningless for the rows this class
+     * matches, so treating it as this class's business protects nothing and costs a
+     * wider walk on every call.
+     *
+     * @returns An array of Dream classes
+     */
+    private static selfAndStiDescendants;
     private static stiSiblings;
     /**
      * @internal

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

@@ -1521,7 +1521,7 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * use {@link Query.destroy} instead.
      *
      * ```ts
-     * await User.where({ email: ops.ilike('%burpcollaborator%').delete() })
+     * await User.where({ email: ops.ilike('%burpcollaborator%') }).delete()
      * // 12
      * ```
      *
@@ -1692,7 +1692,10 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      *   hanging.
      * - **`skipHooks` composes with `lock`, but stays on the per-instance
      *   path.** With an attributes object and no `lock`, `skipHooks: true`
-     *   issues a single `UPDATE ... WHERE` statement that writes raw columns.
+     *   issues a single `UPDATE ... WHERE` statement that writes raw columns —
+     *   with one refusal: it will not write a non-null value into an
+     *   `@Encrypted` backing column, since nothing on that path encrypts it, and
+     *   throws instead; `null`, which clears the column, is permitted.
      *   With `lock: true`, `skipHooks: true` skips the model hooks on each
      *   claimed record but still writes through the instance, so custom setters
      *   — including the setters encrypted attributes encrypt through — run as
@@ -1715,6 +1718,7 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * @throws InvalidBatchSize if `batchSize` is not a positive integer
      * @throws MissingRequiredLockOptionForUpdateCallback if a callback is passed without an options object carrying a boolean `lock`
      * @throws BatchingIncompatibleWithLimitOrOffset if the query carries a `limit` or `offset`
+     * @throws CannotSetEncryptedColumnInQueryUpdate if the single-statement `skipHooks` form's attributes name an `@Encrypted` backing column with anything other than `null`
      */
     update(cb: (record: DreamInstance) => UpdateableProperties<DreamInstance> | undefined | Promise<UpdateableProperties<DreamInstance> | undefined>, options: {
         lock: boolean;

package/dist/types/src/encrypt/assertNoEncryptedColumnWrites.d.ts

@@ -0,0 +1,27 @@
+import Dream from '../Dream.js';
+/**
+ * @internal
+ *
+ * Throws when `attributes` names an @Encrypted backing column with anything other
+ * than null. Guards the write paths that never instantiate a model, and so never
+ * reach the throwing setter the Encrypted decorator installs for that column.
+ *
+ * `encryptedAttributes` is class-scoped, but a query rooted at an STI base reaches
+ * every one of its children's rows on the shared table, so `dreamClass` and every STI
+ * class below it are searched for backing columns.
+ *
+ * The search deliberately stops there rather than covering the whole hierarchy. A query
+ * rooted at an STI child matches only that child's rows, and a backing column only a
+ * sibling declares holds nothing meaningful for them: writing plaintext into it corrupts
+ * no ciphertext, because there is none to corrupt. Converting such a row to the sibling
+ * type is what has to clear that column, and it has to clear it whatever this guard did.
+ * Widening the walk to the siblings therefore buys no protection, and this guard runs on
+ * every single-statement update, so keep it narrow.
+ *
+ * Keys are matched in their snakeified form, since Kysely's CamelCasePlugin
+ * resolves both the camelCase and the snake_case spelling of a key to the same
+ * physical column.
+ *
+ * null is permitted: it clears the column, and there is no plaintext to mangle.
+ */
+export default function assertNoEncryptedColumnWrites(dreamClass: typeof Dream, attributes: Record<string, unknown>): void;

package/dist/types/src/errors/encrypt/CannotSetEncryptedColumnInQueryUpdate.d.ts

@@ -0,0 +1,8 @@
+import Dream from '../../Dream.js';
+export default class CannotSetEncryptedColumnInQueryUpdate extends Error {
+    private dreamClass;
+    private encryptedColumnName;
+    private encryptedProperty;
+    constructor(dreamClass: typeof Dream, encryptedColumnName: string, encryptedProperty: string);
+    get message(): string;
+}