@adobe/ecs 0.0.0-stage → 0.1.0

package/src/interface/trait/trait.type-test.ts

@@ -0,0 +1,158 @@
+import { Component } from '../component/component.js';
+import { Entity } from '../entity/entity.js';
+import { Resource } from '../resource/resource.js';
+import type { Commands } from '../system/commands.js';
+import type { IsStruct } from '../schema/is-struct.js';
+import type { Components } from '../component/types.js';
+import { Trait } from './trait.js';
+import type { Derived, Essential } from '../component/value.js';
+import type { Reduced } from '../resource/reduction.js';
+
+type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends (<T>() => T extends Y ? 1 : 2) ? true : false;
+const check = <_T extends true>() => { };
+
+// Traits other packages define: one only linear components take, one derived components don't need.
+const gpuOnly = Symbol("traitTest/gpuOnly");
+const nonPersistent = Symbol("traitTest/nonPersistent");
+declare module '@adobe/ecs' {
+    export interface Traits<N> {
+        readonly [gpuOnly]: N extends Component.Key ? (IsStruct<Component.Value<N>> extends true ? true : never) : never;
+        readonly [nonPersistent]: N extends Component.Key ? (Components[N] extends { readonly derived: true } ? never : true) : true;
+    }
+}
+Trait.register(gpuOnly);
+Trait.register(nonPersistent);
+// @ts-expect-error string trait names are the core's built-in traits
+Trait.register("derived");
+
+const parent = Symbol("traitTest/parent");
+const follows = Symbol("traitTest/follows");
+const slot = Symbol("traitTest/slot");
+const ready = Symbol("traitTest/ready");
+const score = Symbol("traitTest/score");
+const link = Symbol("traitTest/link");
+const pair = Symbol("traitTest/pair");
+const cache = Symbol("traitTest/cache");
+const badReference = Symbol("traitTest/badReference");
+const selfWithin = Symbol("traitTest/selfWithin");
+const derivedWithin = Symbol("traitTest/derivedWithin");
+const derivedReference = Symbol("traitTest/derivedReference");
+const gpuString = Symbol("traitTest/gpuString");
+const derivedNonPersistent = Symbol("traitTest/derivedNonPersistent");
+const time = Symbol("traitTest/time");
+const derivedResource = Symbol("traitTest/derivedResource");
+const sum = Symbol("traitTest/sum");
+const anyFlag = Symbol("traitTest/anyFlag");
+const named = Symbol("traitTest/named");
+const reducedComponent = Symbol("traitTest/reducedComponent");
+
+declare module '@adobe/ecs' {
+    export interface Components {
+        [parent]: { type: Entity; reference: "owner" };
+        [follows]: { type: Entity; reference: "weak" };
+        [slot]: { type: number; derived: true };
+        [ready]: { type: true; within: typeof slot };
+        [score]: { type: number };
+        [link]: { type: { readonly to: Entity; readonly weight: number } };
+        [pair]: { type: readonly [number, number]; [gpuOnly]: true };
+        [cache]: { type: number; [nonPersistent]: true };
+        [badReference]: { type: number; reference: "owner" };
+        [selfWithin]: { type: true; within: typeof selfWithin };
+        [derivedWithin]: { type: number; derived: true; within: typeof score };
+        [derivedReference]: { type: Entity; derived: true; reference: "owner" };
+        [gpuString]: { type: string; [gpuOnly]: true };
+        [derivedNonPersistent]: { type: number; derived: true; [nonPersistent]: true };
+        [reducedComponent]: { type: number; reduce: "+" };
+    }
+    export interface Resources {
+        [time]: { type: number };
+        [derivedResource]: { type: number; derived: true };
+        [sum]: { type: number; reduce: "+" };
+        [anyFlag]: { type: boolean; reduce: "+" };
+        [named]: { type: string; reduce: "max" };
+    }
+}
+
+// Registration takes exactly the declared traits, `type` as a schema for the declared type.
+Component.register(parent, { type: Entity.schema, reference: "owner" });
+Component.register(follows, { type: Entity.schema, reference: "weak" });
+Component.register(slot, { type: { type: "number", default: 0 }, derived: true });
+Component.register(ready, { type: { const: true }, within: slot });
+Component.register(score, { type: { type: "number" } });
+Component.register(link, { type: { type: "object", properties: { to: Entity.schema, weight: { type: "number" } } } });
+Component.register(pair, { type: { type: "array", items: { type: "number" }, minItems: 2, maxItems: 2 }, [gpuOnly]: true });
+Component.register(cache, { type: { type: "number" }, [nonPersistent]: true });
+Resource.register(time, { type: { type: "number", default: 0 } });
+Resource.register(sum, { type: { type: "number", default: 0 }, reduce: "+" });
+
+// @ts-expect-error a derived component's type has a default, which it starts at
+Component.register(slot, { type: { type: "number" }, derived: true });
+// @ts-expect-error a reference's value is an entity
+Component.register(badReference, { type: { type: "number" }, reference: "owner" });
+// @ts-expect-error a component can't live within itself
+Component.register(selfWithin, { type: { const: true }, within: selfWithin });
+// @ts-expect-error a derived component's rule covers within
+Component.register(derivedWithin, { type: { type: "number", default: 0 }, derived: true, within: score });
+// @ts-expect-error a rule can't set a derived component's target
+Component.register(derivedReference, { type: { ...Entity.schema, default: Entity.none }, derived: true, reference: "owner" });
+// @ts-expect-error gpuOnly takes only linear components
+Component.register(gpuString, { type: { type: "string" }, [gpuOnly]: true });
+// @ts-expect-error nonPersistent is redundant on a derived component
+Component.register(derivedNonPersistent, { type: { type: "number", default: 0 }, derived: true, [nonPersistent]: true });
+// @ts-expect-error a declared trait is missing
+Component.register(parent, { type: Entity.schema });
+// @ts-expect-error an undeclared trait is given
+Component.register(score, { type: { type: "number" }, derived: true });
+// @ts-expect-error a trait's value differs from the declared one
+Component.register(follows, { type: Entity.schema, reference: "owner" });
+// @ts-expect-error an unknown trait
+Component.register(score, { type: { type: "number" }, unknown: true });
+// @ts-expect-error an entity's schema is Entity.schema
+Component.register(parent, { type: { type: "integer" }, reference: "owner" });
+// @ts-expect-error a number's schema isn't Entity.schema
+Component.register(score, { type: Entity.schema });
+// @ts-expect-error an entity field's schema is Entity.schema too
+Component.register(link, { type: { type: "object", properties: { to: { type: "integer" }, weight: { type: "number" } } } });
+// @ts-expect-error a resource's schema has a default
+Resource.register(time, { type: { type: "number" } });
+// @ts-expect-error derived is a component trait
+Resource.register(derivedResource, { type: { type: "number", default: 0 }, derived: true });
+
+// Types filter components by their traits and value types.
+type Ours = typeof parent | typeof follows | typeof slot | typeof ready | typeof score | typeof link | typeof pair | typeof cache;
+check<Equal<Component.Value<typeof parent>, Entity>>();
+check<Equal<Component.Value<typeof link>, { readonly to: Entity; readonly weight: number }>>();
+check<Equal<Extract<Component.With<"reference">, Ours>, typeof parent | typeof follows>>();
+check<Equal<Extract<Component.With<"reference", "owner">, Ours>, typeof parent>>();
+check<Equal<Extract<Derived, Ours>, typeof slot>>();
+check<Equal<Extract<Component.With<typeof gpuOnly>, Ours>, typeof pair>>();
+type Persisted = Exclude<Essential, Component.With<typeof nonPersistent>>;
+check<Equal<Extract<Persisted, Ours>, Exclude<Ours, typeof slot | typeof cache>>>();
+check<Equal<Resource.Value<typeof time>, number>>();
+
+// Commands add and remove only essential components.
+export const issue = (commands: Commands, entity: Entity): void => {
+    commands.add(entity, [score, parent], { [score]: 1, [parent]: entity });
+    commands.remove(entity, score);
+    // @ts-expect-error derived components are added only by rules
+    commands.spawn([slot])({ [slot]: 1 });
+    // @ts-expect-error derived components are added only by rules
+    commands.add(entity, slot, 1);
+    // @ts-expect-error derived components are removed only by rules
+    commands.remove(entity, slot);
+};
+
+// Entities are branded numbers.
+const raw: number = Entity.none;
+// @ts-expect-error a number isn't an entity
+const forged: Entity = 3;
+void raw;
+void forged;
+// @ts-expect-error booleans reduce bitwise
+Resource.register(anyFlag, { type: { type: "boolean", default: false }, reduce: "+" });
+// @ts-expect-error only numbers and booleans, and tuples and structs of them, are reduced
+Resource.register(named, { type: { type: "string", default: "" }, reduce: "max" });
+// @ts-expect-error reduce is a resource trait
+Component.register(reducedComponent, { type: { type: "number" }, reduce: "+" });
+check<Equal<Reduced & typeof sum, typeof sum>>();
+check<Equal<Reduced & typeof time, never>>();

