@adobe/ecs 0.0.0-stage → 0.1.0

package/src/perftest/reads.ts

@@ -0,0 +1,210 @@
+import { Component } from "../interface/component/component.js";
+import type { Entity } from "../interface/entity/entity.js";
+import { Resource } from "../interface/resource/resource.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 } from "../implementation/index.js";
+import type { Benchmark } from "./benchmark.js";
+import { fastest } from "./suite.js";
+
+// Benchmarks of reading a world from outside it: runs of systems that copy values out, and lookups by entity. The
+// observer factories' are in `observed.ts`.
+
+const level = Symbol("reads/level");
+const value = Symbol("reads/value");
+const rank = Symbol("reads/rank");
+const marked = Symbol("reads/marked");
+declare module "@adobe/ecs" {
+    export interface Components {
+        [value]: { type: number };
+        [rank]: { type: number };
+        [marked]: { type: true };
+    }
+    export interface Resources {
+        [level]: { type: number };
+    }
+}
+Resource.register(level, { type: { type: "number", default: 3 } });
+Component.register(value, { type: { type: "number" } });
+Component.register(rank, { type: { type: "number" } });
+Component.register(marked, { type: { const: true } });
+
+/** `count` entities with a value and a rank, the first of them marked. */
+const seed = System.create({ name: "reads/seed", input: { type: "object", properties: { count: { type: "integer" } } } }, ({ input, commands }) => {
+    commands.spawn([value, rank, marked])({ [value]: 0, [rank]: 0, [marked]: true });
+    for (let i = 1; i < input.count; i++) commands.spawn([value, rank])({ [value]: (i * 7919) % input.count, [rank]: i });
+});
+
+/** Writes the marked entity's value. */
+const nudge = System.create({ name: "reads/nudge", components: { has: [marked], write: [value] } }, row => { row[value] += 1; });
+
+/** A kernel writing every row's rank, whose stamps it keeps only while something watches ranks change. */
+const advance = System.create({ name: "reads/advance", kernel: "cpu", components: { write: [rank] } }, row => { row[rank] += 1; });
+
+/** The entities `look` and `lookChanged` look up, each run. */
+let looked: readonly Entity[] = [];
+let found = 0;
+
+/** Looks up every entity of `looked` by entity, reading its value, after `nudge` where both run. */
+const look = System.create({ name: "reads/look", lookup: { values: { read: [value] } }, after: [nudge] }, ({ lookup }) => {
+    for (let i = 0; i < looked.length; i++) {
+        const row = lookup.values(looked[i]);
+        if (row !== null && row[value] >= 0) found++;
+    }
+});
+
+/** The same, with `changed`: counts the entities whose value may have changed since it last ran. */
+const lookChanged = System.create({ name: "reads/lookChanged", lookup: { values: { read: [value], changed: [value] } }, after: [nudge] }, ({ lookup }) => {
+    for (let i = 0; i < looked.length; i++) {
+        const row = lookup.values(looked[i]);
+        if (row !== null && row[value] >= 0 && row.changed) found++;
+    }
+});
+
+const nudgeThenLook = System.create({ name: "reads/nudgeThenLook", systems: [nudge, look] });
+const nudgeThenLookChanged = System.create({ name: "reads/nudgeThenLookChanged", systems: [nudge, lookChanged] });
+
+/** A run of `system` over a world of `observedEntities` entities `looked` names, `found` after the last. */
+const lookups = async (system: System): Promise<{ readonly best: number; readonly found: number }> => {
+    const world = await seeded(observedEntities);
+    looked = await entitiesOf(world);
+    await world.run(system);
+    found = 0;
+    const best = await fastest(() => world.run(system));
+    found = 0;
+    await world.run(system);
+    const result = { best, found };
+    looked = [];
+    await world.dispose();
+    return result;
+};
+
+/** Every entity a seeded world holds. */
+const entitiesOf = async (world: World): Promise<readonly Entity[]> => {
+    const found: Entity[] = [];
+    await world.run(System.create({ observer: true, components: { has: [value] } }, row => { found.push(row.entity); }));
+    return found;
+};
+
+const seeded = async (count: number): Promise<World> => {
+    const world = createWorld({ [workers]: 0 });
+    await world.run(seed, { count });
+    return world;
+};
+
+/** Entities the lookup benchmarks look up. */
+const observedEntities = 1_000;
+
+let copied = 0;
+
+const check = (condition: boolean, message: string): void => {
+    if (!condition) throw new Error(message);
+};
+
+export const readBenchmarks: readonly Benchmark[] = [
+    {
+        name: "read run",
+        operation: "Reading a resource through a run of a new system that copies it out: a value read from outside the world through a system made for the read.",
+        per: "reads",
+        n: 1,
+        typical: [1, 100],
+        best: { bytes: 64, basis: "A read loads at least one cache line of the resource's cell." },
+        run: async () => {
+            const world = await seeded(10_000);
+            copied = 0;
+            const best = await fastest(() => world.run(System.create({ resources: { read: [level] } }, ({ resources }) => { copied = resources[level]; })), 300);
+            check(copied === 3, "read run: wrong value");
+            await world.dispose();
+            return best;
+        },
+    },
+    {
+        name: "read run observer",
+        operation: "Reading a resource through a run of a new observer system that copies it out, which has no tiers and an empty sync point: as `read run`, through an observer system.",
+        per: "reads",
+        n: 1,
+        typical: [1, 100],
+        best: { bytes: 64, basis: "A read loads at least one cache line of the resource's cell." },
+        run: async () => {
+            const world = await seeded(10_000);
+            copied = 0;
+            const best = await fastest(() => world.run(System.create({ observer: true, resources: { read: [level] } }, ({ resources }) => { copied = resources[level]; })), 300);
+            check(copied === 3, "read run observer: wrong value");
+            await world.dispose();
+            return best;
+        },
+    },
+    {
+        name: "read run changed",
+        operation: "Reading the ranks that changed through a run of a new system filtering on `changed`, with a kernel writing them: a read whose filter turns the kernel's stamps on while the system lives.",
+        per: "reads",
+        n: 1,
+        typical: [1, 100],
+        best: { bytes: 64, basis: "A read loads at least one cache line of a chunk's tick." },
+        run: async () => {
+            // Few rows, since a new system's first run reads every row.
+            const world = await seeded(100);
+            await world.run(advance);
+            copied = 0;
+            const best = await fastest(async () => {
+                await world.run(System.create({ components: { read: [rank], changed: [rank] } }, row => { copied += row[rank]; }));
+            }, 300);
+            check(copied > 0, "read run changed: nothing read");
+            await world.dispose();
+            return best;
+        },
+    },
+    {
+        name: "lookup 1K entities",
+        operation: "A system looking up 1K entities by entity, reading a value of each, with nothing changed: following references, without `changed`.",
+        per: "lookups",
+        n: observedEntities,
+        typical: [10, 1_000],
+        best: { bytes: 16, basis: "Each lookup reads its entity's 8-byte location and its 8-byte value." },
+        run: async () => {
+            const { best, found } = await lookups(look);
+            check(found === observedEntities, "lookup 1K entities: wrong count");
+            return best;
+        },
+    },
+    {
+        name: "lookup 1K entities changed",
+        operation: "The same with `changed`, with nothing changed: watching entities a system follows for changes since it last ran.",
+        per: "lookups",
+        n: observedEntities,
+        typical: [10, 1_000],
+        best: { bytes: 24, basis: "Each lookup reads its entity's 8-byte location, its 8-byte value and its 8-byte changed tick." },
+        run: async () => {
+            const { best, found } = await lookups(lookChanged);
+            check(found === 0, "lookup 1K entities changed: changed");
+            return best;
+        },
+    },
+    {
+        name: "lookup 1K entities one changed",
+        operation: "A run writing one of 1K entities, then a system looking up each by entity, reading its value, without `changed`.",
+        per: "lookups",
+        n: observedEntities,
+        typical: [10, 1_000],
+        best: { bytes: 16, basis: "Each lookup reads its entity's 8-byte location and its 8-byte value." },
+        run: async () => {
+            const { best, found } = await lookups(nudgeThenLook);
+            check(found === observedEntities, "lookup 1K entities one changed: wrong count");
+            return best;
+        },
+    },
+    {
+        name: "lookup 1K entities changed one changed",
+        operation: "The same with `changed`: one of the entities a system follows changed since it last ran.",
+        per: "lookups",
+        n: observedEntities,
+        typical: [10, 1_000],
+        best: { bytes: 24, basis: "Each lookup reads its entity's 8-byte location, its 8-byte value and its 8-byte changed tick." },
+        run: async () => {
+            const { best, found } = await lookups(nudgeThenLookChanged);
+            check(found === 1, "lookup 1K entities changed one changed: wrong count");
+            return best;
+        },
+    },
+];

