archetype-ecs 1.2.0 → 1.3.2

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);
+// get/set: field descriptor access
+const px = em.get(id, Position.x);
 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); });
+// --- 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();

package/tsconfig.json

@@ -1,10 +1,13 @@
 {
   "compilerOptions": {
     "strict": true,
-    "noEmit": true,
-    "moduleResolution": "node",
-    "module": "ESNext",
-    "target": "ESNext"
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "skipLibCheck": true
   },
-  "include": ["tests/types.ts"]
+  "include": ["src/**/*.ts"]
 }

package/tsconfig.test.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "strict": true,
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "declaration": false,
+    "outDir": "dist-test",
+    "rootDir": ".",
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts"]
+}

package/.claude/settings.local.json

@@ -1,32 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(node /mnt/d/Projects/ECS/bench/vs-bitecs.js:*)",
-      "Bash(node:*)",
-      "Bash(npm test:*)",
-      "Bash(git add:*)",
-      "Bash(git commit -m \"$\\(cat <<''EOF''\nAdd getField/setField for zero-allocation field access with TS generics\n\ngetField and setField read/write individual component fields directly\nfrom TypedArrays without reconstructing an object. TypeScript generics\non component\\(\\) flow through to autocomplete field names and catch\ninvalid fields at compile time.\n\nCo-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>\nEOF\n\\)\")",
-      "Bash(git push:*)",
-      "Bash(git commit -m \"$\\(cat <<''EOF''\nAdd compile-time type tests for TS generics validation\n\ntests/types.ts validates that component\\(\\) schema inference flows\nthrough getField, setField, addComponent, and forEach field\\(\\) with\n@ts-expect-error assertions for invalid field names. npm test now\nruns both runtime tests and tsc --noEmit.\n\nCo-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>\nEOF\n\\)\")",
-      "Bash(git -C /mnt/d/Projects/ECS status)",
-      "Bash(git -C /mnt/d/Projects/ECS diff)",
-      "Bash(git -C /mnt/d/Projects/ECS log --oneline -5)",
-      "Bash(git -C /mnt/d/Projects/ECS add bench/typed-vs-bitecs-1m.js src/ComponentRegistry.js src/EntityManager.js src/index.d.ts src/index.js tests/EntityManager.test.js tests/types.ts)",
-      "Bash(git -C /mnt/d/Projects/ECS commit -m \"$\\(cat <<''EOF''\nAdd field descriptor API: Position.x instead of string literals\n\nComponent objects now have field descriptors as properties, enabling\nem.get\\(id, Position.x\\) / em.set\\(id, Position.x, 5\\) for zero-alloc\nfield access and arch.field\\(Position.x\\) in forEach hot loops.\n\n- component\\(\\) supports short form: component\\(''Pos'', ''f32'', [''x'',''y'']\\)\n- toSym\\(\\) helper normalizes component objects to underlying symbols\n- Updated TS types: ComponentDef<T> with FieldRef descriptors\n- All tests and benchmarks updated to new API\n\nCo-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>\nEOF\n\\)\")",
-      "Bash(wc:*)",
-      "Bash(git commit:*)",
-      "WebSearch",
-      "WebFetch(domain:github.com)",
-      "WebFetch(domain:www.webgamedev.com)",
-      "WebFetch(domain:3mcd.github.io)",
-      "WebFetch(domain:www.npmjs.com)",
-      "WebFetch(domain:raw.githubusercontent.com)",
-      "Bash(npm view:*)",
-      "Bash(npm pack:*)",
-      "Bash(curl:*)",
-      "Bash(npm install:*)",
-      "Bash(npm run bench:*)",
-      "Bash(FILTER_BRANCH_SQUELCH_WARNING=1 git filter-branch:*)"
-    ]
-  }
-}

package/src/ComponentRegistry.js

@@ -1,21 +0,0 @@
-export const TYPED = Symbol('typed');
-
-export const TYPE_MAP = {
-  'f32': Float32Array,
-  'f64': Float64Array,
-  'i8': Int8Array,
-  'i16': Int16Array,
-  'i32': Int32Array,
-  'u8': Uint8Array,
-  'u16': Uint16Array,
-  'u32': Uint32Array,
-  'string': Array,
-};
-
-/** @type {Map<symbol, Record<string, typeof Float32Array>>} */
-export const componentSchemas = new Map();
-
-/** Extract the underlying symbol from a component object or pass through a plain symbol */
-export function toSym(type) {
-  return type._sym || type;
-}