archetype-ecs 1.0.0 → 1.2.0

package/tests/EntityManager.test.js

@@ -1,89 +1,91 @@
-import { describe, test, expect, beforeEach } from '@jest/globals';
+import { describe, it, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
 import { createEntityManager } from '../src/EntityManager.js';
+import { component } from '../src/index.js';
 
 describe('EntityManager', () => {
   let em;
-  const Position = Symbol('Position');
-  const Velocity = Symbol('Velocity');
-  const Health = Symbol('Health');
+  const Position = component('Position', 'f32', ['x', 'y']);
+  const Velocity = component('Velocity', 'f32', ['vx', 'vy']);
+  const Health = component('Health', 'f32', ['hp']);
 
   beforeEach(() => {
     em = createEntityManager();
   });
 
   describe('createEntity / destroyEntity', () => {
-    test('creates entities with incrementing ids', () => {
+    it('creates entities with incrementing ids', () => {
       const a = em.createEntity();
       const b = em.createEntity();
-      expect(b).toBe(a + 1);
+      assert.equal(b, a + 1);
     });
 
-    test('destroyEntity removes entity', () => {
+    it('destroyEntity removes entity', () => {
       const id = em.createEntity();
       em.addComponent(id, Position, { x: 0, y: 0 });
       em.destroyEntity(id);
-      expect(em.getAllEntities()).toEqual([]);
-      expect(em.getComponent(id, Position)).toBeUndefined();
+      assert.deepEqual(em.getAllEntities(), []);
+      assert.equal(em.getComponent(id, Position), undefined);
     });
   });
 
   describe('addComponent / getComponent / hasComponent', () => {
-    test('adds and retrieves a component', () => {
+    it('adds and retrieves a component', () => {
       const id = em.createEntity();
       em.addComponent(id, Position, { x: 1, y: 2 });
-      expect(em.getComponent(id, Position)).toEqual({ x: 1, y: 2 });
-      expect(em.hasComponent(id, Position)).toBe(true);
+      assert.deepEqual(em.getComponent(id, Position), { x: 1, y: 2 });
+      assert.equal(em.hasComponent(id, Position), true);
     });
 
-    test('returns undefined for missing component', () => {
+    it('returns undefined for missing component', () => {
       const id = em.createEntity();
-      expect(em.getComponent(id, Position)).toBeUndefined();
-      expect(em.hasComponent(id, Position)).toBe(false);
+      assert.equal(em.getComponent(id, Position), undefined);
+      assert.equal(em.hasComponent(id, Position), false);
     });
 
-    test('overwrites component data on duplicate add', () => {
+    it('overwrites component data on duplicate add', () => {
       const id = em.createEntity();
       em.addComponent(id, Position, { x: 1, y: 2 });
       em.addComponent(id, Position, { x: 10, y: 20 });
-      expect(em.getComponent(id, Position)).toEqual({ x: 10, y: 20 });
+      assert.deepEqual(em.getComponent(id, Position), { x: 10, y: 20 });
     });
 
-    test('adds multiple component types', () => {
+    it('adds multiple component types', () => {
       const id = em.createEntity();
       em.addComponent(id, Position, { x: 0, y: 0 });
       em.addComponent(id, Velocity, { vx: 1, vy: 1 });
-      expect(em.getComponent(id, Position)).toEqual({ x: 0, y: 0 });
-      expect(em.getComponent(id, Velocity)).toEqual({ vx: 1, vy: 1 });
+      assert.deepEqual(em.getComponent(id, Position), { x: 0, y: 0 });
+      assert.deepEqual(em.getComponent(id, Velocity), { vx: 1, vy: 1 });
     });
   });
 
   describe('removeComponent', () => {
-    test('removes a component', () => {
+    it('removes a component', () => {
       const id = em.createEntity();
       em.addComponent(id, Position, { x: 1, y: 2 });
       em.addComponent(id, Velocity, { vx: 1, vy: 1 });
       em.removeComponent(id, Position);
-      expect(em.hasComponent(id, Position)).toBe(false);
-      expect(em.hasComponent(id, Velocity)).toBe(true);
+      assert.equal(em.hasComponent(id, Position), false);
+      assert.equal(em.hasComponent(id, Velocity), true);
     });
 
-    test('removing last component leaves entity alive but without archetype', () => {
+    it('removing last component leaves entity alive but without archetype', () => {
       const id = em.createEntity();
       em.addComponent(id, Position, { x: 1, y: 2 });
       em.removeComponent(id, Position);
-      expect(em.getAllEntities()).toContain(id);
-      expect(em.hasComponent(id, Position)).toBe(false);
+      assert.ok(em.getAllEntities().includes(id));
+      assert.equal(em.hasComponent(id, Position), false);
     });
 
-    test('removing non-existent component is a no-op', () => {
+    it('removing non-existent component is a no-op', () => {
       const id = em.createEntity();
-      em.removeComponent(id, Position); // no-op
-      expect(em.getAllEntities()).toContain(id);
+      em.removeComponent(id, Position);
+      assert.ok(em.getAllEntities().includes(id));
     });
   });
 
   describe('query', () => {
-    test('returns entities matching component types', () => {
+    it('returns entities matching component types', () => {
       const a = em.createEntity();
       em.addComponent(a, Position, { x: 0, y: 0 });
       em.addComponent(a, Velocity, { vx: 1, vy: 1 });
@@ -92,11 +94,11 @@ describe('EntityManager', () => {
       em.addComponent(b, Position, { x: 5, y: 5 });
 
       const result = em.query([Position, Velocity]);
-      expect(result).toContain(a);
-      expect(result).not.toContain(b);
+      assert.ok(result.includes(a));
+      assert.ok(!result.includes(b));
     });
 
-    test('exclude types filters out entities', () => {
+    it('exclude types filters out entities', () => {
       const a = em.createEntity();
       em.addComponent(a, Position, { x: 0, y: 0 });
 
@@ -105,25 +107,21 @@ describe('EntityManager', () => {
       em.addComponent(b, Health, { hp: 100 });
 
       const result = em.query([Position], [Health]);
-      expect(result).toContain(a);
-      expect(result).not.toContain(b);
+      assert.ok(result.includes(a));
+      assert.ok(!result.includes(b));
     });
   });
 
   describe('createEntityWith', () => {
-    test('creates entity with multiple components at once', () => {
-      const map = new Map();
-      map.set(Position, { x: 3, y: 4 });
-      map.set(Velocity, { vx: 1, vy: 0 });
-
-      const id = em.createEntityWith(map);
-      expect(em.getComponent(id, Position)).toEqual({ x: 3, y: 4 });
-      expect(em.getComponent(id, Velocity)).toEqual({ vx: 1, vy: 0 });
+    it('creates entity with multiple components at once', () => {
+      const id = em.createEntityWith(Position, { x: 3, y: 4 }, Velocity, { vx: 1, vy: 0 });
+      assert.deepEqual(em.getComponent(id, Position), { x: 3, y: 4 });
+      assert.deepEqual(em.getComponent(id, Velocity), { vx: 1, vy: 0 });
     });
   });
 
   describe('count', () => {
-    test('counts entities matching query', () => {
+    it('counts entities matching query', () => {
       const a = em.createEntity();
       em.addComponent(a, Position, { x: 0, y: 0 });
 
@@ -131,22 +129,20 @@ describe('EntityManager', () => {
       em.addComponent(b, Position, { x: 1, y: 1 });
       em.addComponent(b, Velocity, { vx: 1, vy: 0 });
 
-      expect(em.count([Position])).toBe(2);
-      expect(em.count([Position, Velocity])).toBe(1);
+      assert.equal(em.count([Position]), 2);
+      assert.equal(em.count([Position, Velocity]), 1);
     });
   });
 
   describe('serialize / deserialize', () => {
     const symbolToName = new Map([
-      [Position, 'Position'],
-      [Velocity, 'Velocity'],
-      [Health, 'Health']
+      [Position._sym, 'Position'],
+      [Velocity._sym, 'Velocity'],
+      [Health._sym, 'Health']
     ]);
-    const nameToSymbol = {
-      Position, Velocity, Health
-    };
+    const nameToSymbol = { Position, Velocity, Health };
 
-    test('round-trips entities and components', () => {
+    it('round-trips entities and components', () => {
       const a = em.createEntity();
       em.addComponent(a, Position, { x: 1, y: 2 });
       em.addComponent(a, Velocity, { vx: 3, vy: 4 });
@@ -157,23 +153,23 @@ describe('EntityManager', () => {
       const data = em.serialize(symbolToName);
       em.deserialize(data, nameToSymbol);
 
-      expect(em.getAllEntities().sort()).toEqual([a, b].sort());
-      expect(em.getComponent(a, Position)).toEqual({ x: 1, y: 2 });
-      expect(em.getComponent(a, Velocity)).toEqual({ vx: 3, vy: 4 });
-      expect(em.getComponent(b, Position)).toEqual({ x: 5, y: 6 });
+      assert.deepEqual(em.getAllEntities().sort(), [a, b].sort());
+      assert.deepEqual(em.getComponent(a, Position), { x: 1, y: 2 });
+      assert.deepEqual(em.getComponent(a, Velocity), { vx: 3, vy: 4 });
+      assert.deepEqual(em.getComponent(b, Position), { x: 5, y: 6 });
     });
 
-    test('strip components excludes component data but keeps entity', () => {
+    it('strip components excludes component data but keeps entity', () => {
       const a = em.createEntity();
       em.addComponent(a, Position, { x: 1, y: 2 });
       em.addComponent(a, Velocity, { vx: 3, vy: 4 });
 
       const data = em.serialize(symbolToName, [Velocity]);
-      expect(data.components['Velocity']).toBeUndefined();
-      expect(data.components['Position']).toBeDefined();
+      assert.equal(data.components['Velocity'], undefined);
+      assert.notEqual(data.components['Position'], undefined);
     });
 
-    test('skip entities with component excludes entire entity', () => {
+    it('skip entities with component excludes entire entity', () => {
       const a = em.createEntity();
       em.addComponent(a, Position, { x: 1, y: 2 });
 
@@ -182,43 +178,312 @@ describe('EntityManager', () => {
       em.addComponent(b, Health, { hp: 100 });
 
       const data = em.serialize(symbolToName, [], [Health]);
-      expect(data.entities).toContain(a);
-      expect(data.entities).not.toContain(b);
+      assert.ok(data.entities.includes(a));
+      assert.ok(!data.entities.includes(b));
     });
 
-    test('custom serializers are used when provided', () => {
+    it('custom serializers are used when provided', () => {
+      const Meta = component('Meta', { x: 'f32', y: 'f32', secret: 'i32' });
+      const metaSymbolToName = new Map([...symbolToName, [Meta._sym, 'Meta']]);
+
       const a = em.createEntity();
-      em.addComponent(a, Position, { x: 1, y: 2, _internal: 'secret' });
+      em.addComponent(a, Meta, { x: 1, y: 2, secret: 42 });
 
       const serializers = new Map([
-        ['Position', (data) => ({ x: data.x, y: data.y })]
+        ['Meta', (data) => ({ x: data.x, y: data.y })]
       ]);
 
-      const result = em.serialize(symbolToName, [], [], { serializers });
-      expect(result.components['Position'][a]).toEqual({ x: 1, y: 2 });
-      expect(result.components['Position'][a]._internal).toBeUndefined();
+      const result = em.serialize(metaSymbolToName, [], [], { serializers });
+      assert.deepEqual(result.components['Meta'][a], { x: 1, y: 2 });
+      assert.equal(result.components['Meta'][a].secret, undefined);
     });
 
-    test('custom deserializers are used when provided', () => {
+    it('custom deserializers are used when provided', () => {
+      const Meta = component('Meta2', { x: 'f32', y: 'f32' });
+      const metaSymbolToName = new Map([...symbolToName, [Meta._sym, 'Meta2']]);
+      const metaNameToSymbol = { ...nameToSymbol, Meta2: Meta };
+
       const a = em.createEntity();
-      em.addComponent(a, Position, { x: 1, y: 2 });
+      em.addComponent(a, Meta, { x: 1, y: 2 });
 
-      const data = em.serialize(symbolToName);
+      const data = em.serialize(metaSymbolToName);
 
       const deserializers = new Map([
-        ['Position', (compData) => ({ ...compData, restored: true })]
+        ['Meta2', (compData) => ({ ...compData, restored: true })]
       ]);
 
-      em.deserialize(data, nameToSymbol, { deserializers });
-      expect(em.getComponent(a, Position)).toEqual({ x: 1, y: 2, restored: true });
+      em.deserialize(data, metaNameToSymbol, { deserializers });
+      const result = em.getComponent(a, Meta);
+      assert.ok(Math.abs(result.x - 1) < 0.01);
+      assert.ok(Math.abs(result.y - 2) < 0.01);
     });
 
-    test('deserialize clears previous state', () => {
+    it('deserialize clears previous state', () => {
       const a = em.createEntity();
       em.addComponent(a, Position, { x: 1, y: 2 });
 
       em.deserialize({ nextId: 1, entities: [], components: {} }, nameToSymbol);
-      expect(em.getAllEntities()).toEqual([]);
+      assert.deepEqual(em.getAllEntities(), []);
+    });
+  });
+});
+
+describe('Typed Components (SoA)', () => {
+  let em;
+
+  beforeEach(() => {
+    em = createEntityManager();
+  });
+
+  it('typed component round-trip (add/get)', () => {
+    const Pos = component('Pos', 'f32', ['x', 'y']);
+    const id = em.createEntity();
+    em.addComponent(id, Pos, { x: 1.5, y: 2.5 });
+    const result = em.getComponent(id, Pos);
+    assert.ok(Math.abs(result.x - 1.5) < 0.001);
+    assert.ok(Math.abs(result.y - 2.5) < 0.001);
+  });
+
+  it('growth past initial capacity (>64 entities)', () => {
+    const Pos = component('PosGrow', 'f32', ['x', 'y']);
+    const ids = [];
+    for (let i = 0; i < 100; i++) {
+      const id = em.createEntity();
+      em.addComponent(id, Pos, { x: i, y: i * 2 });
+      ids.push(id);
+    }
+    for (let i = 0; i < 100; i++) {
+      const result = em.getComponent(ids[i], Pos);
+      assert.ok(Math.abs(result.x - i) < 0.001);
+      assert.ok(Math.abs(result.y - i * 2) < 0.001);
+    }
+  });
+
+  it('swap-remove preserves typed data', () => {
+    const Pos = component('PosSwap', 'f32', ['x', 'y']);
+    const a = em.createEntity();
+    const b = em.createEntity();
+    const c = em.createEntity();
+    em.addComponent(a, Pos, { x: 1, y: 2 });
+    em.addComponent(b, Pos, { x: 3, y: 4 });
+    em.addComponent(c, Pos, { x: 5, y: 6 });
+
+    em.destroyEntity(a);
+
+    const resultB = em.getComponent(b, Pos);
+    assert.ok(Math.abs(resultB.x - 3) < 0.001);
+    assert.ok(Math.abs(resultB.y - 4) < 0.001);
+
+    const resultC = em.getComponent(c, Pos);
+    assert.ok(Math.abs(resultC.x - 5) < 0.001);
+    assert.ok(Math.abs(resultC.y - 6) < 0.001);
+  });
+
+  it('typed + tag on same entity', () => {
+    const Pos = component('PosMixed', 'f32', ['x', 'y']);
+    const Tag = component('Tag');
+    const id = em.createEntity();
+    em.addComponent(id, Pos, { x: 10, y: 20 });
+    em.addComponent(id, Tag, {});
+
+    const pos = em.getComponent(id, Pos);
+    assert.ok(Math.abs(pos.x - 10) < 0.001);
+    assert.ok(Math.abs(pos.y - 20) < 0.001);
+
+    // Tag has no schema, getComponent returns undefined
+    assert.equal(em.getComponent(id, Tag), undefined);
+    assert.equal(em.hasComponent(id, Tag), true);
+  });
+
+  it('forEach raw field access and mutation', () => {
+    const Pos = component('PosLoop', 'f32', ['x', 'y']);
+    const Vel = component('VelLoop', 'f32', ['vx', 'vy']);
+
+    for (let i = 0; i < 10; i++) {
+      const id = em.createEntity();
+      em.addComponent(id, Pos, { x: i, y: 0 });
+      em.addComponent(id, Vel, { vx: 1, vy: 2 });
+    }
+
+    em.forEach([Pos, Vel], (arch) => {
+      const px = arch.field(Pos.x);
+      const py = arch.field(Pos.y);
+      const vx = arch.field(Vel.vx);
+      const vy = arch.field(Vel.vy);
+      for (let i = 0; i < arch.count; i++) {
+        px[i] += vx[i];
+        py[i] += vy[i];
+      }
+    });
+
+    const ids = em.query([Pos, Vel]);
+    for (const id of ids) {
+      const pos = em.getComponent(id, Pos);
+      assert.ok(pos.x >= 1);
+      assert.ok(Math.abs(pos.y - 2) < 0.001);
+    }
+  });
+
+  it('serialize/deserialize round-trip with typed components', () => {
+    const Pos = component('PosSer', 'f32', ['x', 'y']);
+    const symbolToName = new Map([[Pos._sym, 'PosSer']]);
+    const nameToSymbol = { PosSer: Pos };
+
+    const a = em.createEntity();
+    em.addComponent(a, Pos, { x: 1.5, y: 2.5 });
+    const b = em.createEntity();
+    em.addComponent(b, Pos, { x: 3.5, y: 4.5 });
+
+    const data = em.serialize(symbolToName);
+    em.deserialize(data, nameToSymbol);
+
+    const posA = em.getComponent(a, Pos);
+    assert.ok(Math.abs(posA.x - 1.5) < 0.01);
+    assert.ok(Math.abs(posA.y - 2.5) < 0.01);
+
+    const posB = em.getComponent(b, Pos);
+    assert.ok(Math.abs(posB.x - 3.5) < 0.01);
+    assert.ok(Math.abs(posB.y - 4.5) < 0.01);
+  });
+
+  it('archetype migration with typed components', () => {
+    const Pos = component('PosMig', 'f32', ['x', 'y']);
+    const Vel = component('VelMig', 'f32', ['vx', 'vy']);
+
+    const id = em.createEntity();
+    em.addComponent(id, Pos, { x: 5, y: 10 });
+    em.addComponent(id, Vel, { vx: 1, vy: 2 });
+
+    const pos = em.getComponent(id, Pos);
+    assert.ok(Math.abs(pos.x - 5) < 0.001);
+    assert.ok(Math.abs(pos.y - 10) < 0.001);
+
+    const vel = em.getComponent(id, Vel);
+    assert.ok(Math.abs(vel.vx - 1) < 0.001);
+    assert.ok(Math.abs(vel.vy - 2) < 0.001);
+
+    em.removeComponent(id, Vel);
+    const pos2 = em.getComponent(id, Pos);
+    assert.ok(Math.abs(pos2.x - 5) < 0.001);
+    assert.ok(Math.abs(pos2.y - 10) < 0.001);
+    assert.equal(em.hasComponent(id, Vel), false);
+  });
+
+  it('overwrite typed component data in-place', () => {
+    const Pos = component('PosOw', 'f32', ['x', 'y']);
+    const id = em.createEntity();
+    em.addComponent(id, Pos, { x: 1, y: 2 });
+    em.addComponent(id, Pos, { x: 99, y: 88 });
+    const result = em.getComponent(id, Pos);
+    assert.ok(Math.abs(result.x - 99) < 0.001);
+    assert.ok(Math.abs(result.y - 88) < 0.001);
+  });
+
+  it('get/set for zero-allocation field access', () => {
+    const Pos = component('PosGS', 'f32', ['x', 'y']);
+    const id = em.createEntity();
+    em.addComponent(id, Pos, { x: 3.5, y: 7.5 });
+    assert.ok(Math.abs(em.get(id, Pos.x) - 3.5) < 0.001);
+    assert.ok(Math.abs(em.get(id, Pos.y) - 7.5) < 0.001);
+    em.set(id, Pos.x, 42);
+    assert.ok(Math.abs(em.get(id, Pos.x) - 42) < 0.001);
+    assert.ok(Math.abs(em.get(id, Pos.y) - 7.5) < 0.001);
+  });
+
+  it('get returns undefined for missing entity/component', () => {
+    const Pos = component('PosGFM', 'f32', ['x', 'y']);
+    assert.equal(em.get(999, Pos.x), undefined);
+    const id = em.createEntity();
+    assert.equal(em.get(id, Pos.x), undefined);
+  });
+
+  it('forEach field returns undefined for tag component', () => {
+    const Tag = component('TagFE');
+    const Pos = component('PosFE', 'f32', ['x', 'y']);
+    const id = em.createEntity();
+    em.addComponent(id, Pos, { x: 1, y: 2 });
+    em.addComponent(id, Tag, {});
+
+    em.forEach([Pos, Tag], (arch) => {
+      assert.ok(arch.field(Pos.x) instanceof Float32Array);
+    });
+  });
+
+  it('string component round-trip (add/get/set)', () => {
+    const Name = component('NameRT', { name: 'string', title: 'string' });
+    const id = em.createEntity();
+    em.addComponent(id, Name, { name: 'Hero', title: 'Sir' });
+
+    assert.equal(em.get(id, Name.name), 'Hero');
+    assert.equal(em.get(id, Name.title), 'Sir');
+
+    em.set(id, Name.name, 'Villain');
+    assert.equal(em.get(id, Name.name), 'Villain');
+
+    const obj = em.getComponent(id, Name);
+    assert.deepEqual(obj, { name: 'Villain', title: 'Sir' });
+  });
+
+  it('string component short form', () => {
+    const Label = component('LabelSF', 'string', ['text', 'color']);
+    const id = em.createEntity();
+    em.addComponent(id, Label, { text: 'hello', color: 'red' });
+
+    assert.equal(em.get(id, Label.text), 'hello');
+    assert.equal(em.get(id, Label.color), 'red');
+  });
+
+  it('string component growth past capacity', () => {
+    const Name = component('NameGrow', 'string', ['value']);
+    for (let i = 0; i < 100; i++) {
+      const id = em.createEntity();
+      em.addComponent(id, Name, { value: `entity_${i}` });
+    }
+    const ids = em.query([Name]);
+    assert.equal(ids.length, 100);
+    assert.equal(em.get(ids[0], Name.value), 'entity_0');
+    assert.equal(em.get(ids[99], Name.value), 'entity_99');
+  });
+
+  it('string component swap-remove preserves data', () => {
+    const Name = component('NameSwap', 'string', ['value']);
+    const a = em.createEntity();
+    const b = em.createEntity();
+    const c = em.createEntity();
+    em.addComponent(a, Name, { value: 'aaa' });
+    em.addComponent(b, Name, { value: 'bbb' });
+    em.addComponent(c, Name, { value: 'ccc' });
+
+    em.destroyEntity(a);
+    assert.equal(em.get(b, Name.value), 'bbb');
+    assert.equal(em.get(c, Name.value), 'ccc');
+  });
+
+  it('mixed string + numeric fields in one component', () => {
+    const Item = component('Item', { name: 'string', weight: 'f32' });
+    const id = em.createEntity();
+    em.addComponent(id, Item, { name: 'Sword', weight: 3.5 });
+
+    assert.equal(em.get(id, Item.name), 'Sword');
+    assert.ok(Math.abs(em.get(id, Item.weight) - 3.5) < 0.01);
+
+    const obj = em.getComponent(id, Item);
+    assert.equal(obj.name, 'Sword');
+    assert.ok(Math.abs(obj.weight - 3.5) < 0.01);
+  });
+
+  it('string component forEach field access', () => {
+    const Name = component('NameFE', 'string', ['value']);
+    for (let i = 0; i < 5; i++) {
+      const id = em.createEntity();
+      em.addComponent(id, Name, { value: `e${i}` });
+    }
+
+    em.forEach([Name], (arch) => {
+      const values = arch.field(Name.value);
+      assert.ok(Array.isArray(values));
+      assert.equal(values[0], 'e0');
+      assert.equal(values[4], 'e4');
     });
   });
 });

package/tests/types.ts

@@ -0,0 +1,101 @@
+// Compile-time type tests — run with: npx tsc --noEmit
+// These tests validate TS generics 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';
+
+// --- component() infers schema fields ---
+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;
+
+// --- EntityManager typed methods ---
+const em = createEntityManager();
+const id: EntityId = em.createEntity();
+
+// addComponent: accepts correct data shape
+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
+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');
+
+// 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);
+});
+
+// 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); });
+
+// @ts-expect-error wrong data shape for Name
+em.addComponent(id, Name, { foo: 'bar' });
+
+// @ts-expect-error number not assignable to string field
+em.set(id, Name.name, 42);

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "strict": true,
+    "noEmit": true,
+    "moduleResolution": "node",
+    "module": "ESNext",
+    "target": "ESNext"
+  },
+  "include": ["tests/types.ts"]
+}