package/src/perftest/remote.ts

@@ -0,0 +1,364 @@
+/// <reference types="node" />
+import { Component } from "../interface/component/component.js";
+import { Index } from "../interface/indexes/index-type.js";
+import { Resource } from "../interface/resource/resource.js";
+import { always } from "../interface/resources/always.js";
+import { eachTick } from "./observer.js";
+import { workers } from "../interface/resources/workers.js";
+import { System } from "../interface/system/system.js";
+import type { World } from "../interface/world/world.js";
+import { backToBack, createWorld } from "../implementation/index.js";
+import type { Benchmark } from "./benchmark.js";
+
+// Benchmarks of a thread joined to a world: its runs, and what it reads after each sync point, through observer systems
+// it adds and the observer factories. The joined thread is `joined.ts`.
+
+export const counter = Symbol("remote/counter");
+export const sign = Symbol("remote/sign");
+export const rank = Symbol("remote/rank");
+export const order = Symbol("remote/order");
+export const caption = Symbol("remote/caption");
+export const amount = Symbol("remote/amount");
+declare module "@adobe/ecs" {
+    export interface Components {
+        [rank]: { type: number };
+        [order]: { type: number };
+        [caption]: { type: string };
+        [amount]: { type: number };
+    }
+    export interface Resources {
+        [counter]: { type: number };
+        [sign]: { type: number };
+    }
+}
+Resource.register(counter, { type: { type: "number", default: 0 } });
+Resource.register(sign, { type: { type: "number", default: 1 } });
+Component.register(rank, { type: { type: "number" } });
+Component.register(order, { type: { type: "number" } });
+Component.register(caption, { type: { type: "string" } });
+Component.register(amount, { type: { type: "number" } });
+
+/** An empty transaction. */
+export const empty = System.create({ name: "remote/empty" }, () => {});
+/** Changes the observed resource every tick. */
+export const count = System.create({ name: "remote/count", resources: { write: [counter] } }, ({ resources }) => { resources[counter] += 1; });
+export const seedRanks = System.create({ name: "remote/seedRanks", input: { type: "object", properties: { count: { type: "integer" } } } }, ({ input, commands }) => {
+    for (let i = 0; i < input.count; i++) commands.spawn([rank, order])({ [rank]: i, [order]: i });
+});
+const flip = System.create({ name: "remote/flip", resources: { write: [sign] } }, ({ resources }) => { resources[sign] = -resources[sign]; });
+const reverse = System.create({ name: "remote/reverse", kernel: "cpu", components: { read: [rank], write: [order] }, resources: { read: [sign] }, after: [flip] }, (row, { resources }) => {
+    row[order] = row[rank] * resources[sign];
+});
+/** Reverses the entities' order every tick. */
+export const reorder = System.create([flip, reverse]);
+
+/** What a joined thread's observer systems saw: the last value, and how many runs gave one. */
+export const observerSeen = { last: 0, notified: 0 };
+
+/** On a joined thread, after each sync point that changed it: the observed resource. */
+export const observerCounter = System.create({ name: "remote/observerCounter", observer: true, resources: { read: [counter], changed: [counter] } }, ({ resources }) => {
+    observerSeen.last = resources[counter];
+    observerSeen.notified++;
+});
+
+/** Every entity with a rank, in entity order. */
+const ranked = Index.create({ name: "remote/ranked", key: [], components: { has: [rank, order] } });
+const sortedKeys = { keys: new Float64Array(0), entities: new Float64Array(0), positions: new Uint32Array(0) };
+/**
+ * On a joined thread, after each sync point: the entities in `order`, sorted from a scan of the index of every ranked
+ * entity into reused arrays.
+ */
+export const observerSelect = System.create({ name: "remote/observerSelect", observer: true, lookup: { all: { index: ranked, read: [order] } } }, ({ lookup }) => {
+    const list = lookup.all();
+    const count = list.length;
+    if (sortedKeys.keys.length < count) {
+        sortedKeys.keys = new Float64Array(count);
+        sortedKeys.entities = new Float64Array(count);
+        sortedKeys.positions = new Uint32Array(count);
+    }
+    const { keys, entities } = sortedKeys;
+    for (let k = 0; k < count; k++) {
+        const row = list.at(k);
+        if (row === null) continue;
+        keys[k] = row[order];
+        entities[k] = row.entity;
+    }
+    const positions = sortedKeys.positions.subarray(0, count);
+    for (let k = 0; k < count; k++) positions[k] = k;
+    positions.sort((a, b) => keys[a] - keys[b] || entities[a] - entities[b]);
+    observerSeen.last = count;
+    observerSeen.notified++;
+});
+
+/** Rows with a caption and an amount, a todo's label and a number, which `retext` and `reamount` rewrite 1% of a tick. */
+export const seedCaptions = System.create({ name: "remote/seedCaptions", input: { type: "object", properties: { count: { type: "integer" } } } }, ({ input, commands }) => {
+    for (let i = 0; i < input.count; i++) commands.spawn([rank, caption, amount])({ [rank]: i, [caption]: `Buy milk and bread #${i}`, [amount]: i });
+});
+const recaption = System.create({ name: "remote/recaption", components: { read: [rank], write: [caption] }, resources: { read: [counter] }, after: [count] }, (row, { resources }) => {
+    if (row[rank] % 100 === resources[counter] % 100) row[caption] = `Buy milk and bread #${row[rank]}.${resources[counter]}`;
+});
+const reamount = System.create({ name: "remote/reamount", components: { read: [rank], write: [amount] }, resources: { read: [counter] }, after: [count] }, (row, { resources }) => {
+    if (row[rank] % 100 === resources[counter] % 100) row[amount] = row[rank] + resources[counter];
+});
+/** Rewrites 1% of the captions a tick. */
+export const retext = System.create([count, recaption]);
+/** Rewrites 1% of the amounts a tick. */
+export const reamounted = System.create([count, reamount]);
+
+/** On a joined thread, after each sync point: every row's caption, out of its record. */
+export const observerCaptions = System.create({ name: "remote/observerCaptions", observer: true, components: { read: [caption] } }, row => {
+    observerSeen.last += row[caption].length;
+    observerSeen.notified++;
+});
+/** On a joined thread, after each sync point: every row's amount. */
+export const observerAmounts = System.create({ name: "remote/observerAmounts", observer: true, components: { read: [amount] } }, row => {
+    observerSeen.last += row[amount];
+    observerSeen.notified++;
+});
+
+/** Runs in each timed stretch of `remote run`, and ticks in each of the joined benchmarks'. */
+export const remoteRuns = 1_000;
+export const joinedTicks = 1_000;
+/** Entities `joined observer 10K` selects. */
+export const selected = 10_000;
+
+/** What a joined thread reads in a joined benchmark: through an observer system, or the observer factories. */
+type Observed = "observer resource" | "observer select" | "observer captions" | "observer amounts" | "factory resource" | "factory select";
+
+/** What the joined thread is asked to do, and what it answers. */
+export type ToJoined = { readonly kind: "runs"; readonly stretches: number } | { readonly kind: Observed } | { readonly kind: "stop" };
+export type FromJoined = { readonly kind: "ran"; readonly milliseconds: number } | { readonly kind: "observing" } | { readonly kind: "stopped"; readonly last: number; readonly notified: number };
+
+type Joined = { readonly ask: (message: ToJoined) => Promise<FromJoined>; readonly terminate: () => Promise<void> };
+
+const joinedFile = "./joined.js";
+
+/** The observed resource, read by an observer run. */
+const counterOf = async (world: World): Promise<number> => {
+    let value = 0;
+    await world.run(System.create({ observer: true, resources: { read: [counter] } }, ({ resources }) => { value = resources[counter]; }));
+    return value;
+};
+
+/** Starts `joined.ts` on a worker, joining `world` through a channel it's given. */
+const startJoined = async (world: World): Promise<Joined> => {
+    if (typeof globalThis.Worker === "function") {
+        const { port1, port2 } = new MessageChannel();
+        world.share(port1);
+        const worker = new globalThis.Worker(new URL("./joined.js", import.meta.url), { type: "module" });
+        const ask = (message: unknown, transfer: Transferable[] = []): Promise<FromJoined> => new Promise(resolve => {
+            worker.onmessage = (event: MessageEvent<FromJoined>) => resolve(event.data);
+            worker.postMessage(message, transfer);
+        });
+        await ask({ kind: "port", port: port2 }, [port2]);
+        return { ask, terminate: async () => worker.terminate() };
+    }
+    const threads = globalThis.process.getBuiltinModule("node:worker_threads");
+    const { port1, port2 } = new threads.MessageChannel();
+    world.share(port1);
+    const worker = new threads.Worker(new URL(joinedFile, import.meta.url));
+    const ask = (message: unknown, transfer: readonly import("node:worker_threads").Transferable[] = []): Promise<FromJoined> => new Promise(resolve => {
+        worker.once("message", resolve);
+        worker.postMessage(message, transfer);
+    });
+    await ask({ kind: "port", port: port2 }, [port2]);
+    return { ask, terminate: async () => { await worker.terminate(); } };
+};
+
+/** The fastest of `stretches` stretches of `remoteRuns` empty runs from a joined thread, timed there. */
+const remoteRun = async (stretches = 5): Promise<number> => {
+    const world = createWorld({ [workers]: 0 });
+    const joined = await startJoined(world);
+    try {
+        const reply = await joined.ask({ kind: "runs", stretches });
+        return reply.kind === "ran" ? reply.milliseconds : NaN;
+    }
+    finally {
+        await joined.terminate();
+        await world.dispose();
+    }
+};
+
+/**
+ * The fastest of `stretches` stretches of `joinedTicks` ticks on the world's thread, driven back to back, of `system`
+ * while a joined thread reads what it changes, after one to warm up.
+ */
+const joinedBest = async (kind: Observed, system: System<void>, stretches = 5): Promise<number> => {
+    const driver = backToBack();
+    const world = createWorld({ [workers]: 0, [always]: true }, { loop: driver });
+    const reads = kind.endsWith("resource");
+    const rows = kind === "observer captions" || kind === "observer amounts";
+    if (rows) await world.run(seedCaptions, { count: selected });
+    else if (!reads) await world.run(seedRanks, { count: selected });
+    const joined = await startJoined(world);
+    let best = Infinity;
+    try {
+        await joined.ask({ kind });
+        await new Promise<void>(resolve => {
+            let ticks = 0;
+            let stretch = 0;
+            let start = 0;
+            const unobserve = eachTick(world, () => {
+                if (ticks++ % joinedTicks !== 0) return;
+                const now = performance.now();
+                if (stretch > 1) best = Math.min(best, now - start);
+                start = now;
+                if (stretch++ <= stretches) return;
+                unobserve();
+                resolve();
+            });
+            world.add(system);
+        });
+        const counted = reads ? await counterOf(world) : 0;
+        const stopped = await joined.ask({ kind: "stop" });
+        if (stopped.kind !== "stopped" || stopped.notified === 0) throw new Error(`joined ${kind}: the joined thread saw nothing.`);
+        // Timed only while the joined thread keeps up: one that stopped being woken costs the world nothing.
+        if (reads && stopped.last < counted - joinedTicks) throw new Error(`joined ${kind}: the joined thread saw ${stopped.last} of ${counted}.`);
+    }
+    finally {
+        await joined.terminate();
+        await world.dispose();
+        driver.close();
+    }
+    return best;
+};
+
+/**
+ * Ticks the cadence benchmarks give their time for, the ticks they time, after as many to warm up, and the milliseconds
+ * between their frames.
+ */
+export const cadenceTicks = 100;
+const cadenceSamples = 1_000;
+const cadenceMilliseconds = 2;
+
+/**
+ * Frames `milliseconds` apart, as a display's are. The loop asks for the next frame once a tick is done, so each ask
+ * after a frame began tells `ended` how long that frame's tick took.
+ */
+const spaced = (milliseconds: number, ended: (milliseconds: number) => void) => {
+    let began = -1;
+    return {
+        frame: (callback: (time: number) => void): (() => void) => {
+            if (began >= 0) ended(performance.now() - began);
+            began = -1;
+            const timer = setTimeout(() => {
+                began = performance.now();
+                callback(began);
+            }, milliseconds);
+            return () => clearTimeout(timer);
+        },
+    };
+};
+
+/**
+ * What the world's thread spends on `cadenceTicks` ticks of `system`, from each frame's start until its tick is done,
+ * with frames far enough apart that a joined thread observing what it changes keeps up: the cost of `kind` at a
+ * display's cadence rather than back to back. A tick's time varies with what else the machine runs, a few ticks taking
+ * many times the rest, so it's the mean of the middle half of `cadenceSamples` ticks, about their median, rather than
+ * the least; and a mean rather than the median itself, as chromium's timer steps are as long as a tick.
+ */
+const cadenceMiddle = async (kind: Observed, system: System<void>): Promise<number> => {
+    const spent = new Float64Array(cadenceSamples);
+    let ticks = 0;
+    let finished = (): void => {};
+    const done = new Promise<void>(resolve => { finished = resolve; });
+    const driver = spaced(cadenceMilliseconds, milliseconds => {
+        const tick = ticks++ - cadenceSamples;
+        if (tick < 0 || tick >= cadenceSamples) return;
+        spent[tick] = milliseconds;
+        if (tick === cadenceSamples - 1) finished();
+    });
+    const world = createWorld({ [workers]: 0, [always]: true }, { loop: driver });
+    const joined = await startJoined(world);
+    try {
+        await joined.ask({ kind });
+        world.add(system);
+        await done;
+        const counted = await counterOf(world);
+        const stopped = await joined.ask({ kind: "stop" });
+        if (stopped.kind !== "stopped" || stopped.last < counted - 2) throw new Error(`${kind} at a cadence: the joined thread saw ${stopped.kind === "stopped" ? stopped.last : "nothing"} of ${counted}.`);
+    }
+    finally {
+        await joined.terminate();
+        await world.dispose();
+    }
+    spent.sort();
+    let middle = 0;
+    for (let k = cadenceSamples >> 2; k < cadenceSamples - (cadenceSamples >> 2); k++) middle += spent[k];
+    return cadenceTicks * middle / (cadenceSamples >> 1);
+};
+
+export const remoteBenchmarks: readonly Benchmark[] = [
+    {
+        name: "remote run",
+        operation: "An empty transaction run from a joined thread, through its run slots and completed word: input from another thread, such as the DOM on main driving a world on a worker.",
+        per: "runs",
+        n: remoteRuns,
+        typical: [1, 100],
+        best: { bytes: 192, basis: "A run moves at least its slot's line and the posted and completed words' lines between cores." },
+        run: () => remoteRun(),
+    },
+    {
+        name: "joined observer resource",
+        operation: "Ticks that change one resource an observer system a joined thread added reads after each sync point, posted to it and waking it once.",
+        per: "ticks",
+        n: joinedTicks,
+        typical: [1, 1],
+        best: { bytes: 64, basis: "A tick reads at least one cache line of its system's state." },
+        run: () => joinedBest("observer resource", count),
+    },
+    {
+        name: "joined observer 10K",
+        operation: "Ticks that reverse the order of 10K entities an observer system a joined thread added reads through an index and sorts after each sync point.",
+        per: "ticks",
+        n: joinedTicks,
+        typical: [1, 1],
+        best: { bytes: selected * 24, basis: "Each tick writes 10K 8-byte values, reads them to sort, and sorts 10K 8-byte entities." },
+        run: () => joinedBest("observer select", reorder, 3),
+    },
+    {
+        name: "joined observer strings 10K",
+        operation: "Ticks that rewrite 1% of 10K captions, a todo's label each, while an observer system a joined thread added reads every caption after each sync point, out of its record: a binding on main reading a world on a worker.",
+        per: "ticks",
+        n: joinedTicks,
+        typical: [1, 1],
+        best: { bytes: 40_000, basis: "A pass reads at least each row's 4-byte handle." },
+        run: () => joinedBest("observer captions", retext, 3),
+    },
+    {
+        name: "joined observer numbers 10K",
+        operation: "The same with 10K numbers in place of the captions, as `joined observer strings 10K` measures against.",
+        per: "ticks",
+        n: joinedTicks,
+        typical: [1, 1],
+        best: { bytes: 80_000, basis: "A pass reads at least each row's 8-byte number." },
+        run: () => joinedBest("observer amounts", reamounted, 3),
+    },
+    {
+        name: "joined resource factory",
+        operation: "Ticks that change one resource a joined thread observes through `Observe.resource`, an observer system it added, posted to it and waking it once.",
+        per: "ticks",
+        n: joinedTicks,
+        typical: [1, 1],
+        best: { bytes: 64, basis: "A tick reads at least one cache line of its system's state." },
+        run: () => joinedBest("factory resource", count),
+    },
+    {
+        name: "joined select 10K factory",
+        operation: "Ticks that reverse the order of 10K entities a joined thread selects in order through `Observe.select`.",
+        per: "ticks",
+        n: joinedTicks,
+        typical: [1, 1],
+        best: { bytes: selected * 24, basis: "Each tick writes 10K 8-byte values, reorders them in the index, and reads 10K 8-byte entities." },
+        run: () => joinedBest("factory select", reorder, 3),
+    },
+    {
+        name: "joined resource factory cadence",
+        operation: "`joined resource factory` at a display's cadence, frames 2 ms apart, the joined thread keeping up: what the world's thread spends on a tick, from its frame until the tick is done.",
+        per: "ticks",
+        n: cadenceTicks,
+        typical: [1, 1],
+        best: { bytes: 64, basis: "A tick reads at least one cache line of its system's state." },
+        run: () => cadenceMiddle("factory resource", count),
+    },
+];

