@adobe/ecs 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,101 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Entity } from "../../interface/entity/entity.js";
+import { System } from "../../interface/system/system.js";
+import type { Schema } from "../../interface/schema/schema.js";
+
+// Keys and systems every thread of the transfer tests imports: systems on thread "transfersTest", which a joined thread
+// fills, and on the world's, taking Transferable values in their input, and `transfer` components holding them.
+// An input field's schema `{ allOf: [] }` takes any value, typed `unknown`, which each body narrows.
+
+export const anchor = Symbol("transfersTest/anchor");
+export const order = Symbol("transfersTest/order");
+export const port = Symbol("transfersTest/port");
+export const bitmap = Symbol("transfersTest/bitmap");
+export const portHere = Symbol("transfersTest/portHere");
+export const bitmapHere = Symbol("transfersTest/bitmapHere");
+export const parent = Symbol("transfersTest/parent");
+export const depth = Symbol("transfersTest/depth");
+declare module "@adobe/ecs" {
+    export interface Threads {
+        transfersTest: true;
+    }
+    export interface Components {
+        [port]: { type: MessagePort; thread: "transfersTest"; transfer: true };
+        [bitmap]: { type: ImageBitmap; thread: "transfersTest"; transfer: true };
+        [portHere]: { type: MessagePort; transfer: true };
+        [bitmapHere]: { type: ImageBitmap; transfer: true };
+        [parent]: { type: Entity; reference: "owner" };
+        [depth]: { type: number };
+    }
+    export interface Resources {
+        [anchor]: { type: { readonly text: string }; thread: "transfersTest"; default: { text: "anchor" } };
+        [order]: { type: Schema.Type<{ type: "integer" }>; default: 0 };
+    }
+}
+/** An object resource of "transfersTest", which places the systems reading it there. */
+/** Counts the runs that read it, in the order they ran. */
+
+const any = { allOf: [] } as const;
+
+/** What a system was given, on the thread it ran on: an ArrayBuffer's length and first byte, and the run's order. */
+export type Stored = { readonly bytes: number; readonly first: number; readonly order: number; readonly value: unknown };
+export const stored: Stored[] = [];
+/** The values systems gave components, on the thread they ran on. */
+export const kept: unknown[] = [];
+
+const store = (value: unknown, at: number): void => {
+    const bytes = value instanceof ArrayBuffer ? value.byteLength : -1;
+    stored.push({ bytes, first: bytes > 0 && value instanceof ArrayBuffer ? new Uint8Array(value)[0] : -1, order: at, value });
+};
+
+/** On "transfersTest": records the buffer it's given. */
+export const storeThere = System.create({}, ({ resources }, input: { readonly buffer: unknown }) => {
+    if (resources[anchor].text === "anchor") store(input.buffer, resources[order]++);
+});
+/** On the world's thread: records the buffer it's given. */
+export const storeHere = System.create({}, ({ resources }, input: { readonly buffer: unknown }) => {
+    store(input.buffer, resources[order]++);
+});
+/** On the world's thread: what a run from a joined thread saw of the order, by its value. */
+export const marks: { readonly value: number; readonly order: number }[] = [];
+export const mark = System.create({}, ({ resources }, input: { readonly value: number }) => {
+    marks.push({ value: input.value, order: resources[order]++ });
+});
+/** On "transfersTest": gives an entity the port or bitmap it's given. */
+export const attachThere = System.create({}, ({ resources, commands }, input: { readonly entity: Entity; readonly value: unknown }) => {
+    if (resources[anchor].text !== "anchor") return;
+    kept.push(input.value);
+    if (input.value instanceof MessagePort) commands.add(input.entity, port, input.value);
+    else if (typeof ImageBitmap === "function" && input.value instanceof ImageBitmap) commands.add(input.entity, bitmap, input.value);
+});
+/** On the world's thread: gives an entity the port or bitmap it's given. */
+export const attachHere = System.create({}, ({ commands }, input: { readonly entity: Entity; readonly value: unknown }) => {
+    kept.push(input.value);
+    if (input.value instanceof MessagePort) commands.add(input.entity, portHere, input.value);
+    else if (typeof ImageBitmap === "function" && input.value instanceof ImageBitmap) commands.add(input.entity, bitmapHere, input.value);
+});
+/** On "transfersTest": says hello through the port it's given, which only moving it there, not copying it, gives. */
+export const greetThere = System.create({}, ({ resources }, input: { readonly port: unknown }) => {
+    if (input.port instanceof MessagePort) input.port.postMessage(resources[anchor].text);
+});
+
+/** On the world's thread: spawns an entity holding the port it's given. */
+export const spawnHere = System.create({}, ({ commands }, input: { readonly value: unknown }) => {
+    if (input.value instanceof MessagePort) commands.spawn([portHere])({ [portHere]: input.value });
+});
+
+/**
+ * On "transfersTest", declaring `up`, which runs only on the world's thread: once a joined thread fills
+ * "transfersTest", it fails to register, so a run of it never runs.
+ */
+export const unregistered = System.create({
+    components: { with: [port, depth] }, up: { through: parent },
+}, (row, { up }, input: { readonly value: unknown }) => {
+    row[depth] = (up === null ? 0 : up[depth]) + (row[port] === input.value ? 1 : 0);
+});
+
+/** On the world's thread: nothing, a run of its own. */
+export const idle = System.create({}, () => {});
+
+/** Every system the joined threads run or place, which they import so the world can place them there. */
+export const transferSystems: readonly { readonly name: string }[] = [storeThere, storeHere, mark, attachThere, attachHere, spawnHere, greetThere, unregistered];

