@rvoh/dream 2.21.1 → 2.23.0

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

@@ -256,6 +256,32 @@ export default class QueryDriverBase {
     options = {}) {
         throw new Error('implement takeAll in child class');
     }
+    /**
+     * @internal
+     *
+     * Adapter seam for exclusive row locking. Given the select statement about to
+     * be executed, return a statement that additionally acquires an exclusive
+     * lock on each row it returns, held until the enclosing transaction commits
+     * or rolls back (Postgres: `SELECT ... FOR UPDATE OF <table>`).
+     *
+     * This is only ever reached when a caller opts into a locked read (today,
+     * `Query#destroy({ lock: true })`), and only from inside a transaction. The
+     * base implementation throws so that an adapter which has not implemented row
+     * locking fails loud rather than silently performing an unlocked read and
+     * quietly dropping the compare-and-set guarantee the caller asked for.
+     *
+     * @param kyselyQuery - the select statement to lock
+     * @param tableAlias - the alias of the Query's base table; only rows of that
+     * table are locked, so a joined query does not lock unrelated rows and does
+     * not fail on the nullable side of an outer join
+     */
+    applyRowLock(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    kyselyQuery, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    tableAlias) {
+        throw new Error('implement applyRowLock in child class');
+    }
     /**
      * Retrieves the max value of the specified column
      * for this Query

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

@@ -29,6 +29,9 @@ import MissingThroughAssociationSource from '../../errors/associations/MissingTh
 import CannotNegateSimilarityClause from '../../errors/CannotNegateSimilarityClause.js';
 import CannotNamespaceAssociationFilterToAnotherTable from '../../errors/CannotNamespaceAssociationFilterToAnotherTable.js';
 import CannotPassUndefinedAsAValueToAWhereClause from '../../errors/CannotPassUndefinedAsAValueToAWhereClause.js';
+import ArrayEqualityRequiresArrayColumn from '../../errors/ops/ArrayEqualityRequiresArrayColumn.js';
+import RowLockIncompatibleWithDistinct from '../../errors/RowLockIncompatibleWithDistinct.js';
+import RowLockIncompatibleWithJoinLoad from '../../errors/RowLockIncompatibleWithJoinLoad.js';
 import CheckConstraintViolation from '../../errors/db/CheckConstraintViolation.js';
 import ColumnOverflow from '../../errors/db/ColumnOverflow.js';
 import DataTypeColumnTypeMismatch from '../../errors/db/DataTypeColumnTypeMismatch.js';
@@ -39,6 +42,7 @@ import ASTSchemaBuilder from '../../helpers/cli/ASTSchemaBuilder.js';
 import generateMigration from '../../helpers/cli/generateMigration.js';
 import compact from '../../helpers/compact.js';
 import { normalizeDataForDb } from '../../helpers/db/normalizeDataForDb.js';
+import isDatabaseArrayColumn from '../../helpers/db/types/isDatabaseArrayColumn.js';
 import EnvInternal from '../../helpers/EnvInternal.js';
 import groupBy from '../../helpers/groupBy.js';
 import isEmpty from '../../helpers/isEmpty.js';
@@ -412,9 +416,22 @@ export default class KyselyQueryDriver extends QueryDriverBase {
      * @returns an array of dreams
      */
     async takeAll(options = {}) {
-        if (this.query['joinLoadActivated'])
+        if (this.query['joinLoadActivated']) {
+            // executeJoinLoad builds its own select and has nowhere to put a row
+            // lock, so a locked read here has to fail rather than quietly return
+            // unlocked rows and drop the guarantee the caller asked for
+            if (options.lock)
+                throw new RowLockIncompatibleWithJoinLoad();
             return await this.executeJoinLoad(options);
-        const kyselyQuery = this.buildSelect(options);
+        }
+        // `SELECT DISTINCT ON (...) ... FOR UPDATE` is rejected by the database, so
+        // fail loudly here instead of emitting SQL that cannot run
+        if (options.lock && this.query['distinctColumn'])
+            throw new RowLockIncompatibleWithDistinct();
+        let kyselyQuery = this.buildSelect(options);
+        // row locking is adapter-specific, so it goes through the query driver seam
+        if (options.lock)
+            kyselyQuery = this.applyRowLock(kyselyQuery, this.query['baseSqlAlias']);
         const results = await executeDatabaseQuery(kyselyQuery, 'execute');
         const theAll = results.map(r => this.dbResultToDreamInstance(r, this.dreamClass));
         await this.applyPreload(this.query['preloadStatements'], this.query['preloadOnStatements'], theAll);
@@ -1484,8 +1501,8 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             b = '=';
             c = val;
         }
