@spearwolf/shadow-objects 0.30.2 → 0.31.0

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

@@ -1,569 +1,592 @@
-import { emit, eventize, off, on, once, Priority } from '@spearwolf/eventize';
-import { batch, createEffect, createMemo, createSignal, destroySignal, isSignal, link, } from '@spearwolf/signalize';
-import { ComponentChangeType, MessageToView } from '../constants.js';
-import { ConsoleLogger } from '../utils/ConsoleLogger.js';
-import { toMaybe } from '../utils/toMaybe.js';
-import { Entity } from './Entity.js';
-import { onCreate, onDestroy, onParentChanged, onViewEvent } from './events.js';
-import { Registry } from './Registry.js';
-import { SignalsPath } from './SignalsPath.js';
-var ShadowObjectAction;
-(function (ShadowObjectAction) {
-    ShadowObjectAction[ShadowObjectAction["CreateAndDestroy"] = 0] = "CreateAndDestroy";
-    ShadowObjectAction[ShadowObjectAction["JustCreate"] = 1] = "JustCreate";
-    ShadowObjectAction[ShadowObjectAction["DestroyOnly"] = 2] = "DestroyOnly";
-})(ShadowObjectAction || (ShadowObjectAction = {}));
+import { emit, eventize, off, on, once, Priority } from "@spearwolf/eventize";
+import {
+  batch,
+  createEffect,
+  createMemo,
+  createSignal,
+  destroySignal,
+  isSignal,
+  link
+} from "@spearwolf/signalize";
+import { ComponentChangeType, MessageToView } from "../constants.js";
+import { ConsoleLogger } from "../utils/ConsoleLogger.js";
+import { toMaybe } from "../utils/toMaybe.js";
+import { Entity } from "./Entity.js";
+import { onCreate, onDestroy, onParentChanged, onViewEvent } from "./events.js";
+import { Registry } from "./Registry.js";
+import { SignalsPath } from "./SignalsPath.js";
+var ShadowObjectAction = /* @__PURE__ */ ((ShadowObjectAction2) => {
+  ShadowObjectAction2[ShadowObjectAction2["CreateAndDestroy"] = 0] = "CreateAndDestroy";
+  ShadowObjectAction2[ShadowObjectAction2["JustCreate"] = 1] = "JustCreate";
+  ShadowObjectAction2[ShadowObjectAction2["DestroyOnly"] = 2] = "DestroyOnly";
+  return ShadowObjectAction2;
+})(ShadowObjectAction || {});
 const getDisplayName = (construct) => construct.displayName || construct.name;
 let provideContextOptionsDeprecatedShown = false;
 let provideGlobalContextOptionsDeprecatedShown = false;
 let useContextOptionsDeprecatedShown = false;
 let useParentContextOptionsDeprecatedShown = false;
 let usePropertyOptionsDeprecatedShown = false;