package/src/interface/trait/types.ts

@@ -0,0 +1,56 @@
+import type { Component } from '../component/component.js';
+import type { Components } from '../component/types.js';
+import type { Entity } from '../entity/entity.js';
+import type { IsNode, IsTransferable } from '../platform/platform.js';
+import type { Resource } from '../resource/resource.js';
+import type { Reduction } from '../resource/reduction.js';
+import type { IsString, IsStruct } from '../schema/is-struct.js';
+import type { Thread } from '../thread/thread.js';
+
+/** The value type of the component or resource `N`. */
+type ValueOf<N> = N extends Component.Key ? Component.Value<N> : N extends Resource.Key ? Resource.Value<N> : never;
+
+/**
+ * Whether each component's and resource's value is a struct, `"string"` for a string, computed once so a check is a
+ * lookup. Its keys are remapped (`as K`) so a generic key's lookup stays one: resolved as `IsStruct` of a generic value,
+ * as a registration resolves its contextual type, it recurses without end.
+ */
+type Structs = { readonly [K in Component.Key | Resource.Key as K]: IsString<ValueOf<K>> extends true ? "string" : IsStruct<ValueOf<K>> };
+
+/**
+ * The value each trait allows on the component or resource `N`. Augment it, with this exact type parameter, to
+ * define a trait, and register its name with `Trait.register`. A trait that doesn't apply to `N` resolves to `never`.
+ * An allowed value may look at `N`'s own traits and at the one component a declared value names, never map over
+ * every component, or checking grows with the square of the component count.
+ */
+export interface Traits<N extends Component.Key | Resource.Key> {
+    /** The value type: declared as a TypeScript type, registered as a schema for it when it's data. */
+    readonly type: unknown;
+    /** Present only while a rule deriving it matches, so commands never add or remove it. */
+    readonly derived: N extends Component.Key ? true : never;
+    /** Exists only while its host component does, and is removed with it. Not on a derived component, which its rule covers. */
+    readonly within: N extends Component.Key
+        ? Components[N] extends { readonly derived: true } | { readonly within: N } ? never : Component.Key
+        : never;
+    /**
+     * On an entity-valued component: when its target despawns, `owner` despawns the holder and `weak` removes the
+     * component. Not on a derived component, whose target only a command could set.
+     */
+    readonly reference: N extends Component.Key
+        ? Components[N] extends { readonly derived: true } ? never : [Component.Value<N>] extends [Entity] ? "owner" | "weak" : never
+        : never;
+    /**
+     * On a resource, the operator systems reduce into it with: each run that a contributor runs in starts it at the
+     * operator's identity and leaves it holding the fold of every contribution. Booleans fold bitwise.
+     */
+    readonly reduce: N extends Resource.Key
+        ? [Resource.Value<N>] extends [boolean] ? "&" | "|" | "^" : Structs[N] extends true ? Reduction : never
+        : never;
+    /**
+     * The logical thread an object lives on, `"world"` without it. Not on a struct or a string, which live in shared
+     * memory. A DOM `Node` lives on `"main"`, and says so.
+     */
+    readonly thread: Structs[N] extends true | "string" ? never : IsNode<ValueOf<N>> extends true ? "main" : Thread;
+    /** The value may be moved, never copied, to its thread: only a Transferable value. */
+    readonly transfer: IsTransferable<ValueOf<N>> extends true ? true : never;
+}

