@adobe/ecs 0.0.0-stage → 0.1.0

package/src/implementation/world/joining-worker.fixture.ts

@@ -0,0 +1,69 @@
+import type { MessagePort as NodeMessagePort } from "node:worker_threads";
+import { workers } from "../../interface/resources/workers.js";
+import { System } from "../../interface/system/system.js";
+import { Observe } from "../../observe/index.js";
+import { createWorld, join } from "./create.js";
+import { scopeChannel } from "./port.js";
+import { drive, idle, names, total, until, withReports, type Driven, type Reported } from "./joining.test-helper.js";
+
+/** A thread joining a world through the port it's sent and driving it, or holding a world it shares through it. */
+
+/** A system only this thread imports, which a world elsewhere never did. */
+const unimportedByMain = System.create({ name: "joiningTest/unimportedByMain" }, () => {});
+
+type Port = MessagePort | NodeMessagePort;
+export type ToJoiningWorker =
+    | { readonly kind: "join"; readonly port: Port; readonly threads: readonly "main"[] }
+    | { readonly kind: "idle"; readonly port: Port; readonly threads: readonly "main"[] }
+    | { readonly kind: "host"; readonly port: Port }
+    /** Hold a world shared through this worker's own scope, which this fixture's messages share. */
+    | { readonly kind: "host scope" }
+    /** Once the thread that joined has left: the world's state, and the reports of the runs it drove. */
+    | { readonly kind: "state"; readonly driven?: Driven };
+export type FromJoiningWorker =
+    | { readonly kind: "driven"; readonly driven: Driven }
+    | { readonly kind: "joined"; readonly ran: string }
+    | { readonly kind: "shared" }
+    | { readonly kind: "state"; readonly driven: Reported | null; readonly total: number; readonly names: readonly string[]; readonly status: string | null };
+
+const channel = scopeChannel<FromJoiningWorker, ToJoiningWorker>();
+let hosted: ReturnType<typeof createWorld> | null = null;
+channel.onMessage(async message => {
+    // The world's own messages, where it shares the scope.
+    if ("protocol" in message) return;
+    if (message.kind === "host scope") {
+        const world = createWorld({ [workers]: 0 });
+        const scope = globalThis.process?.getBuiltinModule?.("node:worker_threads")?.parentPort ?? self;
+        world.share(scope);
+        hosted = world;
+        channel.post({ kind: "shared" });
+    }
+    else if (message.kind === "join") {
+        const remote = join(message.port, { threads: message.threads });
+        channel.post({ kind: "driven", driven: await drive(remote, unimportedByMain) });
+        await remote.dispose();
+    }
+    else if (message.kind === "idle") {
+        // Joins and stays, its one run's outcome posted.
+        const remote = join(message.port, { threads: message.threads });
+        const ran = await remote.run(idle).then(() => "ran", (error: unknown) => error instanceof Error ? error.message : String(error));
+        channel.post({ kind: "joined", ran });
+    }
+    else if (message.kind === "host") {
+        const world = createWorld({ [workers]: 0 });
+        world.share(message.port);
+        hosted = world;
+        channel.post({ kind: "shared" });
+    }
+    else if (message.kind === "state" && hosted !== null) {
+        // Once the thread that joined has left.
+        const threads = await until(hosted.threads, shown => shown[0]?.status === "gone");
+        channel.post({
+            kind: "state",
+            driven: message.driven === undefined ? null : await withReports(hosted, message.driven),
+            total: await Observe.toPromise(Observe.resource(hosted, total)),
+            names: await Observe.toPromise(Observe.resource(hosted, names)),
+            status: threads[0]?.status ?? null,
+        });
+    }
+});

