@rvoh/dream 2.35.0 → 2.36.0

package/dist/cjs/src/dream/QueryDriver/Base.js

@@ -554,6 +554,78 @@ export default class QueryDriverBase {
     async pluck(...fields) {
         throw new Error('implement pluck in child class');
     }
+    /**
+     * @internal
+     *
+     * The order statements that the declared `order` of the associations the
+     * Query is built on or joins contributes to its ORDER BY, in the order they
+     * sort, each column namespaced by the alias it is read from. Cursor
+     * pagination folds these into its cursor.
+     *
+     * @returns An array of namespaced order statements
+     */
+    associationOrderStatements() {
+        throw new Error('implement associationOrderStatements in child class');
+    }
+    /**
+     * @internal
+     *
+     * The primary key of each table the Query reaches through a HasOne or
+     * HasMany association (one it joins, one an association it joins goes
+     * through, or one its association query is built on), namespaced by the
+     * alias it is read from, in join order. Such a join can return a row of the
+     * Query's table once for each row it matches, and these keys, with the
+     * Query's own primary key, tell those rows apart. Cursor pagination pages by
+     * them after the Query's own primary key.
+     *
+     * @returns An array of namespaced primary key columns
+     */
+    joinedRowKeyColumns() {
+        throw new Error('implement joinedRowKeyColumns in child class');
+    }
+    /**
+     * @internal
+     *
+     * A page of a select that keeps one row of each group (DISTINCT ON, as a
+     * Query that calls `distinct`, or an association that declares `distinct`,
+     * produces), or null for any other select, whose pages cursor pagination
+     * reads as it reads any select's.
+     *
+     * The page is the values of the Query's order statement columns for each
+     * row the select returns that matches any of `rowsAfter` (every row when it
+     * is null), sorted by the Query's order statements and limited by its
+     * limit. The select chooses each group's row before `rowsAfter` narrows the
+     * rows, so that the page holds only rows the select returns.
+     *
+     * A driver whose selects never keep one row of each group returns null.
+     *
+     * @param rowsAfter - where statements, any of which a row of the page matches
+     * @returns The page's rows, each an array of its order statement columns' values, or null
+     */
+    // eslint-disable-next-line @typescript-eslint/require-await, @typescript-eslint/no-unused-vars
+    async pluckDistinctOnPage(rowsAfter) {
+        return null;
+    }
+    /**
+     * @internal
+     *
+     * For a select that keeps one row of each group (DISTINCT ON, as a Query
+     * that calls `distinct`, or an association that declares `distinct`,
+     * produces), the values of `rowKeyColumns` for every row it returns, sorted
+     * by those columns, ascending; null for any other select. `findEach` and
+     * `pluckEach` read a select that keeps one row of each group from these
+     * keys rather than by a cursor, which would narrow the select before it
+     * chooses each group's row.
+     *
+     * A driver whose selects never keep one row of each group returns null.
+     *
+     * @param rowKeyColumns - the namespaced columns that tell the select's rows apart
+     * @returns The rows' values of `rowKeyColumns`, or null
+     */
+    // eslint-disable-next-line @typescript-eslint/require-await, @typescript-eslint/no-unused-vars
+    async pluckDistinctOnRowKeys(rowKeyColumns) {
+        return null;
+    }
     /**
      * Returns a new Kysely SelectQueryBuilder instance to be used
      * in a sub Query

package/dist/cjs/src/dream/QueryDriver/Kysely.js

@@ -76,6 +76,21 @@ import checkForNeedToBeRunMigrations from './helpers/kysely/checkForNeedToBeRunM
 import foreignKeyTypeFromPrimaryKey from './helpers/kysely/foreignKeyTypeFromPrimaryKey.js';
 import runMigration from './helpers/kysely/runMigration.js';
 export default class KyselyQueryDriver extends QueryDriverBase {
+    /**
+     * @internal
+     *
+     * While `associationOrderStatements` builds a select, the order statements
+     * that association joins add to it, in the order they are added.
+     */
+    associationOrderCollector = null;
+    /**
+     * @internal
+     *
+     * While `joinedRowKeyColumns` builds a select, the namespaced primary keys of
+     * the tables that HasOne and HasMany joins add to it, in the order they are
+     * added.
+     */
+    joinedRowKeyCollector = null;
     // ATTENTION FRED
     // stop trying to make this async. You never learn...
     //
@@ -639,7 +654,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             bypassOrder: true,
         });
         const countClause = distinctColumn
