@spearwolf/shadow-objects 0.33.0 → 0.34.0

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

@@ -1,4 +1,4 @@
-import type { IComponentEvent, ShadowObjectType, SyncEvent } from '../types.js';
+import type { ComponentPropertiesType, IComponentEvent, ShadowObjectType, SyncEvent } from '../types.js';
 import { ConsoleLogger } from '../utils/ConsoleLogger.js';
 import { Entity } from './Entity.js';
 import { Registry } from './Registry.js';
@@ -7,14 +7,19 @@ export interface MessageToViewEvent {
     uuid: string;
     type: string;
     data?: unknown;
-    transferables?: Transferable[];
-    traverseChildren?: boolean;
+    transferables?: Transferable[] | undefined;
+    traverseChildren?: boolean | undefined;
+}
+interface OmittedGraphChild {
+    uuid: string;
+    reason: 'already-in-graph' | 'not-in-kernel';
 }
 interface EntityGraphNode {
     token: string;
     entity: Entity;
     props: Record<string, unknown>;
     children: EntityGraphNode[];
+    omittedChildren?: OmittedGraphChild[];
 }
 /**
  * The entity kernel manages the lifecycle of all entities and shadow-objects.
@@ -26,20 +31,60 @@ interface EntityGraphNode {
 export declare class Kernel {
     #private;
     registry: Registry;
-    readonly logger: ConsoleLogger;
+    /** The logger this Kernel reports through. */
+    get logger(): ConsoleLogger;
     constructor(registry?: Registry);
     getEntity(uuid: string): Entity;
+    /**
+     * The entity behind a uuid, or `undefined` when the kernel does not hold one.
+     *
+     * The counterpart to `getEntity()`, which throws. Which of the two a caller wants follows from what an
+     * absent entity means to it: a change that describes the entity tree -- a new parent, a new order, new
+     * properties -- names an entity the view believes to be there, and a uuid the kernel does not know is a
+     * disagreement the caller has to hear about. An event is the other case: it carries no structure, and the
+     * entity it was meant for may have been torn down between the two sides.
+     */
+    findEntity(uuid: string): Entity | undefined;
     hasEntity(uuid: string): boolean;
     /**
      * @returns all entities in breadth-first order
+     *
+     * The list belongs to the caller: sorting or reversing it changes nothing about what the next call
+     * hands out. The walk behind it visits every entity once, which also carries it over a children list
+     * that points back at an ancestor -- `Entity.addChild()` writes such a list without touching the parent
+     * link, so no check along the parent chain can cover it.
+     *
+     * A uuid the kernel no longer holds drops out, and what hangs below it with it -- `getEntityGraph()`
+     * walks the same tree by the same rule.
      */
     traverseLevelOrderBFS(reverse?: boolean): Entity[];
+    /**
+     * The entity tree as nested nodes, one node per entity. The visited set is what makes that count
+     * hold: a children list that points back at an ancestor would otherwise be walked forever, and this
+     * is the one traversal a caller reaches for while debugging a tree that is already broken. A child
+     * the walk leaves out is named at its parent under `omittedChildren`, with the reason -- a uuid the
+     * kernel does not hold, or one the walk has already placed elsewhere in the graph. A root the walk
+     * has already reached through another root's children falls off the top level without a note; it
+     * still stands in the graph, just at the other position.
+     */
     getEntityGraph(): EntityGraphNode[];
-    private getEntityGraphNode;
     upgradeEntities(): void;
+    /**
+     * Apply a change trail, entry by entry, and say how far it got if it cannot be applied in full.
+     *
+     * The loop ends at the entry that throws, so what the kernel holds afterwards is a prefix of the
+     * trail; the {@link ChangeTrailRefusedError} names its length. The counter sits behind
+     * `#parse` and therefore counts only entries that returned normally.
+     *
+     * An effect the batch defers belongs to no single entry: the batch releases it once the loop is
+     * through, and a throw from there arrives with every entry already counted. `appliedCount` then
+     * equals `entryCount` — everything was applied, something failed nevertheless, and both
+     * statements are true at once.
+     *
+     * @throws {ChangeTrailRefusedError} if any entry, or any effect the batch deferred, threw
+     */
     run(event: SyncEvent): void;
-    private parse;
-    createEntity(uuid: string, token: string, parentUuid?: string, order?: number, properties?: [string, unknown][], autoDestructionOnParentRemoval?: boolean): void;
+    createEntity(uuid: string, token: string, parentUuid?: string, order?: number, properties?: ComponentPropertiesType, autoDestructionOnParentRemoval?: boolean): void;
     destroyEntity(uuid: string): void;
     /**
      * @param order the new order, or `undefined` to keep the current one. A set-parent change
@@ -48,20 +93,34 @@ export declare class Kernel {
      */
     setParent(uuid: string, parentUuid?: string, order?: number): void;
     updateOrder(uuid: string, order: number): void;
