@spearwolf/shadow-objects 0.33.0 → 0.34.0

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

@@ -0,0 +1,596 @@
+import { emit, on, once, Priority } from "@spearwolf/eventize";
+import {
+  createEffect,
+  createMemo,
+  createSignal,
+  destroySignal,
+  isSignal,
+  link
+} from "@spearwolf/signalize";
+import { runGuarded } from "../utils/runGuarded.js";
+import { toMaybe } from "../utils/toMaybe.js";
+import { onDestroy, onViewEvent } from "./events.js";
+const inertSignal = () => {
+  const sig = createSignal(void 0);
+  destroySignal(sig);
+  return sig;
+};
+const inertEffect = () => {
+  const effect = createEffect(() => {
+  }, { autorun: false });
+  effect.destroy();
+  return effect;
+};
+const noSubscription = () => {
+};
+class ShadowObjectCreationScope {
+  #entity;
+  #logger;
+  #displayName;
+  // The kernel's list of member names whose deprecation report has already been made. Shared by
+  // every scope of one kernel, which is what makes the report fall once per kernel and name.
+  #shownDeprecations;
+  // The cleanup callbacks of the shadow-object itself, registered through `onDestroy()`.
+  #unsubscribePrimary = /* @__PURE__ */ new Set();
+  // The cleanup callbacks the creation API registered on its own behalf. A `Set` iterating in
+  // insertion order: which cleanup runs before which is observable behaviour.
+  #unsubscribeSecondary = /* @__PURE__ */ new Set();
+  // The releases of the provider feeds, one per context name this shadow-object provides. The
+  // entity hands each of them out when the provider is attached to it, and they fall after every
+  // other cleanup callback, so a write the teardown still makes -- the `undefined` of a
+  // `clearOnDestroy`, or one from an `onDestroy` callback -- reaches the entity-side signal instead
+  // of stopping at the provider. Where the entity lives on, that is what makes the write count: the
+  // entity hands it on to its own context signal one microtask later, and from there to its readers
+  // and to the entities below it. The order matters in the other direction as well, because a
+  // release also lets a provider that stays on the entity write its value once more, and that
+  // hand-over may only happen once the write of the leaving provider is through.
+  //
+  // Where the entity is destroyed, the two kinds of target part ways. The signal behind
+  // `provideContext()` takes the write and keeps it: the microtask that would hand it on falls
+  // after the entity has cleared and destroyed its context signals, and the children that outlive
+  // it were re-bound before the teardown even began. The signal behind `provideGlobalContext()`
+  // stays a member of the kernel-wide chain of its name until the entity's own destruction runs at
+  // `Priority.Min`, so the write does travel on to the inherited signals of other entities -- with
+  // no observable difference, because the entity takes its signal out of that chain in the same run,
+  // and what the chain resolves to without it is what those readers were going to see anyway: the
+  // contribution of the next entity that holds the name, or nothing where there is none. The
+  // ordering is kept for the paths on which it is observable.
+  #unsubscribeContextFeeds = /* @__PURE__ */ new Set();
+  #contextReaders = /* @__PURE__ */ new Map();
+  #contextReaderCompares = /* @__PURE__ */ new Map();
+  #contextParentReaders = /* @__PURE__ */ new Map();
+  #contextParentReaderCompares = /* @__PURE__ */ new Map();
+  #contextProviders = /* @__PURE__ */ new Map();
+  #contextRootProviders = /* @__PURE__ */ new Map();
+  // The provider signals that already have their `clearOnDestroy` write registered in
+  // `#unsubscribeSecondary`. Keyed by the signal itself rather than by name, because a
+  // `provideContext(name)` and a `provideGlobalContext(name)` call can share one name while landing
+  // in two different maps above -- a name-keyed set would conflate the two providers.
+  #clearOnDestroyRegistered = /* @__PURE__ */ new Set();
+  #propertyReaders = /* @__PURE__ */ new Map();
+  #propertyCompares = /* @__PURE__ */ new Map();
+  #shadowObject;
+  #releaseScope;
+  #forgetShadowObject;
+  #unsubscribeFromEntityDestroy;
+  #isTornDown = false;
+  // Armed at the *end* of `tearDown()`, not at its start, and the difference is the whole point:
+  // the teardown runs the shadow-object's own cleanup callbacks, and those are allowed the creation
+  // API -- a goodbye to the view, a last write. What they register there is still swept up by the
+  // steps behind them. What arrives after the teardown has returned is not, which is what this
+  // closes.
+  #isCreationApiClosed = false;
+  // The member names whose late call has already been reported, at most as many as the API has
+  // members. Lazy, because a scope that is used correctly never allocates it.
+  #lateCallsReported;
+  /**
+   * The name the kernel gave this scope, taken from the constructor it belongs to rather than from
+   * the shadow-object that came out of it. The two agree for most forms -- a class and a function
+   * that returns nothing both leave their own name on the instance's `constructor` -- but not for a
+   * function that returns an object literal: `new` hands that literal back, and it reports `Object`.
+   * Reports about the shadow-object are keyed by this name, so the kernel reads it here instead of
+   * asking the instance.
+   */
+  get displayName() {
+    return this.#displayName;
+  }
+  /**
+   * The four teardown handles, read without waiting on a garbage collector: a test can check that
+   * `tearDown()` let go of them by comparing this before and after, rather than by proving the
+   * absence of a reference through a `WeakRef`.
+   *
+   * @internal
+   */
+  get debugHandles() {
+    return {
+      shadowObject: this.#shadowObject,
+      releaseScope: this.#releaseScope,
+      forgetShadowObject: this.#forgetShadowObject,
+      unsubscribeFromEntityDestroy: this.#unsubscribeFromEntityDestroy
+    };
+  }
+  /**
+   * How many cleanup callbacks the scope is holding, one count per set, read without waiting on a
+   * garbage collector: a test can subscribe and unsubscribe n times and see that the scope let go
+   * of each handle as it went, rather than inferring it from what a collector happened to do.
+   *
+   * @internal
+   */
+  get debugCleanupCounts() {
+    return {
+      primary: this.#unsubscribePrimary.size,
+      secondary: this.#unsubscribeSecondary.size,
+      contextFeeds: this.#unsubscribeContextFeeds.size
+    };
+  }
+  constructor(entity, logger, displayName, shownDeprecations) {
+    this.#entity = entity;
+    this.#logger = logger;
+    this.#displayName = displayName;
+    this.#shownDeprecations = shownDeprecations;
+  }
+  /**
+   * The object that goes into `new construct(…)`.
+   *
+   * Every member is a bound function, because a shadow-object constructor is expected to destructure the
+   * API in its parameter list — a member that took its receiver from the call site would lose it there.
+   */
+  createAPI() {
+    return {
+      entity: this.#entity,
+      provideContext: this.provideContext.bind(this),
+      provideGlobalContext: this.provideGlobalContext.bind(this),
+      useContext: this.useContext.bind(this),
+      useParentContext: this.useParentContext.bind(this),
+      dispatchMessageToView: this.dispatchMessageToView.bind(this),
+      useProperty: this.useProperty.bind(this),
+      useProperties: this.useProperties.bind(this),
+      createResource: this.createResource.bind(this),
+      createEffect: this.createEffect.bind(this),
+      createSignal: this.createSignal.bind(this),
+      createMemo: this.createMemo.bind(this),
+      on: this.on.bind(this),
+      once: this.once.bind(this),
+      emit: this.emit.bind(this),
+      onViewEvent: this.onViewEvent.bind(this),
+      onDestroy: this.onDestroy.bind(this)
+    };
+  }
+  /**
+   * Binds the scope to the shadow-object it made the API for and subscribes to the destruction of the entity.
+   *
+   * A shadow-object reaches its end on two independent paths: the entity is destroyed, or the shadow-object
+   * leaves the constructor set of a still living entity (token or route change). Both run the same teardown,
+   * and each path reaches it through a handle of its own.
+   *
+   * The kernel keeps two releases rather than one, because they belong to opposite ends of the teardown:
+   * `releaseScope` runs at its start, `forgetShadowObject` at its end.
+   *
+   * One scope serves one shadow-object, once: the call is part of the contract, and both ways of breaking
+   * it are refused below.
+   */
+  bindTo(shadowObject, releaseScope, forgetShadowObject) {
+    if (this.#isTornDown) {
+      throw new Error(`the creation scope of "${this.#displayName}" has torn down and cannot be bound`);
+    }
+    if (this.#shadowObject !== void 0) {
+      throw new Error(`the creation scope of "${this.#displayName}" is already bound to a shadow-object`);
+    }
+    this.#shadowObject = shadowObject;
+    this.#releaseScope = releaseScope;
+    this.#forgetShadowObject = forgetShadowObject;
+    this.#logger.info("create shadow-object", this.#displayName, { shadowObject, entity: this.#entity });
+    this.#unsubscribeFromEntityDestroy = once(this.#entity, onDestroy, Priority.Low, () => {
+      this.tearDown();
+    });
+  }
+  /**
+   * Runs once, whichever path reaches it first.
+   *
+   * Three lead here. Two belong to a shadow-object that lived: its entity is destroyed, or it leaves the
+   * constructor set of an entity that stays. On the third, the kernel calls this directly on a scope that
+   * `bindTo()` never saw, because the constructor threw -- there is no shadow-object then, and three of the
+   * handles below are still unset (`#releaseScope` and `#unsubscribeFromEntityDestroy` at the start,
+   * `#forgetShadowObject` at the end), which is why all three are called optionally.
+   *
+   * The provider feeds are released after everything else, so that a write made on the way out reaches the
+   * entity-side signal rather than stopping at the provider, and so that the entity hands the context over to
+   * a provider that stays only once that write is through.
+   *
+   * The flag makes the teardown a one-time act: a destroy callback reaching back into the kernel finds no
+   * way to start it a second time. Releasing both handles right after ends the retention in both directions
+   * -- the kernel's map points from the shadow-object to this scope, the subscription points from the entity
+   * to the same scope.
+   *
+   * The kernel is told to forget the shadow-object at the very end, so a destroy callback that reaches back
+   * into the kernel still finds its shadow-object listed among the ones the constructor created. Once that
+   * call is through, the four handles above are let go of as well -- the shadow-object, both kernel releases
+   * and the entity subscription -- so a scope past this point holds none of the four through these fields.
+   *
+   * Every step below runs behind its own guard, so a callback or signal teardown that throws does not stop
+   * the ones after it: the remaining callbacks, the remaining signal releases, and the provider feed
+   * hand-over all still happen. A caught error goes to the logger by displayName and the label of the step
+   * that failed, and is not re-thrown -- neither `changeToken()` nor `destroyEntity()` deliver it to their
+   * caller, nor does it stop the destroy notification the entity is still delivering to whatever comes after
+   * this shadow-object in the same run.
+   *
+   * The creation API is closed as the very last step, after everything above has run. Until then it
+   * is open, because the cleanup callbacks of the shadow-object run inside this method and are
+   * entitled to it -- a last message to the view, a last write to a context. What such a callback
+   * registers is still reached by the steps behind it. The two sets of cleanup callbacks are run
+   * in rounds until neither has anything left, so a callback that another one registers is reached
+   * whichever of the two it lands in. The context feed releases follow all of them. What arrives
+   * once this method has returned is not, and is turned away by `#refuseAfterTearDown()`.
+   */
+  tearDown() {
+    if (this.#isTornDown) return;
+    this.#isTornDown = true;
+    this.#runGuarded("scope release", () => this.#releaseScope?.());
+    this.#runGuarded("entity destroy subscription", () => this.#unsubscribeFromEntityDestroy?.());
+    if (this.#shadowObject !== void 0) {
+      this.#logger.info("destroy shadow-object", this.#displayName, { shadowObject: this.#shadowObject, entity: this.#entity });
+    }
+    const alreadyRun = /* @__PURE__ */ new Set();
+    const runCleanups = (callbacks, step) => {
+      let ranAny = false;
+      for (const callback of callbacks) {
+        if (alreadyRun.has(callback)) continue;
+        alreadyRun.add(callback);
+        ranAny = true;
+        this.#runGuarded(step, callback);
+      }
+      return ranAny;
+    };
+    let ranAnything = true;
+    while (ranAnything) {
+      const ranPrimary = runCleanups(this.#unsubscribePrimary, "onDestroy callback");
+      const ranSecondary = runCleanups(this.#unsubscribeSecondary, "creation-api cleanup");
+      ranAnything = ranPrimary || ranSecondary;
+    }
+    for (const callback of this.#unsubscribeContextFeeds) {
+      this.#runGuarded("context feed release", callback);
+    }
+    for (const sig of this.#contextReaders.values()) {
+      this.#runGuarded("context reader", () => destroySignal(sig));
+    }
+    for (const sig of this.#contextParentReaders.values()) {
+      this.#runGuarded("parent context reader", () => destroySignal(sig));
+    }
+    for (const sig of this.#propertyReaders.values()) {
+      this.#runGuarded("property reader", () => destroySignal(sig));
+    }
+    for (const sig of this.#contextProviders.values()) {
+      this.#runGuarded("context provider", () => destroySignal(sig));
+    }
+    for (const sig of this.#contextRootProviders.values()) {
+      this.#runGuarded("global context provider", () => destroySignal(sig));
+    }
+    this.#unsubscribePrimary.clear();
+    this.#unsubscribeSecondary.clear();
+    this.#unsubscribeContextFeeds.clear();
+    this.#contextReaders.clear();
+    this.#contextReaderCompares.clear();
+    this.#contextParentReaders.clear();
+    this.#contextParentReaderCompares.clear();
+    this.#propertyReaders.clear();
+    this.#propertyCompares.clear();
+    this.#contextProviders.clear();
+    this.#contextRootProviders.clear();
+    this.#clearOnDestroyRegistered.clear();
+    this.#runGuarded("forget shadow-object", () => this.#forgetShadowObject?.());
+    this.#shadowObject = void 0;
+    this.#releaseScope = void 0;
+    this.#forgetShadowObject = void 0;
+    this.#unsubscribeFromEntityDestroy = void 0;
+    this.#isCreationApiClosed = true;
+  }
+  /**
+   * Isolates one teardown step from the ones around it: a step that throws is reported through the
+   * logger -- ungated, so the report stays visible outside localhost -- and does not stop `tearDown()`
+   * 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 display name it belongs to.
+   */
+  #runGuarded(step, run) {
+    runGuarded(this.#logger, run, `shadow-object teardown failed (${step}):`, this.#displayName);
+  }
+  /**
+   * Books an `on()` or `once()` subscription into the cleanup set and hands back a handle that takes
+   * it out again. Unsubscribing releases the callback there and then rather than at the teardown, so
+   * a shadow-object that subscribes and unsubscribes over the whole life of its entity holds one
+   * handle at a time instead of one per call. The target makes no difference to that: a subscription
+   * on the entity ends the same way one on any other object does.
+   */
+  #trackSubscription(unsubscribe) {
+    this.#unsubscribeSecondary.add(unsubscribe);
+    return Object.assign(() => {
+      this.#unsubscribeSecondary.delete(unsubscribe);
+      unsubscribe();
+    }, unsubscribe);
+  }
+  /**
+   * The body the three cached readers share: one reader per name, created on the first call and fed
+   * from the entity-side source, plus a warning when a later call brings a different {compare}
+   * function than the one the reader was created with.
+   *
+   * `linkSource` is a thunk because the source may only be read when a reader is actually created.
+   */
+  #cachedReader(name, readers, compares, linkSource, opts, apiName, subject) {
+    let reader = readers.get(name);
+    if (reader === void 0) {
+      reader = createSignal(void 0, opts).get;
+      readers.set(name, reader);
+      compares.set(name, opts?.compare);
+      const ln = link(linkSource(), reader);
+      this.#unsubscribeSecondary.add(ln.destroy.bind(ln));
+    } else if (opts?.compare != null && compares.get(name) !== opts.compare) {
+      this.#logger.error(
+        `[shadow-objects] ${apiName}("${String(name)}"): the cached signal already exists with a different (or no) {compare} function \u2014 the new options are ignored. Pass options only on the first call per ${subject}.`
+      );
+    }
+    return reader;
+  }
+  /**
+   * Reports the deprecated call form in which a bare compare function stands where the options
+   * object belongs, at most once per kernel and member name.
+   *
+   * Through `error` rather than `warn`: this names a mistake in the calling code, and its author
+   * has to see it wherever the application runs. `logger.warn` is asked `isWarn` first, and the
+   * shared `enable` behind that getter is off anywhere but `localhost` -- a deprecation notice
+   * that goes silent everywhere the code actually ships is no notice at all. See the table of
+   * call against getter under "Console Logger" in `docs/api-reference.md`.
+   *
+   * One line per kernel and member name: a shadow-object calling a deprecated member inside a
+   * loop would otherwise fill the console.
+   */
+  #reportDeprecatedIsEqualOption(options, apiName) {
+    if (typeof options !== "function" || this.#shownDeprecations.has(apiName)) return;
+    this.#logger.error(
+      `[shadow-objects] Deprecation Warning: The "isEqual" option of "${apiName}()" is now passed as {compare} argument. Please update your code accordingly.`
+    );
+    this.#shownDeprecations.add(apiName);
+  }
+  /**
+   * Answers whether the creation API still has anything to give, and reports it where it has not.
+   *
+   * Past the teardown the scope has released what it held and cleared what it tracked. A call
+   * arriving now would fill those maps again with entries no second teardown ever reaches -- the
+   * teardown runs once, and it has run. Such a call is therefore turned away rather than served.
+   *
+   * Turned away quietly: the callers that arrive late are the ones with nobody to catch a throw --
+   * a timer, a continuation behind an `await`, a callback of some other object that outlived this
+   * one. It is reported instead, through `error` for the same reason the deprecation report above
+   * uses it: this names a mistake in the calling code, and its author has to see it wherever the
+   * application runs. Once per member name and scope, because a stale timer comes back on its next
+   * tick and a line per tick would bury the first one.
+   */
+  #refuseAfterTearDown(apiName) {
+    if (!this.#isCreationApiClosed) return false;
+    if (!this.#lateCallsReported?.has(apiName)) {
+      (this.#lateCallsReported ??= /* @__PURE__ */ new Set()).add(apiName);
+      this.#logger.error(
+        `[shadow-objects] ${apiName}(): the creation scope of "${this.#displayName}" has torn down \u2014 the call does nothing. Something is still holding the creation API past the end of its shadow-object.`
+      );
+    }
+    return true;
+  }
+  useProperty(name, options) {
+    if (this.#refuseAfterTearDown("useProperty")) return inertSignal().get;
+    this.#reportDeprecatedIsEqualOption(options, "useProperty");
+    const opts = typeof options === "function" ? { compare: options } : options;
+    return this.#cachedReader(
+      name,
+      this.#propertyReaders,
+      this.#propertyCompares,
+      () => this.#entity.getPropertyReader(name),
+      opts,
+      "useProperty",
+      "property"
+    );
+  }
+  useProperties(props) {
+    const result = {};
+    for (const key in props) {
+      if (Object.hasOwn(props, key)) {
+        result[key] = this.useProperty(props[key]);
+      }
+    }
+    return result;
+  }
+  /**
+   * The body the two context providers share: one provider signal per name, created on the first
+   * call, attached to the entity-side context signal, and cleared on teardown unless the caller
+   * opted out -- a clearing that finds the way to the entity side still open. A source signal handed
+   * in instead of an initial value feeds the provider through a link of its own.
+   *
+   * The entity keeps every provider of a name together and answers the attachment with the release
+   * that detaches this one again. Releasing it does more than cut the feed: the entity then lets a
+   * provider that stays write its value once more, so the name ends up with a value that is actually
+   * still being provided rather than with what this shadow-object left behind on its way out.
+   *
+   * `attachToEntity` is called inside the creation branch only, so the entity-side signal is
+   * requested when a provider is actually created. The `clearOnDestroy` check sits outside that
+   * branch: every call is allowed to ask for the clearing, not only the one that created the signal.
+   * The request is booked once per provider, though -- a repeated ask does not queue a second write,
+   * and once a provider has one on file, an opt-out on a later call does not take it back.
+   */
+  #provideContextSignal(name, providers, attachToEntity, sourceOrInitialValue, opts) {
+    let ctxProvider = providers.get(name);
+    if (ctxProvider == null) {
+      const isSig = isSignal(sourceOrInitialValue);
+      const initialValue = isSig ? void 0 : toMaybe(sourceOrInitialValue);
+      ctxProvider = createSignal(initialValue, opts?.compare ? { compare: opts.compare } : void 0);
+      if (isSig) {
+        const ln = link(sourceOrInitialValue, ctxProvider);
+        this.#unsubscribeSecondary.add(ln.destroy.bind(ln));
+      }
+      this.#unsubscribeContextFeeds.add(attachToEntity(ctxProvider));
+      providers.set(name, ctxProvider);
+    }
+    if ((opts?.clearOnDestroy ?? true) && !this.#clearOnDestroyRegistered.has(ctxProvider)) {
+      this.#clearOnDestroyRegistered.add(ctxProvider);
+      this.#unsubscribeSecondary.add(() => {
+        ctxProvider.set(void 0);
+      });
+    }
+    return ctxProvider;
+  }
+  provideContext(name, sourceOrInitialValue, options) {
+    if (this.#refuseAfterTearDown("provideContext")) return inertSignal();
+    this.#reportDeprecatedIsEqualOption(options, "provideContext");
+    const opts = typeof options === "function" ? { compare: options } : options;
+    return this.#provideContextSignal(
+      name,
+      this.#contextProviders,
+      (provider) => this.#entity.attachContextProvider(name, provider),
+      sourceOrInitialValue,
+      opts
+    );
+  }
+  provideGlobalContext(name, sourceOrInitialValue, options) {
+    if (this.#refuseAfterTearDown("provideGlobalContext")) return inertSignal();
+    this.#reportDeprecatedIsEqualOption(options, "provideGlobalContext");
+    const opts = typeof options === "function" ? { compare: options } : options;
+    return this.#provideContextSignal(
+      name,
+      this.#contextRootProviders,
+      (provider) => this.#entity.attachGlobalContextProvider(name, provider),
+      sourceOrInitialValue,
+      opts
+    );
+  }
+  useContext(name, options) {
+    if (this.#refuseAfterTearDown("useContext")) return inertSignal().get;
+    this.#reportDeprecatedIsEqualOption(options, "useContext");
+    const opts = typeof options === "function" ? { compare: options } : options;
+    return this.#cachedReader(
+      name,
+      this.#contextReaders,
+      this.#contextReaderCompares,
+      () => this.#entity.useContext(name),
+      opts,
+      "useContext",
+      "context"
+    );
+  }
+  useParentContext(name, options) {
+    if (this.#refuseAfterTearDown("useParentContext")) return inertSignal().get;
+    this.#reportDeprecatedIsEqualOption(options, "useParentContext");
+    const opts = typeof options === "function" ? { compare: options } : options;
+    return this.#cachedReader(
+      name,
+      this.#contextParentReaders,
+      this.#contextParentReaderCompares,
+      () => this.#entity.useParentContext(name),
+      opts,
+      "useParentContext",
+      "parent context"
+    );
+  }
+  createSignal(...args) {
+    if (this.#refuseAfterTearDown("createSignal")) return inertSignal();
+    const sig = createSignal(...args);
+    this.#unsubscribeSecondary.add(() => {
+      destroySignal(sig);
+    });
+    return sig;
+  }
+  createEffect(...args) {
+    if (this.#refuseAfterTearDown("createEffect")) return inertEffect();
+    const effect = createEffect(...args);
+    this.#unsubscribeSecondary.add(effect.destroy);
+    return effect;
+  }
+  createMemo(...args) {
+    if (this.#refuseAfterTearDown("createMemo")) return inertSignal().get;
+    const sig = createMemo(...args);
+    this.#unsubscribeSecondary.add(() => {
+      destroySignal(sig);
+    });
+    return sig;
+  }
+  createResource(factory, cleanup) {
+    if (this.#refuseAfterTearDown("createResource")) return inertSignal();
+    const resourceSignal = createSignal();
+    const effect = createEffect(() => {
+      const resource = toMaybe(factory());
+      resourceSignal.set(resource);
+      if (resource !== void 0 && cleanup) {
+        return () => {
+          cleanup(resource);
+          resourceSignal.set(void 0);
+        };
+      }
+      return () => {
+        resourceSignal.set(void 0);
+      };
+    });
+    this.#unsubscribeSecondary.add(() => {
+      try {
+        effect.destroy();
+      } finally {
+        resourceSignal.set(void 0);
+        destroySignal(resourceSignal);
+      }
+    });
+    return resourceSignal;
+  }
+  on(...args) {
+    if (this.#refuseAfterTearDown("on")) return noSubscription;
+    const [firstArg] = args;
+    const unsubscribe = typeof firstArg === "string" || typeof firstArg === "symbol" || Array.isArray(firstArg) ? (
+      // @ts-ignore
+      on(this.#entity, ...args)
+    ) : (
+      // @ts-ignore
+      on(...args)
+    );
+    return this.#trackSubscription(unsubscribe);
+  }
+  once(...args) {
+    if (this.#refuseAfterTearDown("once")) return noSubscription;
+    const [firstArg] = args;
+    const unsubscribe = typeof firstArg === "string" || typeof firstArg === "symbol" || Array.isArray(firstArg) ? (
+      // @ts-ignore
+      once(this.#entity, ...args)
+    ) : (
+      // @ts-ignore
+      once(...args)
+    );
+    return this.#trackSubscription(unsubscribe);
+  }
+  /**
+   * The plain `emit()`, deliberately, where every notification the framework sends out of its own
+   * accord runs on the guarded dispatch. This one is outbound and belongs to the Shadow Object: it
+   * owns the listeners, a throw from one of them is its own bug, and letting it surface where it
+   * happened is the fastest way to find it. A listener that needs a policy of its own carries a
+   * `try`/`catch` in its own body, which is where that decision belongs.
+   */
+  emit(...args) {
+    if (this.#refuseAfterTearDown("emit")) return;
+    const [firstArg] = args;
+    if (typeof firstArg === "string" || typeof firstArg === "symbol" || Array.isArray(firstArg)) {
+      emit(this.#entity, ...args);
+    } else {
+      emit(...args);
+    }
+  }
+  onViewEvent(callback) {
+    if (this.#refuseAfterTearDown("onViewEvent")) return;
+    const unsub = on(this.#entity, onViewEvent, (type, data) => {
+      callback(type, data);
+    });
+    this.#unsubscribeSecondary.add(unsub);
+  }
+  onDestroy(callback) {
+    if (this.#refuseAfterTearDown("onDestroy")) return;
+    this.#unsubscribePrimary.add(callback);
+  }
+  dispatchMessageToView(type, data, transferables, traverseChildren = false) {
+    if (this.#refuseAfterTearDown("dispatchMessageToView")) return;
+    this.#entity.dispatchMessageToView(type, data, transferables, traverseChildren);
+  }
+}
+export {
+  ShadowObjectCreationScope
+};
+//# sourceMappingURL=ShadowObjectCreationScope.js.map