-        c = this.normalizedWhereValue(dreamClass, attr, c);
-        c2 = this.normalizedWhereValue(dreamClass, attr, c2);
+        c = maybeBindArrayAsSingleValue(dreamClass, a, b, this.normalizedWhereValue(dreamClass, attr, c));
+        c2 = maybeBindArrayAsSingleValue(dreamClass, a2, b2, this.normalizedWhereValue(dreamClass, attr, c2));
         if (a && c === undefined)
             throw new CannotPassUndefinedAsAValueToAWhereClause(this.dreamClass, a);
         if (a2 && c2 === undefined)
@@ -2525,6 +2542,31 @@ export function resolvePostgresSsl(connectionConf) {
         return { rejectUnauthorized: false };
     return false;
 }
+const EQUALITY_OPERATORS_TAKING_A_WHOLE_ARRAY_VALUE = ['=', '!=', '<>'];
+/**
+ * Kysely renders a raw Javascript array passed as the right-hand side of a
+ * comparison as a value list (`($1, $2)`), which is what `in` / `not in` need,
+ * but which Postgres rejects for `=` against an array column
+ * (`operator does not exist: text[] = record`). For the equality operators,
+ * bind the array as a single parameter so that `ops.equal([...])` against an
+ * array column means literal array equality (`"col" = $1`).
+ *
+ * The rewrite is gated on the column actually being a database array column.
+ * An array reaching an equality operator against a *scalar* column is a
+ * mistake, and binding it as a single value would turn that mistake into a
+ * clause that matches nothing (`"name" = '{}'`) instead of one that raises, so
+ * it throws instead.
+ */
+function maybeBindArrayAsSingleValue(dreamClass, column, operator, val) {
+    if (!Array.isArray(val))
+        return val;
+    if (!EQUALITY_OPERATORS_TAKING_A_WHOLE_ARRAY_VALUE.includes(operator))
+        return val;
+    const isolatedColumn = maybeNamespacedColumnNameToColumnName(column ?? '');
+    if (!isDatabaseArrayColumn(dreamClass, isolatedColumn))
+        throw new ArrayEqualityRequiresArrayColumn(dreamClass, isolatedColumn, operator);
+    return sql.val(val);
+}
 function shouldSoftDelete(dream, reallyDestroy) {
     const dreamClass = dream.constructor;
     return dreamClass['softDelete'] && !reallyDestroy;

package/dist/esm/src/dream/QueryDriver/Postgres.js

@@ -198,6 +198,27 @@ export default class PostgresQueryDriver extends KyselyQueryDriver {
         await client.end();
         DreamCLI.logger.logEndProgress();
     }
+    /**
+     * @internal
+     *
+     * Postgres implementation of the row-locking seam: appends
+     * `FOR UPDATE OF "<tableAlias>"` to the select, so every row the statement
+     * returns is exclusively locked until the enclosing transaction ends.
+     *
+     * Scoping the lock to the Query's own base table (rather than a bare
+     * `FOR UPDATE`) means a query that joins other tables neither locks rows the
+     * caller never asked about nor raises Postgres's "FOR UPDATE cannot be
+     * applied to the nullable side of an outer join".
+     *
+     * This is a waiting lock: neither `NOWAIT` nor `SKIP LOCKED` is applied, so a
+     * statement that collides with another transaction's lock blocks until that
+     * transaction ends. Callers that cannot afford an unbounded wait should set a
+     * `lock_timeout` on the connection; see the guarded-destroy notes on
+     * `Query#destroy`.
+     */
+    applyRowLock(kyselyQuery, tableAlias) {
+        return kyselyQuery.forUpdate(tableAlias);
+    }
     static supportsParallelTestDatabases = true;
     /**
      * @internal

package/dist/esm/src/dream/internal/buildSerializerPreloadPaths.js

@@ -1,18 +1,39 @@
-import { inferSerializersFromDreamClassOrViewModelClass } from '../../serializer/helpers/inferSerializerFromDreamOrViewModel.js';
+import { inferSerializersFromDreamClassOrViewModelClassOrFail } from '../../serializer/helpers/inferSerializerFromDreamOrViewModel.js';
 import { RECURSIVE_SERIALIZATION_MAX_REPEATS } from '../constants.js';
 import buildAssociationPaths from './buildAssociationPaths.js';
-import resolveSerializerAssociationEdges from './resolveSerializerAssociationEdges.js';
+import mergeSerializerAssociationEdges from './mergeSerializerAssociationEdges.js';
 export default function buildSerializerPreloadPaths(dreamClass, serializerKey) {
     const key = serializerKey || 'default';
-    const serializer = inferSerializersFromDreamClassOrViewModelClass(dreamClass, key)[0] ?? null;
-    if (!serializer)
-        throw new Error(`unable to find serializer with key: ${key}`);
-    const paths = buildAssociationPaths({
-        dreamClass,
-        serializer,
-    }, {
+    /**
+     * When `dreamClass` is an STI base, this returns one serializer per STI child (deduped), since
+     * each child may register a different serializer under `key`. Every child's serializer has to be
+     * walked: an association rendered only by, say, the alphabetically-last child would otherwise be
+     * missing from the preload set and throw NonLoadedAssociation at render time.
+     */
+    const serializers = inferSerializersFromDreamClassOrViewModelClassOrFail(dreamClass, key);
+    /**
+     * All of the serializers are walked in a *single* traversal, as one node per Dream class carrying
+     * the set of serializers that reach it, rather than one traversal per serializer. A path is a
+     * sequence of [DreamClass, associationName] tuples — it records no serializer — so walking each
+     * serializer separately recomputes the same paths once per route through the graph, which is
+     * exponential in the number of sibling serializers when a serializer cycles back to the STI base.
+     * Merging is exactly equivalent: an edge is emitted from the merged node when *some* serializer in
+     * the set declares it, and every serializer in the set is reachable by a real route with this
+     * path's prefix, so the merged walk emits precisely the paths the per-serializer walks emit after
+     * deduping — with one exception: where one serializer of a class renders no associations and
+     * another renders some, the per-serializer walk also emitted the bare prefix path reached by the
+     * first, which is a strict prefix of a path the second contributes and so preloads nothing extra.
+     * The recursion budget is keyed on the Dream class and counted along the current path, so it is
+     * unaffected by the merge.
+     *
+     * Every tuple emitted at the root of the traversal carries `dreamClass` (the STI base) rather than
+     * the contributing child, both so that identical paths dedupe below and so that a caller's
+     * `modifierFn` keeps receiving the class it was queried on. Tuples emitted deeper in a path carry
+     * the association's target class, which is what `modifierFn` receives for a nested association.
+     */
+    const paths = buildAssociationPaths({ dreamClass, serializers }, {
         getKey: node => node.dreamClass.globalName,
-        getEdges: serializerNodeToEdges,
+        getEdges: memoizedSerializerNodeToEdges(),
         maxRepeats: RECURSIVE_SERIALIZATION_MAX_REPEATS,
     });
     const dedupedPaths = new Map();
@@ -23,16 +44,68 @@ export default function buildSerializerPreloadPaths(dreamClass, serializerKey) {
     }
     return [...dedupedPaths.values()];
 }
