@codehz/ecs 0.7.1 → 0.7.3

package/src/__tests__/commands/buffer.test.ts

@@ -0,0 +1,195 @@
+import { describe, expect, it } from "bun:test";
+import { CommandBuffer, type Command } from "../../commands/buffer";
+import type { EntityId } from "../../entity";
+
+describe("CommandBuffer", () => {
+  it("should buffer commands and execute them", () => {
+    const executedCommands: { entityId: EntityId; commands: Command[] }[] = [];
+
+    const mockExecutor = (entityId: EntityId, commands: Command[]) => {
+      executedCommands.push({ entityId, commands });
+    };
+
+    const buffer = new CommandBuffer(mockExecutor);
+
+    // Create mock entity IDs
+    const entity1 = 1 as EntityId;
+    const entity2 = 2 as EntityId;
+    const componentType1 = 100 as EntityId<any>;
+    const componentType2 = 200 as EntityId<any>;
+
+    // Add commands
+    buffer.set(entity1, componentType1, { x: 1 });
+    buffer.set(entity1, componentType2, { y: 2 });
+    buffer.remove(entity2, componentType1);
+
+    // Execute
+    buffer.execute();
+
+    // Verify execution
+    expect(executedCommands).toHaveLength(2);
+
+    // Check entity1 commands
+    const entity1Execution = executedCommands.find((e) => e.entityId === entity1);
+    expect(entity1Execution).toBeDefined();
+    if (entity1Execution) {
+      expect(entity1Execution.commands).toHaveLength(2);
+      expect(entity1Execution.commands[0]!.type).toBe("set");
+      expect(entity1Execution.commands[1]!.type).toBe("set");
+    }
+
+    // Check entity2 commands
+    const entity2Execution = executedCommands.find((e) => e.entityId === entity2);
+    expect(entity2Execution).toBeDefined();
+    if (entity2Execution) {
+      expect(entity2Execution.commands).toHaveLength(1);
+      expect(entity2Execution.commands[0]!.type).toBe("delete");
+    }
+
+    // Verify buffer is cleared
+    expect(buffer.getCommands()).toHaveLength(0);
+  });
+
+  it("should handle destroy commands", () => {
+    const executedCommands: { entityId: EntityId; commands: Command[] }[] = [];
+
+    const mockExecutor = (entityId: EntityId, commands: Command[]) => {
+      executedCommands.push({ entityId, commands });
+    };
+
+    const buffer = new CommandBuffer(mockExecutor);
+
+    const entity = 1 as EntityId;
+    const componentType = 100 as EntityId<any>;
+
+    // Add commands including destroy
+    buffer.set(entity, componentType, { x: 1 });
+    buffer.delete(entity);
+
+    buffer.execute();
+
+    // Should still execute (destroy logic is handled in the executor)
+    expect(executedCommands).toHaveLength(1);
+    const execution = executedCommands[0]!;
+    expect(execution.entityId).toBe(entity);
+    expect(execution.commands).toHaveLength(2);
+  });
+
+  it("should clear commands after execution", () => {
+    const mockExecutor = () => {};
+    const buffer = new CommandBuffer(mockExecutor);
+
+    const entity = 1 as EntityId;
+    const componentType = 100 as EntityId<any>;
+
+    buffer.set(entity, componentType, { x: 1 });
+    expect(buffer.getCommands()).toHaveLength(1);
+
+    buffer.execute();
+    expect(buffer.getCommands()).toHaveLength(0);
+  });
+
+  it("should allow manual clearing", () => {
+    const mockExecutor = () => {};
+    const buffer = new CommandBuffer(mockExecutor);
+
+    const entity = 1 as EntityId;
+    const componentType = 100 as EntityId<any>;
+
+    buffer.set(entity, componentType, { x: 1 });
+    expect(buffer.getCommands()).toHaveLength(1);
+
+    buffer.clear();
+    expect(buffer.getCommands()).toHaveLength(0);
+  });
+
+  it("should execute commands added during execution until queue is empty", () => {
+    const executedCommands: { entityId: EntityId; commands: Command[] }[] = [];
+
+    let bufferRef: CommandBuffer;
+    const mockExecutor = (entityId: EntityId, commands: Command[]) => {
+      executedCommands.push({ entityId, commands });
+
+      // If this is the first execution, add more commands
+      if (executedCommands.length === 1) {
+        const newEntity = 3 as EntityId;
+        const newComponentType = 300 as EntityId<any>;
+        bufferRef.set(newEntity, newComponentType, { z: 3 });
+      }
+    };
+
+    const buffer = new CommandBuffer(mockExecutor);
+    bufferRef = buffer;
+
+    const entity1 = 1 as EntityId;
+    const entity2 = 2 as EntityId;
+    const componentType1 = 100 as EntityId<any>;
+    const componentType2 = 200 as EntityId<any>;
+
+    // Add initial commands
+    buffer.set(entity1, componentType1, { x: 1 });
+    buffer.set(entity2, componentType2, { y: 2 });
+
+    // Execute
+    buffer.execute();
+
+    // Should have executed three times: entity1, entity2, and the new entity3
+    expect(executedCommands).toHaveLength(3);
+
+    // First execution: entity1
+    const entity1Execution = executedCommands.find((e) => e.entityId === entity1);
+    expect(entity1Execution).toBeDefined();
+    if (entity1Execution) {
+      expect(entity1Execution.commands).toHaveLength(1);
+      expect(entity1Execution.commands[0]!.type).toBe("set");
+    }
+
+    // Second execution: entity2
+    const entity2Execution = executedCommands.find((e) => e.entityId === entity2);
+    expect(entity2Execution).toBeDefined();
+    if (entity2Execution) {
+      expect(entity2Execution.commands).toHaveLength(1);
+      expect(entity2Execution.commands[0]!.type).toBe("set");
+    }
+
+    // Third execution: new entity
+    const entity3Execution = executedCommands.find((e) => e.entityId === (3 as EntityId));
+    expect(entity3Execution).toBeDefined();
+    if (entity3Execution) {
+      expect(entity3Execution.commands).toHaveLength(1);
+      expect(entity3Execution.commands[0]!.type).toBe("set");
+    }
+
+    // Buffer should be empty
+    expect(buffer.getCommands()).toHaveLength(0);
+  });
+
+  it("should throw error on infinite loop detection", () => {
+    const executedCommands: { entityId: EntityId; commands: Command[] }[] = [];
+
+    let bufferRef: CommandBuffer;
+    const mockExecutor = (entityId: EntityId, commands: Command[]) => {
+      executedCommands.push({ entityId, commands });
+
+      // Always add more commands to create infinite loop
+      const newEntity = (entityId + 1) as EntityId;
+      const newComponentType = 100 as EntityId<any>;
+      bufferRef.set(newEntity, newComponentType, { value: entityId });
+    };
+
+    const buffer = new CommandBuffer(mockExecutor);
+    bufferRef = buffer;
+
+    const entity = 1 as EntityId;
+    const componentType = 100 as EntityId<any>;
+
+    // Add initial command
+    buffer.set(entity, componentType, { x: 1 });
+
+    // Execute should throw error due to infinite loop
+    expect(() => buffer.execute()).toThrow("Command execution exceeded maximum iterations, possible infinite loop");
+
+    // Should have executed many times (up to MAX_ITERATIONS)
+    expect(executedCommands.length).toBeGreaterThan(0);
+  });
+});