package/src/interface/tsconfig.json

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

package/src/interface/world/create.ts

@@ -0,0 +1,15 @@
+import type { Resource } from '../resource/resource.js';
+import type { WorldWritten } from '../resource/written.js';
+import type { World } from './world.js';
+
+/** Values resources start at in place of their defaults: any but those only the world writes. */
+export type InitialResources = { readonly [K in Exclude<Resource.Key, WorldWritten>]?: Resource.Value<K> };
+
+/**
+ * Creates a world on this thread, synchronously, with resources starting at the given values in place of their
+ * defaults. This thread is its `"world"` thread for the world's life: it runs the sync points, the ticks and the GPU
+ * device, and fills every logical thread no joined thread claims. Keys are the resources' symbols, built-in ones
+ * included (`{ [workers]: 0 }`); string keys are never a resource's, so they're ignored. Throws for a symbol that isn't
+ * a resource, or is one only the world writes.
+ */
+export type Create = (resources?: InitialResources) => World;

package/src/interface/world/filter.ts

@@ -0,0 +1,9 @@
+
+export type Comparison<T> = {
+    readonly "=="?: T;
+    readonly "!="?: T;
+    readonly "<"?: T;
+    readonly ">"?: T;
+    readonly "<="?: T;
+    readonly ">="?: T;
+};