package/src/perftest/run.ts

@@ -0,0 +1,43 @@
+/// <reference types="node" />
+import { calibrationSource, copyBandwidth, environmentLine, resultLine, threadsBandwidth, type Curve } from "./benchmark.js";
+import { benchmarks } from "./benchmarks.js";
+import { runKeyReading } from "./keys.js";
+import { threads } from "./placed.js";
+
+/** Every worker's copy bandwidth together, through `worker_threads` running the calibration script over `parentPort`. */
+const nodeThreadsBandwidth = (): Promise<Curve> => {
+    const { Worker } = process.getBuiltinModule("node:worker_threads");
+    const scope = `const { parentPort } = require("node:worker_threads");
+        const postMessage = message => parentPort.postMessage(message);
+        let onmessage = null;
+        parentPort.on("message", data => onmessage({ data }));`;
+    return threadsBandwidth(threads, () => {
+        const worker = new Worker(`${scope}\n${calibrationSource}`, { eval: true });
+        return {
+            ask: message => new Promise(resolve => {
+                worker.once("message", resolve);
+                worker.postMessage(message);
+            }),
+            terminate: () => void worker.terminate(),
+        };
+    });
+};
+
+/**
+ * Runs benchmarks bundled, on plain node: real module bindings, as in production. `scripts/perf.mjs` reads its lines.
+ * - `--names` prints the benchmarks' names, one per line.
+ * - `--environment` prints the environment line, with measured copy bandwidth, of one thread and of every worker.
+ * - `--keys` prints the key-reading microbenchmark (`keys.ts`).
+ * - Otherwise it runs the benchmark with the given name, or those whose names match a regular expression with `--match`.
+ */
+const [option, value] = process.argv.slice(2);
+if (option === "--names") for (const { name } of benchmarks) console.log(name);
+else if (option === "--keys") runKeyReading();
+else if (option === "--environment") console.log(environmentLine(`node ${process.versions.node}`, { thread: copyBandwidth(), threads: await nodeThreadsBandwidth() }));
+else {
+    const pattern = option === "--match" && value !== undefined ? new RegExp(value) : null;
+    for (const benchmark of benchmarks) {
+        if (pattern === null ? benchmark.name !== option : !pattern.test(benchmark.name)) continue;
+        console.log(resultLine(benchmark, await benchmark.run()));
+    }
+}