package/src/__tests__/component/singleton.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, it } from "bun:test";
+import { component } from "../../entity";
+import { World } from "../../world/world";
+
+describe("World - Singleton Component", () => {
+  type GlobalConfig = { debug: boolean; version: string };
+  type GameState = { score: number; level: number };
+
+  const GlobalConfigId = component<GlobalConfig>();
+  const GameStateId = component<GameState>();
+
+  it("should set singleton component using shorthand syntax", () => {
+    const world = new World();
+    const config: GlobalConfig = { debug: true, version: "1.0.0" };
+
+    // Use singleton syntax: set(componentId, data)
+    world.set(GlobalConfigId, config);
+    world.sync();
+
+    // Verify it was set on the component entity itself
+    expect(world.has(GlobalConfigId)).toBe(true);
+    expect(world.get(GlobalConfigId)).toEqual(config);
+  });
+
+  it("should update singleton component using shorthand syntax", () => {
+    const world = new World();
+    const config1: GlobalConfig = { debug: true, version: "1.0.0" };
+    const config2: GlobalConfig = { debug: false, version: "2.0.0" };
+
+    world.set(GlobalConfigId, config1);
+    world.sync();
+    expect(world.get(GlobalConfigId)).toEqual(config1);
+
+    world.set(GlobalConfigId, config2);
+    world.sync();
+    expect(world.get(GlobalConfigId)).toEqual(config2);
+  });
+
+  it("should be equivalent to set(comp, comp, data)", () => {
+    const world1 = new World();
+    const world2 = new World();
+    const config: GlobalConfig = { debug: true, version: "1.0.0" };
+
+    // Singleton syntax
+    world1.set(GlobalConfigId, config);
+    world1.sync();
+
+    // Traditional syntax
+    world2.set(GlobalConfigId, GlobalConfigId, config);
+    world2.sync();
+
+    // Both should have the same result
+    expect(world1.get(GlobalConfigId)).toEqual(world2.get(GlobalConfigId));
+  });
+
+  it("should work with multiple singleton components", () => {
+    const world = new World();
+    const config: GlobalConfig = { debug: true, version: "1.0.0" };
+    const state: GameState = { score: 100, level: 5 };
+
+    world.set(GlobalConfigId, config);
+    world.set(GameStateId, state);
+    world.sync();
+
+    expect(world.get(GlobalConfigId)).toEqual(config);
+    expect(world.get(GameStateId)).toEqual(state);
+  });
+
+  it("should throw error if component entity does not exist", () => {
+    const world = new World();
+    const config: GlobalConfig = { debug: true, version: "1.0.0" };
+
+    // Try to set a component on an entity that doesn't exist
+    const nonExistentEntity = 99999 as any; // Use a fake entity ID
+    expect(() => {
+      world.set(nonExistentEntity, GlobalConfigId, config);
+    }).toThrow("does not exist");
+  });
+
+  it("should check singleton component existence using shorthand syntax", () => {
+    const world = new World();
+    const config: GlobalConfig = { debug: true, version: "1.0.0" };
+
+    // Before setting, should return false
+    expect(world.has(GlobalConfigId)).toBe(false);
+
+    // Set singleton component
+    world.set(GlobalConfigId, config);
+    world.sync();
+
+    // After setting, should return true
+    expect(world.has(GlobalConfigId)).toBe(true);
+  });
+
+  it("should be equivalent to has(comp, comp)", () => {
+    const world1 = new World();
+    const world2 = new World();
+    const config: GlobalConfig = { debug: true, version: "1.0.0" };
+
+    // Singleton syntax
+    world1.set(GlobalConfigId, config);
+    world1.sync();
+
+    // Traditional syntax
+    world2.set(GlobalConfigId, GlobalConfigId, config);
+    world2.sync();
+
+    // Both should have the same result
+    expect(world1.has(GlobalConfigId)).toBe(world2.has(GlobalConfigId, GlobalConfigId));
+    expect(world1.has(GlobalConfigId)).toBe(true);
+  });
+
+  it("should remove singleton component using shorthand syntax", () => {
+    const world = new World();
+    const config: GlobalConfig = { debug: true, version: "1.0.0" };
+
+    world.set(GlobalConfigId, config);
+    world.sync();
+    expect(world.has(GlobalConfigId)).toBe(true);
+
+    // Remove using singleton syntax
+    world.remove(GlobalConfigId);
+    world.sync();
+    expect(world.has(GlobalConfigId)).toBe(false);
+  });
+
+  it("should be equivalent to remove(comp, comp)", () => {
+    const world1 = new World();
+    const world2 = new World();
+    const config: GlobalConfig = { debug: true, version: "1.0.0" };
+
+    // Set on both worlds
+    world1.set(GlobalConfigId, config);
+    world1.sync();
+    world2.set(GlobalConfigId, GlobalConfigId, config);
+    world2.sync();
+
+    // Remove using different syntax
+    world1.remove(GlobalConfigId); // Singleton syntax
+    world2.remove(GlobalConfigId, GlobalConfigId); // Traditional syntax
+    world1.sync();
+    world2.sync();
+
+    // Both should have the same result
+    expect(world1.has(GlobalConfigId)).toBe(world2.has(GlobalConfigId, GlobalConfigId));
+    expect(world1.has(GlobalConfigId)).toBe(false);
+  });
+});