-function serializerNodeToEdges({ dreamClass, serializer, }) {
-    const edges = resolveSerializerAssociationEdges(dreamClass, serializer);
-    return edges.flatMap(edge => {
-        const tuple = [dreamClass, edge.associationAs];
-        if (edge.type === 'delegatedAttribute' || edge.targets.length === 0) {
-            return [{ nextNode: null, tuple }];
+/**
+ * `serializerNodeToEdges` is a pure function of the node's (Dream class, ordered serializer set), so
+ * two nodes carrying the same pair have the same edges no matter which route reached them. The
+ * traversal hands `getEdges` a *fresh* node object per edge it descends — the `nextNode`s built
+ * below are new objects every time — so memoizing on the object itself would never hit; the key has
+ * to be the node's contents. Without this the whole merge (resolve every serializer's edges, then
+ * one Map per association and one node object per target class) is rebuilt at every visit, and the
+ * visit count is the number of *routes* through the serializer graph rather than the number of
+ * distinct nodes in it: an STI base whose children render `n` differently-named self-referential
+ * associations visits 1 + n + n² + n³ nodes to reach n⁴ paths, all of them the same one node.
+ *
+ * The serializer identifiers are assigned per call rather than globally so that the key stays short
+ * and so that nothing here holds a serializer alive; identity is all that matters, since the key is
+ * only ever compared against others built in the same call. Order-sensitive on purpose: the merge
+ * is insertion-ordered, so two nodes carrying the same serializers in a different order do not have
+ * the same edges.
+ *
+ * Scoped to a single `buildSerializerPreloadPaths` call for the same reason: it cannot then serve
+ * edges resolved against a stale serializer registry or a not-yet-complete set of STI children.
+ */
+function memoizedSerializerNodeToEdges() {
+    const cache = new Map();
+    const serializerIds = new Map();
+    const serializerId = (serializer) => {
+        let id = serializerIds.get(serializer);
+        if (id === undefined) {
+            id = serializerIds.size;
+            serializerIds.set(serializer, id);
         }
-        return edge.targets.map(target => ({
-            nextNode: target,
-            tuple,
-        }));
+        return id;
+    };
+    return node => {
+        const cacheKey = `${node.dreamClass.globalName}|${node.serializers.map(serializerId).join(',')}`;
+        const cached = cache.get(cacheKey);
+        if (cached !== undefined)
+            return cached;
+        const edges = serializerNodeToEdges(node);
+        cache.set(cacheKey, edges);
+        return edges;
+    };
+}
+/**
+ * `mergeSerializerAssociationEdges` — the single union both serializer walks run on, the other being
+ * `Dream.recursiveSerializationMap`'s display walk — has already resolved every serializer in the
+ * node's set and merged them into one insertion-ordered edge set keyed on (association, target
+ * class). All that is left here is to shed what only the display walk needs (the per-serializer edge
+ * type and serializer-side association name) and turn each merged edge into path edges: a leaf where
+ * some serializer terminates the association, plus one traversal node per target class carrying that
+ * class's serializers.
+ */
+function serializerNodeToEdges({ dreamClass, serializers, }) {
+    return mergeSerializerAssociationEdges(dreamClass, serializers).flatMap(edge => {
+        const tuple = [dreamClass, edge.associationAs];
+        return [
+            ...(edge.terminates ? [{ nextNode: null, tuple }] : []),
+            ...edge.targets.map(target => ({
+                nextNode: {
+                    dreamClass: target.dreamClass,
+                    serializers: target.serializers.map(({ serializer }) => serializer),
+                },
+                tuple,
+            })),
+        ];
     });
 }

package/dist/esm/src/dream/internal/convertDreamClassAndAssociationNameTupleArrayToPreloadArgs.js

@@ -1,15 +1,23 @@
-import compact from '../../helpers/compact.js';
 export default function convertDreamClassAndAssociationNameTupleArrayToPreloadArgs(dreamClassAndAssociationNameTupleArray, modifierFn, counter) {
-    return compact(dreamClassAndAssociationNameTupleArray.flatMap(dreamClassAndAssociationNameTuple => {
+    const preloadArgs = [];
+    for (const dreamClassAndAssociationNameTuple of dreamClassAndAssociationNameTupleArray) {
         const associationName = dreamClassAndAssociationNameTuple[1];
-        const aliasedAssociationName = counter
-            ? `${dreamClassAndAssociationNameTuple[1]} as drsz${counter.count++}`
-            : dreamClassAndAssociationNameTuple[1];
-        if (!modifierFn)
-            return aliasedAssociationName;
+        const aliasedAssociationName = counter ? `${associationName} as drsz${counter.count++}` : associationName;
+        if (!modifierFn) {
+            preloadArgs.push(aliasedAssociationName);
+            continue;
+        }
         const modifier = modifierFn(associationName, dreamClassAndAssociationNameTuple[0]);
+        // omitting an association prunes the entire subtree beneath it: the path is truncated at the
+        // omitted association, keeping the ancestors already accumulated (so the omitted association's
+        // parent is still preloaded) and discarding the remainder, since the surviving tail would be
+        // re-rooted on the class the query was rooted on and preload a different association than the
+        // caller asked for. When the omitted association is the first tuple, this yields an empty list.
         if (modifier === 'omit')
-            return undefined;
-        return [aliasedAssociationName, modifier];
-    }));
+            return preloadArgs;
+        preloadArgs.push(aliasedAssociationName);
+        if (modifier !== undefined && modifier !== null)
+            preloadArgs.push(modifier);
+    }
+    return preloadArgs;
 }

package/dist/esm/src/dream/internal/destroyAssociatedRecords.js

@@ -1,20 +1,69 @@
+import loadDependentDestroyTree from './loadDependentDestroyTree.js';
+/**
+ * @internal
+ *
+ * Marks a Dream instance as one whose `dependent: 'destroy'` associations were
+ * hydrated by this cascade's own call to `loadDependentDestroyTree`, using the
+ * same destroy options the cascade is running under.
+ *
+ * Associations a caller happened to preload themselves (e.g.
+ * `Post.preload('comments')`) are deliberately NOT trusted: they may have been
+ * loaded under different default scopes than the destroy requires — most
+ * importantly, `reallyDestroy` strips the soft-delete scope, so a
+ * caller-preloaded association could be missing soft-deleted records that the
+ * cascade must destroy.
+ */
+const CASCADE_LOADED = Symbol.for('dream:dependentDestroyTreeLoaded');
 /**
  * @internal
  *
  * Destroys all HasOne/HasMany associations on this
  * dream that are marked as `dependent: 'destroy'`.
  *
- * Expects associations to be preloaded onto the dream instance
- * via `loadDependentDestroyTree`. Iterates loaded associations
- * directly instead of querying the database.
+ * The whole dependent-destroy tree is loaded ONCE, at the root of the destroy
+ * operation, by `loadDependentDestroyTree`. Descendants reached by recursing
+ * through this function consume those already-hydrated associations rather
+ * than re-querying their own subtrees.
+ *
+ * A load still happens here when an association is not hydrated. That covers
+ * two cases:
+ *
+ * 1. the root of the operation, whose associations have not been loaded yet
+ * 2. a node past `RECURSIVE_DESTROY_PRELOAD_MAX_REPEATS` levels of
+ *    self-reference, which the root's preload could not reach
+ *
+ * The second case is why the check is per-association-hydration rather than a
+ * "descendants are already loaded" flag: such a flag would truncate cascades
+ * deeper than the preload horizon.
+ *
+ * NOTE: reusing a hydrated subtree is only sound because the same `options`
+ * are forwarded unchanged all the way down the cascade (see the recursive
+ * `destroy`/`reallyDestroy` calls below), so every node's associations were
+ * loaded under the scopes this node would have used. Nothing in the types
+ * enforces that; if `options` ever start varying by depth, this reuse has to
+ * be revisited.
  */
 export default async function destroyAssociatedRecords(dream, txn, options) {
     const dreamClass = dream.constructor;
     const { reallyDestroy } = options;
+    // `loadDependentDestroyTree` hydrates and returns a CLONE rather than
+    // mutating the receiver, so the result must be assigned back — otherwise
+    // each association in the loop below would trigger its own reload.
+    let dreamWithAssociations = dream;
+    let alreadyLoadedTree = false;
     for (const associationName of dreamClass['dependentDestroyAssociationNames']()) {
-        const loaded = dream[associationName];
+        if (!alreadyLoadedTree && !cascadeLoaded(dreamWithAssociations, associationName)) {
+            dreamWithAssociations = await loadDependentDestroyTree(dreamWithAssociations, txn, {
+                reallyDestroy,
+                bypassAllDefaultScopes: options.bypassAllDefaultScopes ?? false,
+                defaultScopesToBypass: options.defaultScopesToBypass ?? [],
+            });
+            alreadyLoadedTree = true;
+        }
+        const loaded = dreamWithAssociations[associationName];
         const records = Array.isArray(loaded) ? loaded : loaded ? [loaded] : [];
         for (const record of records) {
+            markCascadeLoaded(record);
             if (reallyDestroy) {
                 await record.txn(txn).reallyDestroy(options);
             }
@@ -24,3 +73,26 @@ export default async function destroyAssociatedRecords(dream, txn, options) {
         }
     }
 }
+/**
+ * @internal
+ *
+ * True when this dream was hydrated by this cascade's own preload AND the
+ * given association is hydrated on it.
+ */
+function cascadeLoaded(dream, associationName) {
+    if (!dream[CASCADE_LOADED])
+        return false;
+    return dream.loaded(associationName);
+}
+/**
+ * @internal
+ *
+ * A plain assignment rather than `Object.defineProperty`: the key is a symbol,
+ * so it is already excluded from `Object.keys`, `for...in` and
+ * `JSON.stringify` without an explicit descriptor, and this runs once per node
+ * of a potentially wide cascade tree.
+ */
+function markCascadeLoaded(dream) {
+    ;
+    dream[CASCADE_LOADED] = true;
+}

package/dist/esm/src/dream/internal/destroyDream.js

@@ -1,6 +1,5 @@
 import DreamApp from '../../dream-app/index.js';
 import destroyAssociatedRecords from './destroyAssociatedRecords.js';
-import loadDependentDestroyTree from './loadDependentDestroyTree.js';
 import runHooksFor from './runHooksFor.js';
 /**
  * @internal
@@ -31,12 +30,12 @@ export default async function destroyDream(dream, txn = null, options) {
 async function destroyDreamWithTransaction(dream, txn, options) {
     const { cascade, reallyDestroy, skipHooks } = options;
     if (cascade) {
-        const dreamWithAssociations = await loadDependentDestroyTree(dream, txn, {
-            reallyDestroy,
-            bypassAllDefaultScopes: options.bypassAllDefaultScopes ?? false,
-            defaultScopesToBypass: options.defaultScopesToBypass ?? [],
-        });
-        await destroyAssociatedRecords(dreamWithAssociations, txn, options);
+        // NOTE: the dependent-destroy tree is loaded lazily, inside
+        // destroyAssociatedRecords, so that a cascaded descendant whose
+        // associations the root already preloaded does not re-query its own
+        // subtree. `dream` itself is intentionally never replaced by the loaded
+        // clone: the hooks and the delete below operate on the original.
+        await destroyAssociatedRecords(dream, txn, options);
     }
     if (!skipHooks) {
         await runHooksFor('beforeDestroy', dream, true, null, txn);

package/dist/esm/src/dream/internal/mergeSerializerAssociationEdges.js

@@ -0,0 +1,75 @@
+import resolveSerializerAssociationEdges from './resolveSerializerAssociationEdges.js';
+/**
+ * @internal
+ *
+ * Resolves the association edges of *every* serializer that can render `dreamClass` at this point
+ * in a serialization walk and merges them into one set, so that a walk rooted at an STI base sees
+ * the union across its children's serializers rather than one child's view of the class.
+ *
+ * The merge is keyed on (association, target class), so:
+ *
+ * - an association several children render identically (all three `stiUnion` serializers render
+ *   `sandbags`) collapses to a single edge with a single target, rather than repeating per child;
+ * - a polymorphic association keeps one target per target class
+ *   (`Polymorphic/Task#taskable` → `Chore` and `Workout`), which is a real distinction, not a
+ *   duplicate;
+ * - an association only some children render (`heartRatings`, rendered only by Latex's `stiUnion`
+ *   serializer) is present exactly once.
+ *
+ * Grouping the serializers *under* the target rather than emitting one target per serializer is
+ * what lets a caller recurse once per target class with the full set, so nested trees from
+ * different children of the same target merge instead of clobbering one another.
+ *
+ * Insertion-ordered throughout, so edges come back in the order the serializers declare them.
+ *
+ * This is the single union both serializer walks run on: `buildSerializerPreloadPaths` turns these
+ * edges into preload paths (taking `terminates` and the target classes, ignoring the per-serializer
+ * edge type and serializer-side name), and `Dream.recursiveSerializationMap` prints them (taking the
+ * per-serializer edge type and name, ignoring `terminates`). Keeping the two walks on one merge is the point: the bug
+ * this exists to prevent is `psy i:serialization` and `preloadFor` disagreeing about which
+ * associations a serializer key reaches, which a second hand-maintained merge invites back.
+ */
+export default function mergeSerializerAssociationEdges(dreamClass, serializers) {
+    /**
+     * Each target carries a Set mirroring its `serializers`, so the identity dedupe below is a lookup
+     * rather than a scan of the array. Dropped when the merged edges are built at the end.
+     */
+    const mergedEdges = new Map();
+    for (const serializer of serializers) {
+        for (const edge of resolveSerializerAssociationEdges(dreamClass, serializer)) {
+            let mergedEdge = mergedEdges.get(edge.associationAs);
+            if (mergedEdge === undefined) {
+                mergedEdge = { terminates: false, targets: new Map() };
+                mergedEdges.set(edge.associationAs, mergedEdge);
+            }
+            if (edge.targets.length === 0) {
+                mergedEdge.terminates = true;
+                continue;
+            }
+            for (const target of edge.targets) {
+                const targetKey = target.dreamClass.globalName;
+                const mergedTarget = mergedEdge.targets.get(targetKey);
+                const targetSerializer = {
+                    serializer: target.serializer,
+                    type: edge.type,
+                    serializerAssociationName: edge.serializerAssociationName,
+                };
+                if (mergedTarget === undefined) {
+                    mergedEdge.targets.set(targetKey, {
+                        target: { dreamClass: target.dreamClass, serializers: [targetSerializer] },
+                        serializerSet: new Set([target.serializer]),
+                    });
+                }
+                else if (!mergedTarget.serializerSet.has(target.serializer)) {
+                    mergedTarget.serializerSet.add(target.serializer);
+                    mergedTarget.target.serializers.push(targetSerializer);
+                }
+            }
+        }
+    }
+    return [...mergedEdges.entries()].map(([associationAs, { terminates, targets }]) => ({
+        associationAs,
+        terminates,
+        targets: [...targets.values()].map(({ target }) => target),
+    }));
+}

package/dist/esm/src/dream/internal/printSerializerHierarchyLevel.js

@@ -1,16 +1,58 @@
 import yoctocolors from 'yoctocolors';
 import { indent } from '../../helpers/indent.js';
-export default function printSerializerHierarchyLevel({ serializerAssociationType, serializerAssociationName, associationSerializer, forDisplayDepth, }) {
+/**
+ * @internal
+ *
+ * Prints one level of `psy i:serialization`'s tree: the heading for an association, then the name
+ * of every serializer that renders the target of that association at this point in the walk. That
+ * is more than one serializer when the target is an STI base, since each child may register a
+ * different serializer under the same key.
+ *
+ * Those serializers are printed under a *single* heading rather than one heading each, because the
+ * caller prints the union of their association trees below, indented one level in from the
+ * heading. Repeating the heading per serializer would leave that union sitting directly beneath
+ * whichever child's serializer happened to print last, reading as though every sibling's
+ * associations belonged to that one child. Grouped, the shape matches what `displaySerialization`
+ * prints at the root of the tree — one name, then every serializer that can render it, then one
+ * merged tree.
+ *
+ * A target reached under more than one edge type or serializer-side name (two children of an STI
+ * base rendering the same class through `rendersOne` and `rendersMany`, say) gets one heading per
+ * distinct (type, name), since those are genuinely different lines rather than repetitions of one.
+ */
+export default function printSerializerHierarchyLevel({ targetSerializers, forDisplayDepth, }) {
     const hierarchyLine = '└───';
     const indentation = indent((hierarchyLine.length + 1) * forDisplayDepth, {
         tabWidth: 1,
     });
     const prefix = `${hierarchyLine} `;
-    const nestedAssociationDisplay = indentation + `${prefix}${serializerAssociationType} ${yoctocolors.cyan(serializerAssociationName)}`;
-    // eslint-disable-next-line no-console
-    console.log(nestedAssociationDisplay);
-    // eslint-disable-next-line no-console
-    console.log(yoctocolors.gray(indentation +
-        indent(prefix.length, { tabWidth: 1 }) +
-        associationSerializer.globalName));
+    groupByHeading(targetSerializers).forEach(({ type, serializerAssociationName, serializers }) => {
+        // eslint-disable-next-line no-console
+        console.log(indentation + `${prefix}${type} ${yoctocolors.cyan(serializerAssociationName)}`);
+        serializers.forEach(serializer => {
+            // eslint-disable-next-line no-console
+            console.log(yoctocolors.gray(indentation +
+                indent(prefix.length, { tabWidth: 1 }) +
+                serializer.globalName));
+        });
+    });
+}
+/**
+ * Collects the serializers rendering a single merged target into one entry per heading they print
+ * under — (edge type, serializer-side association name) — preserving the order the serializers
+ * were merged in.
+ */
+function groupByHeading(targetSerializers) {
+    const headings = new Map();
+    for (const { serializer, type, serializerAssociationName } of targetSerializers) {
+        const headingKey = `${type}:${serializerAssociationName}`;
+        const heading = headings.get(headingKey);
+        if (heading === undefined) {
+            headings.set(headingKey, { type, serializerAssociationName, serializers: [serializer] });
+        }
+        else {
+            heading.serializers.push(serializer);
+        }
+    }
+    return [...headings.values()];
 }