@adobe/ecs 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,261 @@
+import { Component } from "../../interface/component/component.js";
+import { Entity } from "../../interface/entity/entity.js";
+import { Resource } from "../../interface/resource/resource.js";
+import type { Schema } from "../../interface/schema/schema.js";
+import { System } from "../../interface/system/system.js";
+import type { World } from "../../interface/world/world.js";
+import { read, readEach, readResource, select } from "./reads.test-helper.js";
+import { createWorld } from "./create.js";
+import { workers } from "../../interface/resources/workers.js";
+import { countingWorkers } from "./platforms.test-helper.js";
+import type { WorkerPlatform } from "./worker-platform.js";
+
+/** Scenarios of kernels on workers against the main thread alone, run built in node and from source in chromium. */
+
+type Vec2 = readonly [number, number];
+const vec2 = { type: "array", items: { type: "number", precision: 1 }, minItems: 2, maxItems: 2 } as const satisfies Schema;
+
+const position = Symbol("workersTest/position");
+const velocity = Symbol("workersTest/velocity");
+const target = Symbol("workersTest/target");
+const offset = Symbol("workersTest/offset");
+const spawned = Symbol("workersTest/spawned");
+const tagA = Symbol("workersTest/tag-a");
+const tagB = Symbol("workersTest/tag-b");
+const tagC = Symbol("workersTest/tag-c");
+const tagD = Symbol("workersTest/tag-d");
+const tagE = Symbol("workersTest/tag-e");
+const tagF = Symbol("workersTest/tag-f");
+const tagG = Symbol("workersTest/tag-g");
+const tagH = Symbol("workersTest/tag-h");
+const tagI = Symbol("workersTest/tag-i");
+const tags = [tagA, tagB, tagC, tagD, tagE, tagF, tagG, tagH, tagI] as const;
+const seconds = Symbol("workersTest/seconds");
+
+declare module "@adobe/ecs" {
+    export interface Components {
+        [position]: { type: readonly [number, number] };
+        [velocity]: { type: readonly [number, number] };
+        [target]: { type: Entity };
+        [offset]: { type: number };
+        [spawned]: { type: true };
+        [tagA]: { type: true };
+        [tagB]: { type: true };
+        [tagC]: { type: true };
+        [tagD]: { type: true };
+        [tagE]: { type: true };
+        [tagF]: { type: true };
+        [tagG]: { type: true };
+        [tagH]: { type: true };
+        [tagI]: { type: true };
+    }
+    export interface Resources {
+        [seconds]: { type: number };
+    }
+}
+
+Component.register(position, { type: vec2 });
+Component.register(velocity, { type: vec2 });
+Component.register(target, { type: Entity.schema });
+Component.register(offset, { type: { type: "number", precision: 1 } });
+Component.register(spawned, { type: { const: true } });
+Component.register(tagA, { type: { const: true } });
+Component.register(tagB, { type: { const: true } });
+Component.register(tagC, { type: { const: true } });
+Component.register(tagD, { type: { const: true } });
+Component.register(tagE, { type: { const: true } });
+Component.register(tagF, { type: { const: true } });
+Component.register(tagG, { type: { const: true } });
+Component.register(tagH, { type: { const: true } });
+Component.register(tagI, { type: { const: true } });
+
+/** 64 entities in each of the 512 archetypes the tags combine into. */
+const scatter = System.create({ name: "workersTest/scatter" }, ({ commands }) => {
+    for (let i = 0; i < 512 * 64; i++) {
+        const components: (typeof position | typeof velocity | (typeof tags)[number])[] = [position, velocity];
+        tags.forEach((tag, bit) => { if (((i >> 6) & (1 << bit)) !== 0) components.push(tag); });
+        commands.spawn(components)({ [position]: [i, 0], [velocity]: [1, i % 5] });
+    }
+});
+Resource.register(seconds, { type: { type: "number", default: 0.25 } });
+
+/** Spawns `count` moving entities, each following the one before it. */
+const seed = System.create({ name: "workersTest/seed", input: { type: "object", properties: { count: { type: "integer" } } } }, ({ input, commands }) => {
+    let previous = commands.spawn([position, velocity])({ [position]: [0, 0], [velocity]: [1, 0] });
+    for (let i = 1; i < input.count; i++) {
+        previous = commands.spawn([position, velocity, target])({ [position]: [i, 0], [velocity]: [1, i % 7], [target]: previous });
+    }
+});
+
+const integrate = System.create({
+    name: "workersTest/integrate",
+    kernel: "cpu",
+    components: { read: [velocity], write: [position] },
+    resources: { read: [seconds] },
+}, (row, { resources }) => {
+    const [x, y] = row[position];
+    const [vx, vy] = row[velocity];
+    row[position] = [x + vx * resources[seconds], y + vy * resources[seconds]];
+});
+
+/** Structural commands from workers: rows past a threshold spawn a marker and lose their velocity. */
+const split = System.create({
+    name: "workersTest/split",
+    kernel: "cpu",
+    components: { read: [position], has: [velocity] },
+    after: [integrate],
+}, (row, { commands }) => {
+    const [x, y] = row[position];
+    if (y > 3) {
+        commands.spawn([position, spawned])({ [position]: [x, -y], [spawned]: true });
+        commands.remove(row.entity, velocity);
+    }
+});
+
+/** Lookups from workers: offset by the distance to the target. */
+const follow = System.create({
+    name: "workersTest/follow",
+    kernel: "cpu",
+    components: { read: [position, target], write: [offset] },
+    lookup: { targets: { read: [position] } },
+    after: [split],
+}, (row, { lookup: { targets } }) => {
+    const other = targets(row[target]);
+    const [x] = row[position];
+    row[offset] = other === null ? -1 : x - other[position][0];
+}, );
+
+const main = System.create({ name: "workersTest/main", systems: [integrate, split, follow] });
+
+/** Every row writes the same entity, so only merge order decides which value survives. */
+const stamp = System.create({
+    name: "workersTest/stamp",
+    kernel: "cpu",
+    input: { type: "object", properties: { entity: Entity.schema } },
+    components: { read: [position] },
+}, (row, { input, commands }) => {
+    const [x, y] = row[position];
+    commands.add(input.entity, offset, x * 1000 + y);
+});
+
+/** Despawns entity 1, the resource entity, since index 0 is never an entity and registration reserves the next first. */
+const unlink = System.create({
+    name: "workersTest/unlink",
+    kernel: "cpu",
+    components: { has: [target] },
+}, (_, { commands }) => {
+    // @ts-expect-error an untyped caller can pass any number
+    commands.despawn(1);
+});
+
+/** Archetypes in this order: 5 rows the main thread runs, 1,000 that workers run, then 10 more on the main thread. */
+const sources = System.create({ name: "workersTest/sources" }, ({ commands }) => {
+    for (let i = 0; i < 5; i++) commands.spawn([offset, tagD])({ [offset]: i });
+    for (let i = 5; i < 1_005; i++) commands.spawn([offset, tagA])({ [offset]: i });
+    for (let i = 1_005; i < 1_015; i++) commands.spawn([offset, tagB])({ [offset]: i });
+});
+
+/** A spawn per row, from wherever its chunk runs; with `edit`, each spawn is also added to and removed from. */
+const emit = System.create({
+    name: "workersTest/emit",
+    kernel: "cpu",
+    input: { type: "object", properties: { edit: { type: "boolean" } } },
+    components: { read: [offset], not: [spawned] },
+}, (row, { input, commands }) => {
+    const entity = commands.spawn([position, spawned, tagC])({ [position]: [row[offset], -row[offset]] });
+    if (input.edit) {
+        commands.add(entity, velocity, [row[offset], 1]);
+        commands.remove(entity, tagC);
+    }
+});
+
+const emitted = { seen: 0 };
+const countEmitted = System.create({ name: "workersTest/countEmitted", components: { added: [position], has: [spawned] } }, () => { emitted.seen++; });
+
+const gathered: Entity[] = [];
+const gatherPositioned = System.create({ name: "workersTest/gatherPositioned", observer: true, components: { has: [position] } }, row => { gathered.push(row.entity); });
+const gatherSpawned = System.create({ name: "workersTest/gatherSpawned", observer: true, components: { has: [spawned] } }, row => { gathered.push(row.entity); });
+
+/** The entities an observer row system passes, in storage order. */
+const storageOrder = async (world: World, gather: System<void>): Promise<Entity[]> => {
+    gathered.length = 0;
+    await world.run(gather);
+    return [...gathered];
+};
+
+/** Runs `use` with a world, then disposes it. */
+const using = async <T>(world: World, use: (world: World) => Promise<T>): Promise<T> => {
+    try {
+        return await use(world);
+    }
+    finally {
+        await world.dispose();
+    }
+};
+
+/** Every entity's values, in a canonical order, since entity ids depend on reservation interleaving. */
+const snapshot = async (world: World): Promise<string[]> => {
+    const rows = await Promise.all((await select(world, { required: [position] })).map(entity => Promise.all([
+        read(world, entity, position),
+        read(world, entity, velocity),
+        read(world, entity, offset),
+        read(world, entity, spawned),
+    ])));
+    return rows.map(row => JSON.stringify(row)).sort();
+};
+
+/** 2,000 following entities run through `main` for 12 frames, on the platform's workers or these, and the run tasks posted to workers. */
+export const simulate = async (count: number, wasm = true, simd = false, platform?: WorkerPlatform): Promise<{ readonly rows: readonly string[]; readonly tasks: number }> => {
+    const counting = countingWorkers(platform);
+    return using(createWorld({ [workers]: count }, { minimumChunk: 64, wasm, simd, pool: counting.platform }), async world => {
+        await world.run(seed, { count: 2000 });
+        for (let frame = 0; frame < 12; frame++) await world.run(main);
+        return { rows: await snapshot(world), tasks: counting.posted("run") };
+    });
+};
+
+/** `integrate` over 512 archetypes, three frames. */
+export const scattered = (count: number): Promise<readonly string[]> => using(createWorld({ [workers]: count }, { minimumChunk: 64 }), async world => {
+    await world.run(scatter);
+    for (let frame = 0; frame < 3; frame++) await world.run(integrate);
+    return snapshot(world);
+});
+
+/** What survives every row's command to one entity, and every position. */
+export const ordered = (count: number): Promise<readonly unknown[]> => using(createWorld({ [workers]: count }, { minimumChunk: 64 }), async world => {
+    await world.run(seed, { count: 2000 });
+    for (let frame = 0; frame < 4; frame++) await world.run(main);
+    const [first] = await storageOrder(world, gatherPositioned);
+    await world.run(stamp, { entity: first });
+    return [await read(world, first, offset), await readEach(world, await storageOrder(world, gatherPositioned), position)];
+});
+
+/** Kernel spawns from 1,015 rows over three archetypes: how many an `added` system saw, and the spawns' values. */
+export const spawns = (count: number, edit: boolean): Promise<readonly unknown[]> => using(createWorld({ [workers]: count }, { minimumChunk: 64 }), async world => {
+    await world.run(sources);
+    await world.run(emit, { edit });
+    emitted.seen = 0;
+    await world.run(countEmitted);
+    await world.run(countEmitted);
+    const entities = await storageOrder(world, gatherSpawned);
+    return [emitted.seen, await readEach(world, entities, position), await readEach(world, entities, velocity), await readEach(world, entities, tagC)];
+});
+
+/** The resource after a worker kernel despawned the resource entity. */
+export const unlinked = (): Promise<number> => using(createWorld({ [workers]: 2 }, { minimumChunk: 64 }), async world => {
+    await world.run(seed, { count: 500 });
+    await world.run(unlink);
+    await world.run(integrate);
+    return readResource(world, seconds);
+});
+
+/** Workers ended by `dispose`, and what a run after it rejects with. */
+export const disposed = async (): Promise<{ readonly started: number; readonly terminated: number; readonly after: string }> => {
+    const counting = countingWorkers();
+    const world = createWorld({ [workers]: 2 }, { pool: counting.platform });
+    // Workers start with the first kernel.
+    await world.run(main);
+    await world.dispose();
+    const after = await world.run(main).then(() => "resolved", (error: unknown) => String(error));
+    return { started: counting.started(), terminated: counting.terminated(), after };
+};