-            ? count(sql `DISTINCT ${distinctColumn}`)
+            ? count(sql `DISTINCT ${sql.ref(distinctColumn)}`)
             : count(query['namespaceColumn'](query.dreamInstance['_primaryKey']));
         kyselyQuery = kyselyQuery.select(countClause.as('tablecount'));
         const data = await executeDatabaseQuery(kyselyQuery, 'executeTakeFirstOrThrow');
@@ -884,13 +899,58 @@ export default class KyselyQueryDriver extends QueryDriverBase {
         return new this.constructor(results.clone).buildCommon(results.kyselyQuery);
     }
     buildSelect({ bypassSelectAll = false, bypassOrder = false, columns, } = {}) {
+        const selectCore = this.buildSelectCore({ bypassOrder });
+        let kyselyQuery = selectCore.kyselyQuery;
+        if (this.query['bypassImplicitOrder']) {
+            // a keyset cursor compares only the Query's order statements, so the
+            // orderings emitted above (a similarity rank, an association's declared
+            // `order`, including those of an association query's base select) are
+            // cleared rather than left to sort ahead of them
+            kyselyQuery = kyselyQuery.clearOrderBy();
+        }
+        if (this.query['orderStatements'].length && !bypassOrder) {
+            this.query['orderStatements'].forEach(orderStatement => {
+                this.validatePlainColumn(this.dreamClass, orderStatement.column);
+                kyselyQuery = kyselyQuery.orderBy(this.namespaceColumn(orderStatement.column), this.orderByDirection(orderStatement.direction));
+            });
+        }
+        if (this.query['limitStatement'])
+            kyselyQuery = kyselyQuery.limit(this.query['limitStatement']);
+        if (this.query['offsetStatement'])
+            kyselyQuery = kyselyQuery.offset(this.query['offsetStatement']);
+        if (columns) {
+            kyselyQuery = kyselyQuery.select(this.columnsWithRequiredLoadColumns(columns).map(column => this.namespaceColumn(column)));
+        }
+        else if (!bypassSelectAll) {
+            kyselyQuery = kyselyQuery.selectAll(this.query['baseSqlAlias']);
+        }
+        // even though we manually bypass explicit order statements above,
+        // associations can contain their own ordering systems. If we do not
+        // escape all orders, we can mistakenly allow an order clause to sneak in.
+        if (bypassOrder)
+            kyselyQuery = kyselyQuery.clearOrderBy();
+        return kyselyQuery;
+    }
+    /**
+     * @internal
+     *
+     * The select's source, joins, conditions, DISTINCT ON and similarity
+     * ranking, before the Query's own order statements, limit, offset and
+     * selection are applied, together with the connection the select runs on.
+     */
+    buildSelectCore({ bypassOrder = false } = {}) {
         let kyselyQuery;
+        let selectDb;
         if (this.query['baseSelectQuery']) {
             const connectionOverride = this.query['connectionOverride'];
             const query = connectionOverride
                 ? this.query['baseSelectQuery'].connection(connectionOverride)
                 : this.query['baseSelectQuery'];
-            kyselyQuery = new this.constructor(query).buildSelect({
+            const baseSelectDriver = new this.constructor(query);
+            baseSelectDriver.associationOrderCollector = this.associationOrderCollector;
+            baseSelectDriver.joinedRowKeyCollector = this.joinedRowKeyCollector;
+            selectDb = baseSelectDriver.dbFor('select');
+            kyselyQuery = baseSelectDriver.buildSelect({
                 bypassSelectAll: true,
             });
         }
@@ -898,7 +958,8 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             const from = this.query['baseSqlAlias'] === this.query['tableName']
                 ? this.query['tableName']
                 : `${this.query['tableName']} as ${this.query['baseSqlAlias']}`;
-            kyselyQuery = this.dbFor('select').selectFrom(from);
+            selectDb = this.dbFor('select');
+            kyselyQuery = selectDb.selectFrom(from);
         }
         if (this.query['distinctColumn']) {
             kyselyQuery = kyselyQuery.distinctOn(this.query['distinctColumn']);
@@ -907,28 +968,135 @@ export default class KyselyQueryDriver extends QueryDriverBase {
         kyselyQuery = this.conditionallyAttachSimilarityColumnsToSelect(kyselyQuery, {
             bypassOrder: bypassOrder || !!this.query['distinctColumn'],
         });
-        if (this.query['orderStatements'].length && !bypassOrder) {
-            this.query['orderStatements'].forEach(orderStatement => {
-                this.validatePlainColumn(this.dreamClass, orderStatement.column);
-                kyselyQuery = kyselyQuery.orderBy(this.namespaceColumn(orderStatement.column), this.orderByDirection(orderStatement.direction));
-            });
+        return { kyselyQuery, selectDb };
+    }
+    /**
+     * @internal
+     *
+     * The order statements that the declared `order` of the associations the
+     * Query is built on or joins contributes to its ORDER BY, in the order they
+     * sort, each column namespaced by the alias it is read from. They are read
+     * off the same join code that emits them, by building the select.
+     *
+     * @returns An array of namespaced order statements
+     */
+    associationOrderStatements() {
+        const collected = [];
+        this.associationOrderCollector = collected;
+        try {
+            this.buildSelect();
         }
-        if (this.query['limitStatement'])
-            kyselyQuery = kyselyQuery.limit(this.query['limitStatement']);
-        if (this.query['offsetStatement'])
-            kyselyQuery = kyselyQuery.offset(this.query['offsetStatement']);
-        if (columns) {
-            kyselyQuery = kyselyQuery.select(this.columnsWithRequiredLoadColumns(columns).map(column => this.namespaceColumn(column)));
+        finally {
+            this.associationOrderCollector = null;
         }
-        else if (!bypassSelectAll) {
-            kyselyQuery = kyselyQuery.selectAll(this.query['baseSqlAlias']);
+        return collected;
+    }
+    /**
+     * @internal
+     *
+     * The primary key of each table the Query reaches through a HasOne or
+     * HasMany association (one it joins, one an association it joins goes
+     * through, or one its association query is built on), namespaced by the
+     * alias it is read from, in join order. They are read off the same join code
+     * that emits the joins, by building the select.
+     *
+     * @returns An array of namespaced primary key columns
+     */
+    joinedRowKeyColumns() {
+        const collected = [];
+        this.joinedRowKeyCollector = collected;
+        try {
+            this.buildSelect();
         }
-        // even though we manually bypass explicit order statements above,
-        // associations can contain their own ordering systems. If we do not
-        // escape all orders, we can mistakenly allow an order clause to sneak in.
-        if (bypassOrder)
-            kyselyQuery = kyselyQuery.clearOrderBy();
-        return kyselyQuery;
+        finally {
+            this.joinedRowKeyCollector = null;
+        }
+        return collected;
+    }
+    /**
+     * @internal
+     *
+     * A page of a select that carries DISTINCT ON (as a Query that calls
+     * `distinct`, or an association that declares `distinct`, produces), or null
+     * for any other select.
+     *
+     * Such a select keeps the row of each group that sorts first in its ORDER
+     * BY, so narrowing it to the rows after a cursor would let it keep a row it
+     * does not return (a group's later row, once the cursor has passed the
+     * group's first). It is read as a derived table instead, and narrowed to
+     * `rowsAfter`, sorted and limited outside it. The Query's order statements
+     * follow the select's own ORDER BY, if it has one, so that the select keeps
+     * the same row of each group every time it runs, and each of their columns
+     * is read out of it under a short alias (as `pluck` reads them), since a
+     * joined table's column cannot be named outside it.
+     *
+     * @param rowsAfter - where statements, any of which a row of the page matches
+     * @returns The page's rows, each an array of its order statement columns' values, or null
+     */
+    async pluckDistinctOnPage(rowsAfter) {
+        const { kyselyQuery: selectCore, selectDb } = this.buildSelectCore();
+        const selectNode = selectCore.toOperationNode();
+        if (!selectNode.distinctOn?.length)
+            return null;
+        const baseSqlAlias = this.query['baseSqlAlias'];
+        const orderStatements = this.query['orderStatements'];
+        const pageColumns = orderStatements.map((orderStatement, index) => {
+            this.validatePlainColumn(this.dreamClass, orderStatement.column);
+            return { column: this.namespaceColumn(orderStatement.column), alias: `pluck${index}` };
+        });
+        let distinctSelect = selectCore;
+        orderStatements.forEach(orderStatement => {
+            distinctSelect = distinctSelect.orderBy(this.namespaceColumn(orderStatement.column), this.orderByDirection(orderStatement.direction));
+        });
+        distinctSelect = distinctSelect.select(pageColumns.map(({ column, alias }) => `${column} as ${alias}`));
+        let pageSelect = selectDb.selectFrom(distinctSelect.as(baseSqlAlias));
+        pageSelect = pageSelect.select(pageColumns.map(({ alias }) => `${baseSqlAlias}.${alias}`));
+        if (rowsAfter) {
+            const derivedColumns = new Map(pageColumns.map(({ column, alias }) => [column, `${baseSqlAlias}.${alias}`]));
+            pageSelect = pageSelect.where((eb) => eb.or(rowsAfter.map(whereStatement => this.whereStatementToExpressionWrapper(this.dreamClass, eb, Object.fromEntries(Object.entries(whereStatement).map(([column, value]) => [
+                derivedColumns.get(this.namespaceColumn(column)),
+                value,
+            ]))))));
+        }
+        pageColumns.forEach(({ alias }, index) => {
+            pageSelect = pageSelect.orderBy(`${baseSqlAlias}.${alias}`, this.orderByDirection(orderStatements[index].direction));
+        });
+        if (this.query['limitStatement'])
+            pageSelect = pageSelect.limit(this.query['limitStatement']);
+        return (await executeDatabaseQuery(pageSelect, 'execute')).map(row => pageColumns.map(({ alias }) => row[alias]));
+    }
+    /**
+     * @internal
+     *
+     * For a select that carries DISTINCT ON (as a Query that calls `distinct`,
+     * or an association that declares `distinct`, produces), the values of
+     * `rowKeyColumns` for every row it returns, sorted by those columns,
+     * ascending; null for any other select.
+     *
+     * The select runs as `all()` runs it, with its own ORDER BY choosing each
+     * group's row, and is read as a derived table, sorted outside it. Each of
+     * `rowKeyColumns` is read out of it under a short alias (as `pluck` reads
+     * them), since a joined table's column cannot be named outside it.
+     *
+     * @param rowKeyColumns - the namespaced columns that tell the select's rows apart
+     * @returns The rows' values of `rowKeyColumns`, or null
+     */
+    async pluckDistinctOnRowKeys(rowKeyColumns) {
+        const { kyselyQuery: selectCore, selectDb } = this.buildSelectCore();
+        if (!selectCore.toOperationNode().distinctOn?.length)
+            return null;
+        const baseSqlAlias = this.query['baseSqlAlias'];
+        const keyColumns = rowKeyColumns.map((column, index) => {
+            this.validatePlainColumn(this.dreamClass, column);
+            return { column: this.namespaceColumn(column), alias: `key${index}` };
+        });
+        const distinctSelect = this.buildSelect({ bypassSelectAll: true }).select(keyColumns.map(({ column, alias }) => `${column} as ${alias}`));
+        let keySelect = selectDb.selectFrom(distinctSelect.as(baseSqlAlias));
+        keySelect = keySelect.select(keyColumns.map(({ alias }) => `${baseSqlAlias}.${alias}`));
+        keyColumns.forEach(({ alias }) => {
+            keySelect = keySelect.orderBy(`${baseSqlAlias}.${alias}`, this.orderByDirection('asc'));
+        });
+        return (await executeDatabaseQuery(keySelect, 'execute')).map(row => keyColumns.map(({ alias }) => row[alias]));
     }
     orderByDirection(direction) {
         return orderByDirection(direction);
@@ -1500,26 +1668,22 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             c = val.value;
         }
         else if (val instanceof Range) {
-            const rangeStart = val.begin;
-            const rangeEnd = val.end;
-            const excludeEnd = val.excludeEnd;
-            if (rangeStart && rangeEnd) {
-                a = attr;
-                b = '>=';
-                c = rangeStart;
+            // a bound is present unless it is null or undefined, matching the Range
+            // constructor, so falsy bounds such as 0, 0n and '' still constrain the query
+            const boundConditions = [];
+            if (val.begin != null)
+                boundConditions.push({ operator: '>=', value: val.begin });
+            if (val.end != null)
+                boundConditions.push({ operator: val.excludeEnd ? '<' : '<=', value: val.end });
+            // the Range constructor rejects a range with neither bound, so firstBound is always set
+            const [firstBound, secondBound] = boundConditions;
+            a = attr;
+            b = firstBound.operator;
+            c = firstBound.value;
+            if (secondBound) {
                 a2 = attr;
-                b2 = excludeEnd ? '<' : '<=';
-                c2 = rangeEnd;
-            }
-            else if (rangeStart) {
-                a = attr;
-                b = '>=';
-                c = rangeStart;
-            }
-            else {
-                a = attr;
-                b = excludeEnd ? '<' : '<=';
-                c = rangeEnd;
+                b2 = secondBound.operator;
+                c2 = secondBound.value;
             }
         }
         else {
@@ -2253,6 +2417,7 @@ export default class KyselyQueryDriver extends QueryDriverBase {
                 join = this.applyJoinAndStatement(modelClassUsedForJoinConditions, join, joinAndStatement, currentTableAlias);
                 return join;
             });
+            this.joinedRowKeyCollector?.push(this.namespaceColumn(association.modelCB().primaryKey, currentTableAlias));
             if (association.type === 'HasMany') {
                 if (association.order) {
                     query = this.applyOrderStatementForAssociation({
@@ -2280,15 +2445,16 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             return query;
         let selectQuery = query;
         const orderStatement = association.order;
-        if (typeof orderStatement === 'string') {
-            selectQuery = selectQuery.orderBy(this.namespaceColumn(orderStatement, tableNameOrAlias), 'asc');
-        }
-        else {
-            Object.keys(orderStatement).forEach(column => {
-                const direction = orderStatement[column];
-                selectQuery = selectQuery.orderBy(this.namespaceColumn(column, tableNameOrAlias), direction);
-            });
-        }
+        const orderQueryStatements = typeof orderStatement === 'string'
+            ? [{ column: this.namespaceColumn(orderStatement, tableNameOrAlias), direction: 'asc' }]
+            : Object.keys(orderStatement).map(column => ({
+                column: this.namespaceColumn(column, tableNameOrAlias),
+                direction: orderStatement[column],
+            }));
+        orderQueryStatements.forEach(({ column, direction }) => {
+            selectQuery = selectQuery.orderBy(column, direction);
+        });
+        this.associationOrderCollector?.push(...orderQueryStatements);
         return selectQuery;
     }
     distinctColumnNameForAssociation({ association, tableNameOrAlias, foreignKey, }) {

package/dist/cjs/src/dream/internal/associations/assertRecognizedAssociationConditionKeys.js

@@ -0,0 +1,48 @@
+import UnrecognizedAssociationConditionKeys from '../../../errors/associations/UnrecognizedAssociationConditionKeys.js';
+import isObject from '../../../helpers/isObject.js';
+/**
+ * The keys a condition object on an association accepts, whether it is
+ * passed in a chain (`preload('posts', { and: { ... } })`), returned from a
+ * `preloadFor`/`loadFor` modifier, or passed to `associationQuery`.
+ */
+export const ASSOCIATION_CONDITION_KEYS = ['and', 'andNot', 'andAny'];
+/**
+ * The keys accepted by `destroyAssociation`, `reallyDestroyAssociation`
+ * and `undestroyAssociation`.
+ */
+export const DESTROY_ASSOCIATION_OPTION_KEYS = [
+    ...ASSOCIATION_CONDITION_KEYS,
+    'bypassAllDefaultScopes',
+    'defaultScopesToBypass',
+    'cascade',
+    'skipHooks',
+];
+/**
+ * The keys accepted by `updateAssociation`.
+ */
+export const UPDATE_ASSOCIATION_OPTION_KEYS = [
+    ...ASSOCIATION_CONDITION_KEYS,
+    'bypassAllDefaultScopes',
+    'defaultScopesToBypass',
+    'skipHooks',
+];
+/**
+ * Throws UnrecognizedAssociationConditionKeys when `value` is an object
+ * carrying any own key outside `acceptedKeys`, including a key whose value
+ * is `undefined`. Dream reads only the accepted keys, so an unrecognized key
+ * would otherwise be silently ignored (and, for the destroy family, act on
+ * every associated row instead of the ones the caller meant to select).
+ * Non-object values (`undefined`, `null`) pass through untouched.
+ *
+ * @param value - The condition object or options object to check
+ * @param acceptedKeys - The keys `value` may carry
+ * @param associationName - The association the object applies to, for the error message
+ * @param methodName - The public method the options were passed to, or null for a chain condition
+ */
+export default function assertRecognizedAssociationConditionKeys(value, acceptedKeys, associationName, methodName = null) {
+    if (!isObject(value))
+        return;
+    const unrecognizedKeys = Object.keys(value).filter(key => !acceptedKeys.includes(key));
+    if (unrecognizedKeys.length)
+        throw new UnrecognizedAssociationConditionKeys(String(associationName), unrecognizedKeys, acceptedKeys, methodName);
+}

package/dist/cjs/src/dream/internal/associations/associationQuery.js

@@ -1,5 +1,9 @@
 import applyScopeBypassingSettingsToQuery from '../applyScopeBypassingSettingsToQuery.js';
+import assertRecognizedAssociationConditionKeys, { ASSOCIATION_CONDITION_KEYS, } from './assertRecognizedAssociationConditionKeys.js';
 export default function associationQuery(dream, txn = null, associationName, { joinAndStatements, bypassAllDefaultScopes, defaultScopesToBypass, }) {
+    // a condition carrying none of and/andNot/andAny skips the join below, so the
+    // chain check in Query never sees it
+    assertRecognizedAssociationConditionKeys(joinAndStatements, ASSOCIATION_CONDITION_KEYS, associationName, 'associationQuery');
     const association = dream['associationMetadataMap']()[associationName];
     const associationClass = association.modelCB();
     const dreamClass = dream.constructor;

package/dist/cjs/src/dream/internal/reload.js

@@ -14,7 +14,12 @@ export default async function reload(dream, txn = null) {
         [dream['_primaryKey']]: dream.primaryKeyValue(),
     });
     const reloadedRecord = await query.firstOrFail();
-    dream.setAttributes(reloadedRecord.getAttributes());
+    // a row read from the database, so its @Encrypted backing columns hold the
+    // ciphertext Dream stored and are written without setAttribute's decryption check
+    dream['_setAttributes'](reloadedRecord.getAttributes(), {
+        bypassUserDefinedSetters: true,
+        fromDatabase: true,
+    });
     dream['freezeAttributes']();
     dream['originalAttributes'] = dream.getAttributes();
     return dream;

package/dist/cjs/src/dream/internal/saveDream.js

@@ -132,8 +132,14 @@ async function writeDream(dream, txn, { alreadyPersisted, sortableFieldConfigs,
         // the row returned by the driver comes from `RETURNING *` (or a
         // `select *` reload on drivers without RETURNING support), so under
         // schema/image skew it can contain columns this build's compiled
-        // schema doesn't know about; those must never reach setAttributes
-        dream.setAttributes(filterRowToKnownColumns(data, dream.columns()));
+        // schema doesn't know about; those are filtered out before the row is
+        // written back. It is a row read from the database, so its @Encrypted
+        // backing columns hold the ciphertext Dream stored and are written
+        // without setAttribute's decryption check
+        dream['_setAttributes'](filterRowToKnownColumns(data, dream.columns()), {
+            bypassUserDefinedSetters: true,
+            fromDatabase: true,
+        });
     }
     // set frozen attributes to what has already been saved
     dream['freezeAttributes']();

package/dist/cjs/src/dream/internal/sqlResultToDreamInstance.js

@@ -16,6 +16,7 @@ export default function sqlResultToDreamInstance(dreamClass, sqlResult) {
             throw new STIChildMissing(dreamClass, sqlResult.type, sqlResult[dreamClass.primaryKey]);
         const dreamModel = new extendingDreamClass(filterRowToKnownColumns(sqlResult, extendingDreamClass.columns()), {
             bypassUserDefinedSetters: true,
+            fromDatabase: true,
             isPersisted: true,
             _internalUseOnly: true,
         });
@@ -25,6 +26,7 @@ export default function sqlResultToDreamInstance(dreamClass, sqlResult) {
     else {
         const dreamModel = new dreamClass(filterRowToKnownColumns(sqlResult, dreamClass.columns()), {
             bypassUserDefinedSetters: true,
+            fromDatabase: true,
             isPersisted: true,
             _internalUseOnly: true,
         });

package/dist/cjs/src/dream/internal/undestroyDream.js

@@ -148,7 +148,7 @@ async function undestroyAssociatedRecords(dream, txn, options) {
                 bypassAllDefaultScopes: options.bypassAllDefaultScopes ?? false,
                 defaultScopesToBypass: (options.defaultScopesToBypass ?? []),
             });
-            await query.removeDefaultScope(SOFT_DELETE_SCOPE_NAME).findEach(async (record) => {
+            await query.removeDefaultScope(SOFT_DELETE_SCOPE_NAME)['findEachRecordOnce'](async (record) => {
                 markSortableCascadeEdge(record, association);
                 await record.txn(txn).undestroy(options);
             });

package/dist/cjs/src/dream-app/index.js

@@ -179,6 +179,7 @@ export default class DreamApp {
     _specialHooks = {
         dbLog: [],
         replStart: [],
+        encryptionLegacyKeyUsed: [],
     };
     get specialHooks() {
         return this._specialHooks;
@@ -520,6 +521,40 @@ export default class DreamApp {
             }
         }
     }
+    /**
+     * Registers a callback for an app-level event. Callbacks for the same
+     * event run in the order they were registered.
+     *
+     * - `'db:log'`: called with a {@link KyselyLogEvent} each time a query on a
+     *   Dream database connection completes or fails.
+     * - `'repl:start'`: called, and awaited, with the console's REPL context
+     *   when the Dream console starts.
+     * - `'encryption:legacy-key-used'`: called with an
+     *   {@link EncryptionLegacyKeyUsedEvent} when reading an `@deco.Encrypted`
+     *   property needed the `legacy` column encryption key, not `current`, to
+     *   open the stored value. Use it during a key rotation to find rows still
+     *   encrypted with the old key. The property decrypts on every read, so a
+     *   record whose value is still under the old key fires the event each time
+     *   the property is read. A row nobody reads never fires it, so a quiet
+     *   event does not prove that `legacy` is safe to drop;
+     *   `Model.reencryptEncryptedColumns()` rewrites every row instead. Neither
+     *   it nor the migration helpers fire the event. The callback runs
+     *   synchronously inside the property read, and an error it throws
+     *   propagates from that read. Reading the same property of the same
+     *   record inside the callback returns its value without firing the event
+     *   again, so a callback can read the property and assign the value back,
+     *   which re-encrypts it under `current` for the record's next save. That
+     *   holds only while the callback runs synchronously: a callback that
+     *   reads the property after an `await` fires the event again from that
+     *   read, so an `async` callback should read the property before its
+     *   first `await`.
+     *
+     * ```ts
+     * dreamApp.on('encryption:legacy-key-used', ({ dream, property }) => {
+     *   console.warn(`${dream.constructor.name} ${dream.primaryKeyValue()} ${property} still uses the legacy key`)
+     * })
+     * ```
+     */
     on(hookEventType, cb) {
         switch (hookEventType) {
             case 'db:log':
@@ -528,6 +563,9 @@ export default class DreamApp {
             case 'repl:start':
                 this._specialHooks.replStart.push(cb);
                 break;
+            case 'encryption:legacy-key-used':
+                this._specialHooks.encryptionLegacyKeyUsed.push(cb);
+                break;
         }
     }
 }

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

@@ -1,4 +1,7 @@
 import DreamApp from '../dream-app/index.js';
+import DecryptionError from '../errors/encrypt/DecryptionError.js';
+import DecryptionParseError from '../errors/encrypt/DecryptionParseError.js';
+import DecryptionRotationError from '../errors/encrypt/DecryptionRotationError.js';
 import MissingColumnEncryptionOpts from '../errors/encrypt/MissingColumnEncryptionOpts.js';
 import Encrypt from './index.js';
 export default class InternalEncrypt {
@@ -11,19 +14,61 @@ export default class InternalEncrypt {
             return null;
         return this.doEncryption(data, encryptOpts.current);
     }
-    static decryptColumn(data) {
+    /**
+     * Decrypts `data` with the column keys, current then legacy.
+     * `onLegacyKeyUsed` is passed to `Encrypt.decrypt`, so it is called only
+     * when the legacy key opened the value.
+     */
+    static decryptColumn(data, callbacks = {}) {
         const dreamApp = DreamApp.getOrFail();
         const encryptOpts = dreamApp.encryption?.columns;
         if (!encryptOpts)
             throw new MissingColumnEncryptionOpts();
         if (data === null || data === undefined)
             return null;
-        return this.doDecryption(data, encryptOpts.current, encryptOpts.legacy);
+        return this.doDecryption(data, encryptOpts.current, encryptOpts.legacy, callbacks);
+    }
+    /**
+     * Encrypts `data`, a column's ciphertext, again with the current column key
+     * (see `Encrypt.reencrypt`), opening it with the current key or, failing
+     * that, the legacy one. It does not call `onLegacyKeyUsed`.
+     */
+    static reencryptColumn(data) {
+        const dreamApp = DreamApp.getOrFail();
+        const encryptOpts = dreamApp.encryption?.columns;
+        if (!encryptOpts)
+            throw new MissingColumnEncryptionOpts();
+        if (data === null || data === undefined)
+            return null;
+        return Encrypt.reencrypt(data, encryptOpts.current, encryptOpts.legacy);
+    }
+    /**
+     * Whether `data` is ciphertext that the column keys (current, then legacy)
+     * open to a value `decryptColumn` returns. A missing column encryption
+     * config or key still throws, since that is a configuration error rather
+     * than a property of `data`.
+     */
+    static isDecryptableColumnCiphertext(data) {
+        const dreamApp = DreamApp.getOrFail();
+        const encryptOpts = dreamApp.encryption?.columns;
+        if (!encryptOpts)
+            throw new MissingColumnEncryptionOpts();
+        try {
+            this.doDecryption(data, encryptOpts.current, encryptOpts.legacy);
+            return true;
+        }
+        catch (err) {
+            if (err instanceof DecryptionError ||
+                err instanceof DecryptionParseError ||
+                err instanceof DecryptionRotationError)
+                return false;
+            throw err;
+        }
     }
     static doEncryption(data, encryptionOpts) {
         return Encrypt.encrypt(data, encryptionOpts);
     }
-    static doDecryption(data, encryptionOpts, legacyEncryptionOpts) {
-        return Encrypt.decrypt(data, encryptionOpts, legacyEncryptionOpts);
+    static doDecryption(data, encryptionOpts, legacyEncryptionOpts, callbacks = {}) {
+        return Encrypt.decrypt(data, encryptionOpts, legacyEncryptionOpts, callbacks);
     }
 }