@adobe/ecs 0.0.0-stage → 0.1.0

package/src/observe/tsconfig.json

@@ -0,0 +1,31 @@
+{
+  "extends": "../../../data/tsconfig-base.json",
+  "compilerOptions": {
+    "rootDir": "..",
+    "outDir": "../../dist",
+    "tsBuildInfoFile": "../../dist/observe/tsconfig.tsbuildinfo",
+    "composite": true,
+    "types": [
+      "@webgpu/types"
+    ],
+    "paths": {
+      "@adobe/ecs": [
+        "../interface/index.ts"
+      ]
+    },
+    "lib": [
+      "ES2024",
+      "ESNext.Disposable",
+      "DOM",
+      "DOM.Iterable"
+    ]
+  },
+  "include": [
+    "./**/*"
+  ],
+  "references": [
+    {
+      "path": "../interface"
+    }
+  ]
+}

package/src/observe/values.ts

@@ -0,0 +1,9 @@
+import type { Component, Resource } from '../interface/index.js';
+
+type Primitive = string | number | boolean | bigint | symbol | null | undefined;
+
+/** Component `K`'s value as observers give it: read-only, with branded primitives such as `Entity` as they are. */
+export type ReadonlyValue<K extends Component.Key> = Component.Value<K> extends Primitive ? Component.Value<K> : Readonly<Component.Value<K>>;
+
+/** Resource `K`'s value as observers give it. */
+export type ReadonlyResourceValue<K extends Resource.Key> = Resource.Value<K> extends Primitive ? Resource.Value<K> : Readonly<Resource.Value<K>>;

package/src/observe/world-state.ts

