@rvoh/dream 2.22.0 → 2.23.0

package/dist/esm/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/esm/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/esm/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/esm/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/types/src/Dream.d.ts

@@ -429,6 +429,15 @@ export default class Dream {
     private static setGlobalName;
     private static serializationMap;
     private static displaySerialization;
+    /**
+     * @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.
+     */
     private static recursiveSerializationMap;
     /**
      * Returns the column names for the given model

package/dist/types/src/dream/Query.d.ts

@@ -7,6 +7,16 @@ import { CursorPaginatedDreamQueryOptions, CursorPaginatedDreamQueryResult, Defa
 import { JoinedAssociation, JoinedAssociationsTypeFromAssociations, QueryTypeOptions, VariadicJoinsArgs, VariadicLeftJoinLoadArgs, VariadicLoadArgs } from '../types/variadic.js';
 import DreamTransaction from './DreamTransaction.js';
 import QueryDriverBase from './QueryDriver/Base.js';
+/**
+ * @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 declare function clearSerializerPreloadPathsCache(): void;
 export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Readonly<QueryTypeOptions> = DefaultQueryTypeOptions<DreamInstance>> {
     /**
      * @internal

package/dist/types/src/dream/internal/mergeSerializerAssociationEdges.d.ts

@@ -0,0 +1,69 @@
+import Dream from '../../Dream.js';
+import { SerializerType } from '../../types/serializer.js';
+import { ResolvedSerializerAssociationEdge } from './resolveSerializerAssociationEdges.js';
+/**
+ * One contributing serializer's view of a merged target: the serializer that renders the target
+ * through this association, together with how it renders it. The edge type and the serializer-side
+ * association name belong here rather than on the target because they vary per contributing
+ * serializer — two children of an STI base can reach the same target class through the same
+ * association under different names or different edge types.
+ */
+export interface MergedSerializerAssociationTargetSerializer {
+    serializer: SerializerType;
+    type: ResolvedSerializerAssociationEdge['type'];
+    serializerAssociationName: string;
+}
+export interface MergedSerializerAssociationTarget {
+    dreamClass: typeof Dream;
+    /**
+     * Every serializer that renders this target through this association, deduped by serializer
+     * identity. More than one when the target is itself an STI base (one serializer per child).
+     */
+    serializers: MergedSerializerAssociationTargetSerializer[];
+}
+export interface MergedSerializerAssociationEdge {
+    associationAs: string;
+    /**
+     * true when at least one contributing serializer terminates this association — a
+     * delegatedAttribute (which always carries `targets: []`), or a rendersOne/rendersMany resolving
+     * to no serializer.
+     *
+     * Independent of `targets`: an association one child terminates and another descends into (as
+     * Balloon's `stiUnion` key does with `balloonLine`) is both terminating and targeted. The preload
+     * walk emits a leaf path for the terminating side; the display walk ignores it, since a
+     * terminated association prints nothing of its own.
+     */
+    terminates: boolean;
+    targets: MergedSerializerAssociationTarget[];
+}
+/**
+ * @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: typeof Dream, serializers: SerializerType[]): MergedSerializerAssociationEdge[];

package/dist/types/src/dream/internal/printSerializerHierarchyLevel.d.ts

@@ -1,7 +1,25 @@
-import { DreamModelSerializerType, InternalAnyTypedSerializerDelegatedAttribute, InternalAnyTypedSerializerRendersMany, InternalAnyTypedSerializerRendersOne, SimpleObjectSerializerType } from '../../types/serializer.js';
-export default function printSerializerHierarchyLevel({ serializerAssociationType, serializerAssociationName, associationSerializer, forDisplayDepth, }: {
-    serializerAssociationType: (InternalAnyTypedSerializerRendersMany<any> | InternalAnyTypedSerializerRendersOne<any> | InternalAnyTypedSerializerDelegatedAttribute)['type'];
-    serializerAssociationName: string;
-    associationSerializer: DreamModelSerializerType | SimpleObjectSerializerType;
+import { MergedSerializerAssociationTargetSerializer } from './mergeSerializerAssociationEdges.js';
+/**
+ * @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, }: {
+    targetSerializers: MergedSerializerAssociationTargetSerializer[];
     forDisplayDepth: number;
 }): void;

package/dist/types/src/dream/internal/resolveSerializerAssociationEdges.d.ts

@@ -2,7 +2,6 @@ import Dream from '../../Dream.js';
 import { DreamModelSerializerType, SimpleObjectSerializerType } from '../../types/serializer.js';
 export interface ResolvedSerializerAssociationEdge {
     associationAs: string;
-    sourceDreamClass: typeof Dream;
     type: 'rendersOne' | 'rendersMany' | 'delegatedAttribute';
     serializerAssociationName: string;
     targets: {
@@ -10,4 +9,31 @@ export interface ResolvedSerializerAssociationEdge {
         serializer: DreamModelSerializerType | SimpleObjectSerializerType;
     }[];
 }
+/**
+ * @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 declare function clearResolvedSerializerAssociationEdgesCache(): void;
+/**
+ * @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: typeof Dream, serializer: DreamModelSerializerType | SimpleObjectSerializerType): ResolvedSerializerAssociationEdge[];

package/dist/types/src/errors/serializers/NoSerializersResolvedForKey.d.ts

@@ -0,0 +1,18 @@
+import Dream from '../../Dream.js';
+import { ViewModelClass } from '../../types/dream.js';
+/**
+ * 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 {
+    private classDef;
+    private serializerKey;
+    constructor(classDef: typeof Dream | ViewModelClass | null | undefined, serializerKey: string);
+    get message(): string;
+}

package/dist/types/src/serializer/helpers/inferSerializerFromDreamOrViewModel.d.ts

@@ -4,3 +4,19 @@ import { DreamModelSerializerType, SerializerType, SimpleObjectSerializerType }
 export declare const DEFAULT_SERIALIZER_KEY = "default";
 export default function inferSerializerFromDreamOrViewModel<T extends Dream | ViewModel | null | undefined, ReturnType extends T extends null | undefined ? null : T extends Dream | ViewModel ? SerializerType : never>(obj: T, serializerKey?: string | undefined): ReturnType;
 export declare function inferSerializersFromDreamClassOrViewModelClass(classDef: typeof Dream | ViewModelClass | null | undefined, serializerKey?: string | undefined): (DreamModelSerializerType | SimpleObjectSerializerType)[];
+/**
+ * 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 declare function inferSerializersFromDreamClassOrViewModelClassOrFail(classDef: typeof Dream | ViewModelClass | null | undefined, serializerKey: string): (DreamModelSerializerType | SimpleObjectSerializerType)[];