package/src/implementation/world/world-host.fixture.ts

@@ -0,0 +1,10 @@
+import { scopeChannel } from "./port.js";
+import { lentWorkers } from "./worker-platform.js";
+import { simulate } from "./workers.fixture.js";
+import type { FromHost, ToHost } from "./ports.fixture.js";
+
+/** A worker holding a world: runs `simulate(3)` with nested workers or ones its parent lent, and posts the result. */
+const channel = scopeChannel<FromHost, ToHost>();
+channel.onMessage(async message => {
+    channel.post(await simulate(3, true, false, message.kind === "lent" ? lentWorkers(message.lent) : undefined));
+});

package/src/index.ts

@@ -0,0 +1,16 @@
+import { create, join } from './implementation/index.js';
+import type { Create } from './interface/world/create.js';
+import type { Join } from './interface/world/join.js';
+import type { World as Created } from './interface/world/world.js';
+
+export * from './interface/index.js';
+
+/** A world: what systems read and change. */
+export type World = Created;
+
+/**
+ * How a world is made, `World.create(resources?)`, on the thread that will run it, with resources starting at the given
+ * values in place of their defaults; and how another thread joins one that shared itself with it,
+ * `World.join(port, { threads })`.
+ */
+export const World: { readonly create: Create; readonly join: Join } = { create, join };