+    /**
+     * Records that an entity has changed its place in the entity tree: it took a parent, lost one,
+     * or moved among its siblings. Two pieces of bookkeeping follow from that -- the cached
+     * traversal is dropped, and an entity without a parent joins the set of root entities while one
+     * with a parent leaves it.
+     *
+     * `Entity` reports here from every write that moves it, because those writes are reachable from
+     * a shadow-object with no kernel call in between: `entity.parent`, `entity.parentUuid`,
+     * `entity.order` and `entity.removeFromParent()`. The state is read off the entity rather than
+     * taken as an argument, so a caller cannot describe a move the entity did not make.
+     *
+     * A uuid the kernel does not hold reaches the cache and stops there: an entity joins the root
+     * set when the kernel takes it in and leaves it when the kernel lets go.
+     *
+     * That such a uuid passes in silence, where `setParent()` and `updateOrder()` throw at one, is the
+     * difference between a request and a report. Those two are asked to move an entity and cannot do it
+     * without one, so an unknown uuid is a disagreement the caller has to hear about. This is an entity
+     * saying where it stands, and it says so while the kernel is still taking it in: `createEntity()`
+     * writes the order on the entity before the entry is registered, so an entity created with an order
+     * of its own reports once before the kernel holds it. A throw there would cost the creation its own
+     * bookkeeping, and there is nothing to disagree about -- dropping the cache is right either way.
+     */
+    noteEntityTreeChange(uuid: string): void;
     dispatchEventsToEntity(uuid: string, events: IComponentEvent[]): void;
-    changeProperties(uuid: string, properties: [string, unknown][]): void;
+    changeProperties(uuid: string, properties: ComponentPropertiesType): void;
     changeToken(uuid: string, token: string): void;
     dispatchMessageToView(message: MessageToViewEvent): void;
-    /**
-     * Create or destroy the shadow-objects of an entity using the registered constructors.
-     * After a token change or registry changes, an entity may be given different shadow-objects.
-     */
-    private updateShadowObjects;
-    private constructShadowObject;
-    private createShadowObjects;
     findShadowObjects(uuid: string): ShadowObjectType[];
-    private attachShadowObject;
-    private destroyShadowObject;
     findOrCreateRootContext(name: string | symbol): SignalsPath;
     destroy(): void;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"Kernel.d.ts","sourceRoot":"","sources":["../../../src/in-the-dark/Kernel.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAEV,eAAe,EAIf,gBAAgB,EAEhB,SAAS,EACV,MAAM,aAAa,CAAC;AACrB,OAAO,EAAC,aAAa,EAAC,MAAM,2BAA2B,CAAC;AAExD,OAAO,EAAC,MAAM,EAAC,MAAM,aAAa,CAAC;AAEnC,OAAO,EAAC,QAAQ,EAAC,MAAM,eAAe,CAAC;AACvC,OAAO,EAAC,WAAW,EAAC,MAAM,kBAAkB,CAAC;AAE7C,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,aAAa,CAAC,EAAE,YAAY,EAAE,CAAC;IAC/B,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAQD,UAAU,eAAe;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,QAAQ,EAAE,eAAe,EAAE,CAAC;CAC7B;AAgBD;;;;;;GAMG;AACH,qBAAa,MAAM;;IACjB,QAAQ,EAAE,QAAQ,CAAC;IAEnB,QAAQ,CAAC,MAAM,gBAA+B;gBAWlC,QAAQ,CAAC,EAAE,QAAQ;IAK/B,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAmB/B,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIhC;;OAEG;IACH,qBAAqB,CAAC,OAAO,UAAQ,GAAG,MAAM,EAAE;IAkChD,cAAc,IAAI,eAAe,EAAE;IAMnC,OAAO,CAAC,kBAAkB;IAc1B,eAAe,IAAI,IAAI;IAmBvB,GAAG,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAW3B,OAAO,CAAC,KAAK;IA2Cb,YAAY,CACV,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,MAAM,EACnB,KAAK,SAAI,EACT,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAChC,8BAA8B,UAAQ,GACrC,IAAI;IA0BP,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IA6BjC;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAkClE,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAI9C,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,GAAG,IAAI;IAIrE,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI;IAKrE,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAW9C,qBAAqB,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI;IAMxD;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAqC3B,OAAO,CAAC,qBAAqB;IAmY7B,OAAO,CAAC,mBAAmB;IAM3B,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,EAAE;IASnD,OAAO,CAAC,kBAAkB;IAY1B,OAAO,CAAC,mBAAmB;IAU3B,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,WAAW;IAS3D,OAAO,IAAI,IAAI;CAUhB"}
+{"version":3,"file":"Kernel.d.ts","sourceRoot":"","sources":["../../../src/in-the-dark/Kernel.ts"],"names":[],"mappings":"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"}