package/src/interface/world/index.ts

@@ -0,0 +1,2 @@
+// The `World` namespace's members: none, since a consumer declares nothing more with it.
+export {};

package/src/interface/world/join.ts

@@ -0,0 +1,10 @@
+import type { Thread } from '../thread/thread.js';
+import type { World } from './world.js';
+
+/**
+ * Joins, from another thread, a world that `share` let join through the other end of `port`, claiming the logical
+ * `threads` this thread fills: their objects live here, and the systems and finalizers reading them run here. The world
+ * it returns is the same one: its `run` runs systems there, and its `add` and `remove` take observer systems, which run
+ * here after the world's sync points. Its `dispose` disconnects this thread.
+ */
+export type Join = (port: Parameters<World["share"]>[0], options?: { readonly threads?: readonly Exclude<Thread, "world">[] }) => World;

package/src/interface/world/loop.type-test.ts

@@ -0,0 +1,67 @@
+import {
+    Finalizer, System, always, cadence, clock, gpuDevice, wake, workers,
+    type Component, type Resource, type World,
+} from '../index.js';
+import type { Create } from './create.js';
+import type * as Ecs from '../index.js';
+import { main, move } from '../system/system.type-test.js';
+
+type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends (<T>() => T extends Y ? 1 : 2) ? true : false;
+const check = <_T extends true>() => { };
+
+declare const world: World;
+declare const create: Create;
+
+// Systems added to every tick take no input.
+const added: void = world.add(main);
+// @ts-expect-error a system with input can't be added, since ticks pass none
+world.add(move);
+void added;
+// Removing takes a value passed to add, which takes no input.
+const removed: void = world.remove(main);
+// @ts-expect-error a system with input was never added
+world.remove(move);
+void removed;
+
+// Built-in resources.
+check<Equal<Resource.Value<typeof gpuDevice>, GPUDevice | null>>();
+check<Equal<Resource.Value<typeof workers>, number | null>>();
+// null is the platform's choice of pool size.
+export const platformPool: World = create({ [workers]: null });
+check<Equal<Resource.Value<typeof always>, boolean>>();
+check<Equal<Resource.Value<typeof wake>, number>>();
+check<Equal<Resource.Value<typeof clock>, { readonly now: number; readonly delta: number; readonly tick: number }>>();
+check<Equal<Resource.Value<typeof cadence>, { readonly kind: "frame" } | { readonly kind: "fixed"; readonly step: number; readonly maxSteps?: number }>>();
+// Built-in resources are symbols, so worlds start them at other values through their imported keys.
+check<Equal<[typeof gpuDevice, typeof workers, typeof cadence, typeof always, typeof wake, typeof clock] extends readonly symbol[] ? true : false, true>>();
+// @ts-expect-error a resource key is its imported symbol, never its description
+create({ workers: 2 });
+
+// There are no built-in components: a joined thread's progress is the implementation's.
+type Removed = "component" | "persistent" | "shared" | "threadPort" | "threadStatus" | "threadClaims";
+check<Equal<Extract<Removed, keyof typeof Ecs | Component.Key>, never>>();
+
+// Systems read the loop's state, ask for a wake time and change its cadence.
+System.create({ name: "loopTypeTest/read", resources: { read: [clock] } }, ({ resources }) => {
+    const now: number = resources[clock].now;
+    void now;
+});
+System.create({ name: "loopTypeTest/pace", resources: { write: [cadence, always] } }, ({ resources }) => {
+    resources[cadence] = { kind: "fixed", step: 1000 / 60, maxSteps: 2 };
+    resources[always] = true;
+});
+System.create({ name: "loopTypeTest/sleep", reduce: { [wake]: "min" } }, ({ reduce }) => { reduce[wake](1000); });
+// @ts-expect-error clock is written only by the world
+System.create({ name: "loopTypeTest/clock", resources: { write: [clock] } }, () => {});
+// @ts-expect-error wake is reduced, never written
+System.create({ name: "loopTypeTest/wake", resources: { write: [wake] } }, () => {});
+// @ts-expect-error a finalizer doesn't write clock either
+Finalizer.create({ name: "loopTypeTest/finalizeClock", components: {}, resources: { write: [clock] } }, () => {});
+// @ts-expect-error a cadence is a frame or a fixed step
+System.create({ name: "loopTypeTest/badCadence", resources: { write: [cadence] } }, ({ resources }) => { resources[cadence] = { kind: "fixed" }; });
+
+// Worlds start the loop's settings at other values; clock is the world's own.
+const paced: World = create({ [cadence]: { kind: "fixed", step: 10 }, [always]: true, [workers]: 2 });
+// @ts-expect-error clock is written only by the world
+create({ [clock]: { now: 0, delta: 0, tick: 0 } });
+void paced;

