@rvoh/dream 2.24.1 → 2.26.0

package/dist/cjs/src/serializer/helpers/inferSerializerFromDreamOrViewModel.js

@@ -9,33 +9,51 @@ import expandStiClasses from '../../helpers/sti/expandStiClasses.js';
 import uniq from '../../helpers/uniq.js';
 import isDreamSerializer from './isDreamSerializer.js';
 export const DEFAULT_SERIALIZER_KEY = 'default';
-export default function inferSerializerFromDreamOrViewModel(obj, serializerKey = DEFAULT_SERIALIZER_KEY) {
+/**
+ * `resolutionContext` says how resolution reached `obj` — the `rendersOne`/`rendersMany` edge that
+ * led here, and the STI base it was expanded from. It is threaded down purely so that the errors
+ * below can name the route instead of only the class, and it is optional so that a caller with no
+ * route to describe (and every existing caller outside this repo) is unaffected. See
+ * `SerializerResolutionContext`.
+ */
+export default function inferSerializerFromDreamOrViewModel(obj, serializerKey = DEFAULT_SERIALIZER_KEY, resolutionContext) {
     if (!obj)
         return null;
     const serializers = obj.serializers;
     if (!serializers)
-        throw new MissingSerializersDefinition(obj);
+        throw new MissingSerializersDefinition(obj, serializerKey, resolutionContext);
     const serializerOrGlobalName = serializers[serializerKey];
     if (!serializerOrGlobalName)
-        throw new MissingSerializersDefinitionForKey(obj, serializerKey);
+        throw new MissingSerializersDefinitionForKey(obj, serializerKey, resolutionContext);
     if (isDreamSerializer(serializerOrGlobalName))
         return serializerOrGlobalName;
     const globalName = serializerOrGlobalName;
     const dreamApp = DreamApp.getOrFail();
     const serializer = dreamApp.serializers[globalName];
     if (!serializer)
-        throw new NoGlobalSerializerForSpecifiedKey(obj, serializerKey, globalName);
+        throw new NoGlobalSerializerForSpecifiedKey(obj, serializerKey, globalName, resolutionContext);
     if (!isDreamSerializer(serializer))
-        throw new NonDreamSerializerDerivedFromGlobalSerializerForSpecifiedKey(obj, serializerKey, globalName, serializer);
+        throw new NonDreamSerializerDerivedFromGlobalSerializerForSpecifiedKey(obj, serializerKey, globalName, serializer, resolutionContext);
     return serializer;
 }
-export function inferSerializersFromDreamClassOrViewModelClass(classDef, serializerKey = undefined) {
+export function inferSerializersFromDreamClassOrViewModelClass(classDef, serializerKey = undefined, resolutionContext) {
     if (!classDef)
         return [];
     const classes = expandStiClasses(classDef);
-    const serializers = classes.map(classDef => inferSerializerFromDreamOrViewModel(classDef.prototype, serializerKey));
+    // This is the one place that knows *whether* the class an error ends up naming came from STI
+    // expansion: below this line the class the caller passed is gone, replaced by one child per
+    // iteration, and every downstream error names a child. Identity rather than `isSTIBase` because
+    // `classDef` may be a ViewModelClass, which `expandStiClasses` hands straight back.
+    const expandedFromStiBase = classes.length !== 1 || classes[0] !== classDef;
+    const childResolutionContext = expandedFromStiBase
+        ? { ...resolutionContext, stiBase: stiBaseName(classDef) }
+        : resolutionContext;
+    const serializers = classes.map(classDef => inferSerializerFromDreamOrViewModel(classDef.prototype, serializerKey, childResolutionContext));
     return uniq(compact(serializers));
 }
+function stiBaseName(classDef) {
+    return classDef.sanitizedName ?? classDef.name;
+}
 /**
  * As `inferSerializersFromDreamClassOrViewModelClass`, but guarantees a non-empty result.
  *
@@ -51,9 +69,9 @@ export function inferSerializersFromDreamClassOrViewModelClass(classDef, seriali
  * preload-path building and serialization display — so that they raise one typed error between
  * them.
  */
-export function inferSerializersFromDreamClassOrViewModelClassOrFail(classDef, serializerKey) {
-    const serializers = inferSerializersFromDreamClassOrViewModelClass(classDef, serializerKey);
+export function inferSerializersFromDreamClassOrViewModelClassOrFail(classDef, serializerKey, resolutionContext) {
+    const serializers = inferSerializersFromDreamClassOrViewModelClass(classDef, serializerKey, resolutionContext);
     if (serializers.length === 0)
-        throw new NoSerializersResolvedForKey(classDef, serializerKey);
+        throw new NoSerializersResolvedForKey(classDef, serializerKey, resolutionContext);
     return serializers;
 }

package/dist/cjs/src/serializer/helpers/serializerForAssociatedClass.js

@@ -28,5 +28,10 @@ export function serializerForAssociatedClass(object, associationName, options) {
     // would flatten. Unioning every child's serializer here — which is what buildSerializerPreloadPaths
     // does for preload paths — is meaningless: exactly one set of keys can be flattened into the
     // payload.
-    return inferSerializersFromDreamClassOrViewModelClass(associatedClass, options.serializerKey)[0] ?? null;
+    return (inferSerializersFromDreamClassOrViewModelClass(associatedClass, options.serializerKey, {
+        // Reached only from SerializerRenderer's rendersOne branch, so the edge type is fixed. No
+        // declaring serializer: the renderer holds the rendered attribute, not the serializer that
+        // declared it.
+        edge: { type: 'rendersOne', associationName },
+    })[0] ?? null);
 }

package/dist/cjs/src/serializer/helpers/serializerGlobalName.js

@@ -0,0 +1,16 @@
+/**
+ * @internal
+ *
+ * The single reader of a serializer's `globalName`.
+ *
+ * Serializers are plain functions; `globalName` is stamped onto them by `importSerializers` when the
+ * app loads them, so the property is not on any serializer type and every reader would otherwise
+ * have to invent its own cast — three different spellings of it existed before this helper.
+ *
+ * `undefined` is a legitimate answer: a serializer built inline (a spec, or a `{ serializer }`
+ * option) is never stamped. Callers decide what that means for them — the resolution-context message
+ * simply drops the declarer.
+ */
+export default function serializerGlobalName(serializer) {
+    return serializer.globalName;
+}

package/dist/esm/src/Dream.js

@@ -49,6 +49,7 @@ import cloneDeepSafe from './helpers/cloneDeepSafe.js';
 import isJsonColumn from './helpers/db/types/isJsonColumn.js';
 import notEqual from './helpers/notEqual.js';
 import { inferSerializersFromDreamClassOrViewModelClassOrFail } from './serializer/helpers/inferSerializerFromDreamOrViewModel.js';
+import serializerGlobalName from './serializer/helpers/serializerGlobalName.js';
 export default class Dream {
     DB;
     /**
@@ -580,8 +581,10 @@ export default class Dream {
         // One line per serializer: for an STI base the displayed tree is the union across its children,
         // so naming a single child's serializer under the base's own name would misattribute the tree.
         serializers.forEach(serializer => {
+            // Interpolated rather than defaulted so the printed line is unchanged for a serializer with no
+            // globalName; naming inline serializers in this tree is its own change.
             // eslint-disable-next-line no-console
-            console.log(yoctocolors.gray(serializer.globalName));
+            console.log(yoctocolors.gray(`${serializerGlobalName(serializer)}`));
         });
         return this.recursiveSerializationMap(serializers, {
             forDisplay: true,
@@ -667,6 +670,12 @@ export default class Dream {
      *   * foreign key fields for belongs to associations (these should usually be verified before being set)
      *   * type fields corresponding to polymorphic associations
      *
+     * @internal
+     *
+     * Not part of the public API. Psychic reaches it through the bracketed
+     * back-door (`dreamClass['paramSafeColumnsOrFallback']()`), the same escape
+     * hatch used for other Dream internals such as `virtualAttributes`.
+     *
      * @returns A subset of columns for the given dream class
      */
     static paramSafeColumnsOrFallback() {

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

@@ -5,6 +5,7 @@ import DreamApp from '../dream-app/index.js';
 import Encrypt from '../encrypt/index.js';
 import SspawnRequiresDevelopmentOrTest from '../errors/SspawnRequiresDevelopmentOrTest.js';
 import generateDream from '../helpers/cli/generateDream.js';
+import syncWithFailureContext from '../helpers/cli/syncWithFailureContext.js';
 import EnvInternal from '../helpers/EnvInternal.js';
 import loadRepl from '../helpers/loadRepl.js';
 import DreamCliLogger from './logger/DreamCliLogger.js';
@@ -129,7 +130,9 @@ ${INDENT}  create-many-to-many-posts-users         # WRONG: selects 'many_posts_
 ${INDENT}    # -to- inside "many-to-many" matches: with no columns
 ${INDENT}    # this errors; with columns it silently scaffolds it
 ${INDENT}  create-posts-users-join-table           # correct: no marker match
-${INDENT}    # scaffolds alterTable('<table-name>') to hand-edit`;
+${INDENT}    # with no columns, generates empty up/down methods to
+${INDENT}    # write by hand; with columns, scaffolds
+${INDENT}    # alterTable('<table-name>') to hand-edit`;
 export default class DreamCLI {
     /**
      * Starts the Dream console
@@ -184,7 +187,9 @@ ${INDENT}  # Remove columns (include -from-<table_name>; columns are described w
 ${INDENT}  # their types, same shorthand as -to-, so the rollback (down) can recreate them)
 ${INDENT}  pnpm psy g:migration remove-legacy-fields-from-posts legacy_status:string
 ${INDENT}
-${INDENT}  # General schema change (no -to-/-from- marker — scaffolds alterTable('<table-name>') to hand-edit)
+${INDENT}  # General schema change (no -to-/-from- marker — with no columns, generates
+${INDENT}  # empty up/down methods to write by hand; with columns, scaffolds
+${INDENT}  # alterTable('<table-name>') to hand-edit)
 ${INDENT}  pnpm psy g:migration create-unique-index-on-invitations`)
             .argument('<migrationName>', migrationNameArgumentDescription)
             .option('--connection-name <connectionName>', 'the database connection to use for this migration. Only needed for multi-database setups; defaults to "default"')
@@ -345,7 +350,11 @@ ${INDENT}  pnpm psy db:migrate`)
             await initializeDreamApp({ bypassDreamIntegrityChecks: true });
             await DreamBin.dbMigrate();
             if (EnvInternal.isTest && !skipSync) {
-                await DreamBin.sync(onSync);
+                await syncWithFailureContext({
+                    commandName: 'db:migrate',
+                    completedWork: 'Every pending migration ran successfully',
+                    recoveryAdvice: 'run `sync` on its own, or re-run `db:migrate` — the migrations it already applied are not re-applied, so it goes straight back to the sync',
+                }, async () => await DreamBin.sync(onSync));
             }
             process.exit();
         });
@@ -362,7 +371,13 @@ ${INDENT}  pnpm psy db:rollback --steps=3    # rolls back the last 3 migrations`
             await initializeDreamApp({ bypassDreamIntegrityChecks: true });
             await DreamBin.dbRollback({ steps });
             if (EnvInternal.isTest && !skipSync) {
-                await DreamBin.sync(onSync);
+                await syncWithFailureContext({
+                    commandName: 'db:rollback',
+                    completedWork: 'The rollback completed successfully and is already committed',
+                    // never `re-run db:rollback` here: the rollback is already
+                    // committed, so a second run rolls back a further migration
+                    recoveryAdvice: 'run `sync` on its own. Do not re-run `db:rollback` — the rollback it would perform is a further one, undoing a migration you did not ask to undo',
+                }, async () => await DreamBin.sync(onSync));
             }
             process.exit();
         });
@@ -409,7 +424,18 @@ ${INDENT}Warning: all existing data will be lost. The seed file (db/seed.ts) wil
                 logPrefix: ' ',
                 logPrefixColor: 'green',
             });
-            await DreamBin.sync(onSync);
+            await syncWithFailureContext({
+                commandName: 'db:reset',
+                completedWork: 'db:drop, db:create and db:migrate all completed successfully',
+                didNotRun: 'db:seed, which db:reset runs after the sync, did not run',
+                // the two routes are not interchangeable, so the second one names
+                // the env var it needs: db:reset seeds by calling the app's seed
+                // hook directly (below), while the `db:seed` *command* refuses to
+                // seed under NODE_ENV=test unless DREAM_SEED_DB_IN_TEST=1 — and
+                // NODE_ENV=test is the only environment DreamBin.sync does any
+                // work in, so it is the only environment this advice is printed in
+                recoveryAdvice: 're-run `db:reset`, which seeds directly and so picks up the skipped seeding step, or run `sync` on its own followed by `DREAM_SEED_DB_IN_TEST=1 db:seed` — this sync only runs under `NODE_ENV=test`, and a bare `db:seed` does not seed there',
+            }, async () => await DreamBin.sync(onSync));
             DreamCLI.logger.log(arrows, { logPrefix: ' ' });
             DreamCLI.logger.log(colorize('db:seed', { color: 'green' }), {
                 logPrefix: ' ',

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

@@ -1,5 +1,6 @@
 import { sql } from 'kysely';
 import InternalEncrypt from '../../encrypt/InternalEncrypt.js';
+import DropEnumValueRetypeFailed, { quotedRelationName, } from '../../errors/DropEnumValueRetypeFailed.js';
 export default class DreamMigrationHelpers {
     /**
      * Rename a table and its associated primary key index and sequence.
@@ -169,14 +170,29 @@ export default class DreamMigrationHelpers {
      * @param __namedParameters.replacements - Details about which table and column to change and which value to replace the dropped value with (or remove it if the column is an array)
      */
     static async dropEnumValue(db, { enumName, value, replacements }) {
+        // Read the check constraints on every replacement column up front, before anything is
+        // retyped. They are only ever *used* from the catch blocks below, but they cannot be read
+        // from there: dropEnumValue runs inside a migration transaction (runMigration.ts routes any
+        // migration mentioning it through `newTransaction`), and once a statement in a transaction
+        // block errors, Postgres aborts the block and fails every subsequent statement with
+        // `25P02 current transaction is aborted`. A pg_constraint SELECT issued from a catch block
+        // would therefore throw itself and bury the very error we are trying to explain.
+        const checkConstraintsByPosition = await checkConstraintsOnColumns(db, replacements);
         // temporarily set all table columns depending on this enum to an acceptable alternate type
-        for (const tableAndColumnToChange of replacements) {
+        for (const [position, tableAndColumnToChange] of replacements.entries()) {
             const tableAndColumnToChangeAsArray = tableAndColumnToChange;
             const isArray = tableAndColumnToChangeAsArray.array || false;
-            await db.schema
+            await retypeOrExplain(() => db.schema
                 .alterTable(tableAndColumnToChange.table)
                 .alterColumn(tableAndColumnToChange.column, col => col.setDataType(computedTemporaryType(isArray)))
-                .execute();
+                .execute(), {
+                enumName,
+                value,
+                table: tableAndColumnToChange.table,
+                column: tableAndColumnToChange.column,
+                retypeDirection: 'toText',
+                ...constraintContextFor(checkConstraintsByPosition, position),
+            });
         }
         // collect enum values before dropping type
         const allEnumValues = await getEnumValues(db, enumName);
@@ -187,15 +203,23 @@ export default class DreamMigrationHelpers {
             .createType(enumName)
             .asEnum(allEnumValues.filter(val => val !== value))
             .execute();
-        for (const tableAndColumnToChange of replacements) {
+        for (const [position, tableAndColumnToChange] of replacements.entries()) {
             const isArray = tableAndColumnToChange.array || false;
+            const retypeContext = {
+                enumName,
+                value,
+                table: tableAndColumnToChange.table,
+                column: tableAndColumnToChange.column,
+                retypeDirection: 'toEnum',
+                ...constraintContextFor(checkConstraintsByPosition, position),
+            };
             if (isArray) {
                 await replaceArrayValues(db, value, tableAndColumnToChange);
-                await updateTableColumnToNewEnumArrayType(db, enumName, tableAndColumnToChange);
+                await retypeOrExplain(() => updateTableColumnToNewEnumArrayType(db, enumName, tableAndColumnToChange), retypeContext);
             }
             else {
                 await replaceNonArrayValues(db, value, tableAndColumnToChange);
-                await updateTableColumnToNewEnumType(db, enumName, tableAndColumnToChange);
+                await retypeOrExplain(() => updateTableColumnToNewEnumType(db, enumName, tableAndColumnToChange), retypeContext);
             }
         }
     }
@@ -330,6 +354,103 @@ export default class DreamMigrationHelpers {
         }
     }
 }
+/**
+ * Run one of dropEnumValue's internal column retypes, and on failure re-raise it as a
+ * {@link DropEnumValueRetypeFailed} naming the table, the column and the check constraints
+ * that were read before any retype ran. The original error is kept reachable underneath.
+ *
+ * A caught throwable is normalized to an `Error` rather than cast to one: the error's
+ * message getter dereferences `originalError.message`, so a driver (or a mock) that rejects
+ * with a non-Error would otherwise blow up inside the getter and destroy the very
+ * diagnostic this wrapping exists to produce.
+ */
+async function retypeOrExplain(retype, context) {
+    try {
+        await retype();
+    }
+    catch (error) {
+        throw new DropEnumValueRetypeFailed({
+            ...context,
+            originalError: error instanceof Error ? error : new Error(String(error)),
+        });
+    }
+}
+/**
+ * The check constraints defined on each replacement's column, indexed by the replacement's
+ * position in `replacements` (both of dropEnumValue's loops walk the same array in order, so
+ * the position identifies a replacement exactly and no key string has to be kept in sync).
+ *
+ * Position, rather than the replacement object, because the same object may legitimately
+ * appear at two positions — `const r = {...}; replacements: [r, r]` — and a Map keyed on the
+ * object would collapse those two entries onto one, reporting each column's constraints twice
+ * and emitting a duplicated dropConstraint line for every one of them.
+ *
+ * One catalog query covers every replacement: the (relation, column) pairs are passed as two
+ * arrays and unnested `WITH ORDINALITY`, so each row carries the 1-based position of the
+ * replacement it belongs to. Issuing one query per replacement would cost a round trip per
+ * column on every successful `dropEnumValue`, and Kysely serializes them all on the
+ * migration's single connection.
+ *
+ * `relationResolved` is selected separately from the constraints, because "the table has no
+ * check constraints" and "the table name did not resolve" both produce zero constraint rows
+ * and the error message must not confuse the two.
+ *
+ * `to_regclass` rather than a `::regclass` cast so that an unknown table yields no rows
+ * instead of throwing, leaving the retype itself to report a missing table exactly as it
+ * does today. The name handed to it is quoted per segment, because Kysely quotes the
+ * identifiers it emits (`alterTable('MixedCase')` -> `"MixedCase"`) while an unquoted
+ * `to_regclass` argument case-folds and would silently miss every non-lowercase table.
+ *
+ * The selected aliases are deliberately single words: a `CamelCasePlugin` on the connection
+ * rewrites result keys, and `ord`/`resolved`/`name`/`definition` survive that rewrite
+ * unchanged.
+ */
+async function checkConstraintsOnColumns(db, replacements) {
+    const byPosition = replacements.map(() => ({
+        relationResolved: false,
+        checkConstraints: [],
+    }));
+    if (replacements.length === 0)
+        return byPosition;
+    const relationNames = replacements.map(replacement => quotedRelationName(replacement.table));
+    const columnNames = replacements.map(replacement => replacement.column);
+    const response = await sql `
+    SELECT
+      t.ord::int AS ord,
+      (to_regclass(t.relname) IS NOT NULL) AS resolved,
+      con.name AS name,
+      con.definition AS definition
+    FROM unnest(${relationNames}::text[], ${columnNames}::text[])
+      WITH ORDINALITY AS t(relname, colname, ord)
+    LEFT JOIN LATERAL (
+      SELECT c.conname AS name, pg_get_constraintdef(c.oid) AS definition
+      FROM pg_constraint c
+      JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = ANY(c.conkey)
+      WHERE c.contype = 'c'
+        AND c.conrelid = to_regclass(t.relname)
+        AND a.attname = t.colname
+    ) con ON true
+    ORDER BY t.ord, con.name
+  `.execute(db);
+    for (const row of response.rows) {
+        const entry = byPosition[Number(row.ord) - 1];
+        if (entry === undefined)
+            continue;
+        entry.relationResolved = row.resolved;
+        if (row.name !== null && row.definition !== null) {
+            entry.checkConstraints.push({ name: row.name, definition: row.definition });
+        }
+    }
+    return byPosition;
+}
+/**
+ * The constraint metadata for the replacement at `position`. A position with no entry (which
+ * cannot happen today, but would be a silent lie if it did) reads as "not read", never as
+ * "none defined".
+ */
+function constraintContextFor(byPosition, position) {
+    return byPosition[position] ?? { relationResolved: false, checkConstraints: [] };
+}
 async function getEnumValues(db, enumName) {
     const response = await sql `SELECT unnest(enum_range(NULL::${sql.raw(enumName)}))`.execute(db);
     return response.rows.map(row => row.unnest);