package/src/interface/CLAUDE.md

@@ -0,0 +1,33 @@
+# The interface
+
+This folder is the public contract, and only the minimal one: what a consumer must name or call to use the ECS
+correctly. Everything that can be hidden is an implementation detail and stays in `src/implementation`. Each hidden
+part is one the implementation can change freely later.
+
+## Export a type only for consumers to declare with
+
+Name and export a type only when a consumer would use it to declare something in their own code. Every exported name
+is more for a reader to learn. A type that only describes a parameter, a result or part of one stays unexported, often
+inline. A consumer who wants it can infer it, for example `Parameters<World["share"]>[0]`.
+
+## Humans own the interface
+
+Humans own and review this folder; agents own the implementation. An agent doesn't add to or widen the contract on its
+own. That includes:
+
+- exported types, values and functions;
+- fields, options, parameters and return types;
+- union members, failure kinds and report fields;
+- built-in components and resources;
+- the documented behaviour of an existing call.
+
+When work seems to need a change here, first find a way to keep it out:
+
+- Infer the type the implementation needs (`Parameters<…>`, `ReturnType<…>`, indexed access) instead of exporting a
+  name for it.
+- Keep protocol state, progress and bookkeeping in the implementation's own storage, not in components or resources
+  consumers can see.
+- Give a value a narrower public type than its runtime shape.
+
+If it truly can't be hidden, don't make the change. Propose it in your report, with the smallest form that would work
+and why nothing smaller does, and leave it for human review.