-/**
- * The entity kernel manages the lifecycle of all entities and shadow-objects.
- *
- * An entity is created for each view-component. The entities act as containers for the shadow-objects.
- *
- * Which shadow-objects are created is determined by the token.
- */
-export class Kernel {
-    #entities;
-    #rootEntities;
-    #allEntities;
-    #allEntitiesReversed;
-    #allEntitiesNeedUpdate;
-    #rootContexts;
-    constructor(registry) {
-        this.logger = new ConsoleLogger('Kernel');
-        this.#entities = new Map();
-        this.#rootEntities = new Set();
-        this.#allEntitiesNeedUpdate = true;
-        this.#rootContexts = new Map();
-        eventize(this);
-        this.registry = Registry.get(registry);
+class Kernel {
+  constructor(registry) {
+    this.logger = new ConsoleLogger("Kernel");
+    this.#entities = /* @__PURE__ */ new Map();
+    this.#rootEntities = /* @__PURE__ */ new Set();
+    this.#allEntitiesNeedUpdate = true;
+    this.#rootContexts = /* @__PURE__ */ new Map();
+    eventize(this);
+    this.registry = Registry.get(registry);
+  }
+  #entities;
+  #rootEntities;
+  #allEntities;
+  #allEntitiesReversed;
+  #allEntitiesNeedUpdate;
+  #rootContexts;
+  getEntity(uuid) {
+    const entity = this.#entities.get(uuid)?.entity;
+    if (!entity) {
+      throw new Error(`entity with uuid "${uuid}" not found!`);
     }
-    getEntity(uuid) {
-        const entity = this.#entities.get(uuid)?.entity;
-        if (!entity) {
-            throw new Error(`entity with uuid "${uuid}" not found!`);
+    return entity;
+  }
+  hasEntity(uuid) {
+    return this.#entities.has(uuid);
+  }
+  /**
+   * @returns all entities in breadth-first order
+   */
+  traverseLevelOrderBFS(reverse = false) {
+    if (this.#allEntitiesNeedUpdate) {
+      const lvl = /* @__PURE__ */ new Map();
+      const traverse = (uuid, depth) => {
+        const e = this.getEntity(uuid);
+        if (lvl.has(depth)) {
+          lvl.get(depth).push(e);
+        } else {
+          lvl.set(depth, [e]);
         }
-        return entity;
-    }
-    hasEntity(uuid) {
-        return this.#entities.has(uuid);
-    }
-    /**
-     * @returns all entities in breadth-first order
-     */
-    traverseLevelOrderBFS(reverse = false) {
-        if (this.#allEntitiesNeedUpdate) {
-            const lvl = new Map();
-            const traverse = (uuid, depth) => {
-                const e = this.getEntity(uuid);
-                if (lvl.has(depth)) {
-                    lvl.get(depth).push(e);
-                }
-                else {
-                    lvl.set(depth, [e]);
-                }
-                for (const child of e.children) {
-                    traverse(child.uuid, depth + 1);
-                }
-            };
-            this.#rootEntities.forEach((uuid) => {
-                traverse(uuid, 0);
-            });
-            this.#allEntities = Array.from(lvl.entries())
-                .sort((a, b) => a[0] - b[0])
-                .flatMap(([, entities]) => entities);
-            this.#allEntitiesReversed = this.#allEntities.slice().reverse();
-            this.#allEntitiesNeedUpdate = false;
+        for (const child of e.children) {
+          traverse(child.uuid, depth + 1);
         }
-        return reverse ? this.#allEntitiesReversed : this.#allEntities;
+      };
+      this.#rootEntities.forEach((uuid) => {
+        traverse(uuid, 0);
+      });
+      this.#allEntities = Array.from(lvl.entries()).sort((a, b) => a[0] - b[0]).flatMap(([, entities]) => entities);
+      this.#allEntitiesReversed = this.#allEntities.slice().reverse();
+      this.#allEntitiesNeedUpdate = false;
     }
-    getEntityGraph() {
-        return Array.from(this.#rootEntities).map((uuid) => this.getEntityGraphNode(uuid));
+    return reverse ? this.#allEntitiesReversed : this.#allEntities;
+  }
+  getEntityGraph() {
+    return Array.from(this.#rootEntities).map((uuid) => this.getEntityGraphNode(uuid));
+  }
+  getEntityGraphNode(uuid) {
+    if (!this.#entities.has(uuid)) return void 0;
+    const { token, entity } = this.#entities.get(uuid);
+    return {
+      token,
+      entity,
+      props: Object.fromEntries(entity.propEntries()),
+      children: entity.children.map((child) => this.getEntityGraphNode(child.uuid))
+    };
+  }
+  upgradeEntities() {
+    const entityConstructors = /* @__PURE__ */ new Map();
+    for (const entity of this.traverseLevelOrderBFS(true)) {
+      entityConstructors.set(entity.uuid, this.updateShadowObjects(entity.uuid, 2 /* DestroyOnly */));
     }
-    getEntityGraphNode(uuid) {
-        if (!this.#entities.has(uuid))
-            return undefined;
-        const { token, entity } = this.#entities.get(uuid);
-        return {
-            token,
-            entity,
-            props: Object.fromEntries(entity.propEntries()),
-            children: entity.children.map((child) => this.getEntityGraphNode(child.uuid)),
-        };
+    for (const entity of this.traverseLevelOrderBFS(false)) {
+      this.updateShadowObjects(entity.uuid, 1 /* JustCreate */, entityConstructors.get(entity.uuid));
     }
-    upgradeEntities() {
-        const entityConstructors = new Map();
-        for (const entity of this.traverseLevelOrderBFS(true)) {
-            entityConstructors.set(entity.uuid, this.updateShadowObjects(entity.uuid, ShadowObjectAction.DestroyOnly));
-        }
-        for (const entity of this.traverseLevelOrderBFS(false)) {
-            this.updateShadowObjects(entity.uuid, ShadowObjectAction.JustCreate, entityConstructors.get(entity.uuid));
-        }
-        entityConstructors.clear();
-    }
-    run(event) {
-        if (this.logger.isDebug) {
-            this.logger.debug('sync', event);
-        }
-        batch(() => {
-            for (const entry of event.changeTrail) {
-                this.parse(entry);
-            }
-        });
+    entityConstructors.clear();
+  }
+  run(event) {
+    if (this.logger.isDebug) {
+      this.logger.debug("sync", event);
     }
-    parse(entry) {
-        switch (entry.type) {
-            case ComponentChangeType.CreateEntities:
-                this.createEntity(entry.uuid, entry.token, entry.parentUuid, entry.order, entry.properties);
-                this.#allEntitiesNeedUpdate = true;
-                break;
-            case ComponentChangeType.DestroyEntities:
-                this.destroyEntity(entry.uuid);
-                this.#allEntitiesNeedUpdate = true;
-                break;
-            case ComponentChangeType.SetParent:
-                this.setParent(entry.uuid, entry.parentUuid, entry.order);
-                this.#allEntitiesNeedUpdate = true;
-                break;
-            case ComponentChangeType.UpdateOrder:
-                this.updateOrder(entry.uuid, entry.order);
-                this.#allEntitiesNeedUpdate = true;
-                break;
-            case ComponentChangeType.ChangeProperties:
-                this.changeProperties(entry.uuid, entry.properties);
-                break;
-            case ComponentChangeType.ChangeToken:
-                this.changeToken(entry.uuid, entry.token);
-                break;
-            case ComponentChangeType.SendEvents:
-                this.dispatchEventsToEntity(entry.uuid, entry.events);
-                break;
-        }
-    }
-    createEntity(uuid, token, parentUuid, order = 0, properties, autoDestructionOnParentRemoval = false) {
-        const e = new Entity(this, uuid);
-        e.order = order;
-        const entry = { token, entity: e, usedConstructors: new Map() };
-        this.#entities.set(uuid, entry);
-        if (parentUuid) {
-            e.parentUuid = parentUuid;
-        }
-        e.autoDestructionOnParentRemoval = autoDestructionOnParentRemoval;
-        if (!e.hasParent) {
-            this.#rootEntities.add(uuid);
-        }
-        if (properties) {
-            e.setProperties(properties);
-        }
-        this.createShadowObjects(uuid);
-    }
-    destroyEntity(uuid) {
-        if (!this.#entities.has(uuid))
-            return;
-        const { entity, usedConstructors } = this.#entities.get(uuid);
-        entity.removeFromParent();
-        emit(entity, onDestroy, entity);
-        usedConstructors.clear();
-        this.#entities.delete(entity.uuid);
-        this.#rootEntities.delete(entity.uuid);
+    batch(() => {
+      for (const entry of event.changeTrail) {
+        this.parse(entry);
+      }
+    });
+  }
+  parse(entry) {
+    switch (entry.type) {
+      case ComponentChangeType.CreateEntities:
+        this.createEntity(
+          entry.uuid,
+          entry.token,
+          entry.parentUuid,
+          entry.order,
+          entry.properties,
+          entry.autoDestructionOnParentRemoval
+        );
+        this.#allEntitiesNeedUpdate = true;
+        break;
+      case ComponentChangeType.DestroyEntities:
+        this.destroyEntity(entry.uuid);
+        this.#allEntitiesNeedUpdate = true;
+        break;
+      case ComponentChangeType.SetParent:
+        this.setParent(entry.uuid, entry.parentUuid, entry.order);
+        this.#allEntitiesNeedUpdate = true;
+        break;
+      case ComponentChangeType.UpdateOrder:
+        this.updateOrder(entry.uuid, entry.order);
+        this.#allEntitiesNeedUpdate = true;
+        break;
+      case ComponentChangeType.ChangeProperties:
+        this.changeProperties(entry.uuid, entry.properties);
+        break;
+      case ComponentChangeType.ChangeToken:
+        this.changeToken(entry.uuid, entry.token);
+        break;
+      case ComponentChangeType.SendEvents:
+        this.dispatchEventsToEntity(entry.uuid, entry.events);
+        break;
     }
-    setParent(uuid, parentUuid, order = 0) {
-        const e = this.getEntity(uuid);
-        if (e.parentUuid === parentUuid && e.order === order)
-            return;
-        e.removeFromParent();
-        e.order = order;
-        e.parentUuid = parentUuid;
-        if (e.hasParent) {
-            this.#rootEntities.delete(uuid);
-        }
-        else {
-            this.#rootEntities.add(uuid);
-        }
-        e.reSubscribeToParentContexts();
-        queueMicrotask(() => {
-            if (this.logger.isDebug) {
-                this.logger.debug('entity.onParentChanged', { uuid, parentUuid, order, entity: e });
-            }
-            emit(e, onParentChanged, e);
-        });
+  }
+  createEntity(uuid, token, parentUuid, order = 0, properties, autoDestructionOnParentRemoval = false) {
+    const e = new Entity(this, uuid);
+    e.order = order;
+    const entry = { token, entity: e, usedConstructors: /* @__PURE__ */ new Map() };
+    this.#entities.set(uuid, entry);
+    if (parentUuid) {
+      e.parentUuid = parentUuid;
     }
-    updateOrder(uuid, order) {
-        this.getEntity(uuid).order = order;
+    e.autoDestructionOnParentRemoval = autoDestructionOnParentRemoval;
+    if (!e.hasParent) {
+      this.#rootEntities.add(uuid);
     }
-    dispatchEventsToEntity(uuid, events) {
-        this.getEntity(uuid)?.dispatchViewEvents(events);
+    if (properties) {
+      e.setProperties(properties);
     }
-    changeProperties(uuid, properties) {
-        this.getEntity(uuid).setProperties(properties);
-        this.updateShadowObjects(uuid);
+    this.createShadowObjects(uuid);
+  }
+  destroyEntity(uuid) {
+    if (!this.#entities.has(uuid)) return;
+    const { entity, usedConstructors } = this.#entities.get(uuid);
+    const childrenSnapshot = [...entity.children];
+    for (const child of childrenSnapshot) {
+      if (child.autoDestructionOnParentRemoval) {
+        this.destroyEntity(child.uuid);
+      } else {
+        child.removeFromParent();
+        this.#rootEntities.add(child.uuid);
+      }
     }
-    changeToken(uuid, token) {
-        if (!this.#entities.has(uuid))
-            return;
-        const entry = this.#entities.get(uuid);
-        if (entry.token === token)
-            return;
-        entry.token = token;
-        this.updateShadowObjects(uuid);
+    entity.removeFromParent();
+    emit(entity, onDestroy, entity);
+    usedConstructors.clear();
+    this.#entities.delete(entity.uuid);
+    this.#rootEntities.delete(entity.uuid);
+    this.#allEntitiesNeedUpdate = true;
+  }
+  setParent(uuid, parentUuid, order = 0) {
+    const e = this.getEntity(uuid);
+    if (e.parentUuid === parentUuid && e.order === order) return;
+    if (parentUuid && !this.#entities.has(parentUuid)) {
+      throw new Error(`entity with uuid "${parentUuid}" not found!`);
     }
-    dispatchMessageToView(message) {
-        queueMicrotask(() => {
-            emit(this, MessageToView, message);
-        });
+    e.removeFromParent();
+    e.order = order;
+    e.parentUuid = parentUuid;
+    if (e.hasParent) {
+      this.#rootEntities.delete(uuid);
+    } else {
+      this.#rootEntities.add(uuid);
     }
-    /**
-     * 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.
-     */
-    updateShadowObjects(uuid, action = ShadowObjectAction.CreateAndDestroy, nextConstructors) {
-        const entry = this.#entities.get(uuid);
-        nextConstructors ??= new Set(this.registry.findConstructors(entry.token, entry.entity.truthyProps()));
-        const shouldDestroy = action === ShadowObjectAction.CreateAndDestroy || action === ShadowObjectAction.DestroyOnly;
-        const shouldCreate = action === ShadowObjectAction.CreateAndDestroy || action === ShadowObjectAction.JustCreate;
-        // destroy all shadow-objects created by constructors no longer in the list
-        //
-        if (shouldDestroy) {
-            for (const [construct, shadowObjects] of entry.usedConstructors) {
-                if (!nextConstructors.has(construct)) {
-                    entry.usedConstructors.delete(construct);
-                    for (const obj of shadowObjects) {
-                        this.destroyShadowObject(obj, entry.entity);
-                    }
-                }
-            }
+    e.reSubscribeToParentContexts();
+    queueMicrotask(() => {
+      if (this.logger.isDebug) {
+        this.logger.debug("entity.onParentChanged", { uuid, parentUuid, order, entity: e });
+      }
+      emit(e, onParentChanged, e);
+    });
+  }
+  updateOrder(uuid, order) {
+    this.getEntity(uuid).order = order;
+  }
+  dispatchEventsToEntity(uuid, events) {
+    this.getEntity(uuid)?.dispatchViewEvents(events);
+  }
+  changeProperties(uuid, properties) {
+    this.getEntity(uuid).setProperties(properties);
+    this.updateShadowObjects(uuid);
+  }
+  changeToken(uuid, token) {
+    if (!this.#entities.has(uuid)) return;
+    const entry = this.#entities.get(uuid);
+    if (entry.token === token) return;
+    entry.token = token;
+    this.updateShadowObjects(uuid);
+  }
+  dispatchMessageToView(message) {
+    queueMicrotask(() => {
+      emit(this, MessageToView, message);
+    });
+  }
+  /**
+   * 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.
+   */
+  updateShadowObjects(uuid, action = 0 /* CreateAndDestroy */, nextConstructors) {
+    const entry = this.#entities.get(uuid);
+    nextConstructors ??= new Set(this.registry.findConstructors(entry.token, entry.entity.truthyProps()));
+    const shouldDestroy = action === 0 /* CreateAndDestroy */ || action === 2 /* DestroyOnly */;
+    const shouldCreate = action === 0 /* CreateAndDestroy */ || action === 1 /* JustCreate */;
+    if (shouldDestroy) {
+      for (const [construct, shadowObjects] of entry.usedConstructors) {
+        if (!nextConstructors.has(construct)) {
+          entry.usedConstructors.delete(construct);
+          for (const obj of shadowObjects) {
+            this.destroyShadowObject(obj, entry.entity);
+          }
         }
-        // shadow-objects for new constructors are now created using the updated constructor list
-        //
-        if (shouldCreate) {
-            for (const construct of nextConstructors) {
-                if (!entry.usedConstructors.has(construct)) {
-                    this.constructShadowObject(construct, entry);
-                }
-            }
-        }
-        return nextConstructors;
+      }
     }
-    constructShadowObject(construct, entry) {
-        const unsubscribePrimary = new Set();
-        const unsubscribeSecondary = new Set();
-        const contextReaders = new Map();
-        const contextParentReaders = new Map();
-        const contextProviders = new Map();
-        const contextRootProviders = new Map();
-        const propertyReaders = new Map();
-        const getUseProperty = (name, options) => {
-            if (!usePropertyOptionsDeprecatedShown && options != null && typeof options === 'function') {
-                console.warn('[shadow-objects] Deprecation Warning: The "isEqual" option of "useProperty()" is now passed as {compare} argument. Please update your code accordingly.');
-                usePropertyOptionsDeprecatedShown = true;
-            }
-            const opts = typeof options === 'function' ? { compare: options } : options;
-            let propReader = propertyReaders.get(name);
-            if (propReader === undefined) {
-                propReader = createSignal(undefined, opts).get;
-                propertyReaders.set(name, propReader);
-                const con = link(entry.entity.getPropertyReader(name), propReader);
-                unsubscribeSecondary.add(con.destroy.bind(con));
-            }
-            return propReader;
-        };
-        const shadowObject = eventize(new construct({
-            entity: entry.entity,
-            provideContext(name, sourceOrInitialValue, options) {
-                if (!provideContextOptionsDeprecatedShown && options != null && typeof options === 'function') {
-                    console.warn('[shadow-objects] Deprecation Warning: The "isEqual" option of "provideContext()" is now passed as {compare} argument. Please update your code accordingly.');
-                    provideContextOptionsDeprecatedShown = true;
-                }
-                const opts = typeof options === 'function' ? { compare: options } : options;
-                let ctxProvider = contextProviders.get(name);
-                if (ctxProvider == null) {
-                    const isSig = isSignal(sourceOrInitialValue);
-                    const initialValue = isSig ? undefined : toMaybe(sourceOrInitialValue);
-                    ctxProvider = createSignal(initialValue, opts?.compare ? { compare: opts.compare } : undefined);
-                    if (isSig) {
-                        const ln = link(sourceOrInitialValue, ctxProvider);
-                        unsubscribeSecondary.add(ln.destroy.bind(ln));
-                    }
-                    const ln = link(ctxProvider, entry.entity.provideContext(name));
-                    unsubscribeSecondary.add(ln.destroy.bind(ln));
-                    contextProviders.set(name, ctxProvider);
-                }
-                if (ctxProvider != null && (opts?.clearOnDestroy ?? true)) {
-                    unsubscribeSecondary.add(() => {
-                        ctxProvider.set(undefined);
-                    });
-                }
-                return ctxProvider;
-            },
-            provideGlobalContext(name, sourceOrInitialValue, options) {
-                if (!provideGlobalContextOptionsDeprecatedShown && options != null && typeof options === 'function') {
-                    console.warn('[shadow-objects] Deprecation Warning: The "isEqual" option of "provideGlobalContext()" is now passed as {compare} argument. Please update your code accordingly.');
-                    provideGlobalContextOptionsDeprecatedShown = true;
-                }
-                const opts = typeof options === 'function' ? { compare: options } : options;
-                let ctxProvider = contextRootProviders.get(name);
-                if (ctxProvider == null) {
-                    const isSig = isSignal(sourceOrInitialValue);
-                    const initialValue = isSig ? undefined : toMaybe(sourceOrInitialValue);
-                    ctxProvider = createSignal(initialValue, opts?.compare ? { compare: opts.compare } : undefined);
-                    if (isSig) {
-                        const ln = link(sourceOrInitialValue, ctxProvider);
-                        unsubscribeSecondary.add(ln.destroy.bind(ln));
-                    }
-                    const ln = link(ctxProvider, entry.entity.provideGlobalContext(name));
-                    unsubscribeSecondary.add(ln.destroy.bind(ln));
-                    contextRootProviders.set(name, ctxProvider);
-                }
-                if (ctxProvider != null && (opts?.clearOnDestroy ?? true)) {
-                    unsubscribeSecondary.add(() => {
-                        ctxProvider.set(undefined);
-                    });
-                }
-                return ctxProvider;
-            },
-            useContext(name, options) {
-                if (!useContextOptionsDeprecatedShown && options != null && typeof options === 'function') {
-                    console.warn('[shadow-objects] Deprecation Warning: The "isEqual" option of "useContext()" is now passed as {compare} argument. Please update your code accordingly.');
-                    useContextOptionsDeprecatedShown = true;
-                }
-                const opts = typeof options === 'function' ? { compare: options } : options;
-                let ctxReader = contextReaders.get(name);
-                if (ctxReader === undefined) {
-                    ctxReader = createSignal(undefined, opts).get;
-                    contextReaders.set(name, ctxReader);
-                    const ln = link(entry.entity.useContext(name), ctxReader);
-                    unsubscribeSecondary.add(ln.destroy.bind(ln));
-                }
-                return ctxReader;
-            },
-            useParentContext(name, options) {
-                if (!useParentContextOptionsDeprecatedShown && options != null && typeof options === 'function') {
-                    console.warn('[shadow-objects] Deprecation Warning: The "isEqual" option of "useParentContext()" is now passed as {compare} argument. Please update your code accordingly.');
-                    useParentContextOptionsDeprecatedShown = true;
-                }
-                const opts = typeof options === 'function' ? { compare: options } : options;
-                let ctxReader = contextParentReaders.get(name);
-                if (ctxReader === undefined) {
-                    ctxReader = createSignal(undefined, opts).get;
-                    contextParentReaders.set(name, ctxReader);
-                    const ln = link(entry.entity.useParentContext(name), ctxReader);
-                    unsubscribeSecondary.add(ln.destroy.bind(ln));
-                }
-                return ctxReader;
-            },
-            dispatchMessageToView(type, data, transferables, traverseChildren = false) {
-                entry.entity.dispatchMessageToView(type, data, transferables, traverseChildren);
-            },
-            useProperty: getUseProperty,
-            useProperties(props) {
-                const result = {};
-                for (const key in props) {
-                    if (Object.hasOwn(props, key)) {
-                        result[key] = getUseProperty(props[key]);
-                    }
-                }
-                return result;
-            },
-            createResource(factory, cleanup) {
-                const resourceSignal = createSignal();
-                const effect = createEffect(() => {
-                    const resource = toMaybe(factory());
-                    resourceSignal.set(resource);
-                    if (resource !== undefined && cleanup) {
-                        return () => {
-                            cleanup(resource);
-                            resourceSignal.set(undefined);
-                        };
-                    }
-                    return () => {
-                        resourceSignal.set(undefined);
-                    };
-                });
-                unsubscribeSecondary.add(() => {
-                    effect.destroy();
-                    resourceSignal.set(undefined);
-                    destroySignal(resourceSignal);
-                });
-                return resourceSignal;
-            },
-            createEffect(...args) {
-                const effect = createEffect(...args);
-                unsubscribeSecondary.add(effect.destroy);
-                return effect;
-            },
-            createSignal(...args) {
-                const sig = createSignal(...args);
-                unsubscribeSecondary.add(() => {
-                    destroySignal(sig);
-                });
-                return sig;
-            },
-            createMemo(...args) {
-                const sig = createMemo(...args);
-                unsubscribeSecondary.add(() => {
-                    destroySignal(sig);
-                });
-                return sig;
-            },
-            on(...args) {
-                const [firstArg] = args;
-                if (typeof firstArg === 'string' || typeof firstArg === 'symbol' || Array.isArray(firstArg)) {
-                    // @ts-ignore
-                    const unsub = on(entry.entity, ...args);
-                    unsubscribeSecondary.add(unsub);
-                    return unsub;
-                }
-                // @ts-ignore
-                const unsub = on(...args);
-                unsubscribeSecondary.add(unsub);
-                // return unsub;
-                return Object.assign(() => {
-                    unsubscribeSecondary.delete(unsub);
-                    unsub();
-                }, unsub);
-            },
-            once(...args) {
-                const [firstArg] = args;
-                if (typeof firstArg === 'string' || typeof firstArg === 'symbol' || Array.isArray(firstArg)) {
-                    // @ts-ignore
-                    const unsub = once(entry.entity, ...args);
-                    unsubscribeSecondary.add(unsub);
-                    return unsub;
-                }
-                // @ts-ignore
-                const unsub = once(...args);
-                unsubscribeSecondary.add(unsub);
-                // return unsub;
-                return Object.assign(() => {
-                    unsubscribeSecondary.delete(unsub);
-                    unsub();
-                }, unsub);
-            },
-            emit(...args) {
-                const [firstArg] = args;
-                if (typeof firstArg === 'string' || typeof firstArg === 'symbol' || Array.isArray(firstArg)) {
-                    // @ts-ignore
-                    emit(entry.entity, ...args);
-                }
-                else {
-                    // @ts-ignore
-                    emit(...args);
-                }
-            },
-            onViewEvent(callback) {
-                const unsub = on(entry.entity, onViewEvent, (type, data) => {
-                    callback(type, data);
-                });
-                unsubscribeSecondary.add(unsub);
-            },
-            onDestroy(callback) {
-                unsubscribePrimary.add(callback);
-            },
-        }));
-        if (this.logger.isInfo) {
-            this.logger.info('create shadow-object', getDisplayName(construct), { shadowObject, entity: entry.entity });
+    if (shouldCreate) {
+      for (const construct of nextConstructors) {
+        if (!entry.usedConstructors.has(construct)) {
+          this.constructShadowObject(construct, entry);
         }
-        once(entry.entity, onDestroy, Priority.Low, () => {
-            if (this.logger.isInfo) {
-                this.logger.info('destroy shadow-object', getDisplayName(construct), { shadowObject, entity: entry.entity });
-            }
-            for (const callback of unsubscribePrimary) {
-                callback();
-            }
-            for (const callback of unsubscribeSecondary) {
-                callback();
-            }
-            for (const sig of contextReaders.values()) {
-                destroySignal(sig);
-            }
-            for (const sig of contextParentReaders.values()) {
-                destroySignal(sig);
-            }
-            for (const sig of propertyReaders.values()) {
-                destroySignal(sig);
+      }
+    }
+    return nextConstructors;
+  }
+  constructShadowObject(construct, entry) {
+    const unsubscribePrimary = /* @__PURE__ */ new Set();
+    const unsubscribeSecondary = /* @__PURE__ */ new Set();
+    const contextReaders = /* @__PURE__ */ new Map();
+    const contextReaderCompares = /* @__PURE__ */ new Map();
+    const contextParentReaders = /* @__PURE__ */ new Map();
+    const contextParentReaderCompares = /* @__PURE__ */ new Map();
+    const contextProviders = /* @__PURE__ */ new Map();
+    const contextRootProviders = /* @__PURE__ */ new Map();
+    const propertyReaders = /* @__PURE__ */ new Map();
+    const propertyCompares = /* @__PURE__ */ new Map();
+    const getUseProperty = (name, options) => {
+      if (!usePropertyOptionsDeprecatedShown && options != null && typeof options === "function") {
+        console.warn(
+          '[shadow-objects] Deprecation Warning: The "isEqual" option of "useProperty()" is now passed as {compare} argument. Please update your code accordingly.'
+        );
+        usePropertyOptionsDeprecatedShown = true;
+      }
+      const opts = typeof options === "function" ? { compare: options } : options;
+      let propReader = propertyReaders.get(name);
+      if (propReader === void 0) {
+        propReader = createSignal(void 0, opts).get;
+        propertyReaders.set(name, propReader);
+        propertyCompares.set(name, opts?.compare);
+        const con = link(entry.entity.getPropertyReader(name), propReader);
+        unsubscribeSecondary.add(con.destroy.bind(con));
+      } else if (opts?.compare != null && propertyCompares.get(name) !== opts.compare) {
+        console.warn(
+          `[shadow-objects] useProperty("${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 property.`
+        );
+      }
+      return propReader;
+    };
+    const shadowObject = eventize(
+      new construct({
+        entity: entry.entity,
+        provideContext(name, sourceOrInitialValue, options) {
+          if (!provideContextOptionsDeprecatedShown && options != null && typeof options === "function") {
+            console.warn(
+              '[shadow-objects] Deprecation Warning: The "isEqual" option of "provideContext()" is now passed as {compare} argument. Please update your code accordingly.'
+            );
+            provideContextOptionsDeprecatedShown = true;
+          }
+          const opts = typeof options === "function" ? { compare: options } : options;
+          let ctxProvider = contextProviders.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 ln2 = link(sourceOrInitialValue, ctxProvider);
+              unsubscribeSecondary.add(ln2.destroy.bind(ln2));
             }
-            for (const sig of contextProviders.values()) {
-                destroySignal(sig);
+            const ln = link(ctxProvider, entry.entity.provideContext(name));
+            unsubscribeSecondary.add(ln.destroy.bind(ln));
+            contextProviders.set(name, ctxProvider);
+          }
+          if (ctxProvider != null && (opts?.clearOnDestroy ?? true)) {
+            unsubscribeSecondary.add(() => {
+              ctxProvider.set(void 0);
+            });
+          }
+          return ctxProvider;
+        },
+        provideGlobalContext(name, sourceOrInitialValue, options) {
+          if (!provideGlobalContextOptionsDeprecatedShown && options != null && typeof options === "function") {
+            console.warn(
+              '[shadow-objects] Deprecation Warning: The "isEqual" option of "provideGlobalContext()" is now passed as {compare} argument. Please update your code accordingly.'
+            );
+            provideGlobalContextOptionsDeprecatedShown = true;
+          }
+          const opts = typeof options === "function" ? { compare: options } : options;
+          let ctxProvider = contextRootProviders.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 ln2 = link(sourceOrInitialValue, ctxProvider);
+              unsubscribeSecondary.add(ln2.destroy.bind(ln2));
             }
-            for (const sig of contextRootProviders.values()) {
-                destroySignal(sig);
+            const ln = link(ctxProvider, entry.entity.provideGlobalContext(name));
+            unsubscribeSecondary.add(ln.destroy.bind(ln));
+            contextRootProviders.set(name, ctxProvider);
+          }
+          if (ctxProvider != null && (opts?.clearOnDestroy ?? true)) {
+            unsubscribeSecondary.add(() => {
+              ctxProvider.set(void 0);
+            });
+          }
+          return ctxProvider;
+        },
+        useContext(name, options) {
+          if (!useContextOptionsDeprecatedShown && options != null && typeof options === "function") {
+            console.warn(
+              '[shadow-objects] Deprecation Warning: The "isEqual" option of "useContext()" is now passed as {compare} argument. Please update your code accordingly.'
+            );
+            useContextOptionsDeprecatedShown = true;
+          }
+          const opts = typeof options === "function" ? { compare: options } : options;
+          let ctxReader = contextReaders.get(name);
+          if (ctxReader === void 0) {
+            ctxReader = createSignal(void 0, opts).get;
+            contextReaders.set(name, ctxReader);
+            contextReaderCompares.set(name, opts?.compare);
+            const ln = link(entry.entity.useContext(name), ctxReader);
+            unsubscribeSecondary.add(ln.destroy.bind(ln));
+          } else if (opts?.compare != null && contextReaderCompares.get(name) !== opts.compare) {
+            console.warn(
+              `[shadow-objects] useContext("${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 context.`
+            );
+          }
+          return ctxReader;
+        },
+        useParentContext(name, options) {
+          if (!useParentContextOptionsDeprecatedShown && options != null && typeof options === "function") {
+            console.warn(
+              '[shadow-objects] Deprecation Warning: The "isEqual" option of "useParentContext()" is now passed as {compare} argument. Please update your code accordingly.'
+            );
+            useParentContextOptionsDeprecatedShown = true;
+          }
+          const opts = typeof options === "function" ? { compare: options } : options;
+          let ctxReader = contextParentReaders.get(name);
+          if (ctxReader === void 0) {
+            ctxReader = createSignal(void 0, opts).get;
+            contextParentReaders.set(name, ctxReader);
+            contextParentReaderCompares.set(name, opts?.compare);
+            const ln = link(entry.entity.useParentContext(name), ctxReader);
+            unsubscribeSecondary.add(ln.destroy.bind(ln));
+          } else if (opts?.compare != null && contextParentReaderCompares.get(name) !== opts.compare) {
+            console.warn(
+              `[shadow-objects] useParentContext("${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 parent context.`
+            );
+          }
+          return ctxReader;
+        },
+        dispatchMessageToView(type, data, transferables, traverseChildren = false) {
+          entry.entity.dispatchMessageToView(type, data, transferables, traverseChildren);
+        },
+        useProperty: getUseProperty,
+        useProperties(props) {
+          const result = {};
+          for (const key in props) {
+            if (Object.hasOwn(props, key)) {
+              result[key] = getUseProperty(props[key]);
             }
-            unsubscribePrimary.clear();
-            unsubscribeSecondary.clear();
-            contextReaders.clear();
-            contextParentReaders.clear();
-            propertyReaders.clear();
-            contextProviders.clear();
-            contextRootProviders.clear();
-            const otherShadowObjects = entry.usedConstructors.get(construct);
-            if (otherShadowObjects) {
-                otherShadowObjects.delete(shadowObject);
-                if (otherShadowObjects.size === 0) {
-                    entry.usedConstructors.delete(construct);
-                }
+          }
+          return result;
+        },
+        createResource(factory, cleanup) {
+          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);
+              };
             }
-        });
-        // We want to keep track which shadow-objects are created by which constructors.
-        // This will all
-        //
-        if (entry.usedConstructors.has(construct)) {
-            entry.usedConstructors.get(construct).add(shadowObject);
+            return () => {
+              resourceSignal.set(void 0);
+            };
+          });
+          unsubscribeSecondary.add(() => {
+            effect.destroy();
+            resourceSignal.set(void 0);
+            destroySignal(resourceSignal);
+          });
+          return resourceSignal;
+        },
+        createEffect(...args) {
+          const effect = createEffect(...args);
+          unsubscribeSecondary.add(effect.destroy);
+          return effect;
+        },
+        createSignal(...args) {
+          const sig = createSignal(...args);
+          unsubscribeSecondary.add(() => {
+            destroySignal(sig);
+          });
+          return sig;
+        },
+        createMemo(...args) {
+          const sig = createMemo(...args);
+          unsubscribeSecondary.add(() => {
+            destroySignal(sig);
+          });
+          return sig;
+        },
+        on(...args) {
+          const [firstArg] = args;
+          if (typeof firstArg === "string" || typeof firstArg === "symbol" || Array.isArray(firstArg)) {
+            const unsub2 = on(entry.entity, ...args);
+            unsubscribeSecondary.add(unsub2);
+            return unsub2;
+          }
+          const unsub = on(...args);
+          unsubscribeSecondary.add(unsub);
+          return Object.assign(() => {
+            unsubscribeSecondary.delete(unsub);
+            unsub();
+          }, unsub);
+        },
+        once(...args) {
+          const [firstArg] = args;
+          if (typeof firstArg === "string" || typeof firstArg === "symbol" || Array.isArray(firstArg)) {
+            const unsub2 = once(entry.entity, ...args);
+            unsubscribeSecondary.add(unsub2);
+            return unsub2;
+          }
+          const unsub = once(...args);
+          unsubscribeSecondary.add(unsub);
+          return Object.assign(() => {
+            unsubscribeSecondary.delete(unsub);
+            unsub();
+          }, unsub);
+        },
+        emit(...args) {
+          const [firstArg] = args;
+          if (typeof firstArg === "string" || typeof firstArg === "symbol" || Array.isArray(firstArg)) {
+            emit(entry.entity, ...args);
+          } else {
+            emit(...args);
+          }
+        },
+        onViewEvent(callback) {
+          const unsub = on(entry.entity, onViewEvent, (type, data) => {
+            callback(type, data);
+          });
+          unsubscribeSecondary.add(unsub);
+        },
+        onDestroy(callback) {
+          unsubscribePrimary.add(callback);
         }
-        else {
-            entry.usedConstructors.set(construct, new Set([shadowObject]));
+      })
+    );
+    if (this.logger.isInfo) {
+      this.logger.info("create shadow-object", getDisplayName(construct), { shadowObject, entity: entry.entity });
+    }
+    once(entry.entity, onDestroy, Priority.Low, () => {
+      if (this.logger.isInfo) {
+        this.logger.info("destroy shadow-object", getDisplayName(construct), { shadowObject, entity: entry.entity });
+      }
+      for (const callback of unsubscribePrimary) {
+        callback();
+      }
+      for (const callback of unsubscribeSecondary) {
+        callback();
+      }
+      for (const sig of contextReaders.values()) {
+        destroySignal(sig);
+      }
+      for (const sig of contextParentReaders.values()) {
+        destroySignal(sig);
+      }
+      for (const sig of propertyReaders.values()) {
+        destroySignal(sig);
+      }
+      for (const sig of contextProviders.values()) {
+        destroySignal(sig);
+      }
+      for (const sig of contextRootProviders.values()) {
+        destroySignal(sig);
+      }
+      unsubscribePrimary.clear();
+      unsubscribeSecondary.clear();
+      contextReaders.clear();
+      contextParentReaders.clear();
+      propertyReaders.clear();
+      contextProviders.clear();
+      contextRootProviders.clear();
+      const otherShadowObjects = entry.usedConstructors.get(construct);
+      if (otherShadowObjects) {
+        otherShadowObjects.delete(shadowObject);
+        if (otherShadowObjects.size === 0) {
+          entry.usedConstructors.delete(construct);
         }
-        this.attachShadowObject(shadowObject, entry.entity);
-        return shadowObject;
+      }
+    });
+    if (entry.usedConstructors.has(construct)) {
+      entry.usedConstructors.get(construct).add(shadowObject);
+    } else {
+      entry.usedConstructors.set(construct, /* @__PURE__ */ new Set([shadowObject]));
     }
-    createShadowObjects(uuid) {
-        const entry = this.#entities.get(uuid);
-        this.registry.findConstructors(entry.token, entry.entity.truthyProps())?.forEach((construct) => {
-            this.constructShadowObject(construct, entry);
-        });
+    this.attachShadowObject(shadowObject, entry.entity);
+    return shadowObject;
+  }
+  createShadowObjects(uuid) {
+    const entry = this.#entities.get(uuid);
+    this.registry.findConstructors(entry.token, entry.entity.truthyProps())?.forEach((construct) => {
+      this.constructShadowObject(construct, entry);
+    });
+  }
+  findShadowObjects(uuid) {
+    if (!this.#entities.has(uuid)) return [];
+    const { usedConstructors } = this.#entities.get(uuid);
+    return Array.from(new Set(Array.from(usedConstructors.values()).flatMap((objs) => Array.from(objs))));
+  }
+  attachShadowObject(shadowObject, entity) {
+    on(entity, shadowObject);
+    if (typeof shadowObject[onCreate] === "function") {
+      shadowObject[onCreate](entity);
     }
-    findShadowObjects(uuid) {
-        if (!this.#entities.has(uuid))
-            return [];
-        const { usedConstructors } = this.#entities.get(uuid);
-        return Array.from(new Set(Array.from(usedConstructors.values()).flatMap((objs) => Array.from(objs))));
+  }
+  destroyShadowObject(shadowObject, entity) {
+    if (typeof shadowObject[onDestroy] === "function") {
+      shadowObject[onDestroy](entity);
     }
-    attachShadowObject(shadowObject, entity) {
-        // Like all other objects, the new shadow-object should be able to respond to the events that the entity receives.
-        //
-        on(entity, shadowObject);
-        // Finally, the `shadowObject.onCreate(entity)` callback is called on the shadow-object.
-        //
-        if (typeof shadowObject[onCreate] === 'function') {
-            shadowObject[onCreate](entity);
-        }
+    emit(shadowObject, onDestroy, entity);
+    off(entity, shadowObject);
+  }
+  findOrCreateRootContext(name) {
+    let ctx = this.#rootContexts.get(name);
+    if (!ctx) {
+      ctx = new SignalsPath();
+      this.#rootContexts.set(name, ctx);
     }
-    destroyShadowObject(shadowObject, entity) {
-        if (typeof shadowObject[onDestroy] === 'function') {
-            shadowObject[onDestroy](entity);
-        }
-        emit(shadowObject, onDestroy, entity);
-        off(entity, shadowObject);
-    }
-    findOrCreateRootContext(name) {
-        let ctx = this.#rootContexts.get(name);
-        if (!ctx) {
-            ctx = new SignalsPath();
-            this.#rootContexts.set(name, ctx);
-        }
-        return ctx;
+    return ctx;
+  }
+  destroy() {
+    for (const ctx of this.#rootContexts.values()) {
+      ctx.dispose();
     }
-    destroy() {
-        for (const ctx of this.#rootContexts.values()) {
-            ctx.dispose();
-        }
-        this.#rootContexts.clear();
-        for (const entity of this.traverseLevelOrderBFS().reverse()) {
-            this.destroyEntity(entity.uuid);
-        }
+    this.#rootContexts.clear();
+    for (const entity of this.traverseLevelOrderBFS().reverse()) {
+      this.destroyEntity(entity.uuid);
     }
+  }
 }
-//# sourceMappingURL=Kernel.js.map
+export {
+  Kernel
+};
+//# sourceMappingURL=Kernel.js.map