@adobe/ecs 0.0.0-stage → 0.2.0

package/src/implementation/world/observer-joined.test.ts

@@ -0,0 +1,366 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { Index, System, workers } from "../../index.js";
+import { Entity } from "../../interface/entity/entity.js";
+import type { World } from "../../interface/world/world.js";
+import { createWorld, join, type CreatedWorld } from "./create.js";
+import { tablesOf } from "./join.js";
+import { Observe } from "../../observe/index.js";
+import { catchOutOfBand, runReported } from "./outcomes.test-helper.js";
+
+// Observer systems on a joined thread, with the world and the thread on this one, joined through a MessageChannel.
+
+const level = Symbol("observerJoinedTest/level");
+const amount = Symbol("observerJoinedTest/amount");
+const cell = Symbol("observerJoinedTest/cell");
+const tagged = Symbol("observerJoinedTest/tagged");
+const label = Symbol("observerJoinedTest/label");
+const name = Symbol("observerJoinedTest/name");
+declare module "@adobe/ecs" {
+    interface Threads {
+        observerJoinedTest: true;
+    }
+    interface Components {
+        [amount]: { type: number };
+        [cell]: { type: number };
+        [tagged]: { type: true };
+        [label]: { type: Label; thread: "observerJoinedTest" };
+        [name]: { type: string; default: "" };
+    }
+    interface Resources {
+        [level]: { type: number };
+    }
+}
+/** The label's start, which a command here gives it by this value. */
+const blank = { text: "" } as const;
+/** A label, which starts as `blank`, the value commands on other threads give it by identity. */
+type Label = { readonly text: string };
+const Label = { default: blank };
+
+const byCell = Index.create({ key: [cell], components: { with: [amount] } });
+const allTagged = Index.create({ key: [], components: { with: [tagged] } });
+
+const raise = System.create({}, ({ resources }) => { resources[level] += 1; });
+const nothing = System.create({}, () => {});
+const spawn = System.create({}, ({ commands }, input: { readonly at: number }) => {
+    commands.spawn([amount, cell, tagged])({ [amount]: input.at, [cell]: input.at });
+});
+const spawnLabelled = System.create({}, ({ commands }) => { commands.spawn([amount, label])({ [amount]: 4, [label]: blank }); });
+const grow = System.create({ components: { with: [amount] } }, row => { row[amount] += 1; });
+const move = System.create({ components: { with: [cell] } }, row => { row[cell] += 10; });
+
+/** What the joined thread's observer bodies saw, reset by each test. */
+const seen: { levels: number[]; amounts: number[][]; looked: (number | boolean)[][]; tagged: number[]; labels: string[]; calls: number } = { levels: [], amounts: [], looked: [], tagged: [], labels: [], calls: 0 };
+const reset = (): void => {
+    seen.levels.length = seen.amounts.length = seen.looked.length = seen.tagged.length = seen.labels.length = 0;
+    seen.calls = 0;
+};
+
+/** The entities the tests look up, by the joined thread's systems. */
+const watched: Entity[] = [];
+
+const watchLevel = System.create({ observer: true, resources: { changed: [level] } }, ({ resources }) => {
+    seen.calls++;
+    seen.levels.push(resources[level]);
+});
+const watchAmounts = System.create({ observer: true, components: { with: [amount], changed: [amount] } }, row => {
+    (seen.amounts[seen.amounts.length - 1] ??= []).push(row[amount]);
+});
+const startAmounts = System.create({ observer: true }, () => { seen.amounts.push([]); });
+const amountsPass = System.create([startAmounts, watchAmounts]);
+const lookChanged = System.create({ observer: true, lookup: { found: { with: [amount], changed: [amount] } } }, ({ lookup }) => {
+    seen.looked.push(watched.flatMap(entity => {
+        const row = lookup.found(entity);
+        return row === null ? [] : [row[amount], row.changed];
+    }));
+});
+const countTagged = System.create({ observer: true, lookup: { all: { index: allTagged } } }, ({ lookup }) => {
+    seen.tagged.push(lookup.all().length);
+});
+const inCell = System.create({ observer: true, lookup: { found: { index: byCell } } }, ({ lookup }) => {
+    const found = lookup.found(11);
+    seen.tagged.push(found.length === 0 ? 0 : found.length * 100 + (found.at(0)?.[amount] ?? -1));
+});
+const failing = System.create({ observer: true }, ({ resources }) => {
+    if (resources[level] > 1) throw new Error("observer joined failure");
+});
+const readLabels = System.create({ observer: true, components: { with: [label, amount] } }, row => {
+    seen.labels.push(`${row[label].text}${row[amount]}`);
+});
+
+/** On the joined thread, as it reads labels: each watched entity's label and amount, which the world's run resolves to. */
+const labelsThere = System.create({ observer: true, lookup: { labelled: { with: [label, amount] } } }, ({ lookup }) =>
+    watched.map(entity => {
+        const row = lookup.labelled(entity);
+        return row === null ? "none" : `${row[label].text}${row[amount]}`;
+    }));
+/** On the joined thread, as it reads labels: throws there. */
+const failsThere = System.create({ observer: true, lookup: { labelled: { with: [label] } } }, ({ lookup }) => {
+    if (lookup.labelled(Entity.none) === null) throw new Error("observerJoinedTest failure there");
+    return 0;
+});
+
+/** Resolves once `done` holds, between turns of the event loop, which the joined thread's work needs. */
+const settled = async (done: () => boolean): Promise<void> => {
+    for (let turn = 0; turn < 2000 && !done(); turn++) await new Promise(resolve => setTimeout(resolve, 0));
+};
+/** A few turns of the event loop, for work that should not happen to show it didn't. */
+const turns = async (count = 20): Promise<void> => {
+    for (let turn = 0; turn < count; turn++) await new Promise(resolve => setTimeout(resolve, 0));
+};
+
+const joined = async (threads: readonly "observerJoinedTest"[] = []): Promise<{ readonly world: CreatedWorld; readonly remote: World; readonly close: () => Promise<void> }> => {
+    const world = createWorld({ [workers]: 0 });
+    const channel = new MessageChannel();
+    const shared = world.share(channel.port1);
+    const remote = await join(channel.port2, { threads });
+    await shared;
+    return {
+        world, remote,
+        close: async () => {
+            await remote.dispose();
+            await world.dispose();
+        },
+    };
+};
+
+describe("observer systems on a joined thread", () => {
+    it("run there after each sync point, reading resources as of it, only when a filter may pass", async () => {
+        reset();
+        const { world, remote, close } = await joined();
+        remote.add(watchLevel);
+        await turns();
+        await world.run(raise);
+        await settled(() => seen.levels.length === 1);
+        await world.run(raise);
+        await settled(() => seen.levels.length === 2);
+        // Nothing it filters on changed: the thread isn't woken for it.
+        await world.run(nothing);
+        await turns();
+        expect(seen.levels).toEqual([1, 2]);
+        await close();
+    });
+
+    it("run once, for the newest sync point, after falling behind", async () => {
+        reset();
+        const { world, remote, close } = await joined();
+        remote.add(watchLevel);
+        await turns();
+        await Promise.all([world.run(raise), world.run(raise), world.run(raise)]);
+        await settled(() => seen.levels.length >= 1);
+        await turns();
+        expect(seen.levels).toEqual([3]);
+        await close();
+    });
+
+    it("read rows with change filters, and composites of observer systems", async () => {
+        reset();
+        const { world, remote, close } = await joined();
+        remote.add(amountsPass);
+        await turns();
+        await world.run(spawn, { at: 1 });
+        await settled(() => seen.amounts.length === 1);
+        await world.run(spawn, { at: 5 });
+        await settled(() => seen.amounts.length === 2);
+        await world.run(grow);
+        await settled(() => seen.amounts.length === 3);
+        expect(seen.amounts).toEqual([[1], [5], [2, 6]]);
+        await close();
+    });
+
+    it("look up by entity with changed, and through keyless and keyed indexes, in shared memory", async () => {
+        reset();
+        const { world, remote, close } = await joined();
+        await world.run(spawn, { at: 1 });
+        await world.run(spawn, { at: 2 });
+        const [first, second] = await new Promise<readonly Entity[]>(resolve => {
+            const stop = Observe.select(world, { required: [amount], order: { [amount]: true } })(entities => {
+                if (entities.length < 2) return;
+                queueMicrotask(() => stop());
+                resolve(entities);
+            });
+        });
+        watched.length = 0;
+        watched.push(first, second);
+        remote.add(lookChanged);
+        remote.add(countTagged);
+        await turns();
+        await world.run(nothing);
+        await settled(() => seen.looked.length === 1 && seen.tagged.length === 1);
+        await world.run(grow);
+        await settled(() => seen.looked.length === 2);
+        await world.run(spawn, { at: 3 });
+        await settled(() => seen.tagged.at(-1) === 3);
+        expect(seen.looked.slice(0, 2)).toEqual([[1, true, 2, true], [2, true, 3, true]]);
+        // Nothing they read changed since they last ran.
+        expect(seen.looked.at(-1)).toEqual([2, false, 3, false]);
+        expect([seen.tagged[0], seen.tagged.at(-1)]).toEqual([2, 3]);
+        remote.remove(lookChanged);
+        remote.remove(countTagged);
+        seen.tagged.length = 0;
+        remote.add(inCell);
+        await turns();
+        await world.run(move);
+        await settled(() => seen.tagged.length === 1);
+        // Cells 1, 2 and 3 moved to 11, 12 and 13; the first's amount grew to 2.
+        expect(seen.tagged).toEqual([102]);
+        await close();
+    });
+
+    it("look up through indexes without ids, which the world makes from their declarations", async () => {
+        reset();
+        const { world, remote, close } = await joined();
+        await world.run(spawn, { at: 1 });
+        await world.run(spawn, { at: 11 });
+        // Made in a function, so the build gives them no id.
+        const made = (): readonly [Index<{ readonly key: readonly []; readonly components: { readonly with: readonly [typeof tagged, typeof cell] } }>, Index<{ readonly key: readonly [typeof cell]; readonly sorted: true; readonly components: { readonly with: readonly [typeof amount] } }>] => [
+            Index.create({ key: [], components: { with: [tagged, cell] } }),
+            Index.create({ key: [cell], sorted: true, components: { with: [amount] } }),
+        ];
+        const [madeTagged, madeByCell] = made();
+        const sizes = System.create({ observer: true, lookup: { all: { index: madeTagged, changed: [cell] }, cells: { index: madeByCell } } }, ({ lookup }) => {
+            const all = lookup.all();
+            seen.looked.push([all.changed]);
+            const high = lookup.cells({ ">=": 5 });
+            seen.tagged.push(all.length * 1000 + high.length * 100 + (high.at(0)?.[amount] ?? 0));
+        });
+        await remote.run(sizes);
+        await world.run(move);
+        await remote.run(sizes);
+        // Two tagged; then one cell at 11 or more, holding 11, then both, the first holding 1.
+        expect(seen.tagged).toEqual([2111, 2201]);
+        expect(seen.looked).toEqual([[true], [true]]);
+        await close();
+    });
+
+    it("run from the joined thread, resolving once its body ran there, and rejecting with what it threw", async () => {
+        reset();
+        const { world, remote, close } = await joined();
+        await world.run(raise);
+        await remote.run(watchLevel);
+        expect(seen.levels).toEqual([1]);
+        await world.run(raise);
+        await expect(remote.run(failing)).rejects.toThrow("observer joined failure");
+        await close();
+    });
+
+    it("are reported out of band on the world's thread when added ones throw, once while they keep failing", async () => {
+        reset();
+        using reported = catchOutOfBand();
+        const { world, remote, close } = await joined();
+        remote.add(failing);
+        await turns();
+        await world.run(raise);
+        await world.run(raise);
+        await reported.until(error => error.message.includes("observer joined failure"));
+        await world.run(raise);
+        await turns();
+        expect(reported.messages()).toEqual([expect.stringMatching(/^System "failing" .*failed: observer joined failure$/)]);
+        await close();
+    });
+
+    it("never run once removed, and free what both threads held", async () => {
+        reset();
+        const { world, remote, close } = await joined();
+        const cycle = async (): Promise<readonly number[]> => {
+            remote.add(watchLevel);
+            await turns();
+            const from = seen.levels.length;
+            await world.run(raise);
+            await settled(() => seen.levels.length === from + 1);
+            remote.remove(watchLevel);
+            await world.run(raise);
+            await turns();
+            expect(seen.levels.length).toBe(from + 1);
+            await world.run(nothing);
+            await turns();
+            await world.run(nothing);
+            const tables = await world.tables();
+            return [tables.arena, tables.runners, tablesOf.get(remote)?.().observer ?? -1];
+        };
+        const first = await cycle();
+        expect(first[2]).toBe(0);
+        expect(await cycle()).toEqual(first);
+        await close();
+    });
+
+    it("refuse only systems that aren't observer", async () => {
+        const { remote, close } = await joined();
+        expect(() => remote.add(raise)).toThrow("A joined thread adds only observer systems");
+        expect(() => remote.remove(raise)).toThrow("A joined thread removes only observer systems");
+        await close();
+    });
+
+    it("are placed on the joined thread filling their objects, reading them there", async () => {
+        reset();
+        const { world, close } = await joined(["observerJoinedTest"]);
+        await world.run(spawnLabelled);
+        world.add(readLabels);
+        await turns();
+        await world.run(nothing);
+        await settled(() => seen.labels.length === 1);
+        expect(seen.labels).toEqual(["4"]);
+        world.remove(readLabels);
+        await close();
+    });
+
+    it("fail to register when placed on the joined thread filling their objects without an id, which it can't name", async () => {
+        reset();
+        const { world, close } = await joined(["observerJoinedTest"]);
+        await world.run(spawnLabelled);
+        // Made in a function, so the build gives it no id.
+        const made = () => System.create({ observer: true, components: { with: [label, amount] } }, row => {
+            seen.labels.push(`${row[label].text}${row[amount]}`);
+        });
+        const madeLabels = made();
+        await expect(world.run(madeLabels)).rejects.toThrow(`runs on thread "observerJoinedTest", which a joined thread fills, and has no id, so that thread can't name it`);
+        // Another made there, labeled the same, fails to register when added, reported out of band.
+        using reported = catchOutOfBand();
+        const added = made();
+        world.add(added);
+        await turns();
+        await world.run(nothing);
+        expect(reported.messages()).toEqual([expect.stringMatching(/^System "made" failed: .*has no id/)]);
+        world.remove(added);
+        await turns();
+        expect(seen.labels).toEqual([]);
+        await close();
+    });
+
+    it("run there for the world's run of them, which resolves to what they returned there, or rejects with what they threw", async () => {
+        reset();
+        using reported = catchOutOfBand();
+        const { world, close } = await joined(["observerJoinedTest"]);
+        await world.run(spawnLabelled);
+        watched.length = 0;
+        watched.push(...await Observe.toPromise(Observe.select(world, { required: [amount] })));
+        expect(await world.run(labelsThere)).toEqual(["4"]);
+        await expect(world.run(failsThere)).rejects.toThrow(/^System "failsThere" .*failed: observerJoinedTest failure there$/);
+        // One holding rows ran there before its run resolved.
+        await world.run(readLabels);
+        expect(seen.labels).toEqual(["4"]);
+        await turns();
+        expect(reported.errors).toEqual([]);
+        await close();
+    });
+
+    it("run on the joined thread filling their objects when the world runs them, then here once it's gone", async () => {
+        reset();
+        const { world, remote } = await joined(["observerJoinedTest"]);
+        await world.run(spawnLabelled);
+        expect(await runReported(world, readLabels)).toEqual({ failures: [], skipped: [], dropped: 0, warnings: [] });
+        await settled(() => seen.labels.length === 1);
+        expect(seen.labels).toEqual(["4"]);
+        remote.add(watchLevel);
+        await turns();
+        await remote.dispose();
+        await turns();
+        // The thread's own are forgotten with it; those on the threads it filled run here again.
+        await world.run(raise);
+        await world.run(readLabels);
+        await turns();
+        expect([seen.labels, seen.levels]).toEqual([["4", "4"], []]);
+        expect((await world.tables()).joined).toEqual([]);
+        await world.dispose();
+    });
+});

