@rvoh/dream 2.21.1 → 2.23.0

package/dist/cjs/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/cjs/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/cjs/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/cjs/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/cjs/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/cjs/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()];
 }

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/InvalidBatchSize.js

@@ -0,0 +1,19 @@
+export default class InvalidBatchSize extends Error {
+    batchSize;
+    constructor(batchSize) {
+        super();
+        this.batchSize = batchSize;
+    }
+    get message() {
+        return `
+Invalid batchSize provided.
+
+batchSize given:
+  ${String(this.batchSize)}
+
+batchSize must be a positive integer. A batchSize of 0 is especially dangerous,
+since a limit of 0 is treated as "no limit", which would collapse a batched
+operation into a single unbounded pass over the entire matched set.
+`;
+    }
+}

package/dist/cjs/src/errors/RowLockIncompatibleWithDistinct.js

@@ -0,0 +1,14 @@
+export default class RowLockIncompatibleWithDistinct extends Error {
+    get message() {
+        // `SELECT DISTINCT ON (...) ... FOR UPDATE` is rejected by the database
+        // ("FOR UPDATE is not allowed with DISTINCT clause"), so fail here, with a
+        // message that names the two incompatible parts, rather than surfacing a
+        // raw driver error from inside a per-batch transaction.
+        return `
+An exclusive row lock was requested on a query that also calls \`distinct\`.
+
+A locked read cannot be combined with DISTINCT. Drop the \`distinct\` call, or
+drop the lock.
+`;
+    }
+}

package/dist/cjs/src/errors/RowLockIncompatibleWithJoinLoad.js

@@ -0,0 +1,14 @@
+export default class RowLockIncompatibleWithJoinLoad extends Error {
+    get message() {
+        // A join load builds its own select statement (one row per joined
+        // association row, later collapsed in memory), which cannot carry the
+        // Query's row lock. Rather than silently performing an unlocked read and
+        // dropping the compare-and-set guarantee the caller asked for, refuse.
+        return `
+An exclusive row lock was requested on a query that also uses leftJoinPreload.
+
+A join-loaded query cannot be locked. Use \`preload\` instead of
+\`leftJoinPreload\`, or drop the lock.
+`;
+    }
+}

package/dist/cjs/src/errors/ops/ArrayEqualityRequiresArrayColumn.js

@@ -0,0 +1,23 @@
+export default class ArrayEqualityRequiresArrayColumn extends Error {
+    dreamClass;
+    column;
+    operator;
+    constructor(dreamClass, column, operator) {
+        super();
+        this.dreamClass = dreamClass;
+        this.column = column;
+        this.operator = operator;
+    }
+    get message() {
+        return `
+Attempting to compare an array for equality against a column that is not an
+array in the database:
+
+  ${this.dreamClass.sanitizedName}#${this.column} (operator: ${this.operator})
+
+Whole-array equality (\`=\`, \`!=\`, \`<>\`) is only meaningful for array columns.
+If you meant "is this column one of these values", use \`ops.in([...])\`
+(or a bare array) instead.
+`;
+    }
+}