@codehz/ecs 0.9.0 → 0.10.1

package/examples/spatial-grid.ts

@@ -216,7 +216,7 @@ function main() {
   console.log("=========================================================\n");
 
   // Create singleton SpatialGrid
-  world.set(SpatialGrid, { cells: new Map(), cellSize: 64 });
+  world.singleton(SpatialGrid).set({ cells: new Map(), cellSize: 64 });
   console.log("SpatialGrid singleton created (cellSize=64)");
 
   // Create 1 player near the center

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codehz/ecs",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "license": "MIT",
   "module": "src/index.ts",
   "type": "module",

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

@@ -3,6 +3,8 @@ import { ComponentEntityStore } from "../../component/entity-store";
 import { component, createEntityId, relation, type EntityId } from "../../entity";
 import { World } from "../../world/world";
 
+function expectType<T>(_value: T): void {}
+
 describe("World - Singleton Component", () => {
   type GlobalConfig = { debug: boolean; version: string };
   type GameState = { score: number; level: number };
@@ -10,29 +12,125 @@ describe("World - Singleton Component", () => {
   const GlobalConfigId = component<GlobalConfig>();
   const GameStateId = component<GameState>();
 
-  it("should set singleton component using shorthand syntax", () => {
+  it("should set singleton component through the explicit handle", () => {
     const world = new World();
     const config: GlobalConfig = { debug: true, version: "1.0.0" };
+    const singleton = world.singleton(GlobalConfigId);
 
-    // Use singleton syntax: set(componentId, data)
-    world.set(GlobalConfigId, config);
+    singleton.set(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", () => {
+  it("should interpret 2-argument set on a component entity as a void component set", () => {
+    const world = new World();
+    const singleton = world.singleton(GlobalConfigId);
+    const Marker = component<void>();
+    const originalWarn = console.warn;
+    const warnings: string[] = [];
+
+    console.warn = (...args: unknown[]) => {
+      warnings.push(args.join(" "));
+    };
+
+    try {
+      world.set(GlobalConfigId, Marker);
+    } finally {
+      console.warn = originalWarn;
+    }
+
+    world.sync();
+
+    expect(world.has(GlobalConfigId, Marker)).toBe(true);
+    expect(singleton.has()).toBe(false);
+    expect(warnings).toHaveLength(0);
+  });
+
+  it("should support the deprecated singleton data shorthand for non-number values", () => {
+    const world = new World();
+    const config: GlobalConfig = { debug: true, version: "1.0.0" };
+    const originalWarn = console.warn;
+    const warnings: string[] = [];
+
+    if (false) {
+      expectType<void>(world.set(GlobalConfigId, config));
+    }
+
+    console.warn = (...args: unknown[]) => {
+      warnings.push(args.join(" "));
+    };
+
+    try {
+      world.set(GlobalConfigId, config);
+    } finally {
+      console.warn = originalWarn;
+    }
+
+    world.sync();
+
+    expect(world.get(GlobalConfigId)).toEqual(config);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain("deprecated");
+    expect(warnings[0]).toContain("world.singleton(componentId).set(value)");
+  });
+
+  it("should not expose the deprecated shorthand for numeric singleton types at the type level", () => {
+    const world = new World();
+    const Score = component<number>();
+
+    if (false) {
+      // @ts-expect-error Numeric singleton shorthand is intentionally unsupported.
+      expectType<void>(world.set(Score, 123));
+    }
+
+    expect(true).toBe(true);
+  });
+
+  it("should manage singleton data through an explicit handle", () => {
+    const world = new World();
+    const config = world.singleton(GlobalConfigId);
+
+    expect(config.getOptional()).toBeUndefined();
+    expect(config.has()).toBe(false);
+
+    config.set({ debug: true, version: "1.0.0" });
+    world.sync();
+
+    expect(config.has()).toBe(true);
+    expect(config.get()).toEqual({ debug: true, version: "1.0.0" });
+
+    config.remove();
+    world.sync();
+
+    expect(config.has()).toBe(false);
+    expect(config.getOptional()).toBeUndefined();
+  });
+
+  it("should support void singleton components through an explicit handle", () => {
+    const world = new World();
+    const Tag = component<void>();
+    const tag = world.singleton(Tag);
+
+    tag.set();
+    world.sync();
+
+    expect(tag.has()).toBe(true);
+    expect(world.has(Tag)).toBe(true);
+  });
+
+  it("should update singleton component through the explicit handle", () => {
     const world = new World();
     const config1: GlobalConfig = { debug: true, version: "1.0.0" };
     const config2: GlobalConfig = { debug: false, version: "2.0.0" };
+    const singleton = world.singleton(GlobalConfigId);
 
-    world.set(GlobalConfigId, config1);
+    singleton.set(config1);
     world.sync();
     expect(world.get(GlobalConfigId)).toEqual(config1);
 
-    world.set(GlobalConfigId, config2);
+    singleton.set(config2);
     world.sync();
     expect(world.get(GlobalConfigId)).toEqual(config2);
   });
@@ -42,15 +140,12 @@ describe("World - Singleton Component", () => {
     const world2 = new World();
     const config: GlobalConfig = { debug: true, version: "1.0.0" };
 
-    // Singleton syntax
-    world1.set(GlobalConfigId, config);
+    world1.singleton(GlobalConfigId).set(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));
   });
 
@@ -59,8 +154,8 @@ describe("World - Singleton Component", () => {
     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.singleton(GlobalConfigId).set(config);
+    world.singleton(GameStateId).set(state);
     world.sync();
 
     expect(world.get(GlobalConfigId)).toEqual(config);
@@ -78,19 +173,17 @@ describe("World - Singleton Component", () => {
     }).toThrow("does not exist");
   });
 
-  it("should check singleton component existence using shorthand syntax", () => {
+  it("should check singleton component existence through the explicit handle", () => {
     const world = new World();
     const config: GlobalConfig = { debug: true, version: "1.0.0" };
+    const singleton = world.singleton(GlobalConfigId);
 
-    // Before setting, should return false
-    expect(world.has(GlobalConfigId)).toBe(false);
+    expect(singleton.has()).toBe(false);
 
-    // Set singleton component
-    world.set(GlobalConfigId, config);
+    singleton.set(config);
     world.sync();
 
-    // After setting, should return true
-    expect(world.has(GlobalConfigId)).toBe(true);
+    expect(singleton.has()).toBe(true);
   });
 
   it("should be equivalent to has(comp, comp)", () => {
@@ -98,29 +191,26 @@ describe("World - Singleton Component", () => {
     const world2 = new World();
     const config: GlobalConfig = { debug: true, version: "1.0.0" };
 
-    // Singleton syntax
-    world1.set(GlobalConfigId, config);
+    world1.singleton(GlobalConfigId).set(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", () => {
+  it("should remove singleton component through the explicit handle", () => {
     const world = new World();
     const config: GlobalConfig = { debug: true, version: "1.0.0" };
+    const singleton = world.singleton(GlobalConfigId);
 
-    world.set(GlobalConfigId, config);
+    singleton.set(config);
     world.sync();
     expect(world.has(GlobalConfigId)).toBe(true);
 
-    // Remove using singleton syntax
-    world.remove(GlobalConfigId);
+    singleton.remove();
     world.sync();
     expect(world.has(GlobalConfigId)).toBe(false);
   });
@@ -130,19 +220,16 @@ describe("World - Singleton Component", () => {
     const world2 = new World();
     const config: GlobalConfig = { debug: true, version: "1.0.0" };
 
-    // Set on both worlds
-    world1.set(GlobalConfigId, config);
+    world1.singleton(GlobalConfigId).set(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.singleton(GlobalConfigId).remove();
+    world2.remove(GlobalConfigId, GlobalConfigId);
     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__/serialization/bounds.test.ts

@@ -239,8 +239,7 @@ describe("Serialization edge cases", () => {
   it("should serialize and deserialize singleton components (covers componentEntities paths)", () => {
     const world = new World();
     const Config = component<{ debug: boolean }>();
-    // Singleton shorthand populates internal component entity
-    world.set(Config, { debug: true });
+    world.singleton(Config).set({ debug: true });
     world.sync();
 
     const snapshot = world.serialize();
@@ -347,7 +346,7 @@ describe("Serialization edge cases", () => {
     it("should ignore componentEntities snapshot entries whose id is not a real component entity (covers continue guard)", () => {
       const world = new World();
       const Config = component<{ debug: boolean }>();
-      world.set(Config, { debug: true });
+      world.singleton(Config).set({ debug: true });
       world.sync();
 
       const snap: any = world.serialize();

package/src/__tests__/world/component-management.test.ts

@@ -111,15 +111,16 @@ describe("World - Component Management", () => {
     const Inbox = component<string[]>({
       merge: (prev, next) => [...prev, ...next],
     });
+    const inbox = world.singleton(Inbox);
 
-    world.set(Inbox, ["A"]);
-    world.set(Inbox, ["B"]);
+    inbox.set(["A"]);
+    inbox.set(["B"]);
     world.sync();
     expect(world.get(Inbox)).toEqual(["A", "B"]);
 
-    world.remove(Inbox);
-    world.set(Inbox, ["C"]);
-    world.set(Inbox, ["D"]);
+    inbox.remove();
+    inbox.set(["C"]);
+    inbox.set(["D"]);
     world.sync();
     expect(world.get(Inbox)).toEqual(["C", "D"]);
   });

package/src/index.ts

@@ -32,6 +32,8 @@ export type {
 } from "./storage/serialization";
 export { EntityBuilder } from "./world/builder";
 export type { ComponentDef } from "./world/builder";
+export { SingletonHandle } from "./world/singleton";
+export type { SingletonHandleOps } from "./world/singleton";
 export { World } from "./world/world";
 
 // Query class

package/src/world/archetype-manager.ts

@@ -0,0 +1,283 @@
+import { Archetype } from "../archetype/archetype";
+import type { SparseStore } from "../archetype/store";
+import { normalizeComponentTypes } from "../component/type-utils";
+import type { EntityId } from "../entity";
+import {
+  getComponentIdFromRelationId,
+  getDetailedIdType,
+  isSparseRelation,
+  isSparseWildcard,
+  isWildcardRelationId,
+} from "../entity";
+import { matchesFilter } from "../query/filter";
+import type { QueryRegistry } from "../query/registry";
+import type { LifecycleHookEntry } from "../types";
+import { getOrCompute } from "../utils/utils";
+import { filterRegularComponentTypes } from "./commands";
+
+/**
+ * Context provided to ArchetypeManager for notifying dependent systems
+ * (query caching and lifecycle hooks) without creating tight coupling or cycles.
+ * Follows the same callback/context injection pattern used by CommandProcessorContext,
+ * HooksContext, and WorldDeserializationContext.
+ */
+export interface ArchetypeManagerContext {
+  queryRegistry: QueryRegistry;
+  hooks: Set<LifecycleHookEntry>;
+  /** Called only when debug collectors are active (mirrors original guard in World) */
+  recordArchetypeCreated?: () => void;
+  recordArchetypeRemoved?: () => void;
+}
+
+/**
+ * Encapsulates all archetype storage, indexing, creation, removal, and reverse
+ * referencing logic that was previously scattered as private methods + maps
+ * directly on the World class.
+ *
+ * Responsibilities:
+ * - Archetype memoization by signature
+ * - Component-type reverse index (archetypesByComponent)
+ * - Entity → current Archetype map
+ * - Reverse "who references this entity via component/relation" index
+ * - Creation + removal with proper notifications to QueryRegistry + hook matching
+ * - Cleanup of empty archetypes after entity cascades
+ *
+ * This extraction shrinks World while keeping the same behavior and hot-path characteristics.
+ */
+export class ArchetypeManager {
+  // Public for performance (hot paths access these maps frequently).
+  // This intentionally breaks encapsulation a bit for speed, as requested.
+  readonly archetypes: Archetype[] = [];
+  readonly archetypeBySignature = new Map<string, Archetype>();
+  readonly entityToArchetype = new Map<EntityId, Archetype>();
+  readonly archetypesByComponent = new Map<EntityId<any>, Set<Archetype>>();
+  readonly entityToReferencingArchetypes = new Map<EntityId, Set<Archetype>>();
+
+  private readonly sparseStore: SparseStore;
+  private readonly ctx: ArchetypeManagerContext;
+
+  constructor(ctx: ArchetypeManagerContext, sparseStore: SparseStore) {
+    this.ctx = ctx;
+    this.sparseStore = sparseStore;
+  }
+
+  // ------------------------------------------------------------------
+  // Public / package-internal surface used by World and its close collaborators
+  // (commands.ts applyChangeset, serialization deserialization context, etc.)
+  // ------------------------------------------------------------------
+
+  /** Primary entry point — memoized archetype creation/lookup. */
+  ensureArchetype(componentTypes: Iterable<EntityId<any>>): Archetype {
+    const regularTypes = filterRegularComponentTypes(componentTypes);
+    const sortedTypes = normalizeComponentTypes(regularTypes);
+    const hashKey = this.createArchetypeSignature(sortedTypes);
+
+    return getOrCompute(this.archetypeBySignature, hashKey, () => this.createNewArchetype(sortedTypes));
+  }
+
+  getArchetypeForEntity(entityId: EntityId): Archetype | undefined {
+    return this.entityToArchetype.get(entityId);
+  }
+
+  setEntityToArchetype(entityId: EntityId, archetype: Archetype): void {
+    this.entityToArchetype.set(entityId, archetype);
+  }
+
+  // Query helpers (moved from World for cohesion)
+  getMatchingArchetypes(componentTypes: EntityId<any>[]): Archetype[] {
+    if (componentTypes.length === 0) {
+      return [...this.archetypes];
+    }
+
+    const regularComponents: EntityId<any>[] = [];
+    const wildcardRelations: { componentId: EntityId<any>; relationId: EntityId<any> }[] = [];
+
+    for (const componentType of componentTypes) {
+      if (isWildcardRelationId(componentType)) {
+        const componentId = getComponentIdFromRelationId(componentType);
+        if (componentId !== undefined) {
+          wildcardRelations.push({ componentId, relationId: componentType });
+        }
+      } else {
+        regularComponents.push(componentType);
+      }
+    }
+
+    let matchingArchetypes = this.getArchetypesWithComponents(regularComponents);
+
+    for (const { componentId, relationId } of wildcardRelations) {
+      const markerSet = this.archetypesByComponent.get(relationId);
+      const archetypesWithMarker = markerSet ? Array.from(markerSet) : [];
+      matchingArchetypes =
+        matchingArchetypes.length === 0
+          ? archetypesWithMarker
+          : matchingArchetypes.filter((a) => markerSet?.has(a) || a.hasRelationWithComponentId(componentId));
+    }
+
+    return matchingArchetypes;
+  }
+
+  getArchetypesWithComponents(componentTypes: EntityId<any>[]): Archetype[] {
+    if (componentTypes.length === 0) return [...this.archetypes];
+    if (componentTypes.length === 1) {
+      const set = this.archetypesByComponent.get(componentTypes[0]!);
+      return set ? Array.from(set) : [];
+    }
+
+    // Sort by Set size, intersect starting from the smallest
+    const sets = componentTypes
+      .map((type) => this.archetypesByComponent.get(type))
+      .filter((s): s is Set<Archetype> => s !== undefined && s.size > 0)
+      .sort((a, b) => a.size - b.size);
+
+    if (sets.length === 0) return [];
+    if (sets.length < componentTypes.length) return []; // One component has no matching archetypes
+
+    const smallest = sets[0]!;
+
+    // 2-component fast path
+    if (sets.length === 2) {
+      const other = sets[1]!;
+      return Array.from(smallest).filter((a) => other.has(a));
+    }
+
+    // Multi-component intersection
+    let result = new Set(smallest);
+    for (let i = 1; i < sets.length; i++) {
+      for (const item of result) {
+        if (!sets[i]!.has(item)) result.delete(item);
+      }
+      if (result.size === 0) return [];
+    }
+    return Array.from(result);
+  }
+
+  // ------------------------------------------------------------------
+  // Internal creation / removal (core of the original cluster)
+  // ------------------------------------------------------------------
+
+  private createArchetypeSignature(componentTypes: EntityId<any>[]): string {
+    return componentTypes.join(",");
+  }
+
+  /** Deduplicated version of the original pair of methods. */
+  private updateReferencingIndex(componentType: EntityId<any>, archetype: Archetype, isAdd: boolean): void {
+    const detailedType = getDetailedIdType(componentType);
+    let entityId: EntityId | undefined;
+
+    if (detailedType.type === "entity") {
+      entityId = componentType as EntityId;
+    } else if (detailedType.type === "entity-relation") {
+      entityId = detailedType.targetId;
+    }
+
+    if (entityId !== undefined) {
+      let refs = this.entityToReferencingArchetypes.get(entityId);
+      if (isAdd) {
+        if (!refs) {
+          refs = new Set();
+          this.entityToReferencingArchetypes.set(entityId, refs);
+        }
+        refs.add(archetype);
+      } else {
+        if (refs) {
+          refs.delete(archetype);
+          if (refs.size === 0) {
+            this.entityToReferencingArchetypes.delete(entityId);
+          }
+        }
+      }
+    }
+  }
+
+  private createNewArchetype(componentTypes: EntityId<any>[]): Archetype {
+    const newArchetype = new Archetype(componentTypes, this.sparseStore);
+    this.archetypes.push(newArchetype);
+
+    this.ctx.recordArchetypeCreated?.();
+
+    for (const componentType of componentTypes) {
+      let archetypes = this.archetypesByComponent.get(componentType);
+      if (!archetypes) {
+        archetypes = new Set();
+        this.archetypesByComponent.set(componentType, archetypes);
+      }
+      archetypes.add(newArchetype);
+
+      // Update reverse index (deduped)
+      this.updateReferencingIndex(componentType, newArchetype, true);
+    }
+
+    this.ctx.queryRegistry.onNewArchetype(newArchetype);
+    this.updateArchetypeHookMatches(newArchetype);
+
+    return newArchetype;
+  }
+
+  private updateArchetypeHookMatches(archetype: Archetype): void {
+    for (const entry of this.ctx.hooks) {
+      if (this.archetypeMatchesHook(archetype, entry)) {
+        archetype.matchingMultiHooks.add(entry);
+        if (entry.matchedArchetypes) {
+          entry.matchedArchetypes.add(archetype);
+        }
+      }
+    }
+  }
+
+  public archetypeMatchesHook(archetype: Archetype, entry: LifecycleHookEntry): boolean {
+    return (
+      entry.requiredComponents.every((c: EntityId<any>) => {
+        if (isWildcardRelationId(c)) {
+          if (isSparseWildcard(c)) return true;
+          const componentId = getComponentIdFromRelationId(c);
+          return componentId !== undefined && archetype.hasRelationWithComponentId(componentId);
+        }
+        return archetype.componentTypeSet.has(c) || isSparseRelation(c);
+      }) && matchesFilter(archetype, entry.filter)
+    );
+  }
+
+  /** Called during cascade deletion cleanup. */
+  cleanupArchetypesReferencingEntity(entityId: EntityId): void {
+    const refs = this.entityToReferencingArchetypes.get(entityId);
+    if (!refs) return;
+
+    for (const archetype of refs) {
+      if (archetype.getEntities().length === 0) {
+        this.removeArchetype(archetype);
+      }
+    }
+    // removeArchetype already cleans up the reverse index entries for the archetypes themselves
+    this.entityToReferencingArchetypes.delete(entityId);
+  }
+
+  private removeArchetype(archetype: Archetype): void {
+    const index = this.archetypes.indexOf(archetype);
+    if (index !== -1) {
+      // swap-and-pop: O(1) removal
+      const last = this.archetypes[this.archetypes.length - 1]!;
+      this.archetypes[index] = last;
+      this.archetypes.pop();
+    }
+
+    this.ctx.recordArchetypeRemoved?.();
+
+    this.archetypeBySignature.delete(this.createArchetypeSignature(archetype.componentTypes));
+
+    for (const componentType of archetype.componentTypes) {
+      const archetypes = this.archetypesByComponent.get(componentType);
+      if (archetypes) {
+        archetypes.delete(archetype);
+        if (archetypes.size === 0) {
+          this.archetypesByComponent.delete(componentType);
+        }
+      }
+
+      // Clean up reverse index (deduped)
+      this.updateReferencingIndex(componentType, archetype, false);
+    }
+
+    this.ctx.queryRegistry.onArchetypeRemoved(archetype);
+  }
+}