@@ -0,0 +1,414 @@
+import { Report, System, type World } from '../interface/index.js';
+
+// What the factories keep for each world: the values observers share, their subscribers, and the observer systems that
+// read the world for them. Every shape of observer is one observer system, never one per subscriber or entity.
+
+/**
+ * A subscriber: its notify, null once stopped; the flush its first value waits for, 0 once it had it; and the pass
+ * it had it in, so a system later in that pass doesn't notify it again.
+ */
+export type Subscriber<T> = { notify: ((value: T) => void) | null; batch: number; pass: number };
+
+/**
+ * A value observers share, such as a resource's or an entity's: the last value given, `valid` while it's the world's
+ * as of the last pass; its subscribers, null where one stopped, `live` of them active and `waiting` for a first value;
+ * and how many passes found it without subscribers since it last had one.
+ */
+export type Entry<T> = {
+    value: T;
+    valid: boolean;
+    readonly subscribers: Subscriber<T>[];
+    live: number;
+    waiting: number;
+    stopped: number;
+    idle: number;
+};
+
+export const createEntry = <T>(value: T): Entry<T> => ({ value, valid: false, subscribers: [], live: 0, waiting: 0, stopped: 0, idle: 0 });
+
+/**
+ * What a shape removes once it's been idle for a whole pass, how many subscribers its entries have, and how many passes
+ * the maintenance system found it without them since it last had one.
+ */
+export type Shape = { live: number; idle: number; readonly remove: () => void };
+
+/**
+ * A system a flush runs before it delivers, and what it's told of the flush, by number, when it does; on a joined
+ * thread, `delivered` once the run resolved, a post for it having run there.
+ */
+export type Read = { readonly system: System; readonly flushed: (batch: number) => void; readonly delivered: (batch: number) => void };
+
+/**
+ * A world's factories' state: the pass the maintenance system counted last; flushes, `open` the one new cold first
+ * values wait for and `delivered` the last whose delivering run reached its pass; what the next flush runs; and idle
+ * shapes.
+ */
+export type WorldState = {
+    readonly world: World;
+    /**
+     * Whether `world` is a joined thread's: its observer systems run there in posts, in no order with one another, so
+     * a shape's first values come once a run of its own system resolved, rather than from a delivering run.
+     */
+    readonly joined: boolean;
+    /** On a joined thread, whether this turn of its event loop counted a pass, and what ends it once its posts ran. */
+    counted: boolean;
+    readonly endTurn: () => void;
+    pass: number;
+    open: number;
+    delivered: number;
+    scheduled: boolean;
+    readonly reads: Read[];
+    /** Whether the next flush runs the delivering system, for shapes that read in the pass of its run. */
+    delivering: boolean;
+    /** Work for the next flush's delivering run, in its body, before shapes' systems run in its pass. */
+    tasks: (() => void)[];
+    /** By delivering run called and not yet run, its flush and its work. */
+    readonly deliveries: { readonly batch: number; readonly tasks: readonly (() => void)[] }[];
+    readonly idle: Shape[];
+    readonly deliver: System;
+    /** What a rejected run of the factories' own does. */
+    readonly rejected: (error: unknown) => void;
+    /**
+     * The factories' own runs, by number, with how many of each one's report's failures were rethrown; and the
+     * failures of the factories' systems in reports of runs not known to be theirs yet, by run.
+     */
+    /** Run with each of the factories' own systems, as a composite: what reads the reports their runs gave. */
+    readonly rethrow: System;
+    readonly composites: WeakMap<System, System>;
+};
+
+const states = new WeakMap<World, WorldState>();
+
+/** Rethrows an error out of band: it's the caller's, but nothing can return it to them. */
+export const rethrowLater = (error: unknown): void => {
+    queueMicrotask(() => { throw error; });
+};
+
+/**
+ * The names of the systems the factories make. A run of theirs runs every observer system the world added too; only
+ * these systems' failures are the factories' to rethrow.
+ */
+const ownNames = new Set<string>();
+
+/** Names a system the factories make. */
+export const ownName = (name: string): string => {
+    ownNames.add(name);
+    return name;
+};
+
+const ignore = (): void => {
+    // A disposed world runs nothing more: its observers' first values never come.
+};
+
+/** Runs nothing: a run of it resolves while its world lives. */
+const alive = System.create({ name: ownName("Observe/alive"), observer: true }, () => {});
+
+/**
+ * What a rejected run of the factories' own does: nothing for a disposed world, whose first values never come, and for
+ * a live one, such as one whose system failed to register, rethrows the rejection out of band.
+ */
+const rejectedOf = (world: World) => (error: unknown): void => {
+    world.run(alive).then(() => rethrowLater(error), ignore);
+};
+
+/**
+ * A run of the factories' own, whose report nothing reads: its failures of their systems, and its rejection, are
+ * rethrown out of band.
+ */
+const runOwn = (state: WorldState, system: System): void => {
+    let composite = state.composites.get(system);
+    if (composite === undefined) state.composites.set(system, composite = System.create([system, state.rethrow]));
+    state.world.run(composite).then(undefined, state.rejected);
+};
+
+const noTasks: readonly (() => void)[] = [];
+
+/**
+ * A run of a joined thread's shape for first values: once it resolved, a post for it ran there, so `read` gives them.
+ * What its system threw is in a later report of the world's.
+ */
+const runJoined = (state: WorldState, read: Read, batch: number): void => {
+    state.world.run(read.system).then(() => read.delivered(batch), state.rejected);
+};
+
+/** Runs what subscribers waiting for the open flush need, in call order after every run called before them. */
+const flush = (state: WorldState): void => {
+    state.scheduled = false;
+    const batch = state.open++;
+    const { reads, world } = state;
+    if (state.joined) {
+        for (let i = 0; i < reads.length; i++) runJoined(state, reads[i], batch);
+        reads.length = 0;
+        return;
+    }
+    for (let i = 0; i < reads.length; i++) {
+        reads[i].flushed(batch);
+        runOwn(state, reads[i].system);
+    }
+    reads.length = 0;
+    if (!state.delivering) return;
+    state.delivering = false;
+    state.deliveries.push({ batch, tasks: state.tasks.length === 0 ? noTasks : state.tasks });
+    if (state.tasks.length > 0) state.tasks = [];
+    runOwn(state, state.deliver);
+};
+
+/**
+ * Removes the shapes found idle in three passes: one used in a pass, before or after this system ran in it, stays
+ * through the next two, so loops reading first values between runs stay warm.
+ */
+const sweepShapes = (state: WorldState): void => {
+    const { idle } = state;
+    let kept = 0;
+    for (let i = 0; i < idle.length; i++) {
+        const shape = idle[i];
+        if (shape.live > 0) continue;
+        if (++shape.idle > 2) {
+            shape.remove();
+            continue;
+        }
+        idle[kept++] = shape;
+    }
+    idle.length = kept;
+};
+
+/** A system no world adds, which only a joined thread's `remove` refuses, since it isn't an observer. */
+const probe = System.create({ name: "Observe/probe" }, () => {});
+
+/** Whether `world` is a joined thread's: its `remove` takes only observer systems, where the world's ignores one never added. */
+const isJoined = (world: World): boolean => {
+    try {
+        world.remove(probe);
+        return false;
+    }
+    catch {
+        return true;
+    }
+};
+
+/**
+ * On a joined thread, counts a pass once per turn of its event loop that ran a shape's system, and sweeps idle shapes
+ * after the turn's posts ran, for no system orders passes there.
+ */
+export const passed = (state: WorldState): void => {
+    if (!state.joined || state.counted) return;
+    state.counted = true;
+    state.pass++;
+    queueMicrotask(state.endTurn);
+};
+
+export const stateOf = (world: World): WorldState => {
+    let state = states.get(world);
+    if (state !== undefined) return state;
+    const joined = isJoined(world);
+    const created: WorldState = {
+        world,
+        joined,
+        counted: false,
+        endTurn: () => {
+            created.counted = false;
+            if (created.idle.length > 0) sweepShapes(created);
+        },
+        pass: 0,
+        open: 1,
+        delivered: 0,
+        scheduled: false,
+        reads: [],
+        delivering: false,
+        tasks: [],
+        deliveries: [],
+        idle: [],
+        rejected: rejectedOf(world),
+        // Run with the factories' own systems, never added: what one of them throws is in a later report, whose errors
+        // are written once, which the next of the factories' runs sees.
+        rethrow: System.create({ name: ownName("Observe/rethrow"), observer: true, components: { read: [Report.errors], changed: [Report.errors] } }, row => {
+            for (const failure of row[Report.errors].failures) if (ownNames.has(failure.name)) rethrowLater(new Error(`${failure.name}: ${failure.message}`));
+        }),
+        composites: new WeakMap(),
+        deliver: System.create({ name: ownName("Observe/deliver"), observer: true }, () => {
+            const delivery = created.deliveries.shift();
+            if (delivery === undefined) return;
+            created.delivered = delivery.batch;
+            for (let i = 0; i < delivery.tasks.length; i++) delivery.tasks[i]();
+        }),
+    };
+    state = created;
+    states.set(world, created);
+    if (joined) return created;
+    // Added before any shape's system, so in each pass it counts the pass before they run.
+    world.add(System.create({ name: ownName("Observe/maintain"), observer: true }, () => {
+        created.pass++;
+        if (created.idle.length > 0) sweepShapes(created);
+    }));
+    return created;
+};
+
+const schedule = (state: WorldState): void => {
+    if (state.scheduled) return;
+    state.scheduled = true;
+    queueMicrotask(() => flush(state));
+};
+
+/** Makes the next flush, at the end of this task, deliver first values to subscribers of shapes that read in its pass. */
+export const scheduleDelivery = (state: WorldState): void => {
+    state.delivering = true;
+    schedule(state);
+};
+
+/** A read's step that does nothing. */
+export const noDelivery = (): void => {
+    // A read on one kind of thread has nothing to do at the step the other's flush takes.
+};
+
+/** Makes the next flush run a read, once, before it delivers; on a joined thread, once, giving first values once it resolved. */
+export const scheduleRead = (state: WorldState, read: Read): void => {
+    if (!state.reads.includes(read)) state.reads.push(read);
+    schedule(state);
+};
+
+/** Runs `task` in the next flush's delivering run, before shapes' systems run in its pass. */
+export const onNextDelivery = (state: WorldState, task: () => void): void => {
+    scheduleDelivery(state);
+    state.tasks.push(task);
+};
+
+/** Within a flush, before it delivers: makes it deliver, running `task` in its delivering run. */
+export const deliverAlso = (state: WorldState, task: () => void): void => {
+    state.delivering = true;
+    state.tasks.push(task);
+};
+
+/** Marks a shape with no subscribers left, for removal once it's been idle for a pass. */
+export const becameIdle = (state: WorldState, shape: Shape): void => {
+    shape.idle = 0;
+    if (!state.idle.includes(shape)) state.idle.push(shape);
+};
+
+/**
+ * Subscribes `notify` to an entry: with a valid value, given it now, where a throw stops it and throws to the caller;
+ * otherwise waiting for the next flush, which `wait` schedules. Returns the function that stops it.
+ */
+export const subscribe = <T>(state: WorldState, shape: Shape, entry: Entry<T>, notify: (value: T) => void, wait: () => void): (() => void) => {
+    // Before a first value given in a pass, its pass is one `give` never skips: not -1, which skips none.
+    const subscriber: Subscriber<T> = { notify, batch: 0, pass: -2 };
+    entry.subscribers.push(subscriber);
+    entry.live++;
+    entry.idle = 0;
+    shape.live++;
+    shape.idle = 0;
+    let active = true;
+    const stop = (): void => {
+        if (!active) return;
+        active = false;
+        if (subscriber.notify !== null) {
+            subscriber.notify = null;
+            entry.stopped++;
+        }
+        entry.live--;
+        if (subscriber.batch !== 0) {
+            subscriber.batch = 0;
+            entry.waiting--;
+        }
+        if (--shape.live === 0) becameIdle(state, shape);
+    };
+    if (entry.valid) {
+        try {
+            notify(entry.value);
+        }
+        catch (error) {
+            stop();
+            throw error;
+        }
+        return stop;
+    }
+    subscriber.batch = state.open;
+    entry.waiting++;
+    wait();
+    return stop;
+};
+
+/** Drops an entry's stopped subscribers. */
+export const sweepSubscribers = <T>(entry: Entry<T>): void => {
+    if (entry.stopped === 0) return;
+    const { subscribers } = entry;
+    let kept = 0;
+    for (let i = 0; i < subscribers.length; i++) if (subscribers[i].notify !== null) subscribers[kept++] = subscribers[i];
+    subscribers.length = kept;
+    entry.stopped = 0;
+};
+
+/** No error, as `give` returns it. */
+export const none: unique symbol = Symbol("Observe/none");
+
+/**
+ * Gives an entry's value to its subscribers: a first value to each waiting for a flush up to `through`, whose throw
+ * stops it and is rethrown out of band; and with `changed`, the value to the others but those that had their first in
+ * pass `fresh`, -1 for none. Subscribers added meanwhile wait for a later pass. Returns the first error a later value's
+ * notify threw, or `failed` when it's already one.
+ */
+export const give = <T>(entry: Entry<T>, through: number, changed: boolean, pass: number, fresh: number, failed: unknown): unknown => {
+    let error = failed;
+    const { subscribers } = entry;
+    const value = entry.value;
+    for (let i = 0, count = subscribers.length; i < count; i++) {
+        const subscriber = subscribers[i];
+        const notify = subscriber.notify;
+        if (notify === null) continue;
+        if (subscriber.batch !== 0) {
+            if (subscriber.batch > through) continue;
+            subscriber.batch = 0;
+            subscriber.pass = pass;
+            entry.waiting--;
+            try {
+                notify(value);
+            }
+            catch (thrown) {
+                // As a joined thread's first values are, it's thrown where nothing can catch it.
+                if (subscriber.notify !== null) {
+                    subscriber.notify = null;
+                    entry.stopped++;
+                }
+                rethrowLater(thrown);
+            }
+            continue;
+        }
+        if (!changed || subscriber.pass === fresh) continue;
+        try {
+            notify(value);
+        }
+        catch (thrown) {
+            if (error === none) error = thrown;
+        }
+    }
+    return error;
+};
+
+/** On a joined thread, gives an entry's first values to subscribers waiting for a flush up to `through`, once it holds one. */
+export const giveFirst = <T>(state: WorldState, entry: Entry<T>, through: number): void => {
+    if (entry.waiting === 0 || !entry.valid) return;
+    give(entry, through, false, state.pass, -1, none);
+};
+
+/** Throws what a notify threw, so its system's run reports it. */
+export const throwFailed = (failed: unknown): void => {
+    if (failed !== none) throw failed;
+};
+
+const numbers = new Map<symbol, number>();
+
+/** A key's number in this program, for keys of shapes. */
+export const numberOf = (key: symbol): number => {
+    let number = numbers.get(key);
+    if (number === undefined) numbers.set(key, number = numbers.size + 1);
+    return number;
+};
+
+/** A stable key for a list of component keys. */
+export const keysId = (keys: readonly symbol[]): string => {
+    let id = "";
+    for (let i = 0; i < keys.length; i++) id += `${numberOf(keys[i])},`;
+    return id;
+};
+
+/** A label for a list of keys, by their descriptions. */
+export const labelOf = (keys: readonly symbol[]): string => keys.map(key => key.description ?? "?").join(", ");

