@spearwolf/shadow-objects 0.33.0 → 0.35.0

package/src/in-the-dark/Entity.js

@@ -1,4 +1,4 @@
-import { emit, off, on, once, Priority } from "@spearwolf/eventize";
+import { emitStrict, off, on, once, Priority } from "@spearwolf/eventize";
 import {
   batch,
   createSignal,
@@ -7,24 +7,31 @@ import {
   SignalAutoMap,
   value
 } from "@spearwolf/signalize";
+import { MicrotaskCollector } from "../utils/MicrotaskCollector.js";
+import { runGuarded } from "../utils/runGuarded.js";
 import { onDestroy, onViewEvent } from "./events.js";
 import { Kernel } from "./Kernel.js";
 import { SignalsPath } from "./SignalsPath.js";
-const updateContextValues = /* @__PURE__ */ new Map();
-let requestedContextValueBatchUpdate = false;
-const deferContextValueUpdate = (sig, val) => {
-  updateContextValues.set(sig, val);
-  if (!requestedContextValueBatchUpdate) {
-    requestedContextValueBatchUpdate = true;
-    queueMicrotask(() => {
-      requestedContextValueBatchUpdate = false;
-      const contextValues = Array.from(updateContextValues.entries());
-      updateContextValues.clear();
-      for (const [sig2, val2] of contextValues) {
-        sig2.set(val2);
+const contextValueCollectors = /* @__PURE__ */ new WeakMap();
+const collectorOf = (kernel) => {
+  let collector = contextValueCollectors.get(kernel);
+  if (collector == null) {
+    collector = new MicrotaskCollector((contextValues) => {
+      for (const [contextSignal, entry] of contextValues) {
+        runGuarded(
+          kernel.logger,
+          () => contextSignal.set(entry.value),
+          `an effect of a context value failed (${String(entry.name)}):`,
+          entry.uuid
+        );
       }
     });
+    contextValueCollectors.set(kernel, collector);
   }
+  return collector;
+};
+const deferContextValueUpdate = (kernel, signal, val, name, uuid) => {
+  collectorOf(kernel).add(signal, { value: val, name, uuid });
 };
 class Entity {
   #kernel;
@@ -32,11 +39,14 @@ class Entity {
   #props = new SignalAutoMap();
   #context = /* @__PURE__ */ new Map();
   #rootContexts = /* @__PURE__ */ new Map();
-  #parentUuid;
+  // There is one place the parent is kept: `parentUuid` answers from `#parent.uuid`, so a half-set
+  // link -- a uuid with no matching entity, or an entity with no uuid to show for it -- has no field
+  // left to hold it in.
   #parent;
   #childrenUuids = /* @__PURE__ */ new Set();
   #children = [];
   #order = 0;
+  #isReleased = false;
   get kernel() {
     return this.#kernel;
   }
@@ -49,37 +59,40 @@ class Entity {
   set order(value2) {
     if (this.#order !== value2) {
       this.#order = value2;
-      if (this.#parentUuid) {
-        this.parent.resortChildren();
+      if (this.#parent) {
+        this.#parent.resortChildren();
       }
+      this.#kernel.noteEntityTreeChange(this.#uuid);
     }
   }
   get parentUuid() {
-    return this.#parentUuid || void 0;
+    return this.#parent?.uuid;
   }
   set parentUuid(parentUuid) {
-    if (this.#parentUuid !== parentUuid) {
+    if (this.#parent?.uuid !== parentUuid) {
       const nextParent = parentUuid ? this.#kernel.getEntity(parentUuid) : void 0;
-      this.removeFromParent();
-      this.#parentUuid = parentUuid || void 0;
+      if (nextParent != null) {
+        this.assertAttachableTo(nextParent);
+      }
+      this.#detachFromParent(nextParent == null);
       this.#parent = nextParent;
       if (this.#parent) {
         this.#parent.addChild(this);
       }
       this.#updateAutoDestructionSubscription();
+      this.#kernel.noteEntityTreeChange(this.#uuid);
     }
   }
   get parent() {
-    if (!this.#parent && this.#parentUuid) {
-      this.#parent = this.#kernel.getEntity(this.#parentUuid);
-    }
     return this.#parent;
   }
   set parent(parent) {
     this.parentUuid = parent?.uuid;
   }
+  // Reads the same field `parent` and `parentUuid` do, so `Kernel.noteEntityTreeChange()` -- which
+  // reads `hasParent` to decide whether the uuid belongs in the root set -- sees what they see.
   get hasParent() {
-    return !!this.#parentUuid;
+    return !!this.#parent;
   }
   get children() {
     return this.#children;
@@ -87,74 +100,166 @@ class Entity {
   constructor(kernel, uuid) {
     this.#kernel = kernel;
     this.#uuid = uuid;
-    once(this, onDestroy, Priority.Min, this);
   }
   traverse(callback) {
+    this.#traverse(callback, /* @__PURE__ */ new Set());
+  }
+  // The visited set guards the one traversal an outside shadow object drives, over a tree it did not
+  // build. `addChild()` writes a children list without touching the parent link, so no ancestor check
+  // can cover it.
+  #traverse(callback, visited) {
+    if (visited.has(this)) return;
+    visited.add(this);
     callback(this);
     for (const child of this.#children) {
-      child.traverse(callback);
+      child.#traverse(callback, visited);
     }
   }
+  /**
+   * Releases everything the entity holds: its properties, its subscriptions, its contexts and its place
+   * in the entity tree.
+   *
+   * It runs once, whichever way it is reached. The kernel reaches it directly, right behind the
+   * destruction notification it sends on the entity, so that every listener on that notification has
+   * had its turn first -- down to `Priority.Min`, which is nobody's but the caller's. The entity is
+   * not a listener on its own notification: registering it in the constructor would put it ahead of
+   * anything registered at the same priority, because eventize breaks a tie by order of registration,
+   * and the bulk `off(this)` below would then take the listeners still waiting in that delivery with
+   * it. The flag makes a second call cost nothing and keeps every step below written for a
+   * single run: `kernel.getEntity()` hands the entity to anyone, and this method is as reachable as
+   * the rest of it.
+   *
+   * The flag is raised before the first step rather than after the last, because that is what a release
+   * running twice would cost: the steps below are written for one pass, not for a repeat.
+   *
+   * Every step below runs behind a guard of its own, the way `ShadowObjectCreationScope.tearDown()`
+   * gives each of its steps one: a step that throws is reported through the kernel's logger, named by
+   * the step and by the uuid of this entity, and costs only itself -- the steps behind it still run.
+   * The method therefore never throws to its own caller. The plain resets at the end -- clearing a
+   * collection, overwriting a field -- cannot throw and run unguarded, exactly as `tearDown()` empties
+   * its own sets at the end.
+   */
   [onDestroy]() {
-    this.#props.clear();
-    off(this);
-    this.#autoDestructionSubscription?.();
+    if (this.#isReleased) return;
+    this.#isReleased = true;
+    this.#runGuarded("properties", () => this.#props.clear());
+    this.#runGuarded("listeners", () => off(this));
+    this.#runGuarded("auto-destruction subscription", () => this.#autoDestructionSubscription?.());
     for (const rootCtx of this.#rootContexts.values()) {
-      rootCtx.cleanup();
-      rootCtx.signal.destroy();
+      this.#runGuarded("global context cleanup", () => rootCtx.cleanup());
+      this.#runGuarded("global context signal", () => rootCtx.signal.destroy());
     }
-    this.#rootContexts.clear();
     for (const ctx of this.#context.values()) {
-      ctx.context.set(void 0);
-      ctx.unsubscribePathValue();
-      ctx.unsubscribeFromParent?.();
-      ctx.valuePath.dispose();
-      ctx.inherited.destroy();
-      ctx.provide.destroy();
-      ctx.context.destroy();
+      this.#runGuarded("context value reset", () => ctx.context.set(void 0));
+      this.#runGuarded("context value subscription", () => ctx.unsubscribePathValue());
+      this.#runGuarded("context parent subscription", () => ctx.unsubscribeFromParent?.());
+      this.#runGuarded("context value path", () => ctx.valuePath.dispose());
+      this.#runGuarded("inherited context signal", () => ctx.inherited.destroy());
+      this.#runGuarded("provided context signal", () => ctx.provide.destroy());
+      this.#runGuarded("context signal", () => ctx.context.destroy());
     }
-    this.#parentUuid = void 0;
+    this.#rootContexts.clear();
+    this.#context.clear();
     this.#parent = void 0;
     this.#childrenUuids.clear();
     this.#children.length = 0;
   }
-  addChild(child) {
-    if (this.#children.length === 0) {
-      this.#childrenUuids.add(child.uuid);
-      this.#children.push(child);
-      return;
+  /**
+   * Isolates one release step from the ones around it: a step that throws is reported through the
+   * kernel's logger and does not stop `[onDestroy]()` from reaching the steps that follow. The
+   * report goes out through the shared `runGuarded()`; what this wrapper adds is the label of the
+   * step and the uuid of the entity it belongs to.
+   */
+  #runGuarded(step, run) {
+    runGuarded(this.#kernel.logger, run, `entity teardown step failed (${step}):`, this.#uuid);
+  }
+  /**
+   * Refuses a parent that would close the entity tree into a ring: the entity itself, or an entity that
+   * already sits below it. The walk follows the parent chain upwards, which is a chain exactly because
+   * this guard keeps it one.
+   *
+   * `Kernel.setParent()` calls it before it detaches, and the `parentUuid` setter before it resolves the
+   * link, so a refused attachment leaves the entity where it was instead of orphaned halfway through.
+   * `ViewComponent.addChild()` guards the same thing on the view side.
+   */
+  assertAttachableTo(nextParent) {
+    for (let e = nextParent; e != null; e = e.parent) {
+      if (e === this) {
+        throw new Error(
+          `entity "${nextParent.uuid}" cannot become the parent of "${this.uuid}": it is the entity itself or one of its descendants`
+        );
+      }
     }
+  }
+  /**
+   * Puts `child` into the children list, at its place among the siblings.
+   *
+   * Nothing here notifies. Neither this method nor {@link Entity.removeChild} nor a detachment
+   * sends anything to a listener on the entity -- the one notification over a moved entity is
+   * `onParentChanged`, and `Kernel.setParent()` is the call that sends it.
+   */
+  addChild(child) {
     if (this.#childrenUuids.has(child.uuid)) {
       throw new Error(`child with uuid: ${child.uuid} already exists! parentUuid: ${this.uuid}`);
     }
     this.#childrenUuids.add(child.uuid);
-    this.#children.push(child);
-    this.resortChildren();
+    this.#insertChildInOrder(child);
     for (const [, ctx] of child.#context) {
       child.#subscribeToParent(ctx);
     }
   }
+  /**
+   * Puts a child at its place among the siblings, so building a subtree costs one insertion per
+   * child. The scan runs from the end because children usually arrive with an equal or rising
+   * `order`, which makes the common case a plain append. A child lands behind every sibling that
+   * shares its `order` -- the same place a stable sort would give it.
+   *
+   * The result only matches a full sort while `#children` is already sorted when the insertion
+   * starts, so name what keeps it that way: the insertion here preserves the order, `removeChild()`
+   * cuts an element out with `splice`, the destroy handler empties the list, and the `order` setter
+   * re-sorts through the parent. That last one is the condition worth stating, because it needs the
+   * child to know its parent -- the parent link has to be established. Every way an entity is
+   * attached inside this class goes through the `parentUuid` setter, which sets the parent before it
+   * calls `addChild()`. A caller that reaches for `addChild()` on its own leaves the child without a
+   * parent link, and a later `order` on such a child never reaches this list.
+   */
+  #insertChildInOrder(child) {
+    let i = this.#children.length;
+    while (i > 0 && child.order < this.#children[i - 1].order) i--;
+    this.#children.splice(i, 0, child);
+  }
   resortChildren() {
     this.#children.sort((a, b) => a.order - b.order);
   }
   removeChild(child) {
-    if (this.#childrenUuids.has(child.uuid)) {
+    const idx = this.#children.indexOf(child);
+    if (idx !== -1) {
       this.#childrenUuids.delete(child.uuid);
-      this.#children.splice(this.#children.indexOf(child), 1);
+      this.#children.splice(idx, 1);
     }
   }
-  removeFromParent() {
+  /**
+   * @param rebindContexts bind every context back to the root of the entity context tree. An entity
+   *   that carries a context out of a subtree keeps following the value it can still see, rather
+   *   than freezing on the last one the former parent held. Only a caller that attaches the entity
+   *   to the next parent in the same breath passes `false` -- that parent binds the contexts itself,
+   *   and the detour over the root would be visible to `useParentContext()`, which hands out the
+   *   inherited value without the microtask collector `useContext()` has in front of it.
+   */
+  removeFromParent(rebindContexts = true) {
+    this.#detachFromParent(rebindContexts);
+  }
+  #detachFromParent(rebindContexts) {
     if (this.#parent) {
       this.#parent.removeChild(this);
       this.#parent = void 0;
-      this.#parentUuid = void 0;
-      for (const [, ctx] of this.#context) {
-        if (ctx.unsubscribeFromParent) {
-          ctx.unsubscribeFromParent();
-          ctx.unsubscribeFromParent = void 0;
+      if (rebindContexts) {
+        for (const [, ctx] of this.#context) {
+          this.#subscribeToParent(ctx);
         }
       }
       this.#unsubscribeAutoDestruction();
+      this.#kernel.noteEntityTreeChange(this.#uuid);
     }
   }
   #autoDestructionEnabled = false;
@@ -182,6 +287,15 @@ class Entity {
       });
     }
   }
+  /**
+   * Binds every context of this entity to its current position in the entity tree -- to the parent
+   * if there is one, to the root otherwise. `addChild()` and `removeFromParent()` each do this for
+   * the entity they move, so a caller needs this only when it changed the position by other means
+   * or wants the binding re-established without knowing which of the two ran.
+   *
+   * Moving an entity through the kernel is not such a case: both directions bring their own binding,
+   * and a third one would reach every `useParentContext()` reader as another change.
+   */
   reSubscribeToParentContexts() {
     for (const [, ctx] of this.#context) {
       this.#subscribeToParent(ctx);
@@ -190,9 +304,28 @@ class Entity {
   dispatchMessageToView(type, data, transferables, traverseChildren = false) {
     this.#kernel.dispatchMessageToView({ uuid: this.#uuid, type, data, transferables, traverseChildren });
   }
+  /**
+   * Hands the events the view sent to whoever listens on this entity, one delivery per event.
+   *
+   * Each delivery is guarded, and the reason is where this call sits: the kernel makes it from
+   * inside a change trail, on a path that builds. Unguarded, a single shadow-object that cannot cope
+   * with a single view event would leave through `Kernel.run()` and refuse the whole trail -- the
+   * same argument that puts a guard around the `onParentChanged` notification, which is a delivery
+   * on a building path as well. The guard is per event, so one that fails costs neither the events
+   * behind it nor the caller anything; `emitStrict()` inside it makes the same promise one level
+   * down, to the listeners of one event.
+   */
   dispatchViewEvents(events) {
     for (const { type, data } of events) {
-      emit(this, onViewEvent, type, data);
+      runGuarded(
+        this.#kernel.logger,
+        // the concrete class is needed here: eventize cannot reduce its emitter conditional
+        // (`NonTypedEmitter<this>`) over the polymorphic `this` type, and no overload then matches
+        () => emitStrict(this, onViewEvent, type, data),
+        "entity view event delivery failed:",
+        type,
+        this.#uuid
+      );
     }
   }
   dispatchViewEvent(type, data) {
@@ -204,11 +337,30 @@ class Entity {
   getPropertyReader(key) {
     return this.#getPropSignal(key).get;
   }
+  /**
+   * A write head for one property. Every write through it drops the cache behind
+   * `truthyProps()`: that cache answers `Kernel.#updateShadowObjects()`, which picks the shadow
+   * objects of this entity along the property routes of the registry, and a write the cache does
+   * not see routes the entity to a state it no longer has.
+   *
+   * What comes back is a function of the entity, not the `set` of the signal behind the property.
+   * The signalize helpers that take a signal-like -- `isSignal()`, `destroySignal()`, `touch()` --
+   * do not recognise it; `getPropertyReader()` hands out the signal's own reader for that.
+   *
+   * A fresh closure is handed out on every call rather than one cached per key: `SignalAutoMap`
+   * hands out "a fresh, live" signal for a key whose signal was destroyed from the outside, so a
+   * writer cached against the signal captured on an earlier call could end up closing over a corpse.
+   * The call sites this feeds -- `setProperty()` from a change-trail application, at most once per
+   * property that actually changed -- do not turn this into a hot path.
+   */
   getPropertyWriter(key) {
-    return this.#getPropSignal(key).set;
+    const signal = this.#getPropSignal(key);
+    return (value2, params) => {
+      this.clearTruthyPropsCache();
+      signal.set(value2, params);
+    };
   }
   setProperties(properties) {
-    this.clearTruthyPropsCache();
     batch(() => {
       for (const [key, val] of properties) {
         this.setProperty(key, val);
@@ -250,6 +402,44 @@ class Entity {
   hasContext(name) {
     return this.#context.has(name);
   }
+  /** The names of the Entity Contexts this entity holds, used or provided. Reads only, creates none. */
+  contextNames() {
+    return Array.from(this.#context.keys());
+  }
+  /**
+   * The three values behind one Entity Context of this entity: what its own providers wrote, what it
+   * inherits from the parent (or from the global chain at a root), and what `useContext(name)` reads.
+   * `hasProviders` says whether a provider feed is attached -- a value written straight into the
+   * signal from `provideContext()` counts as provided but not as a provider.
+   *
+   * `undefined` when the entity holds no context of that name; asking does not create one. The
+   * reads are plain `.value` reads and track nothing, so a call from inside an effect does not
+   * subscribe that effect to the context.
+   */
+  describeContext(name) {
+    const ctx = this.#context.get(name);
+    if (ctx === void 0) return void 0;
+    return {
+      provided: ctx.provide.value,
+      inherited: ctx.inherited.value,
+      effective: ctx.context.value,
+      hasProviders: ctx.providerFeeds.size > 0
+    };
+  }
+  /** The names of the global Entity Contexts this entity contributes to. Reads only, creates none. */
+  globalContextNames() {
+    return Array.from(this.#rootContexts.keys());
+  }
+  /**
+   * What this entity contributes to the kernel-wide chain of one global Entity Context: the value
+   * and the very signal that stands in the chain, so a caller holding the chain can find this entity
+   * in it by identity. `undefined` when the entity contributes nothing under that name.
+   */
+  describeGlobalContext(name) {
+    const rootCtx = this.#rootContexts.get(name);
+    if (rootCtx === void 0) return void 0;
+    return { value: rootCtx.signal.value, signal: rootCtx.signal, hasProviders: rootCtx.providerFeeds.size > 0 };
+  }
   useContext(name) {
     return this.#findOrCreateContext(name).context.get;
   }
@@ -260,14 +450,91 @@ class Entity {
     return this.#findOrCreateContext(name).provide;
   }
   provideGlobalContext(name) {
+    return this.#findOrCreateGlobalContext(name).signal;
+  }
+  /**
+   * Attaches a provider signal to the context of `name` on this entity and answers with the release
+   * that detaches it again.
+   *
+   * Every provider of one name writes into the single signal that `provideContext()` hands out, so
+   * what a consumer reads is what was written last. The release therefore does two things: it cuts
+   * this feed, and it then lets a provider that is still attached write its value once more. Without
+   * that second step the context would keep whatever the departure left standing -- the `undefined`
+   * of a clearing provider, or the last value of one that opted out of it -- even though this entity
+   * still has a provider of the name that says otherwise.
+   *
+   * A value written straight into the signal from `provideContext()` is not a feed and is therefore
+   * overwritten by the next release. Feeding a value in through this method is what makes it survive
+   * one.
+   */
+  attachContextProvider(name, provider) {
+    const ctx = this.#findOrCreateContext(name);
+    return Entity.#attachProviderFeed(provider, ctx.provide, ctx.providerFeeds);
+  }
+  /**
+   * The counterpart of {@link Entity.attachContextProvider} for the global context of `name`.
+   *
+   * Within one entity the situation is the same one: every provider feeds the single signal this
+   * entity contributes to the kernel-wide chain of that name, and a release hands the name back to a
+   * provider that stays. Across entities the chain decides on its own -- it resolves to the first
+   * entry that holds something, so an entity whose signal falls empty lets the next one through.
+   */
+  attachGlobalContextProvider(name, provider) {
+    const rootCtx = this.#findOrCreateGlobalContext(name);
+    return Entity.#attachProviderFeed(provider, rootCtx.signal, rootCtx.providerFeeds);
+  }
+  static #attachProviderFeed(provider, target, feeds) {
+    const feed = link(provider, target);
+    feeds.add(feed);
+    return () => {
+      if (!feeds.delete(feed)) return;
+      feed.destroy();
+      Entity.#handOverToRemainingProvider(feeds);
+    };
+  }
+  /**
+   * Lets the provider that stays write its value into the context signal again.
+   *
+   * The set iterates in the order the providers were attached and the loop keeps the last hit, so the
+   * winner is the one attached last that still holds a value. Attachment order is the order in which the
+   * providers took the name: attaching feeds the value straight through, so a later attachment writes
+   * over an earlier one, and the hand-over falls back on that order instead of inventing one of its own.
+   * It is not the order of the writes -- a provider that writes to its signal after attaching carries
+   * the name until the next departure, and the hand-over does not restore that write, because what this
+   * entity keeps on file is its providers and not the sequence in which they wrote. Providers holding
+   * nothing are passed over -- by the same `!= null` rule with which `SignalsPath` resolves a context
+   * chain, and for the same reason: a provider without a value has nothing to say about the name, and
+   * electing it would clear a name that is still being provided.
+   *
+   * A feed whose link is destroyed is passed over as well. A shadow-object owns the signal it was
+   * handed and may end it early, which destroys the link without the release ever having run: such a
+   * feed still reports a value through its source while its writes go nowhere, so electing it would
+   * leave the write of the departure standing, silently and over a provider that is alive.
+   *
+   * `touch()` is what makes the winner write, because `SignalLink.write()` is protected: touching is
+   * the only public way to push the current value of a source through its link again, and the source
+   * of a provider that merely stays has no reason to change.
+   *
+   * Where no remaining feed qualifies, nothing is written: then what the departure left stands,
+   * which is the `undefined` of a clearing provider or the last value of one that opted out.
+   */
+  static #handOverToRemainingProvider(feeds) {
+    let winner;
+    for (const feed of feeds) {
+      if (!feed.isDestroyed && feed.source.value != null) winner = feed;
+    }
+    winner?.touch();
+  }
+  #findOrCreateGlobalContext(name) {
     if (this.#rootContexts.has(name)) {
-      return this.#rootContexts.get(name).signal;
+      return this.#rootContexts.get(name);
     }
     const rootCtx = this.#kernel.findOrCreateRootContext(name);
     const signal = createSignal();
     const cleanup = rootCtx.add(signal);
-    this.#rootContexts.set(name, { cleanup, signal });
-    return signal;
+    const ctx = { cleanup, signal, providerFeeds: /* @__PURE__ */ new Set() };
+    this.#rootContexts.set(name, ctx);
+    return ctx;
   }
   #findOrCreateContext(name) {
     if (this.#context.has(name)) {
@@ -278,9 +545,9 @@ class Entity {
     const context = createSignal();
     const valuePath = new SignalsPath([provide, inherited]);
     const unsubscribePathValue = on(valuePath, SignalsPath.Value, (val) => {
-      deferContextValueUpdate(context, val);
+      deferContextValueUpdate(this.#kernel, context, val, name, this.#uuid);
     });
-    const ctx = { name, inherited, provide, context, valuePath, unsubscribePathValue };
+    const ctx = { name, inherited, provide, context, valuePath, providerFeeds: /* @__PURE__ */ new Set(), unsubscribePathValue };
     this.#context.set(name, ctx);
     this.#subscribeToParent(ctx);
     return ctx;