@rvoh/dream 2.22.0 → 2.24.0

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

@@ -1,19 +1,78 @@
-import MissingSerializersDefinition from '../../errors/serializers/MissingSerializersDefinition.js';
 import compact from '../../helpers/compact.js';
 import { inferSerializersFromDreamClassOrViewModelClass } from '../../serializer/helpers/inferSerializerFromDreamOrViewModel.js';
+/**
+ * Keyed on the two arguments. Weak on both, so an entry is collectable once either the Dream class
+ * or the serializer is. The cached arrays are handed out by reference and must be treated as
+ * read-only by callers.
+ */
+let resolvedEdgesCache = new WeakMap();
+/**
+ * @internal
+ *
+ * Drops every memoized edge set. Only needed when a class object that stays in the process has its
+ * `serializers` getter replaced, which the memo cannot detect — specs that install or remove one
+ * around an example. Replacing the model classes themselves needs no call, since the memo keys on
+ * the class and serializer objects and entries resolved against the previous ones become
+ * unreachable.
+ */
+export function clearResolvedSerializerAssociationEdgesCache() {
+    resolvedEdgesCache = new WeakMap();
+}
+/**
+ * @internal
+ *
+ * Resolves the rendersOne/rendersMany/delegatedAttribute attributes of `serializer` to the
+ * associations of `dreamClass` they preload, along with the classes and serializers each one
+ * targets.
+ *
+ * Memoized on its two arguments, because every call rebuilds a throwaway serializer builder and
+ * re-infers the serializers of every association target, and the traversal in
+ * buildSerializerPreloadPaths revisits the same (class, serializer) pair many times.
+ *
+ * The two arguments are not the function's only inputs, though: resolving a target's serializers
+ * also reads that target's `serializers` getter, the STI children registered on it, and the
+ * DreamApp serializer registry. Loading a fresh set of classes replaces the keys along with that
+ * state, so the memo follows it. Mutating a `serializers` getter in place does not, and needs
+ * `clearResolvedSerializerAssociationEdgesCache` — see there.
+ */
 export default function resolveSerializerAssociationEdges(dreamClass, serializer) {
+    let cachedForDreamClass = resolvedEdgesCache.get(dreamClass);
+    if (cachedForDreamClass === undefined) {
+        cachedForDreamClass = new WeakMap();
+        resolvedEdgesCache.set(dreamClass, cachedForDreamClass);
+    }
+    const cached = cachedForDreamClass.get(serializer);
+    if (cached !== undefined)
+        return cached;
+    const edges = buildSerializerAssociationEdges(dreamClass, serializer);
+    cachedForDreamClass.set(serializer, edges);
+    return edges;
+}
+function buildSerializerAssociationEdges(dreamClass, serializer) {
     const serializerBuilder = serializer(undefined, undefined);
     const serializerAssociations = serializerBuilder['attributes'].filter(attribute => ['rendersOne', 'rendersMany', 'delegatedAttribute'].includes(attribute.type));
     return compact(serializerAssociations.map(serializerAssociation => {
         const serializerAssociationName = serializerAssociation.targetName ??
             serializerAssociation.name;
+        // `dreamClass` is the class the walk is rooted at, which for an STI base is the base itself
+        // even while `serializer` is one child's serializer. That pairing is safe because an STI child
+        // cannot declare associations of its own — the `STI` class decorator throws
+        // StiChildCannotDefineNewAssociations — so every association a child's serializer can render
+        // is declared on the base and resolves here.
+        //
+        // The one hole: that guard reads decorator metadata and
+        // `associationDeclarationNamesFromMetadata` returns [] when the metadata is absent, which is
+        // also what happens when the `STI` decorator runs without a `context`. Under a TS config that
+        // does not emit decorator metadata the guard silently passes, a child-declared association
+        // survives, and it is dropped *here*, silently, by the return below — the symptom is then a
+        // missing preload and a NonLoadedAssociation at render, not a decorator error naming the real
+        // problem.
         const association = dreamClass['getAssociationMetadata'](serializerAssociationName);
         if (!association)
             return null;
         if (serializerAssociation.type === 'delegatedAttribute') {
             return {
                 associationAs: association.as,
-                sourceDreamClass: dreamClass,
                 type: serializerAssociation.type,
                 serializerAssociationName,
                 targets: [],
@@ -26,17 +85,24 @@ export default function resolveSerializerAssociationEdges(dreamClass, serializer
             ? maybeAssociatedClasses
             : [maybeAssociatedClasses];
         const targets = associatedClasses.flatMap(associatedClass => {
-            let serializers = [];
-            try {
-                serializers = serializerAssociation.options.serializer
-                    ? compact([serializerAssociation.options.serializer])
-                    : compact(inferSerializersFromDreamClassOrViewModelClass(associatedClass, serializerAssociation.options.serializerKey));
-            }
-            catch (error) {
-                if (!(error instanceof MissingSerializersDefinition))
-                    throw error;
-                serializers = [];
-            }
+            // Deliberately unguarded: every serializer that cannot be resolved while building preload
+            // paths throws, and there is no tolerance here by design.
+            //
+            // Why: an unresolvable serializer is a configuration error, and the first query that walks
+            // the serializer graph is where it should be found — no rows, no rendering required.
+            // Swallowing it means the only way to discover a broken `serializerKey` (or a missing
+            // `serializers` getter) is a spec that creates a row of the affected class *and* renders it.
+            //
+            // Why the obvious tolerance is also wrong, not merely undesirable:
+            // `inferSerializersFromDreamClassOrViewModelClass` below expands STI and throws on the
+            // *first* child that fails, so catching here would drop the serializers of *every* child of
+            // this target. An edge with no targets is treated as terminal by buildSerializerPreloadPaths,
+            // so the association is preloaded but never descended into, and a row of a *well-formed*
+            // sibling fails at render with NonLoadedAssociation — an error naming a class that has
+            // nothing wrong with it.
+            const serializers = serializerAssociation.options.serializer
+                ? compact([serializerAssociation.options.serializer])
+                : compact(inferSerializersFromDreamClassOrViewModelClass(associatedClass, serializerAssociation.options.serializerKey));
             return serializers.map(associatedSerializer => ({
                 dreamClass: associatedClass,
                 serializer: associatedSerializer,
@@ -44,7 +110,6 @@ export default function resolveSerializerAssociationEdges(dreamClass, serializer
         });
         return {
             associationAs: association.as,
-            sourceDreamClass: dreamClass,
             type: serializerAssociation.type,
             serializerAssociationName,
             targets,

package/dist/cjs/src/errors/serializers/NoSerializersResolvedForKey.js

@@ -0,0 +1,30 @@
+/**
+ * Raised when resolving a serializer key against a class yields an empty set of serializers.
+ *
+ * This is an internal-invariant failure, not a misconfiguration: an unresolvable serializer key
+ * raises `MissingSerializersDefinitionForKey` (and a class with no `serializers` getter at all
+ * raises `MissingSerializersDefinition`) while it is being resolved, and STI expansion always
+ * yields at least one class, so there is no supported application shape that reaches this. It is
+ * typed rather than a bare `Error` so that it can be asserted on, and so that the two callers that
+ * guard the invariant raise the same thing.
+ */
+export default class NoSerializersResolvedForKey extends Error {
+    classDef;
+    serializerKey;
+    constructor(classDef, serializerKey) {
+        super();
+        this.classDef = classDef;
+        this.serializerKey = serializerKey;
+    }
+    get message() {
+        const className = this.classDef === null || this.classDef === undefined
+            ? String(this.classDef)
+            : (this.classDef.globalName ?? this.classDef.name);
+        return `
+No serializers resolved for \`${className}\` under serializer key \`${this.serializerKey}\`
+
+This should be impossible — a serializer key that cannot be resolved throws while it is being
+resolved, before reaching here — and indicates a bug in Dream rather than a problem with your
+application. Please report it.`;
+    }
+}

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

@@ -3,6 +3,7 @@ import MissingSerializersDefinition from '../../errors/serializers/MissingSerial
 import MissingSerializersDefinitionForKey from '../../errors/serializers/MissingSerializersDefinitionForKey.js';
 import NoGlobalSerializerForSpecifiedKey from '../../errors/serializers/NoGlobalSerializerForSpecifiedKey.js';
 import NonDreamSerializerDerivedFromGlobalSerializerForSpecifiedKey from '../../errors/serializers/NonDreamSerializerDerivedFromGlobalSerializerForSpecifiedKey.js';
+import NoSerializersResolvedForKey from '../../errors/serializers/NoSerializersResolvedForKey.js';
 import compact from '../../helpers/compact.js';
 import expandStiClasses from '../../helpers/sti/expandStiClasses.js';
 import uniq from '../../helpers/uniq.js';
@@ -35,3 +36,24 @@ export function inferSerializersFromDreamClassOrViewModelClass(classDef, seriali
     const serializers = classes.map(classDef => inferSerializerFromDreamOrViewModel(classDef.prototype, serializerKey));
     return uniq(compact(serializers));
 }
+/**
+ * As `inferSerializersFromDreamClassOrViewModelClass`, but guarantees a non-empty result.
+ *
+ * The guard is unreachable today, and deliberately not phrased as "no serializer found for key": a
+ * serializer key that a class does not register throws `MissingSerializersDefinitionForKey` (and a
+ * class with no `serializers` getter at all throws `MissingSerializersDefinition`) from inside the
+ * inference above, and `expandStiClasses` always yields at least one class. It exists only so that
+ * a future change to any of those cannot turn an unresolvable serializer key into a silently empty
+ * serializer set — which, for the callers below, means a silently empty preload set and a
+ * `NonLoadedAssociation` at render rather than an error naming the real problem.
+ *
+ * Used by everything that walks a serializer graph rooted on a class rather than an instance —
+ * 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);
+    if (serializers.length === 0)
+        throw new NoSerializersResolvedForKey(classDef, serializerKey);
+    return serializers;
+}

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

@@ -15,5 +15,18 @@ export function serializerForAssociatedClass(object, associationName, options) {
     const associatedClass = association.modelCB();
     if (Array.isArray(associatedClass))
         throw new Error('rendersOne flatten is incompatible with a polymorphic belongs-to association');
+    // Taking the first is only a narrowing when `associatedClass` is an STI base, where
+    // inferSerializersFromDreamClassOrViewModelClass returns one serializer per child sorted by
+    // sanitizedName. It is correct here because there is no associated row: this function is reached
+    // only from SerializerRenderer's `flatten: true` branch for a *null* associated object, so no
+    // child of the base is the right one — the row that would have decided is absent. (rendersMany
+    // never reaches here and does not accept `flatten`.)
+    //
+    // It is observable, though, so it is not "nothing happens": the picked serializer is invoked and
+    // its output spread into the parent's payload, so the parent JSON carries the
+    // alphabetically-first child's flattened keys as nulls, and omits keys only a later-sorting child
+    // 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;
 }

package/dist/esm/src/Dream.js

@@ -19,9 +19,9 @@ import destroyDream from './dream/internal/destroyDream.js';
 import { destroyOptions, reallyDestroyOptions, undestroyOptions, } from './dream/internal/destroyOptions.js';
 import ensureSTITypeFieldIsSet from './dream/internal/ensureSTITypeFieldIsSet.js';
 import findOrCreateBy from './dream/internal/findOrCreateBy.js';
+import mergeSerializerAssociationEdges from './dream/internal/mergeSerializerAssociationEdges.js';
 import printSerializerHierarchyLevel from './dream/internal/printSerializerHierarchyLevel.js';
 import reload from './dream/internal/reload.js';
-import resolveSerializerAssociationEdges from './dream/internal/resolveSerializerAssociationEdges.js';
 import runValidations from './dream/internal/runValidations.js';
 import saveDream from './dream/internal/saveDream.js';
 import { DEFAULT_BYPASS_ALL_DEFAULT_SCOPES, DEFAULT_DEFAULT_SCOPES_TO_BYPASS, DEFAULT_SKIP_HOOKS, } from './dream/internal/scopeHelpers.js';
@@ -48,7 +48,7 @@ import areEqual from './helpers/areEqual.js';
 import cloneDeepSafe from './helpers/cloneDeepSafe.js';
 import isJsonColumn from './helpers/db/types/isJsonColumn.js';
 import notEqual from './helpers/notEqual.js';
-import { inferSerializersFromDreamClassOrViewModelClass } from './serializer/helpers/inferSerializerFromDreamOrViewModel.js';
+import { inferSerializersFromDreamClassOrViewModelClassOrFail } from './serializer/helpers/inferSerializerFromDreamOrViewModel.js';
 export default class Dream {
     DB;
     /**
@@ -542,44 +542,89 @@ export default class Dream {
     }
     static serializationMap(serializerKey) {
         const key = serializerKey || 'default';
-        const serializer = inferSerializersFromDreamClassOrViewModelClass(this, key)[0] ?? null;
-        if (!serializer)
-            throw new Error(`unable to find serializer with key: ${key}`);
-        return this.recursiveSerializationMap(serializer);
+        // Deliberately one serializer: this maps a single serializer's view of the class, and taking
+        // the first is only a narrowing when `this` is an STI base (where
+        // inferSerializersFromDreamClassOrViewModelClass returns one serializer per child, sorted by
+        // sanitizedName). That narrowing is deliberate and differs from `buildSerializerPreloadPaths`
+        // and `displaySerialization` below, both of which union every child's serializer because they
+        // answer "what does a query load / display for this class", not "what does one serializer
+        // render". Nothing in src/ calls
+        // this method; it exists as the single-serializer entry point onto recursiveSerializationMap and
+        // is exercised by spec/unit/dream/serializationMap.spec.ts, which pins the narrowing on an STI
+        // base so that the divergence from displaySerialization is executable rather than only
+        // described here. A caller that wants the union for an STI base wants displaySerialization's
+        // shape, not this one.
+        //
+        // Note that the narrowing is to one serializer of *this* class only: every association this
+        // serializer renders is still walked with the full set of serializers its target resolves to,
+        // so an STI base reached as a target below is unioned.
+        const serializer = inferSerializersFromDreamClassOrViewModelClassOrFail(this, key)[0];
+        return this.recursiveSerializationMap([serializer]);
     }
     static displaySerialization(serializerKey) {
         const key = serializerKey || 'default';
-        const serializer = inferSerializersFromDreamClassOrViewModelClass(this, key)[0] ?? null;
-        if (!serializer)
-            throw new Error(`unable to find serializer with key: ${key}`);
+        /**
+         * When `this` is an STI base, this is one serializer per STI child (deduped), since each child
+         * may register a different serializer under `key`. Every one is walked, because this method
+         * backs `psy i:serialization`, whose purpose is verifying what gets preloaded — and
+         * `preloadFor` unions the preload paths of every child's serializer. Walking only one child's
+         * serializer would print a strict subset of what the query actually loads.
+         */
+        // ...OrFail, rather than the plain inference, so that an empty serializer set raises
+        // NoSerializersResolvedForKey instead of silently printing a class name with nothing under it.
+        // That guard is unreachable today and is documented where it lives; it is shared with
+        // buildSerializerPreloadPaths so that the display and the preload walk raise the same thing.
+        const serializers = inferSerializersFromDreamClassOrViewModelClassOrFail(this, key);
         // eslint-disable-next-line no-console
         console.log(yoctocolors.cyan(this.sanitizedName));
-        // eslint-disable-next-line no-console
-        console.log(yoctocolors.gray(serializer.globalName));
-        return this.recursiveSerializationMap(serializer, {
+        // 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 => {
+            // eslint-disable-next-line no-console
+            console.log(yoctocolors.gray(serializer.globalName));
+        });
+        return this.recursiveSerializationMap(serializers, {
             forDisplay: true,
         });
     }
-    static recursiveSerializationMap(serializer, { forDisplay = false, forDisplayDepth = 0, repeatedAssociationTracker = {}, } = {}) {
+    /**
+     * @internal
+     *
+     * Maps the association tree reachable from `serializers` — every serializer that can render this
+     * class at this point in the walk, which is more than one when this class is an STI base. The
+     * serializers are merged into one edge set (see mergeSerializerAssociationEdges) rather than
+     * walked one at a time, so an association several of them render is visited once and the nested
+     * trees of a shared target merge instead of clobbering each other.
+     */
+    static recursiveSerializationMap(serializers, { forDisplay = false, forDisplayDepth = 0, repeatedAssociationTracker = {}, } = {}) {
         const depthTrackerId = this.globalName;
         repeatedAssociationTracker[depthTrackerId] ??= 0;
         if (repeatedAssociationTracker[depthTrackerId] + 1 > RECURSIVE_SERIALIZATION_MAX_REPEATS)
             return {};
         repeatedAssociationTracker[depthTrackerId]++;
-        const edges = resolveSerializerAssociationEdges(this, serializer);
+        const edges = mergeSerializerAssociationEdges(this, serializers);
         const mappedAssociations = edges.reduce((accumulator, edge) => {
+            // An edge with no targets terminates: either a delegatedAttribute (never printed, and
+            // carrying `targets: []` by construction) or an association resolving to no serializer. Its
+            // nestedSerializerInfo is `{}` because this reduce never runs.
             const innerAssociationSerializerInfo = edge.targets.reduce((innerAccumulator, target) => {
-                if (forDisplay && edge.type !== 'delegatedAttribute') {
-                    printSerializerHierarchyLevel({
-                        serializerAssociationType: edge.type,
-                        serializerAssociationName: edge.serializerAssociationName,
-                        associationSerializer: target.serializer,
-                        forDisplayDepth,
-                    });
+                if (forDisplay) {
+                    // One heading per (association, target class), naming every serializer that renders that
+                    // target underneath it, and then — below all of them — the union of their association
+                    // trees, which is what `preloadFor` loads through this association.
+                    //
+                    // The recursion below is a single merged walk of every serializer of the target, so
+                    // there is one tree, not one per child. Grouping the serializer names under a single
+                    // heading is what keeps that honest — repeating the heading per serializer would leave
+                    // the merged tree indented directly beneath the last one's name and attribute every
+                    // sibling's associations to it.
+                    printSerializerHierarchyLevel({ targetSerializers: target.serializers, forDisplayDepth });
                 }
                 return {
                     ...innerAccumulator,
-                    ...target.dreamClass['recursiveSerializationMap'](target.serializer, {
+                    // recursed once per target class with *all* of that class's serializers, so their nested
+                    // trees merge rather than the last one winning a shallow spread
+                    ...target.dreamClass['recursiveSerializationMap'](target.serializers.map(({ serializer }) => serializer), {
                         forDisplay,
                         forDisplayDepth: forDisplayDepth + 1,
                         repeatedAssociationTracker,
@@ -588,7 +633,7 @@ export default class Dream {
             }, {});
             accumulator[edge.associationAs] = {
                 parentDreamClass: this,
-                nestedSerializerInfo: edge.type === 'delegatedAttribute' ? {} : innerAssociationSerializerInfo,
+                nestedSerializerInfo: innerAssociationSerializerInfo,
             };
             return accumulator;
         }, {});

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

@@ -22,8 +22,26 @@ import ops from '../ops/index.js';
 import buildSerializerPreloadPaths from './internal/buildSerializerPreloadPaths.js';
 import computedPaginatePage from './internal/computedPaginatePage.js';
 import convertDreamClassAndAssociationNameTupleArrayToPreloadArgs from './internal/convertDreamClassAndAssociationNameTupleArrayToPreloadArgs.js';
-// Cache for serializer preload-path results, keyed by "${globalName}:${serializerKey}"
-const extractedNestedPathsCache = new Map();
+/**
+ * Cache for serializer preload-path results, keyed on the root class itself and then the serializer
+ * key. Keying on the class rather than its global name is what makes the cache self-invalidating:
+ * loading a fresh set of model classes into the process yields new class objects, so entries
+ * resolved against the previous ones become unreachable and collectable rather than being served
+ * under a name that now means something else.
+ */
+let extractedNestedPathsCache = new WeakMap();
+/**
+ * @internal
+ *
+ * Drops every memoized preload path. Only needed when a class object that stays in the process has
+ * its `serializers` getter replaced, which the cache cannot detect — specs that install or remove
+ * one around an example. Replacing the model classes themselves needs no call, since the cache
+ * keys on the class object. See `clearResolvedSerializerAssociationEdgesCache`, which has the same
+ * contract and is cleared alongside it.
+ */
+export function clearSerializerPreloadPathsCache() {
+    extractedNestedPathsCache = new WeakMap();
+}
 export default class Query {
     /**
      * @internal
@@ -560,17 +578,30 @@ export default class Query {
      * @returns A Query with all serialization associations preloaded
      */
     preloadFor(serializerKey, modifierFn) {
-        const cacheKey = `${this.dreamClass.globalName}:${serializerKey ?? 'default'}`;
-        let preloadArgs = extractedNestedPathsCache.get(cacheKey);
+        const cacheKey = serializerKey ?? 'default';
+        let pathsBySerializerKey = extractedNestedPathsCache.get(this.dreamClass);
+        if (!pathsBySerializerKey) {
+            pathsBySerializerKey = new Map();
+            extractedNestedPathsCache.set(this.dreamClass, pathsBySerializerKey);
+        }
+        let preloadArgs = pathsBySerializerKey.get(cacheKey);
         if (!preloadArgs) {
             preloadArgs = buildSerializerPreloadPaths(this.dreamClass, serializerKey);
-            extractedNestedPathsCache.set(cacheKey, preloadArgs);
+            pathsBySerializerKey.set(cacheKey, preloadArgs);
         }
-        let query = this;
+        // Rather than calling `preload` once per path (which deep clones the accumulating preload tree
+        // on every call, making this quadratic in the number of paths), clone once, flesh out every
+        // path against the same accumulators, and clone the Query once at the end. Iteration order is
+        // preserved, so a later path's `and` still wins over an earlier path's for a shared prefix.
+        const preloadStatements = cloneDeepSafe(this.preloadStatements);
+        const preloadOnStatements = cloneDeepSafe(this.preloadOnStatements);
         preloadArgs.forEach(dreamClassAndAssociationNameTupleArray => {
-            query = query.preload(...convertDreamClassAndAssociationNameTupleArrayToPreloadArgs(dreamClassAndAssociationNameTupleArray, modifierFn));
+            const args = convertDreamClassAndAssociationNameTupleArrayToPreloadArgs(dreamClassAndAssociationNameTupleArray, modifierFn);
+            // `modifierFn` returning 'omit' prunes the path from the omitted association down, which can
+            // leave nothing to preload; `fleshOutJoinStatements` treats an empty arg list as a no-op.
+            this.fleshOutJoinStatements([], preloadStatements, preloadOnStatements, null, args);
         });
-        return query;
+        return this.clone({ preloadStatements, preloadOnStatements });
     }
     /**
      * Returns a new Query instance, with the provided

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

@@ -2421,8 +2421,36 @@ export default class KyselyQueryDriver extends QueryDriverBase {
             dreams = [dreams];
         const { name: associationName } = associationStringToNameAndAlias(associationNameAndMaybeAlias);
         dreams = dreams.filter(dream => dream.hasAssociation(associationName));
-        const groupedDreams = groupBy(dreams, dream => dream.sanitizedConstructorName);
-        return (await Promise.all(Object.keys(groupedDreams).map(key => this._applyOnePreload(associationNameAndMaybeAlias, groupedDreams[key], onStatement)))).flat();
+        // A single preload level can hold Dreams of unrelated classes: a polymorphic
+        // BelongsTo resolves to several target classes, and the Dreams it hands to the
+        // next level down declare their same-named associations independently. Each
+        // distinct declaration needs its own query, so the Dreams are batched by the
+        // pair that determines every query `_applyOnePreload` derives — the association
+        // metadata the Dream resolves for this name, and the class that query roots at.
+        // STI siblings share both (`STI` forbids a child from declaring its own
+        // associations, and all siblings root at the STI base), so they resolve in one
+        // query rather than one per concrete class.
+        const batchesByAssociation = new Map();
+        for (const dream of dreams) {
+            const association = dream['getAssociationMetadata'](associationName);
+            if (association === undefined)
+                throw new UnexpectedUndefined();
+            let batchesByRootClass = batchesByAssociation.get(association);
+            if (batchesByRootClass === undefined) {
+                batchesByRootClass = new Map();
+                batchesByAssociation.set(association, batchesByRootClass);
+            }
+            const rootClass = dream.constructor['stiBaseClassOrOwnClass'];
+            const batch = batchesByRootClass.get(rootClass);
+            if (batch === undefined)
+                batchesByRootClass.set(rootClass, [dream]);
+            else
+                batch.push(dream);
+        }
+        const batches = [...batchesByAssociation.values()].flatMap(batchesByRootClass => [
+            ...batchesByRootClass.values(),
+        ]);
+        return (await Promise.all(batches.map(batch => this._applyOnePreload(associationNameAndMaybeAlias, batch, onStatement)))).flat();
     }
     async _applyOnePreload(associationName, dreams, onStatement = {}) {
         if (!dreams.length)

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;
 }