@rvoh/dream 2.35.0 → 2.36.1

package/dist/types/src/dream/QueryDriver/Base.d.ts

@@ -2,7 +2,7 @@ import { CompiledQuery, DeleteQueryBuilder, SelectQueryBuilder, UpdateQueryBuild
 import type { DreamDbConfig } from '../../dream-app/index.js';
 import Dream from '../../Dream.js';
 import { SchemaBuilderAssociationData, SchemaBuilderColumnData } from '../../helpers/cli/ASTBuilder.js';
-import { AssociationStatement } from '../../types/associations/shared.js';
+import { AssociationStatement, OrderQueryStatement } from '../../types/associations/shared.js';
 import { DbConnectionType, LegacyCompatiblePrimaryKeyType } from '../../types/db.js';
 import { DreamColumnNames, DreamConstructorType, DreamTableSchema } from '../../types/dream.js';
 import { PreloadedDreamsAndWhatTheyPointTo, QueryToKyselyDBType, QueryToKyselyTableNamesType } from '../../types/query.js';
@@ -435,6 +435,68 @@ export default class QueryDriverBase<DreamInstance extends Dream> {
      * @returns An array of plucked values
      */
     pluck(...fields: DreamColumnNames<DreamInstance>[]): Promise<any[]>;
+    /**
+     * @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(): OrderQueryStatement<string>[];
+    /**
+     * @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(): string[];
+    /**
+     * @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
+     */
+    pluckDistinctOnPage(rowsAfter: Record<string, unknown>[] | null): Promise<unknown[][] | 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
+     */
+    pluckDistinctOnRowKeys(rowKeyColumns: string[]): Promise<unknown[][] | null>;
     /**
      * Returns a new Kysely SelectQueryBuilder instance to be used
      * in a sub Query

package/dist/types/src/dream/QueryDriver/Kysely.d.ts

@@ -4,7 +4,7 @@ import { DialectProviderCb } from '../../db/DreamDbConnection.js';
 import { DreamDbConfig } from '../../dream-app/index.js';
 import Dream from '../../Dream.js';
 import { SchemaBuilderInformationSchemaRow } from '../../helpers/cli/ASTBuilder.js';
-import { AssociationStatement } from '../../types/associations/shared.js';
+import { AssociationStatement, OrderQueryStatement } from '../../types/associations/shared.js';
 import { DbConnectionType, LegacyCompatiblePrimaryKeyType } from '../../types/db.js';
 import { DreamColumnNames, DreamTableSchema, OrderDir, SqlCommandType } from '../../types/dream.js';
 import { PreloadedDreamsAndWhatTheyPointTo, QueryToKyselyDBType, QueryToKyselyTableNamesType } from '../../types/query.js';
@@ -12,6 +12,21 @@ import DreamTransaction from '../DreamTransaction.js';
 import Query from '../Query.js';
 import QueryDriverBase from './Base.js';
 export default class KyselyQueryDriver<DreamInstance extends Dream> extends QueryDriverBase<DreamInstance> {
+    /**
+     * @internal
+     *
+     * While `associationOrderStatements` builds a select, the order statements
+     * that association joins add to it, in the order they are added.
+     */
+    private associationOrderCollector;
+    /**
+     * @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.
+     */
+    private joinedRowKeyCollector;
     dbFor(sqlCommandType: SqlCommandType): Kysely<DreamInstance['DB']> | KyselyTransaction<DreamInstance['DB']>;
     static dbFor<I extends Dream>(connectionName: string, dbConnectionType: DbConnectionType, dreamTransaction?: DreamTransaction<I> | null): Kysely<I['DB']> | KyselyTransaction<I['DB']>;
     static dialectProvider(connectionName: string, dbConnectionType: DbConnectionType): DialectProviderCb;
@@ -400,6 +415,75 @@ export default class KyselyQueryDriver<DreamInstance extends Dream> extends Quer
     }>;
     private buildDelete;
     private buildSelect;
+    /**
+     * @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.
+     */
+    private buildSelectCore;
+    /**
+     * @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(): OrderQueryStatement<string>[];
+    /**
+     * @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(): string[];
+    /**
+     * @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
+     */
+    pluckDistinctOnPage(rowsAfter: Record<string, unknown>[] | null): Promise<unknown[][] | null>;
+    /**
+     * @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
+     */
+    pluckDistinctOnRowKeys(rowKeyColumns: string[]): Promise<unknown[][] | null>;
     orderByDirection(direction: OrderDir | null): (obj: OrderByItemBuilder) => OrderByItemBuilder;
     private buildUpdate;
     /**

package/dist/types/src/dream/internal/associations/assertRecognizedAssociationConditionKeys.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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 declare const ASSOCIATION_CONDITION_KEYS: readonly ["and", "andNot", "andAny"];
+/**
+ * The keys accepted by `destroyAssociation`, `reallyDestroyAssociation`
+ * and `undestroyAssociation`.
+ */
+export declare const DESTROY_ASSOCIATION_OPTION_KEYS: readonly ["and", "andNot", "andAny", "bypassAllDefaultScopes", "defaultScopesToBypass", "cascade", "skipHooks"];
+/**
+ * The keys accepted by `updateAssociation`.
+ */
+export declare const UPDATE_ASSOCIATION_OPTION_KEYS: readonly ["and", "andNot", "andAny", "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: unknown, acceptedKeys: readonly string[], associationName: string | number | symbol, methodName?: string | null): void;

package/dist/types/src/dream-app/index.d.ts

@@ -238,9 +238,43 @@ export default class DreamApp {
     load<RT extends 'models' | 'serializers'>(resourceType: RT, resourcePath: string, importCb: (path: string) => Promise<any>): Promise<void>;
     plugin(cb: (app: DreamApp) => void | Promise<void>): void;
     set<ApplyOpt extends DreamAppSetOption>(applyOption: ApplyOpt, options: ApplyOpt extends 'bypassDeprecationChecks' ? boolean : ApplyOpt extends 'db' ? DreamDbCredentialOptions | string : ApplyOpt extends 'encryption' ? DreamAppEncryptionOptions : ApplyOpt extends 'primaryKeyType' ? LegacyCompatiblePrimaryKeyType : ApplyOpt extends 'importExtension' ? GeneratorImportStyle : ApplyOpt extends 'logger' ? DreamLogger : ApplyOpt extends 'projectRoot' ? string : ApplyOpt extends 'inflections' ? () => void | Promise<void> : ApplyOpt extends 'packageManager' ? DreamAppAllowedPackageManagersEnum : ApplyOpt extends 'paths' ? DreamDirectoryPaths : ApplyOpt extends 'parallelTests' ? number : ApplyOpt extends 'unicodeNormalization' ? UnicodeNormalizationForm : ApplyOpt extends 'paginationPageSize' ? number : ApplyOpt extends 'paginationMaxPageSize' ? number : ApplyOpt extends 'sortableScopeLockTimeout' ? number : never, secondaryOptions?: ApplyOpt extends 'db' ? DreamDbCredentialOptions : never): void;
-    on<T extends DreamHookEventType>(hookEventType: T, cb: T extends 'db:log' ? (event: KyselyLogEvent) => void : T extends 'repl:start' ? (context: Context) => void | Promise<void> : never): void;
+    /**
+     * 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<T extends DreamHookEventType>(hookEventType: T, cb: T extends 'db:log' ? (event: KyselyLogEvent) => void : T extends 'repl:start' ? (context: Context) => void | Promise<void> : T extends 'encryption:legacy-key-used' ? (event: EncryptionLegacyKeyUsedEvent) => void : never): void;
 }
-export type DreamHookEventType = 'db:log' | 'repl:start';
+export type DreamHookEventType = 'db:log' | 'repl:start' | 'encryption:legacy-key-used';
 export interface DreamAppOpts {
     projectRoot: string;
     primaryKeyType: LegacyCompatiblePrimaryKeyType;
@@ -373,6 +407,26 @@ interface SegmentedEncryptionOptions {
 export interface DreamAppSpecialHooks {
     dbLog: ((event: KyselyLogEvent) => void)[];
     replStart: ((context: Context) => void | Promise<void>)[];
+    encryptionLegacyKeyUsed: ((event: EncryptionLegacyKeyUsedEvent) => void)[];
+}
+/**
+ * Passed to `dreamApp.on('encryption:legacy-key-used', ...)` callbacks.
+ */
+export interface EncryptionLegacyKeyUsedEvent {
+    /**
+     * The record whose `@deco.Encrypted` property was read. Its class and
+     * `primaryKeyValue()` identify the row; a record not yet saved has no
+     * primary key.
+     */
+    dream: Dream;
+    /**
+     * The `@deco.Encrypted` property that was read, e.g. `'phone'`.
+     */
+    property: string;
+    /**
+     * The column holding the property's ciphertext, e.g. `'encryptedPhone'`.
+     */
+    encryptedColumnName: string;
 }
 export interface DreamAppInitOptions {
     bypassDreamIntegrityChecks?: boolean;

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

@@ -1,6 +1,34 @@
+import { DecryptCallbacks } from './index.js';
 export default class InternalEncrypt {
     static encryptColumn(data: any): string | null;
-    static decryptColumn(data: any): unknown;
+    /**
+     * Returns `existingCiphertext` when the current column key opens it to a
+     * value whose JSON serialization equals `data`'s, the plaintext
+     * `encryptColumn(data)` would encrypt, and otherwise `encryptColumn(data)`.
+     * A value only the legacy key opens, ciphertext no key opens, and a
+     * missing `existingCiphertext` all get fresh ciphertext. It never calls
+     * `onLegacyKeyUsed`.
+     */
+    static reuseOrEncryptColumn(data: any, existingCiphertext: unknown): string | null;
+    /**
+     * 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: any, callbacks?: DecryptCallbacks): unknown;
+    /**
+     * 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: any): string | null;
+    /**
+     * 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: string): boolean;
     private static doEncryption;
     private static doDecryption;
 }

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

@@ -0,0 +1,7 @@
+/**
+ * The column that holds an `@deco.Encrypted` property's ciphertext when the
+ * decorator is not given one: the property's name, pascalized and prefixed
+ * with `encrypted`. `secretPhone`, or `secret_phone`, gives
+ * `encryptedSecretPhone`, which is the `encrypted_secret_phone` column.
+ */
+export default function defaultEncryptedColumnName(propertyName: string): string;

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

@@ -19,12 +19,50 @@ export default class Encrypt {
      *
      * `MissingEncryptionKey` propagates from either form when a key is missing.
      *
+     * **`onLegacyKeyUsed`** (optional fourth argument): during a key rotation,
+     * tells you which values still need the legacy key. It is called with no
+     * arguments, synchronously, before a three-arg call returns a value that
+     * the legacy key opened. It is not called when the current key opens the
+     * value, when decryption throws, or in the two-arg form. An error it
+     * throws propagates from `decrypt` as is.
+     *
+     * ```ts
+     * const value = Encrypt.decrypt<string>(
+     *   encrypted,
+     *   { algorithm: 'aes-256-gcm', key: newKey },
+     *   { algorithm: 'aes-256-gcm', key: oldKey },
+     *   { onLegacyKeyUsed: () => console.warn('this value is still encrypted with the old key') }
+     * )
+     * ```
+     *
+     * @throws MissingEncryptionKey
+     * @throws DecryptionError
+     * @throws DecryptionParseError
+     * @throws DecryptionRotationError
+     */
+    static decrypt<RetType>(encrypted: string, { algorithm, key }: DecryptOptions, legacyOpts?: DecryptOptions, { onLegacyKeyUsed }?: DecryptCallbacks): RetType | null;
+    /**
+     * Opens `encrypted` as {@link Encrypt.decrypt} does, with `currentOpts` and,
+     * when they do not open it, `legacyOpts`, and encrypts the value again with
+     * `currentOpts`, so that reading it no longer needs the legacy key. Use it
+     * during a key rotation for a value stored outside an `@deco.Encrypted`
+     * column, such as a cookie; `Model.reencryptEncryptedColumns()` does this
+     * for every value of a model's encrypted properties.
+     *
+     * ```ts
+     * const rewritten = Encrypt.reencrypt(
+     *   storedValue,
+     *   { algorithm: 'aes-256-gcm', key: newKey },
+     *   { algorithm: 'aes-256-gcm', key: oldKey }
+     * )
+     * ```
+     *
      * @throws MissingEncryptionKey
      * @throws DecryptionError
      * @throws DecryptionParseError
      * @throws DecryptionRotationError
      */
-    static decrypt<RetType>(encrypted: string, { algorithm, key }: DecryptOptions, legacyOpts?: DecryptOptions): RetType | null;
+    static reencrypt(encrypted: string, currentOpts: EncryptOptions, legacyOpts?: DecryptOptions): string;
     private static attemptDecryptionWithLegacyKeys;
     /**
      * Generates a base64-encoded random key suitable for the given algorithm.
@@ -42,11 +80,26 @@ export default class Encrypt {
      *    to decrypt via `legacy` fallback.
      * 4. For cookies, wait at least the cookie `maxAge` so all in-flight
      *    cookies have either expired or been re-issued under the new key. For
-     *    `@Encrypted` columns, re-encrypt every existing row under the new
-     *    key (read each row and write it back; the setter re-encrypts with
-     *    `current`).
+     *    `@Encrypted` columns, re-encrypt every existing row under the new key
+     *    by calling `reencryptEncryptedColumns()` on each model that has
+     *    encrypted properties (`await User.reencryptEncryptedColumns()`), in
+     *    each environment, from a console or a script rather than a migration.
+     *    Run it only once every server in that environment runs with the new
+     *    `current`: a server still on the old `current` keeps writing old-key
+     *    values that its single pass over the table can miss. Writing old-key
+     *    ciphertext straight into a backing column (`setAttribute`,
+     *    `setAttributes` or `updateAttributes` given the backing column) after
+     *    it has run also puts an old-key value back. For any other value
+     *    encrypted with these keys, {@link Encrypt.reencrypt} rewrites it.
      * 5. Drop `legacy` from config and deploy again.
      *
+     * To see which values still need the old key while `legacy` is
+     * configured, register `dreamApp.on('encryption:legacy-key-used', ...)`,
+     * which fires each time reading an `@Encrypted` property needed `legacy`
+     * to open the value, or pass `onLegacyKeyUsed` to {@link Encrypt.decrypt}
+     * for values you decrypt yourself. A value nobody reads never fires
+     * either, so silence alone does not show that `legacy` is safe to drop.
+     *
      * ## When to rotate
      *
      * - On a scheduled cadence (90–180 days is a reasonable policy default).
@@ -58,8 +111,15 @@ export default class Encrypt {
      * - For cookies: at least the cookie `maxAge`, so in-flight sessions are
      *   not forced to re-authenticate.
      * - For `@Encrypted` columns: until every existing row has been
-     *   re-encrypted under the new key. Dropping `legacy` early will cause
-     *   `DecryptionRotationError` on any not-yet-rewritten row.
+     *   re-encrypted under the new key. Once `legacy` is dropped, reading the
+     *   `@Encrypted` property of a row that is still under the old key throws
+     *   `DecryptionError`, the same error a tampered or corrupted value
+     *   throws, so the error class alone cannot show that `legacy` was
+     *   dropped too early. `DecryptionRotationError` is thrown only while
+     *   `legacy` is configured and neither key opens the value. Neither class
+     *   extends the other, so code that catches `DecryptionRotationError`
+     *   during a rotation must also catch `DecryptionError` to handle such a
+     *   read once `legacy` is dropped.
      */
     static generateKey(algorithm: EncryptAlgorithm): string;
     static validateKey(base64EncodedKey: string, algorithm: EncryptAlgorithm): boolean;
@@ -68,6 +128,15 @@ export interface EncryptOptions extends BaseOptions {
 }
 export interface DecryptOptions extends BaseOptions {
 }
+export interface DecryptCallbacks {
+    /**
+     * Called with no arguments, synchronously, before a three-arg
+     * {@link Encrypt.decrypt} returns a value that the legacy key opened.
+     * Never called when the current key opens the value, when decryption
+     * throws, or in the two-arg form.
+     */
+    onLegacyKeyUsed?: () => void;
+}
 interface BaseOptions {
     algorithm: EncryptAlgorithm;
     key: string;

package/dist/types/src/errors/associations/UnrecognizedAssociationConditionKeys.d.ts

@@ -0,0 +1,8 @@
+export default class UnrecognizedAssociationConditionKeys extends Error {
+    private associationName;
+    private unrecognizedKeys;
+    private acceptedKeys;
+    private methodName;
+    constructor(associationName: string, unrecognizedKeys: string[], acceptedKeys: readonly string[], methodName: string | null);
+    get message(): string;
+}

package/dist/types/src/helpers/Env.d.ts

@@ -18,12 +18,40 @@ export default class Env<T extends {
     } | undefined, ReturnType extends OptionalConfig extends undefined ? number : OptionalConfig extends {
         optional: boolean;
     } ? OptionalConfig['optional'] extends true ? number | undefined : number : number>(env: IntegerEnvs, opts?: OptionalConfig): ReturnType;
+    /**
+     * Reads a boolean environment variable. Only the exact string `"1"` is
+     * true. Every other value is false, including `"true"`, `"TRUE"`, `"yes"`
+     * and `""`, and so is an unset variable.
+     *
+     * ```ts
+     * // FEATURE_FLAG=1
+     * AppEnv.boolean('FEATURE_FLAG') // true
+     *
+     * // FEATURE_FLAG=true
+     * AppEnv.boolean('FEATURE_FLAG') // false
+     * ```
+     *
+     * @param env - the name of the environment variable
+     * @returns `true` when the variable is exactly `"1"`, otherwise `false`
+     */
     boolean(env: BooleanEnvs): boolean;
     setString(env: StringEnvs, val: string | undefined): void;
     unsetString(env: StringEnvs): void;
     setInteger(env: IntegerEnvs, val: number | undefined): void;
     unsetInteger(env: IntegerEnvs): void;
+    /**
+     * Sets a boolean environment variable to `"1"`, the only value
+     * {@link Env.boolean} reads as true.
+     *
+     * @param env - the name of the environment variable
+     */
     setBoolean(env: BooleanEnvs): void;
+    /**
+     * Deletes a boolean environment variable. {@link Env.boolean} reads an
+     * unset variable as false, since only the exact string `"1"` is true.
+     *
+     * @param env - the name of the environment variable
+     */
     unsetBoolean(env: BooleanEnvs): void;
     protected required(variable: string): string;
     protected optional(variable: string): string | undefined;

package/dist/types/src/package-exports/openapi.d.ts

@@ -1,2 +1,2 @@
 export { openapiPrimitiveTypes, openapiShorthandPrimitiveTypes } from '../dream/constants.js';
-export { type CommonOpenapiSchemaObjectFields, type OpenapiAllTypes, type OpenapiDescription, type OpenapiFormats, type OpenapiNumberFormats, type OpenapiPrimitiveBaseTypes, type OpenapiPrimitiveTypes, type OpenapiSchemaArray, type OpenapiSchemaArrayShorthand, type OpenapiSchemaBase, type OpenapiSchemaBody, type OpenapiSchemaBodyShorthand, type OpenapiSchemaCommonFields, type OpenapiSchemaExpressionAllOf, type OpenapiSchemaExpressionAnyOf, type OpenapiSchemaExpressionOneOf, type OpenapiSchemaExpressionRef, type OpenapiSchemaExpressionRefSchemaShorthand, type OpenapiSchemaInteger, type OpenapiSchemaNull, type OpenapiSchemaNumber, type OpenapiSchemaObject, type OpenapiSchemaObjectAllOf, type OpenapiSchemaObjectAllOfShorthand, type OpenapiSchemaObjectAnyOf, type OpenapiSchemaObjectAnyOfShorthand, type OpenapiSchemaObjectBase, type OpenapiSchemaObjectBaseShorthand, type OpenapiSchemaObjectOneOf, type OpenapiSchemaObjectOneOfShorthand, type OpenapiSchemaObjectShorthand, type OpenapiSchemaPrimitiveGeneric, type OpenapiSchemaProperties, type OpenapiSchemaPropertiesShorthand, type OpenapiSchemaShorthandExpressionAllOf, type OpenapiSchemaShorthandExpressionAnyOf, type OpenapiSchemaShorthandExpressionOneOf, type OpenapiSchemaShorthandExpressionSerializableRef, type OpenapiSchemaShorthandExpressionSerializerRef, type OpenapiSchemaShorthandPrimitiveGeneric, type OpenapiSchemaString, type OpenapiShorthandAllTypes, type OpenapiShorthandPrimitiveBaseTypes, type OpenapiShorthandPrimitiveTypes, type OpenapiTypeField, type OpenapiTypeFieldObject, } from '../types/openapi.js';
+export { type CommonOpenapiSchemaObjectFields, type OpenapiAllTypes, type OpenapiDescription, type OpenapiFormats, type OpenapiNumberFormats, type OpenapiPrimitiveBaseTypes, type OpenapiPrimitiveTypes, type OpenapiSchemaArray, type OpenapiSchemaArrayShorthand, type OpenapiSchemaBase, type OpenapiSchemaBody, type OpenapiSchemaBodyShorthand, type OpenapiSchemaCombinatorFields, type OpenapiSchemaCommonFields, type OpenapiSchemaExpressionAllOf, type OpenapiSchemaExpressionAnyOf, type OpenapiSchemaExpressionOneOf, type OpenapiSchemaExpressionRef, type OpenapiSchemaExpressionRefSchemaShorthand, type OpenapiSchemaInteger, type OpenapiSchemaNull, type OpenapiSchemaNumber, type OpenapiSchemaObject, type OpenapiSchemaObjectAllOf, type OpenapiSchemaObjectAllOfShorthand, type OpenapiSchemaObjectBase, type OpenapiSchemaObjectBaseShorthand, type OpenapiSchemaObjectShorthand, type OpenapiSchemaPrimitiveGeneric, type OpenapiSchemaProperties, type OpenapiSchemaPropertiesShorthand, type OpenapiSchemaShorthandExpressionAllOf, type OpenapiSchemaShorthandExpressionAnyOf, type OpenapiSchemaShorthandExpressionOneOf, type OpenapiSchemaShorthandExpressionSerializableRef, type OpenapiSchemaShorthandExpressionSerializerRef, type OpenapiSchemaShorthandPrimitiveGeneric, type OpenapiSchemaString, type OpenapiShorthandAllTypes, type OpenapiShorthandPrimitiveBaseTypes, type OpenapiShorthandPrimitiveTypes, type OpenapiTypeField, type OpenapiTypeFieldObject, } from '../types/openapi.js';

package/dist/types/src/package-exports/types.d.ts

@@ -1,5 +1,5 @@
 export { type DecoratorContext } from '../decorators/DecoratorContextType.js';
-export { type EncryptAlgorithm, type EncryptOptions } from '../encrypt/index.js';
+export { type DecryptCallbacks, type EncryptAlgorithm, type EncryptOptions } from '../encrypt/index.js';
 export { type RoundingPrecision } from '../helpers/round.js';
 export { type Camelized, type Hyphenized, type Pascalized, type Snakeified } from '../helpers/stringCasing.js';
 export { type SerializerRendererOpts } from '../serializer/SerializerRenderer.js';
@@ -14,5 +14,5 @@ export { type DurationObject, type DurationUnit, type WeekdayName } from '../typ
 export { type DreamAssociationMetadata, type DreamAttributes, type DreamClassAssociationAndStatement, type DreamClassColumn, type DreamColumn, type DreamColumnNames, type DreamOrViewModelClassSerializerKey, type DreamOrViewModelSerializerKey, type DreamParamSafeAttributes, type DreamParamSafeColumnNames, type DreamSerializable, type DreamSerializableArray, type DreamSerializerKey, type DreamSerializers, type DreamVirtualColumns, type UpdateableAssociationProperties, type UpdateableProperties, type ViewModel, type ViewModelClass, } from '../types/dream.js';
 export { type DreamModelSerializerType, type InternalAnyTypedSerializerRendersMany, type InternalAnyTypedSerializerRendersOne, type SerializerCasing, type SimpleObjectSerializerType, } from '../types/serializer.js';
 export { type ValidationType } from '../types/validation.js';
-export { type DreamAppInitOptions, type DreamAppOpts, type DreamLogger, type DreamLogLevel, type DreamDbConfig, } from '../dream-app/index.js';
+export { type DreamAppInitOptions, type DreamAppOpts, type DreamLogger, type DreamLogLevel, type DreamDbConfig, type EncryptionLegacyKeyUsedEvent, } from '../dream-app/index.js';
 export { type WhereStatementForDream, type WhereStatementForDreamClass, } from '../types/associations/shared.js';

package/dist/types/src/serializer/SerializerRenderer.d.ts

@@ -10,5 +10,18 @@ export default class SerializerRenderer {
     private renderOpts;
     constructor(serializerBuilder: DreamSerializerBuilder<any, any> | ObjectSerializerBuilder<any, any> | null | undefined, passthroughData?: object, { casing }?: SerializerRendererOpts);
     render(): Record<string, any> | null;
+    /**
+     * The keys a flattened `rendersOne` adds to the parent's payload when its associated object is
+     * null: each key any of `serializers` declares, set to `null`. There are several serializers when
+     * the association is a polymorphic BelongsTo, one for each target class, or when the associated
+     * class is an STI base, one for each child, and their keys are unioned.
+     *
+     * Each serializer is built with `undefined` data to read its declarations, as Psychic's OpenAPI
+     * generation and `preloadFor` build it, and nothing is rendered: no attribute callback runs and
+     * no association of the missing object is read. A flattened `rendersOne` it declares adds its
+     * own serializers' keys the same way. A flattened `customAttribute` adds none, since only its
+     * callback knows its keys.
+     */
+    private nullFlattenedAttributes;
     private setCase;
 }