package/src/implementation/world/transfers.test.ts

@@ -0,0 +1,153 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { workers } from "../../interface/resources/workers.js";
+import type { World } from "../../interface/world/world.js";
+import { createWorld, join, type CreatedWorld } from "./create.js";
+import { asEntity } from "./entities.js";
+import { peersOf } from "./join.js";
+import { attachHere, attachThere, greetThere, kept, mark, marks, spawnHere, storeHere, storeThere, stored, unregistered } from "./transfers.test-helper.js";
+import { followRuns, runReported } from "./outcomes.test-helper.js";
+
+// Transfers, with the world, the thread filling "transfersTest" and a thread filling none on this one, joined through
+// MessageChannels: a run's Transferable input moves to the thread its system runs on.
+
+const later = (milliseconds = 0): Promise<void> => new Promise(resolve => setTimeout(resolve, milliseconds));
+
+/** Resolves once `remote` has a channel to another joined thread. */
+const peered = async (remote: World): Promise<void> => {
+    while ((peersOf.get(remote)?.() ?? 0) === 0) await later();
+};
+
+/** A thread on this one joined to `world` claiming `threads`, once both sides say it joined. */
+const sharedWith = async (world: CreatedWorld, threads: readonly "transfersTest"[]): Promise<World> => {
+    const channel = new MessageChannel();
+    const shared = world.share(channel.port1);
+    const remote = await join(channel.port2, { threads });
+    await shared;
+    return remote;
+};
+
+/** A world here, `filler` claiming "transfersTest", and `loader` claiming nothing, each with a channel to the other. */
+const joined = async (): Promise<{ readonly world: CreatedWorld; readonly filler: World; readonly loader: World }> => {
+    stored.length = marks.length = kept.length = 0;
+    const world = createWorld({ [workers]: 0 });
+    const [loader, filler] = await Promise.all([sharedWith(world, []), sharedWith(world, ["transfersTest"])]);
+    await peered(loader);
+    await peered(filler);
+    return { world, filler, loader };
+};
+
+const bufferOf = (first: number, bytes = 1024): ArrayBuffer => {
+    const buffer = new ArrayBuffer(bytes);
+    new Uint8Array(buffer)[0] = first;
+    return buffer;
+};
+
+/** Resolves once a port's other end closed, or with false after `milliseconds`. */
+const closed = (port: MessagePort, milliseconds = 1000): Promise<boolean> => new Promise(resolve => {
+    port.addEventListener("close", () => resolve(true));
+    port.start();
+    setTimeout(() => resolve(false), milliseconds);
+});
+
+const clean = { failures: [], skipped: [], dropped: 0, warnings: [] };
+
+describe("transfers", () => {
+    it("move a run's Transferable input straight to the joined thread its system runs on, in call order with that thread's other runs", async () => {
+        const { world, filler, loader } = await joined();
+        const reports = followRuns(world);
+        const buffers = [bufferOf(1), bufferOf(2)];
+        const runs = [loader.run(storeThere, { buffer: buffers[0] }), loader.run(mark, { value: 1 }), loader.run(storeThere, { buffer: buffers[1] }), loader.run(mark, { value: 2 })];
+        // Moved, not copied: the loader's are detached as soon as it runs them.
+        expect(buffers.map(buffer => buffer.byteLength)).toEqual([0, 0]);
+        await Promise.all(runs);
+        expect(reports.map(report => report.warnings.map(warning => warning.kind))).toEqual([["blocking"], [], ["blocking"], []]);
+        expect(stored.map(({ bytes, first, order }) => [bytes, first, order])).toEqual([[1024, 1, 0], [1024, 2, 2]]);
+        expect(marks).toEqual([{ value: 1, order: 1 }, { value: 2, order: 3 }]);
+        await loader.dispose();
+        await filler.dispose();
+        await world.dispose();
+    });
+    it("move a MessagePort, which can't be copied, to the joined thread its system runs on, where it works", async () => {
+        const { world, filler, loader } = await joined();
+        const channel = new MessageChannel();
+        const greeted = new Promise<unknown>(resolve => {
+            channel.port2.onmessage = event => resolve(event.data);
+        });
+        await loader.run(greetThere, { port: channel.port1 });
+        expect(await greeted).toBe("anchor");
+        channel.port2.close();
+        await loader.dispose();
+        await filler.dispose();
+        await world.dispose();
+    });
+    it("move one to the world's thread where its system runs there", async () => {
+        const { world, filler, loader } = await joined();
+        const buffer = bufferOf(3);
+        const reports = followRuns(world);
+        const ran = loader.run(storeHere, { buffer });
+        expect(buffer.byteLength).toBe(0);
+        await ran;
+        expect(reports).toEqual([clean]);
+        expect(stored.map(({ bytes, first }) => [bytes, first])).toEqual([[1024, 3]]);
+        await loader.dispose();
+        await filler.dispose();
+        await world.dispose();
+    });
+    it("keep one on the joined thread its system runs on, when it runs it", async () => {
+        const { world, filler, loader } = await joined();
+        const buffer = bufferOf(4);
+        await filler.run(storeThere, { buffer });
+        expect(stored.map(({ bytes, first, value }) => [bytes, first, value === buffer])).toEqual([[1024, 4, true]]);
+        await loader.dispose();
+        await filler.dispose();
+        await world.dispose();
+    });
+    it("reject a run whose input moved to a thread that left, the thread's later runs going on", async () => {
+        const { world, filler, loader } = await joined();
+        await filler.dispose();
+        const moved = loader.run(storeThere, { buffer: bufferOf(5) });
+        await expect(moved).rejects.toThrow("moved to a joined thread that's gone");
+        // Once the world has told it, its runs go to the world's thread, which runs the system now.
+        await later(10);
+        await loader.run(storeThere, { buffer: bufferOf(6) });
+        expect(stored.map(({ bytes, first }) => [bytes, first])).toEqual([[1024, 6]]);
+        await loader.dispose();
+        await world.dispose();
+    });
+    it("release a value whose command drops, on its thread", async () => {
+        const { world, filler, loader } = await joined();
+        const there = new MessageChannel();
+        const here = new MessageChannel();
+        const closes = [closed(there.port2), closed(here.port2)];
+        const dead = asEntity(123456);
+        const reports = followRuns(world);
+        await loader.run(attachThere, { entity: dead, value: there.port1 });
+        await loader.run(attachHere, { entity: dead, value: here.port1 });
+        expect(reports.map(report => report.dropped)).toEqual([1, 1]);
+        expect(await Promise.all(closes)).toEqual([true, true]);
+        await loader.dispose();
+        await filler.dispose();
+        await world.dispose();
+    });
+    it("release what moved for a run that never ran there", async () => {
+        const { world, filler, loader } = await joined();
+        const channel = new MessageChannel();
+        const closing = closed(channel.port2);
+        await expect(loader.run(unregistered, { value: channel.port1 })).rejects.toThrow("declares up");
+        expect(await closing).toBe(true);
+        await loader.dispose();
+        await filler.dispose();
+        await world.dispose();
+    });
+    it("release a value whose command drops in a world no thread joined, and keep one whose command lands", async () => {
+        const world = createWorld({ [workers]: 0 });
+        const dropped = new MessageChannel();
+        const landed = new MessageChannel();
+        const closes = [closed(dropped.port2, 200), closed(landed.port2, 200)];
+        expect((await runReported(world, attachHere, { entity: asEntity(123456), value: dropped.port1 })).dropped).toBe(1);
+        expect((await runReported(world, spawnHere, { value: landed.port1 })).dropped).toBe(0);
+        expect(await Promise.all(closes)).toEqual([true, false]);
+        await world.dispose();
+    });
+});