package/src/implementation/world/joining.cases.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+import type * as Fixture from "./joining.fixture.js";
+
+const clean = { failures: [], skipped: [], dropped: 0, warnings: [] };
+
+/** Threads joining worlds on others: the cases, over the fixture built for node or from source. */
+export const joiningCases = (load: () => Promise<typeof Fixture>) => describe("joining", () => {
+    const expectDriven = (driven: Awaited<ReturnType<typeof Fixture.worldThere>>["driven"] | null, unimported: RegExp) => {
+        expect(driven?.reports).toEqual([clean, clean, clean, clean, clean]);
+        expect(driven?.failures).toEqual(["joiningTest failure"]);
+        expect(driven?.total).toBe(123);
+        expect(driven?.selected).toBe(2);
+        expect(driven?.counted).toBe(1);
+        expect(driven?.listed).toEqual([[2, -2], true]);
+        expect(driven?.unimported).toMatch(unimported);
+        expect(driven?.unnamed).toMatch(/has no id, so it can't run from another thread/);
+    };
+
+    it("let a worker join a world here: runs land in call order, observers see the world, and its entity shows its progress", async () => {
+        const fixture = await load();
+        const result = await fixture.worldHere();
+        expectDriven(result.driven, /^System ".*joining-worker\.fixture\.ts#unimportedByMain" isn't one this world imported, so it can't run here\.$/);
+        expect(result.claims).toEqual(["main"]);
+        expect(result.status).toBe("gone");
+        expect(result.total).toBe(123);
+        expect(result.names).toEqual(["a", "b"]);
+    }, 30000);
+
+    it("let this thread join a world on a worker, by the ids of keys and systems both threads imported", async () => {
+        const fixture = await load();
+        const result = await fixture.worldThere();
+        expectDriven(result.driven, /^System ".*joining\.fixture\.ts#unimportedByWorker" isn't one this world imported, so it can't run here\.$/);
+        expect(result.total).toBe(123);
+        expect(result.names).toEqual(["a", "b"]);
+        expect(result.status).toBe("gone");
+    }, 30000);
+
+    it("share a world through a worker's own scope, joined through the worker, the observer factories there giving its values", async () => {
+        const fixture = await load();
+        expect(await fixture.scopes()).toEqual({ observed: 456, total: 456, status: "gone" });
+    }, 30000);
+
+    it("show a joined thread that dies as gone", async () => {
+        const fixture = await load();
+        expect(await fixture.dies()).toEqual({ ran: "ran", status: "gone" });
+    }, 30000);
+
+    it("refuse a thread claimed twice", async () => {
+        const fixture = await load();
+        expect(await fixture.claimedTwice()).toEqual({ first: "ran", second: 'Thread "main" is claimed twice.', status: "gone" });
+    }, 30000);
+});

package/src/implementation/world/joining.fixture.ts

@@ -0,0 +1,138 @@
+/// <reference types="node" />
+import { Observe } from "../../observe/index.js";
+import { workers } from "../../interface/resources/workers.js";
+import { System } from "../../interface/system/system.js";
+import type { World } from "../../interface/world/world.js";
+import { createWorld, join } from "./create.js";
+import type { FromJoiningWorker, ToJoiningWorker } from "./joining-worker.fixture.js";
+import { add, drive, names, total, until, withReports } from "./joining.test-helper.js";
+
+/**
+ * Scenarios of a thread joining a world on another, run built in node and from source in chromium: a worker joining a
+ * world here, this thread joining a world on a worker, a joined worker that dies, and a thread claimed twice.
+ */
+
+/** A system only this thread imports, which a world on a worker never did. */
+const unimportedByWorker = System.create({ name: "joiningTest/unimportedByWorker" }, () => {});
+
+type Worker = {
+    readonly ask: (message: ToJoiningWorker, transfer?: readonly unknown[]) => Promise<FromJoiningWorker>;
+    readonly terminate: () => Promise<void>;
+    /** The worker itself, as a port to join a world it shares through its scope. */
+    readonly port: Parameters<World["share"]>[0];
+};
+
+/** Whether a reply is the fixture's, not the world's, where it shares the worker's scope. */
+const isReply = (data: unknown): boolean => typeof data === "object" && data !== null && !("protocol" in data);
+
+const workerFile = "./joining-worker.fixture.js";
+
+/** Starts the joining worker, which answers each message with one. */
+const start = (): Worker => {
+    if (typeof globalThis.Worker === "function") {
+        const worker = new globalThis.Worker(new URL("./joining-worker.fixture.js", import.meta.url), { type: "module" });
+        return {
+            ask: (message, transfer = []) => new Promise(resolve => {
+                worker.onmessage = (event: MessageEvent<FromJoiningWorker>) => { if (isReply(event.data)) resolve(event.data); };
+                worker.postMessage(message, { transfer: transfer.filter(port => port instanceof MessagePort) });
+            }),
+            terminate: async () => worker.terminate(),
+            port: worker,
+        };
+    }
+    const threads = globalThis.process.getBuiltinModule("node:worker_threads");
+    const worker = new threads.Worker(new URL(workerFile, import.meta.url));
+    return {
+        ask: (message, transfer = []) => new Promise(resolve => {
+            const reply = (data: FromJoiningWorker): void => {
+                if (!isReply(data)) return;
+                worker.off("message", reply);
+                resolve(data);
+            };
+            worker.on("message", reply);
+            worker.postMessage(message, transfer.filter(port => port instanceof threads.MessagePort));
+        }),
+        terminate: async () => { await worker.terminate(); },
+        port: worker,
+    };
+};
+
+const within = <T>(promise: Promise<T>, milliseconds: number, otherwise: T): Promise<T> =>
+    Promise.race([promise, new Promise<T>(resolve => setTimeout(() => resolve(otherwise), milliseconds))]);
+
+/** A world here, a worker joining it and driving it, then leaving. */
+export const worldHere = async () => {
+    const world = createWorld({ [workers]: 0 });
+    const { port1, port2 } = new MessageChannel();
+    world.share(port1);
+    const joined = until(world.threads, threads => threads[0]?.status === "joined");
+    const worker = start();
+    const reply = await worker.ask({ kind: "join", port: port2, threads: ["main"] }, [port2]);
+    const claims = (await joined)[0]?.claims ?? null;
+    const gone = (await until(world.threads, threads => threads[0]?.status === "gone"))[0];
+    const result = {
+        driven: reply.kind === "driven" ? await withReports(world, reply.driven) : null,
+        claims,
+        status: gone?.status ?? null,
+        total: await Observe.toPromise(Observe.resource(world, total)),
+        names: await Observe.toPromise(Observe.resource(world, names)),
+    };
+    await worker.terminate();
+    await world.dispose();
+    return result;
+};
+
+/** A world on a worker, this thread joining it and driving it, then leaving. */
+export const worldThere = async () => {
+    const worker = start();
+    const { port1, port2 } = new MessageChannel();
+    await worker.ask({ kind: "host", port: port1 }, [port1]);
+    const remote = join(port2, { threads: ["main"] });
+    const driven = await drive(remote, unimportedByWorker);
+    await remote.dispose();
+    const state = await worker.ask({ kind: "state", driven });
+    await worker.terminate();
+    return state.kind === "state" ? { driven: state.driven, total: state.total, names: state.names, status: state.status } : { driven: null };
+};
+
+/** A worker that joined, then is ended from outside: its status, `"gone"` if the world heard of it. */
+export const dies = async () => {
+    const world = createWorld({ [workers]: 0 });
+    const { port1, port2 } = new MessageChannel();
+    world.share(port1);
+    const worker = start();
+    const reply = await worker.ask({ kind: "idle", port: port2, threads: [] }, [port2]);
+    await worker.terminate();
+    const gone = await within(until(world.threads, threads => threads[0]?.status === "gone"), 20000, null);
+    await world.dispose();
+    return { ran: reply.kind === "joined" ? reply.ran : null, status: gone?.[0]?.status ?? null };
+};
+
+/** Two workers claiming `main`: the second's run, and its status. */
+export const claimedTwice = async () => {
+    const world = createWorld({ [workers]: 0 });
+    const first = new MessageChannel();
+    const second = new MessageChannel();
+    world.share(first.port1);
+    world.share(second.port1);
+    const pair = [start(), start()];
+    const one = await pair[0].ask({ kind: "idle", port: first.port2, threads: ["main"] }, [first.port2]);
+    const two = await pair[1].ask({ kind: "idle", port: second.port2, threads: ["main"] }, [second.port2]);
+    const gone = (await until(world.threads, threads => threads[1]?.status === "gone"))[1];
+    for (const worker of pair) await worker.terminate();
+    await world.dispose();
+    return { first: one.kind === "joined" ? one.ran : null, second: two.kind === "joined" ? two.ran : null, status: gone?.status ?? null };
+};
+
+/** A world on a worker shared through its own scope, this thread joined through the worker: runs, an observer factory, leaving. */
+export const scopes = async () => {
+    const worker = start();
+    await worker.ask({ kind: "host scope" });
+    const remote = join(worker.port);
+    for (const amount of [4, 5, 6]) await remote.run(add, { amount });
+    const observed = await until(Observe.resource(remote, total), value => value === 456);
+    await remote.dispose();
+    const state = await worker.ask({ kind: "state" });
+    await worker.terminate();
+    return { observed, ...state.kind === "state" ? { total: state.total, status: state.status } : {} };
+};

package/src/implementation/world/joining.test-helper.ts

@@ -0,0 +1,92 @@
+import { Component } from "../../interface/component/component.js";
+import { Resource } from "../../interface/resource/resource.js";
+import { System } from "../../interface/system/system.js";
+import { Observe } from "../../observe/index.js";
+import type { World } from "../../interface/world/world.js";
+import { reportOf } from "./reports.test-helper.js";
+
+// Keys and systems both threads of the joining fixtures import, and the scenario a joined thread drives.
+
+export const point = Symbol("joiningTest/point");
+export const label = Symbol("joiningTest/label");
+export const marked = Symbol("joiningTest/marked");
+export const total = Symbol("joiningTest/total");
+export const names = Symbol("joiningTest/names");
+declare module "@adobe/ecs" {
+    export interface Components {
+        [point]: { type: readonly [number, number] };
+        [label]: { type: string };
+        [marked]: { type: true };
+    }
+    export interface Resources {
+        [total]: { type: number };
+        [names]: { type: readonly string[] };
+    }
+}
+Component.register(point, { type: { type: "array", items: { type: "number" }, minItems: 2, maxItems: 2 } });
+Component.register(label, { type: { type: "string" } });
+Component.register(marked, { type: { const: true } });
+Resource.register(total, { type: { type: "number", default: 0 } });
+Resource.register(names, { type: { type: "array", items: { type: "string" }, default: [] } });
+
+/** Appends a digit to `total`, so the order of runs shows in it. */
+export const add = System.create({ name: "joiningTest/add", input: { type: "object", properties: { amount: { type: "number" } } }, resources: { write: [total] } }, ({ input, resources }) => {
+    resources[total] = resources[total] * 10 + input.amount;
+});
+export const append = System.create({ name: "joiningTest/append", input: { type: "object", properties: { name: { type: "string" } } }, resources: { write: [names] } }, ({ input, resources }) => {
+    resources[names] = [...resources[names], input.name];
+});
+export const spawn = System.create({ name: "joiningTest/spawn", input: { type: "object", properties: { x: { type: "number" } } } }, ({ input, commands }) => {
+    commands.spawn([point, label, marked])({ [point]: [input.x, -input.x], [label]: `p${input.x}` });
+});
+export const fail = System.create({ name: "joiningTest/fail" }, () => { throw new Error("joiningTest failure"); });
+export const idle = System.create({ name: "joiningTest/idle" }, () => {});
+
+/** The first value an observer gives that `accept` takes. */
+export const until = <T>(observe: Observe<T>, accept: (value: T) => boolean): Promise<T> => new Promise(resolve => {
+    let done = false;
+    const stop = observe(value => {
+        if (done || !accept(value)) return;
+        done = true;
+        queueMicrotask(() => stop());
+        resolve(value);
+    });
+});
+
+/**
+ * What a joined thread sees driving a world: runs in call order with struct and object input, by number, a failing
+ * run's number, observers of a resource, a selection, a count and an entity's listed components, and the
+ * rejections of a system the world never imported and of one without an id.
+ */
+export const drive = async (remote: World, unimported: System<void>) => {
+    const runs = await Promise.all([
+        remote.run(add, { amount: 1 }), remote.run(append, { name: "a" }), remote.run(add, { amount: 2 }), remote.run(append, { name: "b" }), remote.run(add, { amount: 3 }),
+    ]);
+    const failed = await remote.run(fail);
+    await remote.run(spawn, { x: 1 });
+    await remote.run(spawn, { x: 2 });
+    const observedTotal = await until(Observe.resource(remote, total), value => value === 123);
+    const selected = await until(Observe.select(remote, { required: [point], order: { [point]: false } }), entities => entities.length === 2);
+    const counted = await until(Observe.count(remote, { required: [point], where: { [point]: [2, -2] } }), count => count === 1);
+    const listed = await until(Observe.entity(remote, selected[0], { required: [point], optional: [marked] }), value => value !== null);
+    const rejected = (run: Promise<unknown>): Promise<string> => run.then(() => "ran", (error: unknown) => error instanceof Error ? error.message : String(error));
+    return {
+        runs,
+        failed,
+        total: observedTotal,
+        selected: selected.length,
+        counted,
+        listed: listed === null ? null : [listed[point], listed[marked]],
+        unimported: await rejected(remote.run(unimported)),
+        unnamed: await rejected(remote.run(System.create(() => {}))),
+    };
+};
+export type Driven = Awaited<ReturnType<typeof drive>>;
+
+/** What a joined thread saw driving a world, its runs' reports read on the world's thread, which holds them. */
+export const withReports = async (world: World, { runs, failed, ...driven }: Driven) => ({
+    ...driven,
+    reports: await Promise.all(runs.map(run => reportOf(world, run))),
+    failures: (await reportOf(world, failed)).failures.map(failure => failure.message),
+});
+export type Reported = Awaited<ReturnType<typeof withReports>>;