archetype-ecs 1.2.0 → 1.4.0

package/tests/System.test.ts

@@ -0,0 +1,546 @@
+import { describe, it, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { createEntityManager, type EntityManager } from '../src/EntityManager.js';
+import { createSystem, createSystems, System, OnAdded, OnRemoved } from '../src/System.js';
+import type { EntityId } from '../src/EntityManager.js';
+import { component } from '../src/index.js';
+
+// ── Components (shared across all suites) ────────────────
+
+const Position = component('Position', 'f32', ['x', 'y']);
+const Velocity = component('Velocity', 'f32', ['vx', 'vy']);
+const Health = component('Health', 'f32', ['hp']);
+const Tag = component('Tag');
+
+// ── Functional API ───────────────────────────────────────
+
+describe('createSystem (functional)', () => {
+  let em: EntityManager;
+
+  beforeEach(() => {
+    em = createEntityManager();
+  });
+
+  it('onAdded fires callback after flush + run', () => {
+    const collected: EntityId[] = [];
+    const sys = createSystem(em, (s) => {
+      s.onAdded(Health, (id: EntityId) => collected.push(id));
+    });
+
+    const e1 = em.createEntity();
+    em.addComponent(e1, Health, { hp: 100 });
+    em.flushHooks();
+    sys();
+    assert.deepEqual(collected, [e1]);
+
+    sys.dispose();
+  });
+
+  it('onAdded with multiple types only fires when entity has ALL types', () => {
+    const collected: EntityId[] = [];
+    const sys = createSystem(em, (s) => {
+      s.onAdded(Health, Position, (id: EntityId) => collected.push(id));
+    });
+
+    const e1 = em.createEntity();
+    em.addComponent(e1, Health, { hp: 100 });
+    em.flushHooks();
+    sys();
+    assert.deepEqual(collected, []);
+
+    em.addComponent(e1, Position, { x: 0, y: 0 });
+    em.flushHooks();
+    sys();
+    assert.deepEqual(collected, [e1]);
+
+    sys.dispose();
+  });
+
+  it('onAdded deduplicates when multiple types trigger for same entity', () => {
+    const collected: EntityId[] = [];
+    const sys = createSystem(em, (s) => {
+      s.onAdded(Health, Position, (id: EntityId) => collected.push(id));
+    });
+
+    const e1 = em.createEntityWith(Health, { hp: 50 }, Position, { x: 0, y: 0 });
+    em.flushHooks();
+    sys();
+    assert.deepEqual(collected, [e1]);
+
+    sys.dispose();
+  });
+
+  it('onRemoved fires callback after flush + run', () => {
+    const collected: EntityId[] = [];
+    const sys = createSystem(em, (s) => {
+      s.onRemoved(Health, (id: EntityId) => collected.push(id));
+    });
+
+    const e1 = em.createEntity();
+    em.addComponent(e1, Health, { hp: 50 });
+    em.flushHooks();
+    sys();
+
+    em.removeComponent(e1, Health);
+    em.flushHooks();
+    sys();
+    assert.deepEqual(collected, [e1]);
+
+    sys.dispose();
+  });
+
+  it('onRemoved with multiple types deduplicates', () => {
+    const collected: EntityId[] = [];
+    const sys = createSystem(em, (s) => {
+      s.onRemoved(Health, Position, (id: EntityId) => collected.push(id));
+    });
+
+    const e1 = em.createEntityWith(Health, { hp: 50 }, Position, { x: 0, y: 0 });
+    em.flushHooks();
+    sys();
+
+    em.removeComponent(e1, Health);
+    em.removeComponent(e1, Position);
+    em.flushHooks();
+    sys();
+    assert.deepEqual(collected, [e1]);
+
+    sys.dispose();
+  });
+
+  it('buffers cleared after sys() — no double processing', () => {
+    const collected: EntityId[] = [];
+    const sys = createSystem(em, (s) => {
+      s.onAdded(Health, (id: EntityId) => collected.push(id));
+    });
+
+    const e1 = em.createEntity();
+    em.addComponent(e1, Health, { hp: 100 });
+    em.flushHooks();
+    sys();
+    assert.deepEqual(collected, [e1]);
+
+    collected.length = 0;
+    sys();
+    assert.deepEqual(collected, []);
+
+    sys.dispose();
+  });
+
+  it('dispose() unsubscribes hooks', () => {
+    const collected: EntityId[] = [];
+    const sys = createSystem(em, (s) => {
+      s.onAdded(Health, (id: EntityId) => collected.push(id));
+    });
+
+    sys.dispose();
+
+    const e1 = em.createEntity();
+    em.addComponent(e1, Health, { hp: 100 });
+    em.flushHooks();
+    sys();
+    assert.deepEqual(collected, []);
+  });
+
+  it('forEach wraps em.forEach correctly (include + exclude)', () => {
+    const e1 = em.createEntity();
+    em.addComponent(e1, Position, { x: 1, y: 2 });
+    em.addComponent(e1, Velocity, { vx: 3, vy: 4 });
+
+    const e2 = em.createEntity();
+    em.addComponent(e2, Position, { x: 5, y: 6 });
+    em.addComponent(e2, Tag);
+
+    let count = 0;
+    const sys = createSystem(em, (s) => {
+      return () => {
+        s.forEach([Position], (view) => { count += view.count; }, [Tag]);
+      };
+    });
+
+    sys();
+    assert.equal(count, 1);
+    sys.dispose();
+  });
+
+  it('hooks-only system (no tick) works', () => {
+    const added: EntityId[] = [];
+    const sys = createSystem(em, (s) => {
+      s.onAdded(Tag, (id: EntityId) => added.push(id));
+    });
+
+    const e1 = em.createEntity();
+    em.addComponent(e1, Tag);
+    em.flushHooks();
+    sys();
+    assert.deepEqual(added, [e1]);
+    sys.dispose();
+  });
+
+  it('query-only system (no hooks) works', () => {
+    const e1 = em.createEntity();
+    em.addComponent(e1, Position, { x: 10, y: 20 });
+    em.addComponent(e1, Velocity, { vx: 1, vy: 2 });
+
+    let totalCount = 0;
+    const sys = createSystem(em, (s) => {
+      return () => {
+        s.forEach([Position, Velocity], (view) => { totalCount += view.count; });
+      };
+    });
+
+    sys();
+    assert.equal(totalCount, 1);
+    sys.dispose();
+  });
+});
+
+// ── Decorator-based class API ────────────────────────────
+
+describe('System (class + decorators)', () => {
+  let em: EntityManager;
+
+  beforeEach(() => {
+    em = createEntityManager();
+  });
+
+  it('@OnAdded fires decorated method after flush + run', () => {
+    const collected: EntityId[] = [];
+
+    class TestSys extends System {
+      @OnAdded(Health)
+      handleAdd(id: EntityId) { collected.push(id); }
+    }
+
+    const sys = new TestSys(em);
+    const e1 = em.createEntity();
+    em.addComponent(e1, Health, { hp: 100 });
+    em.flushHooks();
+    sys.run();
+    assert.deepEqual(collected, [e1]);
+
+    sys.dispose();
+  });
+
+  it('@OnAdded with multiple types only fires when entity has ALL types', () => {
+    const collected: EntityId[] = [];
+
+    class TestSys extends System {
+      @OnAdded(Health, Position)
+      handleAdd(id: EntityId) { collected.push(id); }
+    }
+
+    const sys = new TestSys(em);
+
+    // Only Health — should NOT trigger
+    const e1 = em.createEntity();
+    em.addComponent(e1, Health, { hp: 100 });
+    em.flushHooks();
+    sys.run();
+    assert.deepEqual(collected, []);
+
+    // Add Position — now matches
+    em.addComponent(e1, Position, { x: 0, y: 0 });
+    em.flushHooks();
+    sys.run();
+    assert.deepEqual(collected, [e1]);
+
+    sys.dispose();
+  });
+
+  it('@OnAdded deduplicates with createEntityWith', () => {
+    const collected: EntityId[] = [];
+
+    class TestSys extends System {
+      @OnAdded(Health, Position)
+      handleAdd(id: EntityId) { collected.push(id); }
+    }
+
+    const sys = new TestSys(em);
+    const e1 = em.createEntityWith(Health, { hp: 50 }, Position, { x: 0, y: 0 });
+    em.flushHooks();
+    sys.run();
+    assert.deepEqual(collected, [e1]);
+
+    sys.dispose();
+  });
+
+  it('@OnRemoved fires decorated method after flush + run', () => {
+    const collected: EntityId[] = [];
+
+    class TestSys extends System {
+      @OnRemoved(Health)
+      handleRemove(id: EntityId) { collected.push(id); }
+    }
+
+    const sys = new TestSys(em);
+    const e1 = em.createEntity();
+    em.addComponent(e1, Health, { hp: 50 });
+    em.flushHooks();
+    sys.run();
+
+    em.removeComponent(e1, Health);
+    em.flushHooks();
+    sys.run();
+    assert.deepEqual(collected, [e1]);
+
+    sys.dispose();
+  });
+
+  it('@OnRemoved fires on destroyEntity for all component types', () => {
+    const removedHealth: EntityId[] = [];
+    const removedPos: EntityId[] = [];
+
+    class TestSys extends System {
+      @OnRemoved(Health)
+      handleHealth(id: EntityId) { removedHealth.push(id); }
+
+      @OnRemoved(Position)
+      handlePos(id: EntityId) { removedPos.push(id); }
+    }
+
+    const sys = new TestSys(em);
+    const e1 = em.createEntityWith(Health, { hp: 100 }, Position, { x: 0, y: 0 });
+    em.flushHooks();
+    sys.run();
+
+    em.destroyEntity(e1);
+    em.flushHooks();
+    sys.run();
+    assert.deepEqual(removedHealth, [e1]);
+    assert.deepEqual(removedPos, [e1]);
+
+    sys.dispose();
+  });
+
+  it('buffers cleared after run() — no double processing', () => {
+    const collected: EntityId[] = [];
+
+    class TestSys extends System {
+      @OnAdded(Health)
+      handleAdd(id: EntityId) { collected.push(id); }
+    }
+
+    const sys = new TestSys(em);
+    const e1 = em.createEntity();
+    em.addComponent(e1, Health, { hp: 100 });
+    em.flushHooks();
+    sys.run();
+    assert.deepEqual(collected, [e1]);
+
+    collected.length = 0;
+    sys.run();
+    assert.deepEqual(collected, []);
+
+    sys.dispose();
+  });
+
+  it('dispose() unsubscribes hooks', () => {
+    const collected: EntityId[] = [];
+
+    class TestSys extends System {
+      @OnAdded(Health)
+      handleAdd(id: EntityId) { collected.push(id); }
+    }
+
+    const sys = new TestSys(em);
+    sys.dispose();
+
+    const e1 = em.createEntity();
+    em.addComponent(e1, Health, { hp: 100 });
+    em.flushHooks();
+    sys.run();
+    assert.deepEqual(collected, []);
+  });
+
+  it('tick() is called after hook callbacks', () => {
+    const order: string[] = [];
+
+    class TestSys extends System {
+      @OnAdded(Health)
+      handleAdd(_id: EntityId) { order.push('hook'); }
+
+      tick() { order.push('tick'); }
+    }
+
+    const sys = new TestSys(em);
+    const e1 = em.createEntity();
+    em.addComponent(e1, Health, { hp: 100 });
+    em.flushHooks();
+    sys.run();
+    assert.deepEqual(order, ['hook', 'tick']);
+
+    sys.dispose();
+  });
+
+  it('forEach available on System instance', () => {
+    const e1 = em.createEntity();
+    em.addComponent(e1, Position, { x: 1, y: 2 });
+    em.addComponent(e1, Velocity, { vx: 3, vy: 4 });
+
+    let count = 0;
+
+    class TestSys extends System {
+      tick() {
+        this.forEach([Position, Velocity], (view) => { count += view.count; });
+      }
+    }
+
+    const sys = new TestSys(em);
+    sys.run();
+    assert.equal(count, 1);
+    sys.dispose();
+  });
+
+  it('multiple decorated methods on same class', () => {
+    const added: EntityId[] = [];
+    const removed: EntityId[] = [];
+
+    class TestSys extends System {
+      @OnAdded(Health)
+      handleAdd(id: EntityId) { added.push(id); }
+
+      @OnRemoved(Health)
+      handleRemove(id: EntityId) { removed.push(id); }
+    }
+
+    const sys = new TestSys(em);
+    const e1 = em.createEntity();
+    em.addComponent(e1, Health, { hp: 100 });
+    em.flushHooks();
+    sys.run();
+    assert.deepEqual(added, [e1]);
+    assert.deepEqual(removed, []);
+
+    em.removeComponent(e1, Health);
+    em.flushHooks();
+    sys.run();
+    assert.deepEqual(removed, [e1]);
+
+    sys.dispose();
+  });
+
+  it('multiple instances have independent buffers', () => {
+    const collectedA: EntityId[] = [];
+    const collectedB: EntityId[] = [];
+
+    class TestSys extends System {
+      out: EntityId[];
+      constructor(em: EntityManager, out: EntityId[]) {
+        super(em);
+        this.out = out;
+      }
+      @OnAdded(Health)
+      handleAdd(id: EntityId) { this.out.push(id); }
+    }
+
+    const sysA = new TestSys(em, collectedA);
+    const sysB = new TestSys(em, collectedB);
+
+    const e1 = em.createEntity();
+    em.addComponent(e1, Health, { hp: 100 });
+    em.flushHooks();
+
+    sysA.run();
+    sysB.run();
+
+    assert.deepEqual(collectedA, [e1]);
+    assert.deepEqual(collectedB, [e1]);
+
+    sysA.dispose();
+    sysB.dispose();
+  });
+});
+
+// ── createSystems (activator) ────────────────────────────
+
+describe('createSystems', () => {
+  let em: EntityManager;
+
+  beforeEach(() => {
+    em = createEntityManager();
+  });
+
+  it('runs functional systems in order', () => {
+    const order: string[] = [];
+    function SysA() { return () => { order.push('A'); }; }
+    function SysB() { return () => { order.push('B'); }; }
+
+    const pipeline = createSystems(em, [SysA, SysB]);
+    pipeline();
+    assert.deepEqual(order, ['A', 'B']);
+    pipeline.dispose();
+  });
+
+  it('runs class-based systems in order', () => {
+    const order: string[] = [];
+
+    class SysA extends System { tick() { order.push('A'); } }
+    class SysB extends System { tick() { order.push('B'); } }
+
+    const pipeline = createSystems(em, [SysA, SysB]);
+    pipeline();
+    assert.deepEqual(order, ['A', 'B']);
+    pipeline.dispose();
+  });
+
+  it('mixes functional and class-based systems', () => {
+    const order: string[] = [];
+
+    function FuncSys() { return () => { order.push('func'); }; }
+    class ClassSys extends System { tick() { order.push('class'); } }
+
+    const pipeline = createSystems(em, [FuncSys, ClassSys]);
+    pipeline();
+    assert.deepEqual(order, ['func', 'class']);
+    pipeline.dispose();
+  });
+
+  it('dispose() disposes all systems', () => {
+    const collected: EntityId[] = [];
+
+    class TestSys extends System {
+      @OnAdded(Health)
+      handleAdd(id: EntityId) { collected.push(id); }
+    }
+
+    const pipeline = createSystems(em, [TestSys]);
+    pipeline.dispose();
+
+    const e1 = em.createEntity();
+    em.addComponent(e1, Health, { hp: 100 });
+    em.flushHooks();
+    pipeline();
+    assert.deepEqual(collected, []);
+  });
+
+  it('class hooks fire through pipeline', () => {
+    const added: EntityId[] = [];
+    let moved = 0;
+
+    class HookSys extends System {
+      @OnAdded(Health)
+      handleAdd(id: EntityId) { added.push(id); }
+    }
+
+    class TickSys extends System {
+      tick() {
+        this.forEach([Position, Velocity], (view) => { moved += view.count; });
+      }
+    }
+
+    const pipeline = createSystems(em, [HookSys, TickSys]);
+
+    const e1 = em.createEntityWith(
+      Health, { hp: 100 },
+      Position, { x: 0, y: 0 },
+      Velocity, { vx: 1, vy: 1 }
+    );
+    em.flushHooks();
+    pipeline();
+
+    assert.deepEqual(added, [e1]);
+    assert.equal(moved, 1);
+    pipeline.dispose();
+  });
+});

package/tests/types.ts

@@ -1,101 +1,102 @@
 // Compile-time type tests — run with: npx tsc --noEmit
-// These tests validate TS generics flow correctly through the API.
+// These tests validate TS types flow correctly through the API.
 // No runtime execution needed; if this file compiles, the types are correct.
 
-import { createEntityManager, component, type ComponentDef, type FieldRef, type EntityId } from '../src/index.js';
+import {
+  createEntityManager, createSystem, createSystems, component,
+  System, OnAdded, OnRemoved,
+  type ComponentDef, type FieldRef, type EntityId,
+  type SystemContext, type FunctionalSystemConstructor, type FunctionalSystem, type Pipeline
+} from '../src/index.js';
 
-// --- component() infers schema fields ---
+// --- component() creates ComponentDef ---
 const Position = component('Position', 'f32', ['x', 'y']);
 const Velocity = component('Velocity', { vx: 'f32', vy: 'f32' });
 const Tag = component('Tag');
 const Name = component('Name', { name: 'string', title: 'string' });
 const Label = component('Label', 'string', ['text', 'color']);
 
-// Position should be ComponentDef<{ x: number, y: number }>
-type AssertPosition = typeof Position extends ComponentDef<{ x: number; y: number }> ? true : never;
-const _assertPos: AssertPosition = true;
-
-// Position.x should be a FieldRef<number>
-type AssertFieldRef = typeof Position.x extends FieldRef<number> ? true : never;
-const _assertField: AssertFieldRef = true;
-
-// Name should be ComponentDef<{ name: string, title: string }>
-type AssertName = typeof Name extends ComponentDef<{ name: string; title: string }> ? true : never;
-const _assertName: AssertName = true;
-
-// Name.name should be a FieldRef<string>
-type AssertNameField = typeof Name.name extends FieldRef<string> ? true : never;
-const _assertNameField: AssertNameField = true;
-
-// Label short form: ComponentDef<{ text: string, color: string }>
-type AssertLabel = typeof Label extends ComponentDef<{ text: string; color: string }> ? true : never;
-const _assertLabel: AssertLabel = true;
-
-// Tag should be ComponentDef<unknown> (no schema)
-type AssertTag = typeof Tag extends ComponentDef ? true : never;
-const _assertTag: AssertTag = true;
+// component() returns ComponentDef
+const _assertComp: ComponentDef = Position;
+const _assertTag: ComponentDef = Tag;
 
 // --- EntityManager typed methods ---
 const em = createEntityManager();
 const id: EntityId = em.createEntity();
 
-// addComponent: accepts correct data shape
+// addComponent: accepts data
 em.addComponent(id, Position, { x: 1, y: 2 });
 em.addComponent(id, Velocity, { vx: 0, vy: 0 });
 em.addComponent(id, Name, { name: 'Hero', title: 'Sir' });
 
-// getComponent: returns typed object or undefined
+// getComponent: returns data or undefined
 const pos = em.getComponent(id, Position);
-if (pos) {
-  const x: number = pos.x;
-  const y: number = pos.y;
-}
-
-const nameComp = em.getComponent(id, Name);
-if (nameComp) {
-  const n: string = nameComp.name;
-  const t: string = nameComp.title;
-}
 
-// get/set: numeric field descriptor access
-const px: number | undefined = em.get(id, Position.x);
-const py: number | undefined = em.get(id, Position.y);
-em.set(id, Position.x, 10);
-em.set(id, Position.y, 20);
-
-// get/set: string field descriptor access
-const nameVal: string | undefined = em.get(id, Name.name);
-em.set(id, Name.name, 'Villain');
+// get/set: field descriptor access
+const px: any = em.get(id, Position.x as any);
+em.set(id, Position.x as any, 10);
 
 // forEach + field: accepts FieldRef
 em.forEach([Position, Velocity], (arch) => {
   const count: number = arch.count;
   const ids: EntityId[] = arch.entityIds;
-  const arrX = arch.field(Position.x);
-  const arrVx = arch.field(Velocity.vx);
+  const arrX = arch.field(Position.x as any);
 });
 
 // createEntityWith: alternating type, data
 em.createEntityWith(Position, { x: 0, y: 0 }, Velocity, { vx: 1, vy: 1 });
 
-// --- These should fail if uncommented (negative tests) ---
-// @ts-expect-error 'z' does not exist on Position
-em.get(id, Position.z);
-
-// @ts-expect-error 'z' does not exist on Position
-em.set(id, Position.z, 5);
-
-// @ts-expect-error 'x' does not exist on Velocity
-em.get(id, Velocity.x);
-
-// @ts-expect-error missing 'y' in Position data
-em.addComponent(id, Position, { x: 1 });
-
-// @ts-expect-error 'z' does not exist on Position
-em.forEach([Position], (arch) => { arch.field(Position.z); });
+// --- createSystem returns FunctionalSystem ---
+const sys: FunctionalSystem = createSystem(em, (s: SystemContext) => {
+  // onAdded with 1 type
+  s.onAdded(Position, (entityId: EntityId) => {});
+  // onAdded with 2 types
+  s.onAdded(Position, Velocity, (entityId: EntityId) => {});
+  // onRemoved with 1 type
+  s.onRemoved(Position, (entityId: EntityId) => {});
+  // onRemoved with 2 types
+  s.onRemoved(Position, Velocity, (entityId: EntityId) => {});
+
+  return () => {
+    s.forEach([Position, Velocity], (view) => {
+      const count: number = view.count;
+    });
+    s.forEach([Position], (_view) => {}, [Velocity]);
+  };
+});
+sys();
+sys.dispose();
+
+// --- FunctionalSystemConstructor type ---
+const ctor: FunctionalSystemConstructor = (s) => {
+  s.onAdded(Position, (_id) => {});
+};
+
+// --- createSystems returns Pipeline ---
+const pipeline: Pipeline = createSystems(em, [ctor]);
+pipeline();
+pipeline.dispose();
+
+// --- Class-based System ---
+class TestSystem extends System {
+  @OnAdded(Position)
+  handleAdd(id: EntityId) {}
+
+  @OnRemoved(Position)
+  handleRemove(id: EntityId) {}
+
+  tick() {
+    this.forEach([Position], (view) => {
+      const count: number = view.count;
+    });
+  }
+}
 
-// @ts-expect-error wrong data shape for Name
-em.addComponent(id, Name, { foo: 'bar' });
+const testSys = new TestSystem(em);
+testSys.run();
+testSys.dispose();
 
-// @ts-expect-error number not assignable to string field
-em.set(id, Name.name, 42);
+// --- createSystems accepts mixed entries ---
+const mixedPipeline: Pipeline = createSystems(em, [ctor, TestSystem]);
+mixedPipeline();
+mixedPipeline.dispose();