package/src/interface/world/share.type-test.ts

@@ -0,0 +1,25 @@
+import type { World } from './world.js';
+
+declare const world: World;
+declare const channel: MessageChannel;
+declare const worker: Worker;
+
+// Sharing lets another thread join through a port: a MessagePort, a Worker or a worker's own scope.
+const shared: void = world.share(channel.port1);
+world.share(worker);
+world.share(self);
+// A port is share's parameter, inferred where a consumer names it.
+const port: Parameters<World["share"]>[0] = channel.port2;
+// @ts-expect-error a port posts messages to another thread
+world.share({});
+// @ts-expect-error a thread is shared through one port
+world.share();
+
+// The package root's World.join joins; World names no type for it, its options or its port.
+// @ts-expect-error no World.Join
+export type Joining = World.Join;
+// @ts-expect-error no World.JoinOptions
+export type Options = World.JoinOptions;
+// @ts-expect-error no World.Port
+export type Ported = World.Port;
+void [shared, port];

package/src/interface/world/world.ts

@@ -0,0 +1,58 @@
+import type { Input } from '../system/input.js';
+import type { System } from '../system/system.js';
+
+/**
+ * A world. Systems read and change it; observer systems read it after each run's and tick's sync point. Every member's
+ * type is named from the package root, so declarations a consumer emits for its results name no internal module.
+ */
+export type World = {
+    /**
+     * The one way to change state. Runs are sequential in call order; physically, any that don't conflict overlap. Each
+     * runs a system or composite, ending in a sync point, and resolves to its number: every run and tick takes the
+     * next, in the order they run. What went wrong, if anything, is a report the world spawns for that number (see
+     * `Report`): systems, finalizers and GPU work that failed, systems skipped after a failed tier, commands that did
+     * nothing, and warnings. Rejects only when the run can't happen or finish: registration fails, the world is
+     * disposed, its GPU device is lost, or its sync point can't apply a command's value. Observer systems, the run's and
+     * those added, run after its sync point and its report, before it resolves; their throws are `"system"` failures
+     * in the next run's report, since each report's errors are written once. A run of observer systems alone runs them
+     * once after an empty sync point, and doesn't wake the loop.
+     */
+    run<I>(system: System<I>, ...input: Input<NoInfer<I>>): Promise<number>;
+    /**
+     * Adds a system to every tick, from the next one on, ordered with those already added by its constraints, as a
+     * composite's members are. A tick runs on a beat of the `cadence` resource where `always` is set, `wake` is due or
+     * a run arrived since the last tick, and only while some system is added. Throws for a system with no ordering path
+     * to one already added that conflicts with it; failures are in the tick's report. An observer system runs after
+     * every run's and tick's sync point instead. It never conflicts and doesn't count as an added system for ticking.
+     * On a joined thread `add` takes only observer systems, whose keys need ids: each runs on that thread after the
+     * world's sync points, once for the newest when the thread fell behind, reading structs and the objects of the
+     * threads it fills as of one sync point; its failures are in a later run's report.
+     */
+    add(system: System<void>): void;
+    /**
+     * Takes a value passed to `add`. Once it returns, that system's body is never called again, and its memory is
+     * released. A system added both alone and within an added composite stays until both are removed; constraints
+     * naming a removed system are ignored. Removing a value that isn't added does nothing. Throws, removing nothing,
+     * when the systems left would conflict with no ordering path between them, as `add` does. On a joined thread it
+     * takes only observer systems.
+     */
+    remove(system: System<void>): void;
+    /**
+     * Lets another thread join this world through `port`, one end of a channel to it, of the browser or node: a
+     * `MessagePort`, a `Worker`, or a worker's own scope, `self` or node's `parentPort`. That thread joins through the
+     * other end, claiming the logical threads it fills; a thread claimed twice can't join. Throws on a joined thread,
+     * and where memory can't be shared, as without cross-origin isolation.
+     */
+    share(port: { readonly postMessage: (message: never, transfer: never) => void } & (
+        | { readonly addEventListener: (type: "message", listener: (event: unknown) => void) => void }
+        | { readonly on: (event: "message", listener: (value: unknown) => void) => unknown }
+    )): void;
+    /**
+     * Waits for pending runs, then stops ticking and releases memory, and joined threads' runs reject; the world is
+     * unusable afterwards. On a joined thread, it disconnects this thread.
+     */
+    dispose(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+};
+
+export type * as World from './index.js';

package/src/interface/world/world.type-test.ts

@@ -0,0 +1,81 @@
+import { Component } from '../component/component.js';
+import type { Entity } from '../entity/entity.js';
+import { System } from '../system/system.js';
+import { main, move, position, time, total, watchTime } from '../system/system.type-test.js';
+import type { Create } from './create.js';
+import type { World } from './world.js';
+
+type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends (<T>() => T extends Y ? 1 : 2) ? true : false;
+const check = <_T extends true>() => { };
+
+declare const world: World;
+declare const entity: Entity;
+declare const create: Create;
+
+const point = Symbol("worldTypeTest/point");
+const persistent = Symbol("worldTypeTest/persistent");
+const shared = Symbol("worldTypeTest/shared");
+declare module '@adobe/ecs' {
+    export interface Components {
+        [point]: { type: { readonly x: number } };
+        [persistent]: { type: true };
+        [shared]: { type: true };
+    }
+}
+Component.register(point, { type: { type: "object", properties: { x: { type: "number" } } } });
+Component.register(persistent, { type: { const: true } });
+Component.register(shared, { type: { const: true } });
+// Reading goes through observer systems: a world has no observers, and no synchronous reads.
+// @ts-expect-error no observe: observer systems read a world
+void world.observe;
+// @ts-expect-error no synchronous reads
+void world.query;
+// @ts-expect-error no synchronous reads
+void world.read;
+// @ts-expect-error GPU writes are read back for observer systems, without synchronize
+void world.synchronize;
+// @ts-expect-error no World.Query: observer systems declare what they read
+export type NoQuery = World.Query<[typeof persistent]>;
+
+// A run resolves to its number; what went wrong is in its report (`Report`).
+const ran: Promise<number> = world.run(main);
+const moved: Promise<number> = world.run(move, { distance: 1 });
+// @ts-expect-error a system with input needs it
+world.run(move);
+// @ts-expect-error input must match its schema
+world.run(move, { distance: "far" });
+// @ts-expect-error a system without input takes none
+world.run(main, {});
+
+const created: World = create();
+const withResources: World = create({ [time]: 1, [total]: 0 });
+// @ts-expect-error a resource's initial value has its type
+create({ [time]: "now" });
+// @ts-expect-error resources takes only resource keys
+create({ [position]: 0 });
+// @ts-expect-error a key is its symbol, never its description
+create({ "systemTest/time": 1 });
+// @ts-expect-error systems register on their first run
+void world.systems;
+const disposed: Promise<void> = world.dispose();
+const usingDispose = async () => {
+    await using scoped = create();
+    await scoped.run(main);
+};
+void [disposed, usingDispose, ran, moved, created, withResources];
+
+// How a world is created is the implementation's: World names no Create or InitialResources.
+check<Equal<ReturnType<Create>, World>>();
+// @ts-expect-error no World.Create
+export type Created = World.Create;
+// @ts-expect-error no World.InitialResources: Parameters<typeof createWorld>[0]
+export type Initial = World.InitialResources;
+// @ts-expect-error no World.Failure: Report.Failure
+export type Failed = World.Failure;
+// @ts-expect-error no World.Warning: Report.Warning
+export type Warned = World.Warning;
+
+// An observer system is added to every run and tick, or run once after an empty sync point.
+const addedObserver: void = world.add(watchTime);
+const ranObserver: Promise<number> = world.run(watchTime);
+void [addedObserver, ranObserver];

package/src/observe/compare.ts

@@ -0,0 +1,86 @@
+// Comparing and testing component values for queries: equality, order, and `where` conditions compiled once.
+
+/** Whether two values are equal: primitives by identity, objects and arrays by their own keys, recursively. */
+export const equals = (a: unknown, b: unknown): boolean => {
+    if (a === b) return true;
+    if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+    const keys = Reflect.ownKeys(a);
+    if (keys.length !== Reflect.ownKeys(b).length) return false;
+    for (let i = 0; i < keys.length; i++) if (!equals(Reflect.get(a, keys[i]), Reflect.get(b, keys[i]))) return false;
+    return true;
+};
+
+/** Code points of two strings compared, never by locale, as sorted indexes order them. */
+const compareStrings = (a: string, b: string): number => {
+    const length = Math.min(a.length, b.length);
+    for (let k = 0; k < length; k++) {
+        const x = a.charCodeAt(k);
+        const y = b.charCodeAt(k);
+        if (x === y) continue;
+        // A surrogate encodes a code point above every unit that isn't one.
+        const xs = x >= 0xD800 && x <= 0xDFFF;
+        const ys = y >= 0xD800 && y <= 0xDFFF;
+        if (xs !== ys) return xs ? 1 : -1;
+        return x < y ? -1 : 1;
+    }
+    return a.length - b.length;
+};
+
+/**
+ * Orders values as sorted indexes do: numbers numerically with NaN after every number, booleans false first, strings
+ * by code point, tuples element by element; anything else is equal.
+ */
+export const compare = (a: unknown, b: unknown): number => {
+    if (typeof a === "number" && typeof b === "number") return compareNumbers(a, b);
+    if (Array.isArray(a) && Array.isArray(b)) {
+        const length = Math.min(a.length, b.length);
+        for (let i = 0; i < length; i++) {
+            const order = compare(a[i], b[i]);
+            if (order !== 0) return order;
+        }
+        return a.length - b.length;
+    }
+    if (typeof a === "boolean" && typeof b === "boolean") return a === b ? 0 : a ? 1 : -1;
+    if (typeof a === "string" && typeof b === "string") return compareStrings(a, b);
+    return 0;
+};
+
+/** Numbers in order, NaN after every other, -0 equal to 0. */
+export const compareNumbers = (a: number, b: number): number => {
+    if (a < b) return -1;
+    if (a > b) return 1;
+    if (a === b) return 0;
+    const nanA = a !== a;
+    return nanA === (b !== b) ? 0 : nanA ? 1 : -1;
+};
+
+const operators = new Set(["==", "!=", "<", ">", "<=", ">="]);
+
+/** A `where` condition compiled once: a plain value is equality, an object of comparison operators is a comparison. */
+export const predicateOf = (condition: unknown): ((value: unknown) => boolean) => {
+    if (typeof condition !== "object" || condition === null || Array.isArray(condition)) {
+        if (typeof condition === "number" || typeof condition === "string" || typeof condition === "boolean") return value => value === condition;
+        return value => equals(value, condition);
+    }
+    const entries = Object.entries(condition);
+    if (entries.length === 0 || !entries.every(([operator]) => operators.has(operator))) return value => equals(value, condition);
+    const tests = entries.map(([operator, operand]): ((value: unknown) => boolean) => {
+        switch (operator) {
+            case "==": return value => equals(value, operand);
+            case "!=": return value => !equals(value, operand);
+            case "<": return typeof operand === "number" ? value => typeof value === "number" ? value < operand : compare(value, operand) < 0 : value => compare(value, operand) < 0;
+            case ">": return typeof operand === "number" ? value => typeof value === "number" ? value > operand : compare(value, operand) > 0 : value => compare(value, operand) > 0;
+            case "<=": return typeof operand === "number" ? value => typeof value === "number" ? value <= operand : compare(value, operand) <= 0 : value => compare(value, operand) <= 0;
+            default: return typeof operand === "number" ? value => typeof value === "number" ? value >= operand : compare(value, operand) >= 0 : value => compare(value, operand) >= 0;
+        }
+    });
+    if (tests.length === 1) return tests[0];
+    if (tests.length === 2) {
+        const [first, second] = tests;
+        return value => first(value) && second(value);
+    }
+    return value => {
+        for (let i = 0; i < tests.length; i++) if (!tests[i](value)) return false;
+        return true;
+    };
+};