package/src/implementation/world/observer.browser.test.ts

@@ -0,0 +1,73 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { Index } from "../../interface/indexes/index-type.js";
+import { System } from "../../interface/system/system.js";
+import { createWorld } from "./create.js";
+import { gpuDevice } from "../../interface/resources/gpu-device.js";
+import { workers } from "../../interface/resources/workers.js";
+import type { F32 } from "../../interface/math/index.js";
+import { gpu } from "./gpu.test-helper.js";
+
+const heat = Symbol("observerGpuTest/heat");
+const rate = Symbol("observerGpuTest/rate");
+
+declare module "@adobe/ecs" {
+    export interface Components {
+        [heat]: { type: F32 };
+        [rate]: { type: F32 };
+    }
+}
+
+
+const spawn = System.create({}, ({ commands }) => {
+    for (let i = 0; i < 100; i++) commands.spawn([heat, rate])({ [heat]: i, [rate]: 1 });
+});
+const warm = System.create({ kernel: "gpu", components: { with: [rate, heat] } }, row => {
+    row[heat] = row[heat] + row[rate] * 100;
+});
+
+let total = 0;
+const sum = System.create({ observer: true, components: { with: [heat] } }, row => { total += row[heat]; });
+
+const byHeat = Index.create({ key: [heat], sorted: true });
+let hot = 0;
+const countHot = System.create({ observer: true, lookup: { hot: { index: byHeat } } }, ({ lookup }) => {
+    hot = lookup.hot({ ">=": 150 }).length;
+});
+
+const device = async (): Promise<GPUDevice> => {
+    const adapter = await navigator.gpu.requestAdapter();
+    if (adapter === null) throw new Error("No WebGPU adapter.");
+    return adapter.requestDevice();
+};
+
+describe("observer systems over GPU kernels' writes", () => {
+    it.runIf(gpu)("read what a GPU kernel wrote in the run, read back for them", async () => {
+        const world = createWorld({ [workers]: 0, [gpuDevice]: await device() });
+        await world.run(spawn);
+        world.add(sum);
+        total = 0;
+        await world.run(warm);
+        expect(total).toBe(4950 + 100 * 100);
+        total = 0;
+        await world.run(sum);
+        expect(total).toBe(4950 + 100 * 100);
+        await world.dispose();
+    });
+
+    it.runIf(gpu)("look up through indexes kept by what a GPU kernel wrote in the run, read back before they're refreshed", async () => {
+        const world = createWorld({ [workers]: 0, [gpuDevice]: await device() });
+        await world.run(spawn);
+        world.add(countHot);
+        await world.run(warm);
+        expect(hot).toBe(50);
+        await world.run(warm);
+        expect(hot).toBe(100);
+        await world.dispose();
+    });
+
+    it.runIf(gpu)("look up on a joined thread through indexes kept by what a GPU kernel wrote in the run, read back before they're refreshed", async () => {
+        const fixture = await import("./observer-joined.fixture.js");
+        expect(await fixture.gpuLookups(await device())).toEqual([50, 100]);
+    });
+});