package/src/observe-imports.test.ts

@@ -0,0 +1,48 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const source = dirname(fileURLToPath(import.meta.url));
+const module = join(source, "observe");
+
+/** Every TypeScript file under a directory. */
+const filesOf = (directory: string): string[] => readdirSync(directory, { withFileTypes: true }).flatMap(entry =>
+    entry.isDirectory() ? filesOf(join(directory, entry.name)) : entry.name.endsWith(".ts") ? [join(directory, entry.name)] : []);
+
+/** The specifiers a file imports or re-exports, statically or dynamically, and the modules its declarations augment. */
+const specifiersOf = (file: string): string[] => {
+    const code = readFileSync(file, "utf8");
+    return [
+        ...code.matchAll(/(?:^|[\s;])(?:import|export)\s[^'"]*?\sfrom\s*["']([^"']+)["']/g),
+        ...code.matchAll(/(?:^|[\s;])import\s*["']([^"']+)["']/g),
+        ...code.matchAll(/import\s*\(\s*["']([^"']+)["']\s*\)/g),
+        ...code.matchAll(/declare\s+module\s+["']([^"']+)["']/g),
+    ].map(match => match[1]);
+};
+
+/**
+ * Whether `src/observe` may import a specifier from `file`: the interface's index, the public API but for how a world is
+ * made, which the factories never do, or a module of its own.
+ */
+const allowed = (file: string, specifier: string): boolean => {
+    if (specifier === "@adobe/ecs") return true;
+    if (!specifier.startsWith(".")) return false;
+    const target = resolve(dirname(file), specifier);
+    return target === join(source, "interface", "index.js") || !relative(module, target).startsWith("..");
+};
+
+describe("src/observe, the observer factories", () => {
+    it("imports only the interface's index and its own modules", () => {
+        const files = filesOf(module);
+        expect(files.length).toBeGreaterThan(0);
+        const outside = files.flatMap(file => specifiersOf(file).filter(specifier => !allowed(file, specifier)).map(specifier => `${relative(source, file)}: ${specifier}`));
+        expect(outside).toEqual([]);
+    });
+
+    it("finds imports from anywhere else", () => {
+        const file = join(module, "probe.ts");
+        expect(["../index.js", "../implementation/index.js", "node:fs", "../interface/world/world.js", "../interface/../index.js"].filter(specifier => allowed(file, specifier))).toEqual([]);
+        expect(["../interface/index.js", "./observe.js", "@adobe/ecs"].every(specifier => allowed(file, specifier))).toBe(true);
+    });
+});

package/src/perftest/benchmark.ts

@@ -0,0 +1,106 @@
+/** A benchmark and what it stands for, so its results read without its code. */
+export type Benchmark = {
+    /** Stable across runs: results are tracked by it. */
+    readonly name: string;
+    /** What it measures, and what systems or rules cause it in an app. */
+    readonly operation: string;
+    /** What its time is divided by, such as "matched rows" or "spawns". */
+    readonly per: string;
+    /** How many of `per` it runs with. */
+    readonly n: number;
+    /** The range of `per` this operation usually sees in apps. */
+    readonly typical: readonly [number, number];
+    /** The best time it could take. */
+    readonly best: Best;
+    /** Milliseconds. */
+    readonly run: () => Promise<number>;
+};
+
+/**
+ * The fewest bytes per N an ideal implementation must move, in this ECS's storage model, and why. Its time is those
+ * bytes at the fastest copy bandwidth the environment measured: of one thread, of every worker, or of the GPU.
+ */
+export type Best = { readonly bytes: number; readonly basis: string; readonly on?: "threads" | "gpu" };
+
+/** Copy bandwidths by working set: bytes read and written per copy, and bytes per nanosecond. */
+export type Curve = readonly (readonly [number, number])[];
+
+/** Bandwidths an environment measured. */
+export type Bandwidth = { readonly thread: Curve; readonly threads?: Curve; readonly gpu?: number };
+
+/** Bytes per array of each calibration copy: from within the caches to well past them. */
+export const calibrationSizes: readonly number[] = [1 << 18, 1 << 20, 1 << 22, 1 << 24, 1 << 26];
+
+/** A line `scripts/perf.mjs` reads from a run's output. */
+export const resultLine = (benchmark: Benchmark, milliseconds: number): string => {
+    const { run: _, ...description } = benchmark;
+    return `perf-result ${JSON.stringify({ ...description, milliseconds })}`;
+};
+
+export const environmentLine = (environment: string, bandwidth: Bandwidth): string =>
+    `perf-environment ${JSON.stringify({ environment, bandwidth })}`;
+
+/** One thread's copy bandwidth at each calibration size, from the fastest of repeated timed batches of copies. */
+export const copyBandwidth = (): Curve => calibrationSizes.map(size => {
+    const length = size / 8;
+    const from = new Float64Array(length).fill(1);
+    const to = new Float64Array(length);
+    const copies = Math.max(1, Math.round((1 << 26) / size));
+    let best = Infinity;
+    for (let i = 0; i < 12; i++) {
+        const start = performance.now();
+        for (let k = 0; k < copies; k++) to.set(from);
+        best = Math.min(best, (performance.now() - start) / copies);
+    }
+    return [2 * size, (2 * size) / (best * 1e6)];
+});
+
+/** A calibration worker: `ask` posts a message and resolves with the worker's reply. */
+export type CalibrationWorker = { readonly ask: (message: unknown) => Promise<unknown>; readonly terminate: () => void };
+
+/**
+ * The script each calibration worker runs, over its scope's `onmessage` and `postMessage`. Every claim copies one piece
+ * of `size / pieces` bytes `copies` times, so a pass copies `size` bytes `copies` times. A worker's buffers hold its
+ * share of `size`, at least one piece, and it copies its pieces in turn.
+ */
+export const calibrationSource = `onmessage = ({ data: [piece, share, counter, total, copies] }) => {
+    const length = piece / 8, count = Math.max(1, Math.round(share / piece));
+    const source = new Float64Array(length * count).fill(1), target = new Float64Array(length * count), claims = new Int32Array(counter);
+    let next = 0;
+    postMessage(0);
+    onmessage = () => {
+        for (let claim = Atomics.add(claims, 0, 1); claim < total; claim = Atomics.add(claims, 0, 1)) {
+            const start = next * length, from = source.subarray(start, start + length);
+            for (let k = 0; k < copies; k++) target.set(from, start);
+            next = (next + 1) % count;
+        }
+        postMessage(0);
+    };
+};`;
+
+/**
+ * Every worker's copy bandwidth together at each calibration size, each of `threads` workers copying its share in
+ * buffers of its own, since copies between shared buffers are slower than the kernels' loads and stores. Workers
+ * claim pieces from a shared counter, as the ECS splits work, so the slowest core doesn't set the time.
+ */
+export const threadsBandwidth = async (threads: number, start: () => CalibrationWorker): Promise<Curve> => {
+    const pieces = 64;
+    const curve: [number, number][] = [];
+    for (const size of calibrationSizes) {
+        const workers = Array.from({ length: threads }, start);
+        const counter = new Int32Array(new SharedArrayBuffer(4));
+        const copies = Math.max(1, Math.round((1 << 28) / size));
+        const each = (message: unknown): Promise<unknown> => Promise.all(workers.map(worker => worker.ask(message)));
+        await each([size / pieces, size / threads, counter.buffer, pieces, copies]);
+        let best = Infinity;
+        for (let i = 0; i < 8; i++) {
+            counter[0] = 0;
+            const begin = performance.now();
+            await each(0);
+            best = Math.min(best, (performance.now() - begin) / copies);
+        }
+        for (const worker of workers) worker.terminate();
+        curve.push([2 * size, (2 * size) / (best * 1e6)]);
+    }
+    return curve;
+};