package/src/implementation/world/transfers.ts

@@ -0,0 +1,105 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { TaskChannel } from './remote-systems.js';
+
+// Transfers (threads.md, "Transfers"): a run's input holding Transferable values moves them to the thread its system
+// runs on, a value whose command drops is released there, and a run's input held on that thread until its task.
+
+/** Global constructors of Transferable values, where the platform has them. */
+const constructors: readonly string[] = [
+    "ArrayBuffer", "ImageBitmap", "OffscreenCanvas", "MessagePort", "VideoFrame", "AudioData",
+    "ReadableStream", "WritableStream", "TransformStream", "RTCDataChannel",
+];
+
+/** This platform's constructors of Transferable values, found once. */
+let found: readonly Function[] | null = null;
+const platformConstructors = (): readonly Function[] => found ??= constructors.flatMap(name => {
+    const constructor: unknown = Reflect.get(globalThis, name);
+    return typeof constructor === "function" ? [constructor] : [];
+});
+
+/** Whether `value` is Transferable on this platform: a `SharedArrayBuffer` isn't, as it's shared rather than moved. */
+export const isTransferable = (value: unknown): value is object => {
+    if (typeof value !== "object" || value === null) return false;
+    for (const constructor of platformConstructors()) if (value instanceof constructor) return true;
+    return false;
+};
+
+const collect = (value: unknown, into: object[] | null): object[] | null => {
+    if (!isTransferable(value) || into?.includes(value) === true) return into;
+    (into ??= []).push(value);
+    return into;
+};
+
+/**
+ * The Transferable values a run's input holds, each once: its fields', and the elements of fields that are arrays; null
+ * for none, which allocates nothing.
+ */
+export const transferablesOf = (input: unknown): object[] | null => {
+    if (typeof input !== "object" || input === null) return null;
+    let into: object[] | null = null;
+    for (const field of Object.keys(input)) {
+        const value: unknown = Reflect.get(input, field);
+        if (Array.isArray(value)) {
+            for (const element of value) if (typeof element === "object") into = collect(element, into);
+        }
+        else into = collect(value, into);
+    }
+    return into;
+};
+
+const ignore = (): void => {};
+
+/** Calls a method of `value` by name, if it has one, ignoring what it throws or rejects with. */
+const call = (value: object, method: string): void => {
+    const callable: unknown = Reflect.get(value, method);
+    if (typeof callable !== "function") return;
+    try {
+        const result: unknown = Reflect.apply(callable, value, []);
+        if (result instanceof Promise) result.catch(ignore);
+    }
+    catch {
+        // Released already, or locked: nothing more to release.
+    }
+};
+
+/**
+ * Releases a Transferable value no component will hold: closes an `ImageBitmap`, `VideoFrame`, `AudioData`,
+ * `MessagePort` or `RTCDataChannel`, cancels a `ReadableStream`, aborts a `WritableStream`, and both for a
+ * `TransformStream`'s sides. An `ArrayBuffer`'s and an `OffscreenCanvas`'s memory is the collector's.
+ */
+export const releaseValue = (value: unknown): void => {
+    if (!isTransferable(value)) return;
+    const name = value.constructor?.name;
+    if (name === "ReadableStream") call(value, "cancel");
+    else if (name === "WritableStream") call(value, "abort");
+    else if (name === "TransformStream") {
+        const readable: unknown = Reflect.get(value, "readable");
+        const writable: unknown = Reflect.get(value, "writable");
+        if (typeof readable === "object" && readable !== null) call(readable, "cancel");
+        if (typeof writable === "object" && writable !== null) call(writable, "abort");
+    }
+    else call(value, "close");
+};
+
+/** Releases every Transferable value a run's input holds. */
+export const releaseInput = (input: unknown): void => {
+    for (const value of transferablesOf(input) ?? []) releaseValue(value);
+};
+
+/**
+ * On the world's thread, a run's input held on the joined thread its system runs on, which moved it there: the joined
+ * thread that ran it, by number, the run's sequence there, the channel of the thread holding it, and whether a task
+ * there took it, so what none took is released once the run finishes.
+ */
+export type HeldInput = { readonly from: number; readonly sequence: number; readonly channel: TaskChannel; taken: boolean };
+
+const held = new WeakSet<object>();
+
+export const heldInput = (from: number, sequence: number, channel: TaskChannel): HeldInput => {
+    const input: HeldInput = { from, sequence, channel, taken: false };
+    held.add(input);
+    return input;
+};
+
+/** Whether a run's input is held on a joined thread. */
+export const isHeld = (input: unknown): input is HeldInput => typeof input === "object" && input !== null && held.has(input);