package/src/__tests__/core/archetype.test.ts

@@ -0,0 +1,247 @@
+import { describe, expect, it } from "bun:test";
+import { Archetype } from "../../archetype/archetype";
+import { component, createEntityId, relation, type EntityId } from "../../entity";
+
+describe("Archetype", () => {
+  type Position = { x: number; y: number };
+  type Velocity = { x: number; y: number };
+
+  const positionComponent = component<Position>();
+  const velocityComponent = component<Velocity>();
+
+  // Helper function to create a dontFragmentRelations map for testing
+  const createDontFragmentRelations = () => new Map<EntityId, Map<EntityId<any>, any>>();
+
+  it("should create an archetype with component types", () => {
+    const archetype = new Archetype([positionComponent, velocityComponent], createDontFragmentRelations());
+    expect(archetype.componentTypes).toEqual([positionComponent, velocityComponent]);
+    expect(archetype.size).toBe(0);
+  });
+
+  it("should match component types", () => {
+    const archetype = new Archetype([positionComponent, velocityComponent], createDontFragmentRelations());
+    expect(archetype.matches([positionComponent, velocityComponent])).toBe(true);
+    expect(archetype.matches([velocityComponent, positionComponent])).toBe(true); // Order doesn't matter
+    expect(archetype.matches([positionComponent])).toBe(false);
+  });
+
+  it("should add and remove entities", () => {
+    const archetype = new Archetype([positionComponent, velocityComponent], createDontFragmentRelations());
+    const entity1 = createEntityId(1024);
+    const entity2 = createEntityId(1025);
+
+    const componentData1 = new Map([
+      [positionComponent, { x: 0, y: 0 }],
+      [velocityComponent, { x: 1, y: 1 }],
+    ]);
+
+    const componentData2 = new Map([
+      [positionComponent, { x: 10, y: 10 }],
+      [velocityComponent, { x: 2, y: 2 }],
+    ]);
+
+    archetype.addEntity(entity1, componentData1);
+    expect(archetype.size).toBe(1);
+    expect(archetype.exists(entity1)).toBe(true);
+
+    archetype.addEntity(entity2, componentData2);
+    expect(archetype.size).toBe(2);
+    expect(archetype.exists(entity2)).toBe(true);
+
+    const removedData = archetype.removeEntity(entity1);
+    expect(archetype.size).toBe(1);
+    expect(archetype.exists(entity1)).toBe(false);
+    expect(removedData).toEqual(componentData1);
+  });
+
+  it("should get and set component data", () => {
+    const archetype = new Archetype([positionComponent], createDontFragmentRelations());
+    const entity = createEntityId(1024);
+    const initialPosition: Position = { x: 5, y: 5 };
+
+    archetype.addEntity(entity, new Map([[positionComponent, initialPosition]]));
+
+    const retrieved = archetype.get(entity, positionComponent);
+    expect(retrieved).toEqual(initialPosition);
+
+    const newPosition: Position = { x: 10, y: 10 };
+    archetype.set(entity, positionComponent, newPosition);
+    const retrieved2 = archetype.get(entity, positionComponent);
+    expect(retrieved2).toEqual(newPosition);
+  });
+
+  it("should get wildcard relation components", () => {
+    // Create relation component types
+    const target1 = createEntityId(1027);
+    const target2 = createEntityId(1028);
+    const relation1 = relation(positionComponent, target1);
+    const relation2 = relation(positionComponent, target2);
+    const wildcardPositionRelation = relation(positionComponent, "*");
+
+    const entity = createEntityId(1024);
+
+    // Archetype with multiple relations
+    const archetype = new Archetype([relation1, relation2], createDontFragmentRelations());
+
+    // Add entity with relations to target1 and target2
+    archetype.addEntity(
+      entity,
+      new Map([
+        [relation1, { distance: 10 }],
+        [relation2, { distance: 20 }],
+      ]),
+    );
+
+    // Get wildcard relations
+    const relations = archetype.get(entity, wildcardPositionRelation);
+    expect(relations).toEqual([
+      [target2, { distance: 20 }],
+      [target1, { distance: 10 }],
+    ]);
+
+    // Test with entity not in archetype
+    const nonExistentEntity = createEntityId(9999);
+    expect(() => archetype.get(nonExistentEntity, wildcardPositionRelation)).toThrow(
+      "Entity 9999 is not in this archetype",
+    );
+  });
+
+  it("should iterate over entities", () => {
+    const archetype = new Archetype([positionComponent], createDontFragmentRelations());
+    const entity1 = createEntityId(1024);
+    const entity2 = createEntityId(1025);
+
+    archetype.addEntity(entity1, new Map([[positionComponent, { x: 1, y: 1 }]]));
+    archetype.addEntity(entity2, new Map([[positionComponent, { x: 2, y: 2 }]]));
+
+    const iteratedEntities: EntityId[] = [];
+    archetype.forEach((entityId, _components) => {
+      iteratedEntities.push(entityId);
+    });
+
+    expect(iteratedEntities).toEqual([entity1, entity2]);
+  });
+
+  it("should get component data arrays", () => {
+    const archetype = new Archetype([positionComponent], createDontFragmentRelations());
+    const entity1 = createEntityId(1024);
+    const entity2 = createEntityId(1025);
+    const pos1: Position = { x: 1, y: 1 };
+    const pos2: Position = { x: 2, y: 2 };
+
+    archetype.addEntity(entity1, new Map([[positionComponent, pos1]]));
+    archetype.addEntity(entity2, new Map([[positionComponent, pos2]]));
+
+    const data = archetype.getComponentData(positionComponent);
+    expect(data).toEqual([pos1, pos2]);
+  });
+
+  it("should handle wildcard relations in forEachWithComponents", () => {
+    // Create a relation component type: position relation from entity to entity
+    const wildcardPositionRelation = relation(positionComponent, "*");
+
+    const entity1 = createEntityId(1024);
+    const entity2 = createEntityId(1025);
+    const target1 = createEntityId(1027);
+    const target2 = createEntityId(1028);
+
+    // Create specific relations for entity1 and entity2
+    const relation1 = relation(positionComponent, target1);
+    const relation2 = relation(positionComponent, target2);
+    const relation3 = relation(positionComponent, createEntityId(1029)); // For entity2
+
+    // Archetype with multiple relations
+    const archetype1 = new Archetype([relation1, relation2], createDontFragmentRelations());
+    const archetype2 = new Archetype([relation3], createDontFragmentRelations());
+
+    // Add entity1 with relations to target1 and target2
+    archetype1.addEntity(
+      entity1,
+      new Map([
+        [relation1, { distance: 10 }],
+        [relation2, { distance: 20 }],
+      ]),
+    );
+
+    // Add entity2 with relation to another target
+    archetype2.addEntity(entity2, new Map([[relation3, { distance: 30 }]]));
+
+    // Test forEachWithComponents with wildcard relation on archetype1
+    const results: Array<{ entity: EntityId; relations: [EntityId<any>, any][] }> = [];
+    archetype1.forEachWithComponents([wildcardPositionRelation], (entity, relations) => {
+      results.push({ entity, relations });
+    });
+
+    expect(results).toHaveLength(1);
+    expect(results[0]!.entity).toBe(entity1);
+    expect(results[0]!.relations).toEqual([
+      [target2, { distance: 20 }],
+      [target1, { distance: 10 }],
+    ]);
+
+    // Test on archetype2
+    const results2: Array<{ entity: EntityId; relations: [EntityId<any>, any][] }> = [];
+    archetype2.forEachWithComponents([wildcardPositionRelation], (entity, relations) => {
+      results2.push({ entity, relations });
+    });
+
+    expect(results2).toHaveLength(1);
+    expect(results2[0]!.entity).toBe(entity2);
+    expect(results2[0]!.relations).toEqual([[createEntityId(1029), { distance: 30 }]]);
+  });
+
+  it("should cache componentDataArrays correctly", () => {
+    // Test with wildcard relations to check cache invalidation
+    const target1 = createEntityId(1027);
+    const target2 = createEntityId(1028);
+    const relation1 = relation(positionComponent, target1);
+    const relation2 = relation(positionComponent, target2);
+    const wildcardPositionRelation = relation(positionComponent, "*");
+
+    const archetype = new Archetype([relation1, relation2], createDontFragmentRelations());
+
+    const entity1 = createEntityId(1024);
+
+    archetype.addEntity(
+      entity1,
+      new Map([
+        [relation1, { distance: 10 }],
+        [relation2, { distance: 20 }],
+      ]),
+    );
+
+    // First call - should compute and cache
+    let results1: [EntityId<any>, any][][] = [];
+    archetype.forEachWithComponents([wildcardPositionRelation], (_entity, relations) => {
+      results1.push(relations);
+    });
+    expect(results1[0]).toEqual([
+      [target2, { distance: 20 }],
+      [target1, { distance: 10 }],
+    ]);
+
+    // Second call - should use cache
+    let results2: [EntityId<any>, any][][] = [];
+    archetype.forEachWithComponents([wildcardPositionRelation], (_entity, relations) => {
+      results2.push(relations);
+    });
+    expect(results2[0]).toEqual([
+      [target2, { distance: 20 }],
+      [target1, { distance: 10 }],
+    ]);
+
+    // Modify data
+    (archetype as any).set(entity1, relation1, { distance: 100 });
+
+    // Third call - should still use cache (data is computed dynamically)
+    let results3: [EntityId<any>, any][][] = [];
+    archetype.forEachWithComponents([wildcardPositionRelation], (_entity, relations) => {
+      results3.push(relations);
+    });
+    // Since cache stores structure and data is computed dynamically, this should show updated data
+    expect(results3[0]).toEqual([
+      [target2, { distance: 20 }],
+      [target1, { distance: 100 }], // Updated
+    ]);
+  });
+});