entity: auto destruction on parent removal

Author: spearwolf

packages/shadow-objects/CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to [@spearwolf/shadow-objects](https://github.com/spearwolf/
 The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.30.2] - 2026-02-26
+
+- **API Update:** When calling the `kernel.createEntity()` function, there is now a new parameter `autoDestructionOnParentRemoval`. This makes it easier to create entities yourself from inside a shadow-object.
+  - These entities created _internally_ or _in the dark_ are then cleaned up when the original entity is deleted from the view.
+  - Allow access to `entity.kernel` from inside a shadow-object.
+
 ## [0.30.1] - 2026-02-04
 
 - update dependencies

packages/shadow-objects/package.json

@@ -2,7 +2,7 @@
   "name": "@spearwolf/shadow-objects",
   "description": "a reactive entity-component framework that feels at home in the shadows",
   "homepage": "https://github.com/spearwolf/shadow-objects/",
-  "version": "0.30.1",
+  "version": "0.30.2",
   "author": {
     "name": "Wolfger Schramm",
     "email": "wolfger@spearwolf.de",

packages/shadow-objects/src/in-the-dark/Entity.ts

@@ -143,6 +143,8 @@ export class Entity {
     this.#props.clear();
     off(this);
 
+    this.#autoDestructionSubscription?.();
+
     for (const rootCtx of this.#rootContexts.values()) {
       rootCtx.cleanup();
       rootCtx.signal.destroy();
@@ -224,6 +226,25 @@ export class Entity {
     }
   }
 
+  #autoDestructionSubscription?: () => void;
+
+  get autoDestructionOnParentRemoval(): boolean {
+    return !!this.#autoDestructionSubscription;
+  }
+
+  set autoDestructionOnParentRemoval(autoDestruct: boolean) {
+    if (autoDestruct) {
+      if (!this.#autoDestructionSubscription && this.parentUuid) {
+        this.#autoDestructionSubscription = once(this.parent, onDestroy, Priority.Max, () => {
+          this.kernel.destroyEntity(this.uuid);
+        });
+      }
+    } else if (this.#autoDestructionSubscription) {
+      this.#autoDestructionSubscription();
+      this.#autoDestructionSubscription = undefined;
+    }
+  }
+
   reSubscribeToParentContexts() {
     for (const [, ctx] of this.#context) {
       this.#subscribeToParent(ctx);

packages/shadow-objects/src/in-the-dark/Kernel.spec.ts

@@ -1,5 +1,5 @@
 import {emit, on} from '@spearwolf/eventize';
-import {createSignal, type Signal, type SignalReader, value} from '@spearwolf/signalize';
+import {createSignal, value, type Signal, type SignalReader} from '@spearwolf/signalize';
 import {afterEach, describe, expect, it, vi} from 'vitest';
 import {MessageToView} from '../constants.js';
 import type {ShadowObjectCreationAPI} from '../types.js';
@@ -1048,4 +1048,33 @@ describe('Kernel', () => {
       kernel.destroy();
     });
   });
+
+  describe('Entity destruction', () => {
+    it('Entity destruction should destroy children', () => {
+      const registry = new Registry();
+      const kernel = new Kernel(registry);
+
+      const destroyCallback = vi.fn();
+
+      @ShadowObject({registry, token: 'testOnDestroy'})
+      class TestOnDestroy {
+        constructor({onDestroy, entity}: ShadowObjectCreationAPI) {
+          onDestroy(() => destroyCallback(entity.uuid));
+        }
+      }
+      expect(TestOnDestroy).toBeDefined();
+
+      const [parentUuid, childUuid] = [generateUUID(), generateUUID()];
+
+      kernel.createEntity(parentUuid, 'testOnDestroy');
+      kernel.createEntity(childUuid, 'testOnDestroy', parentUuid, 0, undefined, true);
+
+      expect(destroyCallback).not.toHaveBeenCalled();
+
+      kernel.destroyEntity(parentUuid);
+
+      expect(destroyCallback).toHaveBeenNthCalledWith(1, childUuid);
+      expect(destroyCallback).toHaveBeenNthCalledWith(2, parentUuid);
+    });
+  });
 });

packages/shadow-objects/src/in-the-dark/Kernel.ts

@@ -215,7 +215,14 @@ export class Kernel {
     }
   }
 
-  createEntity(uuid: string, token: string, parentUuid?: string, order = 0, properties?: [string, unknown][]): void {
+  createEntity(
+    uuid: string,
+    token: string,
+    parentUuid?: string,
+    order = 0,
+    properties?: [string, unknown][],
+    autoDestructionOnParentRemoval = false,
+  ): void {
     const e = new Entity(this, uuid);
 
     e.order = order;
@@ -228,6 +235,8 @@ export class Kernel {
       e.parentUuid = parentUuid;
     }
 
+    e.autoDestructionOnParentRemoval = autoDestructionOnParentRemoval;
+
     if (!e.hasParent) {
       this.#rootEntities.add(uuid);
     }

packages/shadow-objects/src/types.ts

@@ -1,4 +1,4 @@
-import type {AnyEventNames, EventArgs, EventizedObject, SubscribeArgs, on, once} from '@spearwolf/eventize';
+import type {AnyEventNames, EventArgs, EventizedObject, on, once, SubscribeArgs} from '@spearwolf/eventize';
 import type {CompareFunc, createEffect, createMemo, createSignal, Signal, SignalReader} from '@spearwolf/signalize';
 import type {AppliedChangeTrail, ComponentChangeType, ImportedModule} from './constants.js';
 import type {Entity} from './in-the-dark/Entity.js';
@@ -86,7 +86,7 @@ export interface AppliedChangeTrailEvent {
 }
 
 export type EntityApi = Readonly<
-  Pick<Entity, 'uuid' | 'order' | 'hasParent' | 'propKeys' | 'propEntries'> & {
+  Pick<Entity, 'uuid' | 'order' | 'hasParent' | 'propKeys' | 'propEntries' | 'kernel'> & {
     parent?: EntityApi;
     children: readonly EntityApi[];
     traverse(callback: (entity: EntityApi) => unknown): void;