package/src/implementation/world/unidentified-finalizers.test.ts

@@ -0,0 +1,58 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { Finalizer, System, workers } from "../../index.js";
+import { createWorld, join } from "./create.js";
+import { runReported } from "./outcomes.test-helper.js";
+
+const held = Symbol("unidentifiedFinalizers/held");
+declare module "@adobe/ecs" {
+    interface Threads { unidentifiedFinalizers: true }
+    interface Components { [held]: { type: { readonly text: string } | null; thread: "unidentifiedFinalizers" } }
+}
+
+const nothing = System.create(() => {});
+const spawn = System.create(({ commands }) => { commands.spawn([held])({ [held]: null }); });
+const seen: unknown[] = [];
+/** A finalizer reading the thread's objects, made where the build gives it no id. */
+const unidentified = (): void => { Finalizer.create({ components: { with: [held] } }, row => { seen.push(row[held]); }); };
+
+/** `"joined"` once a share or join resolved, or the message it rejected with. */
+const outcomeOf = (promise: Promise<unknown>): Promise<string> => promise.then(() => "joined", (error: unknown) => error instanceof Error ? error.message : String(error));
+
+/** A world shared with a thread on this one claiming the thread: what its share and its join gave, and the joined world. */
+const shared = async () => {
+    const world = createWorld({ [workers]: 0 });
+    const channel = new MessageChannel();
+    const sharing = outcomeOf(world.share(channel.port1));
+    const joining = join(channel.port2, { threads: ["unidentifiedFinalizers"] });
+    const joined = await outcomeOf(joining);
+    const remote = joined === "joined" ? await joining : null;
+    return { world, remote, shared: await sharing, joined };
+};
+
+describe("a finalizer without an id on a thread a joined thread fills", () => {
+    // Created after the claim, so the claim is made; the next run reports it once and the world goes on without it.
+    it("fails once, in a report, and leaves the world running", async () => {
+        const { world, remote, shared: share } = await shared();
+        expect(share).toBe("joined");
+        if (remote === null) throw new Error("The thread didn't join.");
+        await remote.run(spawn);
+        unidentified();
+        const first = await runReported(world, nothing);
+        expect(first.failures.map(failure => [failure.kind, failure.message.includes("has no id")])).toEqual([["finalizer", true]]);
+        expect((await runReported(world, nothing)).failures).toEqual([]);
+        await remote.run(nothing);
+        await world.dispose();
+    }, 10_000);
+
+    // Finalizers are program-wide, so the one the test above made is present when this thread claims: the claim is
+    // refused, and both the world's share and the thread's join say why.
+    it("refuses a later claim of its thread, rejecting its share and its join, saying why", async () => {
+        const { world, remote, shared: share, joined } = await shared();
+        expect(share).toMatch(/has no id, so a joined thread can't run it/);
+        expect(joined).toBe(share);
+        expect(remote).toBeNull();
+        await world.run(nothing);
+        await world.dispose();
+    }, 10_000);
+});