@spearwolf/shadow-objects 0.33.0 → 0.35.0

package/src/in-the-dark/ShadowObjectCreationScope.d.ts

@@ -0,0 +1,133 @@
+import { on, once } from '@spearwolf/eventize';
+import { type CompareFunc, createEffect, createMemo, type Signal, type SignalReader } from '@spearwolf/signalize';
+import type { Maybe, ProvideContextOptions, ShadowObjectCreationAPI, ShadowObjectScopeDescription, ShadowObjectType, SignalValueOptions } from '../types.js';
+import type { ConsoleLogger } from '../utils/ConsoleLogger.js';
+import type { Entity } from './Entity.js';
+/**
+ * Everything a single shadow-object was given at construction time, and the end of all of it.
+ *
+ * The scope holds the signals, links and subscriptions the creation API hands out, and it hands the API
+ * itself to the kernel through `createAPI()`. The instance stays with the kernel: a shadow-object only ever
+ * sees the API object, never the scope behind it.
+ *
+ * One scope belongs to exactly one shadow-object, and it ends with it -- or, where the constructor throws,
+ * without it: a scope that never reached `bindTo()` is torn down by the kernel on the spot, and everything the
+ * constructor registered before the throw is released, although no shadow-object came out of it.
+ *
+ * Eight methods share their name with a module-level import: `on`, `once`, `emit`, `onDestroy`,
+ * `onViewEvent`, `createSignal`, `createEffect` and `createMemo`. They are named that way deliberately,
+ * because those names are part of the `ShadowObjectCreationAPI` contract a shadow-object destructures by
+ * name. Seven of them call or reference their namesake inside their own body; `onDestroy` is the exception,
+ * as its import is the entity event that `bindTo()` subscribes to. A bare name inside one of these eight
+ * bodies is therefore always the import, and a call on the method of the same name always carries `this.`
+ * -- `inertSignal`, `inertEffect` and `noSubscription` are bare names of a different kind, module-level
+ * functions with no method of the same name to tell them apart from.
+ */
+export declare class ShadowObjectCreationScope {
+    #private;
+    /**
+     * 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(): string;
+    /**
+     * The names this scope handed readers and providers out for, by kind, plus the display name. Read
+     * off the private maps and nothing else: no reader is created, no late call is reported, and a
+     * scope past its teardown answers empty lists rather than a throw -- `tearDown()` clears the maps
+     * it reads.
+     */
+    describe(): ShadowObjectScopeDescription;
+    constructor(entity: Entity, logger: ConsoleLogger, displayName: string, shownDeprecations: Set<string>);
+    /**
+     * 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(): ShadowObjectCreationAPI;
+    /**
+     * 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: ShadowObjectType, releaseScope: () => void, forgetShadowObject: () => void): void;
+    /**
+     * 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(): void;
+    useProperty<T = unknown>(name: string, options?: SignalValueOptions<T> | CompareFunc<T | undefined>): SignalReader<Maybe<T>>;
+    useProperties<T extends Record<string, unknown> = Record<string, unknown>>(props: {
+        [K in keyof T]: string;
+    }): {
+        [K in keyof T]: SignalReader<Maybe<T[K]>>;
+    };
+    provideContext<T = unknown>(name: string | symbol, sourceOrInitialValue?: T | SignalReader<T> | SignalReader<T | undefined>, options?: ProvideContextOptions<T> | CompareFunc<T | undefined>): Signal<any>;
+    provideGlobalContext<T = unknown>(name: string | symbol, sourceOrInitialValue?: T | SignalReader<T> | SignalReader<T | undefined>, options?: ProvideContextOptions<T> | CompareFunc<T | undefined>): Signal<any>;
+    useContext<T = unknown>(name: string | symbol, options?: SignalValueOptions<T> | CompareFunc<T | undefined>): SignalReader<any>;
+    useParentContext<T = unknown>(name: string | symbol, options?: SignalValueOptions<T> | CompareFunc<T | undefined>): SignalReader<any>;
+    createSignal(...args: any[]): any;
+    createEffect(...args: any[]): ReturnType<typeof createEffect>;
+    createMemo<T = unknown>(...args: Parameters<typeof createMemo<T>>): SignalReader<T>;
+    createResource<T = unknown>(factory: () => T | undefined, cleanup?: (resource: NonNullable<T>) => unknown): Signal<Maybe<T>>;
+    on(...args: any[]): ReturnType<typeof on>;
+    once(...args: any[]): ReturnType<typeof once>;
+    /**
+     * 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: any[]): void;
+    onViewEvent(callback: (type: string, data: unknown) => any): void;
+    onDestroy(callback: () => any): void;
+    dispatchMessageToView(type: string, data?: unknown, transferables?: Transferable[], traverseChildren?: boolean): void;
+}
+//# sourceMappingURL=ShadowObjectCreationScope.d.ts.map

package/src/in-the-dark/ShadowObjectCreationScope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShadowObjectCreationScope.d.ts","sourceRoot":"","sources":["../../../src/in-the-dark/ShadowObjectCreationScope.ts"],"names":[],"mappings":"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"}