package/src/interface/archetype/archetype.ts

@@ -0,0 +1,3 @@
+export type Archetype = never;
+
+export * as Archetype from './index.js';

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

@@ -0,0 +1,37 @@
+import { Resource } from '../resource/resource.js';
+import { Component } from '../component/component.js';
+import { Archetype, System } from "@adobe/ecs";
+
+const position = Symbol("archetypeTypeTest/position");
+const velocity = Symbol("archetypeTypeTest/velocity");
+const scale = Symbol("archetypeTypeTest/scale");
+declare module "@adobe/ecs" {
+    interface Components {
+        [position]: { type: number };
+        [velocity]: { type: number };
+    }
+    interface Resources {
+        [scale]: { type: number };
+    }
+}
+Component.register(position, { type: { type: "number" } });
+Component.register(velocity, { type: { type: "number" } });
+Resource.register(scale, { type: { type: "number", default: 0 } });
+
+type Equal<A, B> = (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? true : false;
+const expectType = <T extends true>(): T | undefined => undefined;
+
+// `create` returns its argument, typed as the tuple it was given.
+export const particle = Archetype.create([position, velocity]);
+expectType<Equal<typeof particle, readonly [typeof position, typeof velocity]>>();
+export const one: readonly Component.Key[] = particle;
+// A plain readonly list of components is an archetype too.
+export const plain = [position] as const;
+export const moveOver = System.create({ name: "archetypeTypeTest/moveOver", components: { write: plain } }, row => { row[position] += 1; });
+// @ts-expect-error a resource is never in an archetype
+Archetype.create([position, scale]);
+// @ts-expect-error nor is a string
+Archetype.create(["position"]);
+// Archetypes go wherever component lists do.
+export const move = System.create({ name: "archetypeTypeTest/move", components: { write: particle } }, row => { row[position] += row[velocity]; });
+export const read = System.create({ name: "archetypeTypeTest/read", observer: true, components: { read: particle } }, row => { void row[velocity]; });

package/src/interface/archetype/create.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import { Component } from "../component/component.js";
+import { archetypeIndexOf } from "../registry/index.js";
+import { Archetype } from "./archetype.js";
+
+const position = Symbol("archetypeCreateTest/position");
+const velocity = Symbol("archetypeCreateTest/velocity");
+declare module "@adobe/ecs" {
+    interface Components {
+        [position]: { type: number };
+        [velocity]: { type: number };
+    }
+}
+Component.register(position, { type: { type: "number" } });
+Component.register(velocity, { type: { type: "number" } });
+
+describe("Archetype.create", () => {
+    it("returns its argument, with a program-wide index of its own", () => {
+        const list = [position, velocity] as const;
+        const particle = Archetype.create(list);
+        const other = Archetype.create([velocity]);
+        expect(particle).toBe(list);
+        expect(particle).toEqual([position, velocity]);
+        expect(archetypeIndexOf(particle)).toBeGreaterThanOrEqual(0);
+        expect(archetypeIndexOf(other)).toBeGreaterThan(archetypeIndexOf(particle));
+        expect(Object.keys(particle)).toEqual(["0", "1"]);
+    });
+    it("keeps the index of a list given again", () => {
+        const particle = Archetype.create([position]);
+        const index = archetypeIndexOf(particle);
+        expect(Archetype.create(particle)).toBe(particle);
+        expect(archetypeIndexOf(particle)).toBe(index);
+    });
+    it("gives a plain list no index", () => {
+        expect(archetypeIndexOf([position])).toBe(-1);
+    });
+    it("throws for a component listed twice", () => {
+        expect(() => Archetype.create([position, velocity, position])).toThrow(`An archetype lists "archetypeCreateTest/position" twice.`);
+    });
+});

package/src/interface/archetype/create.ts

@@ -0,0 +1,12 @@
+import type { Component } from '../component/component.js';
+import { indexArchetype } from '../registry/archetypes.js';
+
+/**
+ * Declares an archetype, the components an entity has, listed once each: returns `components`, typed as the tuple
+ * given, with a program-wide index the world finds its storage by. It goes wherever a list of components does, as any
+ * readonly list of components does. Throws for a component listed twice.
+ */
+export const create = <const C extends readonly Component.Key[]>(components: C): C => {
+    indexArchetype(components);
+    return components;
+};

package/src/interface/archetype/index.ts

@@ -0,0 +1 @@
+export * from './create.js';

package/src/interface/archetype/values-of.ts

@@ -0,0 +1,16 @@
+import type { Component } from '../component/component.js';
+
+/** Components a spawn or add may leave out: a tag, whose value is `true`, and one whose type allows `null`, its start. */
+type Omissible<K extends Component.Key> = Component.Value<K> extends true ? K : null extends Component.Value<K> ? K : never;
+
+/**
+ * The values a spawn or add of the components `C` takes, keyed by component and exact against `C`: a tag needs no
+ * value, a component whose type allows `null` may be left out to start at `null`, and every other one is required.
+ * Leaving one out, or giving `undefined`, never leaves the component out. A list that isn't a tuple takes any of its
+ * components' values.
+ */
+export type ValuesOf<C extends readonly Component.Key[]> = number extends C["length"]
+    // A list whose components aren't known until it runs, so any of them may be given.
+    ? { readonly [K in C[number]]?: Component.Value<K> }
+    : { readonly [K in C[number] as K extends Omissible<K> ? never : K]: Component.Value<K> }
+        & { readonly [K in C[number] as K extends Omissible<K> ? K : never]?: Component.Value<K> };

package/src/interface/component/component.ts

@@ -0,0 +1,4 @@
+
+export type Component = never;
+
+export * as Component from './index.js';

package/src/interface/component/declaration.ts

@@ -0,0 +1,67 @@
+import type { IsData } from "../schema/is-data.js";
+import type { Schema } from "../schema/schema.js";
+import type { Key as TraitKey } from "../trait/key.js";
+import type { Required } from "../trait/required.js";
+import type { Traits } from "../trait/types.js";
+import type { SymbolKeys } from "../trait/symbol-keys.js";
+import type { Key } from "./key.js";
+import type { Components } from "./types.js";
+
+/** A value starts at `default`, which a type that allows `null` may leave out: it's `null` then. */
+export type Starting<T> = null extends T ? { readonly default?: T } : { readonly default: T };
+
+type Same<A, B> = (<X>() => X extends A ? 1 : 2) extends (<X>() => X extends B ? 1 : 2) ? true : false;
+
+/** How deep `Flattened` goes: deeper values are compared as they are, so recursive types stay finite. */
+type Depth = [never, 0, 1, 2, 3, 4, 5, 6, 7];
+
+/** `T` with every object, at any depth up to eight, as one object type, so `A & B` compares equal to the object it is. */
+type Flattened<T, D extends number = 8> =
+    [D] extends [never] ? T :
+    T extends string | number | boolean | bigint | symbol | null | undefined | ((...parameters: never[]) => unknown) ? T :
+    T extends ReadonlyMap<infer K, infer V> ? (T extends Map<K, V> ? T : ReadonlyMap<Flattened<K, Depth[D]>, Flattened<V, Depth[D]>>) :
+    T extends ReadonlySet<infer E> ? (T extends Set<E> ? T : ReadonlySet<Flattened<E, Depth[D]>>) :
+    { [K in keyof T]: Flattened<T[K], Depth[D]> };
+
+/** Whether `A` and `B` are the same type, flattened only when they aren't identical. */
+type Equivalent<A, B> = Same<A, B> extends true ? true : Same<Flattened<A>, Flattened<B>>;
+
+/**
+ * Nothing when schema `S` describes exactly the declared type `T` and its `default`, if any, is a `T`; else a required
+ * property naming the problem, so registration fails to compile and says why. A check rather than `type`'s own type,
+ * so `type` is inferred from the schema alone.
+ */
+export type Describing<S, T> =
+    ((S extends Schema ? Equivalent<Schema.ToType<S>, T> : false) extends true ? {} : { readonly "the schema describes another type than the declared one": T })
+    & (S extends { readonly default: infer V } ? ([V] extends [T] ? {} : { readonly "the schema's default isn't of the declared type": T }) : {});
+
+/** A derived component starts at its schema's `default`, at its `const`, or at `null` when its type allows it. */
+type DerivedStart<S, T> =
+    S extends { readonly const: unknown } | { readonly default: unknown } ? {} :
+    null extends T ? {} :
+    { readonly "a derived component's schema has a default, which it starts at": T };
+
+/**
+ * The value type's part of a declaration: `type`, schema `S`, describing exactly the declared type `T` when it's data.
+ * A type that isn't data has no `type`, and a derived one starts at the declaration's `default`.
+ */
+type TypePart<S, T, Derived> =
+    IsData<T> extends true
+        ? [S] extends [never] ? { readonly type: Schema } : Describing<S, T> & { readonly default?: never } & (Derived extends true ? DerivedStart<S, T> : {})
+        : { readonly type?: never } & (Derived extends true ? Starting<T> : { readonly default?: never });
+
+/**
+ * What `register(K, ...)` takes: exactly the traits `Components[K]` declares, `type` as schema `S` for the declared
+ * type. A trait whose declared value its definition doesn't allow on `K`, or one a value of its type must declare and
+ * doesn't, becomes `never`, so registration fails to compile, as every registration does while a component, resource
+ * or trait is keyed by a string (`SymbolKeys`).
+ */
+export type Declaration<K extends Key, S> =
+    { readonly type?: S }
+    & TypePart<S, Components[K]["type"], Components[K] extends { readonly derived: true } ? true : false>
+    & { readonly [T in Exclude<keyof Components[K], "type">]:
+        T extends TraitKey ? (Components[K][T] extends Traits<K>[T] ? Components[K][T] : never) :
+        never }
+    & { readonly [T in Exclude<TraitKey, keyof Components[K]>]?: never }
+    & Required<Components[K], Components[K]["type"]>
+    & SymbolKeys;

package/src/interface/component/declaration.type-test.ts

@@ -0,0 +1,87 @@
+import { Entity } from '../entity/entity.js';
+import { Vec3 } from '../math/index.js';
+import { Component } from './component.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>() => { };
+
+const position = Symbol("declarationTypeTest/position");
+const score = Symbol("declarationTypeTest/score");
+const parent = Symbol("declarationTypeTest/parent");
+const follows = Symbol("declarationTypeTest/follows");
+const tags = Symbol("declarationTypeTest/tags");
+const weights = Symbol("declarationTypeTest/weights");
+const element = Symbol("declarationTypeTest/element");
+const handle = Symbol("declarationTypeTest/handle");
+const cache = Symbol("declarationTypeTest/cache");
+const level = Symbol("declarationTypeTest/level");
+
+// The declared traits are the source of truth; registration must give exactly them.
+declare module '@adobe/ecs' {
+    export interface Components {
+        [position]: { type: Vec3 };
+        [score]: { type: number };
+        [parent]: { type: Entity; reference: "owner" };
+        [follows]: { type: Entity; reference: "weak" };
+        [tags]: { type: ReadonlySet<string> };
+        [weights]: { type: ReadonlyMap<Entity, number> };
+        [element]: { type: HTMLElement; thread: "main" };
+        [handle]: { type: { readonly release: () => void } };
+        [cache]: { type: Map<string, number> };
+        [level]: { type: number; derived: true };
+    }
+}
+
+Component.register(position, { type: Vec3.schema });
+Component.register(score, { type: { type: "integer" } });
+Component.register(parent, { type: Entity.schema, reference: "owner" });
+Component.register(follows, { type: Entity.schema, reference: "weak" });
+Component.register(tags, { type: { type: "set", items: { type: "string" } } });
+Component.register(weights, { type: { type: "map", keys: Entity.schema, values: { type: "number" } } });
+Component.register(level, { type: { type: "number", default: 0 }, derived: true });
+
+// A schema describes exactly the declared type.
+// @ts-expect-error a variable-length array isn't a Vec3
+Component.register(position, { type: { type: "array", items: { type: "number" } } });
+// @ts-expect-error a string isn't a number
+Component.register(score, { type: { type: "string" } });
+// @ts-expect-error a number's schema isn't an entity's
+Component.register(parent, { type: { type: "integer" }, reference: "owner" });
+// @ts-expect-error a set of numbers isn't a set of strings
+Component.register(tags, { type: { type: "set", items: { type: "number" } } });
+// @ts-expect-error an array isn't a set
+Component.register(tags, { type: { type: "array", items: { type: "string" } } });
+// @ts-expect-error a map's keys are entities
+Component.register(weights, { type: { type: "map", keys: { type: "string" }, values: { type: "number" } } });
+
+// Every declared trait is registered, with its declared value, and nothing undeclared is.
+// @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" }, thread: "main" });
+// @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" });
+// A declaration held in a constant gets no excess property check, so the types name each undeclared trait.
+const placed = { type: { type: "number" }, thread: "main" } as const;
+// @ts-expect-error an undeclared trait is given
+Component.register(score, placed);
+
+// A type that's data is registered with its schema; one that isn't data has none, and is stored as it is.
+// @ts-expect-error a number is data, so it has a schema
+Component.register(score, {});
+// @ts-expect-error a set of strings is data too
+Component.register(tags, {});
+Component.register(element, { thread: "main" });
+Component.register(handle, {});
+// A Set or Map changes in place, so it isn't data.
+Component.register(cache, {});
+// @ts-expect-error a value that isn't data has no schema
+Component.register(handle, { type: { type: "object", properties: {} } });
+
+// Value types are the declared ones.
+check<Equal<Component.Value<typeof position>, Vec3>>();
+check<Equal<Component.Value<typeof tags>, ReadonlySet<string>>>();
+check<Equal<Component.Value<typeof weights>, ReadonlyMap<Entity, number>>>();
+check<Equal<Component.Value<typeof element>, HTMLElement>>();

package/src/interface/component/index.ts

@@ -0,0 +1,3 @@
+export * from './register.js';
+export type { Key } from './key.js';
+export type { Value, With } from './value.js';

package/src/interface/component/key.ts

@@ -0,0 +1,3 @@
+import type { Components } from './types.js';
+
+export type Key = keyof Components;

package/src/interface/component/key.type-test.ts

@@ -0,0 +1,31 @@
+import { Component, Resource } from "@adobe/ecs";
+import type { Key as TraitKey } from "../trait/key.js";
+
+const position = Symbol("keyTypeTest/position");
+const scale = Symbol("keyTypeTest/scale");
+const mark = Symbol("keyTypeTest/mark");
+declare module "@adobe/ecs" {
+    interface Components {
+        [position]: { type: number };
+    }
+    interface Resources {
+        [scale]: { type: number };
+    }
+    interface Traits<N> {
+        readonly [mark]: true;
+    }
+}
+Component.register(position, { type: { type: "number" } });
+Resource.register(scale, { type: { type: "number", default: 0 } });
+
+// Components, resources and traits are named by keys; systems, rules and finalizers by names.
+export const component: Component.Key = position;
+export const resource: Resource.Key = scale;
+export const trait: TraitKey = mark;
+export const builtIn: TraitKey = "derived";
+// @ts-expect-error a resource isn't a component
+export const resourceAsComponent: Component.Key = scale;
+// @ts-expect-error a component isn't a resource
+export const componentAsResource: Resource.Key = position;
+// @ts-expect-error only the core's traits are named by strings
+export const unknownTrait: TraitKey = "unknown";