@codehz/ecs 0.8.2 → 0.10.0

package/src/__tests__/relations/{dont-fragment → sparse}/basic.test.ts

@@ -1,9 +1,10 @@
 import { describe, expect, it } from "bun:test";
 import { component, relation, type EntityId } from "../../../entity";
+import type { SyncDebugStats } from "../../../types";
 import { World } from "../../../world/world";
 
-describe("DontFragment Relations", () => {
-  it("should prevent archetype fragmentation for dontFragment relations", () => {
+describe("Sparse Relations", () => {
+  it("should prevent archetype fragmentation for sparse relations", () => {
     const world = new World();
 
     // Create component types
@@ -11,8 +12,11 @@ describe("DontFragment Relations", () => {
     const PositionId = component<Position>();
     const VelocityId = component();
 
-    // Create ChildOf with dontFragment option
-    const ChildOf = component({ dontFragment: true });
+    // Create ChildOf with sparse option
+    const ChildOf = component({ sparse: true });
+
+    const collected: SyncDebugStats[] = [];
+    using _collector = world.createDebugStatsCollector((s) => collected.push(s));
 
     // Create parent entities
     const parent1 = world.new();
@@ -37,20 +41,10 @@ describe("DontFragment Relations", () => {
 
     world.sync();
 
-    // Verify all children are in the same archetype
-    // This is the key benefit: despite having different parent relations,
-    // they share the same archetype because ChildOf is marked as dontFragment
-    const archetypes = (world as any).archetypes;
-
-    // Count archetypes with Position and Velocity
-    const matchingArchetypes = archetypes.filter((arch: any) => {
-      const types = arch.componentTypes;
-      return types.includes(PositionId) && types.includes(VelocityId);
-    });
-
-    // All three children should be in the SAME archetype
-    expect(matchingArchetypes.length).toBe(1);
-    expect(matchingArchetypes[0].size).toBe(3);
+    // Use debug stats to confirm low archetype count (no fragmentation)
+    const lastStats = collected[collected.length - 1]!;
+    // With sparse, 3 children + different parents should not explode archetype count
+    expect(lastStats.archetypes.total).toBeLessThanOrEqual(4);
 
     // Verify we can still access the relations
     expect(world.has(child1, relation(ChildOf, parent1))).toBe(true);
@@ -62,11 +56,11 @@ describe("DontFragment Relations", () => {
     expect(entities.length).toBe(3);
   });
 
-  it("should handle dontFragment relations with wildcard queries", () => {
+  it("should handle sparse relations with wildcard queries", () => {
     const world = new World();
 
     const PositionId = component();
-    const ChildOf = component({ dontFragment: true });
+    const ChildOf = component({ sparse: true });
 
     const parent1 = world.new();
     const parent2 = world.new();
@@ -81,7 +75,7 @@ describe("DontFragment Relations", () => {
 
     world.sync();
 
-    // Wildcard query should work with dontFragment relations
+    // Wildcard query should work with sparse relations
     const wildcardChildOf = relation(ChildOf, "*");
     const child1Relations = world.get(child1, wildcardChildOf);
     const child2Relations = world.get(child2, wildcardChildOf);
@@ -93,10 +87,10 @@ describe("DontFragment Relations", () => {
     expect(child2Relations[0]![0]).toBe(parent2);
   });
 
-  it("should allow updating dontFragment relations", () => {
+  it("should allow updating sparse relations", () => {
     const world = new World();
 
-    const ChildOf = component({ dontFragment: true, exclusive: true });
+    const ChildOf = component({ sparse: true, exclusive: true });
     const PositionId = component();
 
     const parent1 = world.new();
@@ -117,10 +111,10 @@ describe("DontFragment Relations", () => {
     expect(world.has(child, relation(ChildOf, parent2))).toBe(true);
   });
 
-  it("should handle removing dontFragment relations", () => {
+  it("should handle removing sparse relations", () => {
     const world = new World();
 
-    const ChildOf = component({ dontFragment: true });
+    const ChildOf = component({ sparse: true });
     const PositionId = component();
 
     const parent = world.new();
@@ -140,17 +134,20 @@ describe("DontFragment Relations", () => {
     expect(world.has(child, PositionId)).toBe(true);
   });
 
-  it("should handle queries with dontFragment relations", () => {
+  it("should handle queries with sparse relations", () => {
     const world = new World();
 
     const PositionId = component();
     const VelocityId = component();
-    const ChildOf = component({ dontFragment: true });
+    const ChildOf = component({ sparse: true });
+
+    const collected: SyncDebugStats[] = [];
+    using _collector = world.createDebugStatsCollector((s) => collected.push(s));
 
     const parent1 = world.new();
     const parent2 = world.new();
 
-    // Create entities with dontFragment relations
+    // Create entities with sparse relations
     for (let i = 0; i < 10; i++) {
       const entity = world.new();
       world.set(entity, PositionId);
@@ -165,19 +162,19 @@ describe("DontFragment Relations", () => {
     const entities = query.getEntities();
     expect(entities.length).toBe(10);
 
-    // All should be in the same archetype
-    const archetypes = (world as any).archetypes;
-    const matchingArchetypes = archetypes.filter((arch: any) => {
-      return arch.componentTypes.includes(PositionId) && arch.componentTypes.includes(VelocityId);
-    });
-    expect(matchingArchetypes.length).toBe(1);
+    // Use debug collector to verify we stayed in a single archetype despite 10 different parents
+    const stats = collected[collected.length - 1]!;
+    expect(stats.archetypes.total).toBeLessThanOrEqual(3);
   });
 
-  it("should compare fragmentation: with and without dontFragment", () => {
-    // Test WITHOUT dontFragment (causes fragmentation)
+  it("should compare fragmentation: with and without sparse", () => {
+    // Test WITHOUT sparse (causes fragmentation)
     const world1 = new World();
     const PositionId1 = component();
-    const ChildOf1 = component(); // No dontFragment
+    const ChildOf1 = component(); // No sparse
+
+    const stats1: SyncDebugStats[] = [];
+    using _collector1 = world1.createDebugStatsCollector((s) => stats1.push(s));
 
     for (let i = 0; i < 5; i++) {
       const parent = world1.new();
@@ -187,14 +184,13 @@ describe("DontFragment Relations", () => {
     }
     world1.sync();
 
-    const archetypes1 = (world1 as any).archetypes.filter((arch: any) => {
-      return arch.componentTypes.includes(PositionId1);
-    });
-
-    // Test WITH dontFragment (prevents fragmentation)
+    // Test WITH sparse (prevents fragmentation)
     const world2 = new World();
     const PositionId2 = component();
-    const ChildOf2 = component({ dontFragment: true }); // With dontFragment
+    const ChildOf2 = component({ sparse: true }); // With sparse
+
+    const stats2: SyncDebugStats[] = [];
+    using _collector2 = world2.createDebugStatsCollector((s) => stats2.push(s));
 
     for (let i = 0; i < 5; i++) {
       const parent = world2.new();
@@ -204,23 +200,22 @@ describe("DontFragment Relations", () => {
     }
     world2.sync();
 
-    const archetypes2 = (world2 as any).archetypes.filter((arch: any) => {
-      return arch.componentTypes.includes(PositionId2);
-    });
+    const last1 = stats1[stats1.length - 1]!;
+    const last2 = stats2[stats2.length - 1]!;
 
-    // Without dontFragment: 5 archetypes (one per parent)
-    expect(archetypes1.length).toBe(5);
+    // Without sparse: we expect significantly more archetypes created due to fragmentation
+    // (one per unique parent relation target)
+    expect(last1.archetypes.total).toBeGreaterThan(last2.archetypes.total);
 
-    // With dontFragment: 1 archetype (all children share it)
-    expect(archetypes2.length).toBe(1);
-    expect(archetypes2[0].size).toBe(5);
+    // With sparse: far fewer archetypes for the same number of entities
+    expect(last2.archetypes.total).toBeLessThanOrEqual(3); // entities + relations archetype(s)
   });
 
-  it("should query entities with wildcard relation on dontFragment component using createQuery", () => {
+  it("should query entities with wildcard relation on sparse component using createQuery", () => {
     const world = new World();
 
     const PositionId = component();
-    const ChildOf = component({ dontFragment: true });
+    const ChildOf = component({ sparse: true });
 
     const parent1 = world.new();
     const parent2 = world.new();
@@ -246,12 +241,12 @@ describe("DontFragment Relations", () => {
     expect(entities).toContain(child2);
   });
 
-  it("should query entities with wildcard relation + other components on dontFragment", () => {
+  it("should query entities with wildcard relation + other components on sparse", () => {
     const world = new World();
 
     const PositionId = component();
     const VelocityId = component();
-    const ChildOf = component({ dontFragment: true });
+    const ChildOf = component({ sparse: true });
 
     const parent1 = world.new();
     const parent2 = world.new();
@@ -285,17 +280,17 @@ describe("DontFragment Relations", () => {
     expect(entities).not.toContain(child3);
   });
 
-  it("should correctly cleanup dontFragment relations when target entity is destroyed", () => {
+  it("should correctly cleanup sparse relations when target entity is destroyed", () => {
     const world = new World();
 
     const PositionId = component();
     const VelocityId = component();
-    const ChildOf = component({ dontFragment: true });
+    const ChildOf = component({ sparse: true });
 
     const parent1 = world.new();
     const parent2 = world.new();
 
-    // Create children with dontFragment relations
+    // Create children with sparse relations
     const child1 = world.new();
     world.set(child1, PositionId);
     world.set(child1, VelocityId);
@@ -313,7 +308,7 @@ describe("DontFragment Relations", () => {
 
     world.sync();
 
-    // All children should be in the same archetype (due to dontFragment)
+    // All children should be in the same archetype (due to sparse)
     const archetypes = (world as any).archetypes;
     const matchingArchetypesBefore = archetypes.filter((arch: any) => {
       return arch.componentTypes.includes(PositionId) && arch.componentTypes.includes(VelocityId);
@@ -356,11 +351,11 @@ describe("DontFragment Relations", () => {
     expect(matchingArchetypesAfter.length).toBe(2);
   });
 
-  it("should not create new archetypes when removing dontFragment relation from entity", () => {
+  it("should not create new archetypes when removing sparse relation from entity", () => {
     const world = new World();
 
     const PositionId = component();
-    const ChildOf = component({ dontFragment: true });
+    const ChildOf = component({ sparse: true });
 
     const parent1 = world.new();
     const parent2 = world.new();
@@ -398,10 +393,10 @@ describe("DontFragment Relations", () => {
     }
   });
 
-  it("should trigger lifecycle hooks when dontFragment relations are removed due to entity destruction", () => {
+  it("should trigger lifecycle hooks when sparse relations are removed due to entity destruction", () => {
     const world = new World();
 
-    const ChildOf = component({ dontFragment: true });
+    const ChildOf = component({ sparse: true });
     const PositionId = component();
 
     const parent = world.new();
@@ -429,12 +424,12 @@ describe("DontFragment Relations", () => {
     expect(removedRelations[0]!.relations).toEqual([[parent, undefined]]);
   });
 
-  it("should handle cascade delete with dontFragment relations correctly", () => {
+  it("should handle cascade delete with sparse relations correctly", () => {
     const world = new World();
 
     const PositionId = component();
-    // Cascade delete AND dontFragment - when parent dies, children die too
-    const ChildOf = component({ dontFragment: true, cascadeDelete: true });
+    // Cascade delete AND sparse - when parent dies, children die too
+    const ChildOf = component({ sparse: true, cascadeDelete: true });
 
     const grandparent = world.new();
     const parent = world.new();
@@ -462,16 +457,16 @@ describe("DontFragment Relations", () => {
     expect(world.exists(child)).toBe(false);
   });
 
-  it("should maintain entity archetype integrity when removing dontFragment relations", () => {
+  it("should maintain entity archetype integrity when removing sparse relations", () => {
     const world = new World();
 
     const PositionId = component<{ x: number; y: number }>();
     const VelocityId = component<{ vx: number; vy: number }>();
-    const ChildOf = component({ dontFragment: true });
+    const ChildOf = component({ sparse: true });
 
     const parent = world.new();
 
-    // Create entity with components and dontFragment relation
+    // Create entity with components and sparse relation
     const entity = world.new();
     world.set(entity, PositionId, { x: 10, y: 20 });
     world.set(entity, VelocityId, { vx: 1, vy: 2 });

package/src/__tests__/relations/{dont-fragment → sparse}/query-notification.test.ts

@@ -1,14 +1,18 @@
 import { describe, expect, it } from "bun:test";
 import { component, relation } from "../../../entity";
+import type { SyncDebugStats } from "../../../types";
 import { World } from "../../../world/world";
 
-describe("DontFragment Query Notification Issue", () => {
-  it("should handle dontFragment wildcard queries and archetype lifecycle", () => {
+describe("Sparse Query Notification Issue", () => {
+  it("should handle sparse wildcard queries and archetype lifecycle", () => {
     const world = new World();
     const Position = component();
-    const ChildOf = component({ dontFragment: true });
+    const ChildOf = component({ sparse: true });
     const WildcardChildOf = relation(ChildOf, "*");
 
+    const collected: SyncDebugStats[] = [];
+    using _collector = world.createDebugStatsCollector((s) => collected.push(s));
+
     const query = world.createQuery([WildcardChildOf, Position]);
     expect(query.getEntities().length).toBe(0);
 
@@ -41,11 +45,15 @@ describe("DontFragment Query Notification Issue", () => {
     world.sync();
     expect(query.getEntities()).not.toContain(child1);
     expect((world as any).entityToArchetype.get(child1).componentTypes).not.toContain(WildcardChildOf);
+
+    // Debug stats should reflect archetype lifecycle changes from the wildcard marker add/remove
+    const lastStats = collected[collected.length - 1]!;
+    expect(lastStats.archetypes.total).toBeGreaterThanOrEqual(1);
   });
 
-  it("should handle exclusive dontFragment relations and specific target queries", () => {
+  it("should handle exclusive sparse relations and specific target queries", () => {
     const world = new World();
-    const ChildOf = component({ dontFragment: true, exclusive: true });
+    const ChildOf = component({ sparse: true, exclusive: true });
     const p1 = world.new();
     const p2 = world.new();
     const entity = world.new();
@@ -75,9 +83,9 @@ describe("DontFragment Query Notification Issue", () => {
     expect(wildcardQuery.getEntities()).toContain(entity);
   });
 
-  it("should handle multiple non-exclusive dontFragment relations", () => {
+  it("should handle multiple non-exclusive sparse relations", () => {
     const world = new World();
-    const Tag = component({ dontFragment: true });
+    const Tag = component({ sparse: true });
     const t1 = world.new();
     const t2 = world.new();
     const entity = world.new();
@@ -103,8 +111,8 @@ describe("DontFragment Query Notification Issue", () => {
 
   it("should correctly filter false positives in wildcard queries", () => {
     const world = new World();
-    const TagA = component({ dontFragment: true });
-    const TagB = component({ dontFragment: true });
+    const TagA = component({ sparse: true });
+    const TagB = component({ sparse: true });
     const p = world.new();
 
     const e1 = world.new();

package/src/__tests__/serialization/bounds.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "bun:test";
-import { component, type EntityId } from "../../entity";
+import { component, relation, type EntityId } from "../../entity";
+import { decodeSerializedId, encodeEntityId, encodeEntityIdCached } from "../../storage/serialization";
 import { World } from "../../world/world";
 
 describe("Serialization edge cases", () => {
@@ -234,4 +235,135 @@ describe("Serialization edge cases", () => {
     expect(newWorld.has(e3, Position)).toBe(false);
     expect(newWorld.get(e3, Velocity)).toEqual({ vx: 15 });
   });
+
+  it("should serialize and deserialize singleton components (covers componentEntities paths)", () => {
+    const world = new World();
+    const Config = component<{ debug: boolean }>();
+    world.singleton(Config).set({ debug: true });
+    world.sync();
+
+    const snapshot = world.serialize();
+    const restored = new World(snapshot);
+
+    expect(restored.has(Config)).toBe(true);
+    expect(restored.get(Config)).toEqual({ debug: true });
+  });
+
+  it("should round-trip anonymous (no-name) components in entity-relations and component-relations", () => {
+    const world = new World();
+    const A = component<{ v: number }>(); // anonymous -> triggers numeric fallback + warn paths
+    const B = component<string>(); // also anonymous for target in comp-rel
+    const e1 = world.new();
+    const e2 = world.new();
+    const relE = relation(A, e1);
+    const relC = relation(A, B);
+    world.set(e2, relE, { v: 42 });
+    world.set(e2, relC, { v: 99 });
+    world.sync();
+
+    const snap = world.serialize();
+    const r = new World(snap);
+
+    expect(r.has(e2, relE)).toBe(true);
+    expect(r.get(e2, relE)).toEqual({ v: 42 });
+    expect(r.has(e2, relC)).toBe(true);
+    expect(r.get(e2, relC)).toEqual({ v: 99 });
+  });
+
+  describe("Serialization ID codec (low-level, covers all decode/encode branches)", () => {
+    it("should exercise cache hit/miss and no-cache path in encodeEntityIdCached", () => {
+      const C = component<number>();
+      const cache = new Map();
+      const c1 = encodeEntityIdCached(C, cache);
+      const c2 = encodeEntityIdCached(C, cache);
+      expect(c2).toBe(c1); // hit
+      const noCache = encodeEntityIdCached(C); // else branch (no cache provided)
+      expect(noCache).toBeDefined();
+      // also wrapper
+      expect(encodeEntityId(C)).toBeDefined();
+    });
+
+    it("should round-trip all relation kinds including wildcard via encode/decode", () => {
+      const C = component<boolean>();
+      const E = 9999 as EntityId<any>;
+      const relE = relation(C, E);
+      const C2 = component<string>();
+      const relC = relation(C, C2);
+      const wild = relation(C, "*");
+
+      expect(decodeSerializedId(encodeEntityId(relE))).toBe(relE);
+      expect(decodeSerializedId(encodeEntityId(relC))).toBe(relC);
+      expect(decodeSerializedId(encodeEntityId(wild))).toBe(wild);
+    });
+
+    it("should hit numeric string fallbacks and all error throws in decode", () => {
+      const C1 = component<number>();
+      const C2 = component<string>();
+      const id1 = C1 as unknown as number;
+      const id2 = C2 as unknown as number;
+
+      // numeric fallback paths (when name lookup fails; use real allocated IDs as strings)
+      expect(decodeSerializedId(String(id1) as any)).toBe(id1 as any);
+      expect(decodeSerializedId({ component: String(id2), target: 99999 } as any)).toBeDefined(); // component-relation numeric fallback; creates valid relation(C2, fakeTarget)
+
+      // error paths (unknown names hit throws before relation() ctor)
+      expect(() => decodeSerializedId("TotallyUnknownName!!" as any)).toThrow(/Unknown component name in snapshot/);
+      expect(() => decodeSerializedId({ component: "BadName", target: 1 } as any)).toThrow(
+        /Unknown component name in snapshot/,
+      );
+      expect(() => decodeSerializedId({ component: "123", target: "BadTargetName" } as any)).toThrow(
+        /Unknown target component name in snapshot/,
+      );
+      expect(() => decodeSerializedId({ foo: "bar" } as any)).toThrow(/Invalid ID in snapshot/);
+    });
+  });
+
+  describe("Entity-ID-as-componentType references (ad-hoc entity refs)", () => {
+    it("should round-trip worlds using raw EntityIds as component types (covers 'entity' branch in deserialize reference tracking)", () => {
+      const world = new World();
+
+      const eTarget = world.new();
+      const eHolder = world.new();
+
+      // Use a raw entity ID (>= ENTITY_ID_START) directly as a component "type".
+      // This models an untyped/ad-hoc reference to another entity.
+      // The value is omitted (void presence-only component).
+      world.set(eHolder, eTarget as unknown as EntityId<any>);
+      world.sync();
+
+      const snapshot = world.serialize();
+      const restored = new World(snapshot);
+
+      expect(restored.exists(eTarget)).toBe(true);
+      expect(restored.exists(eHolder)).toBe(true);
+
+      // The ad-hoc component must survive the roundtrip.
+      expect(restored.has(eHolder, eTarget as unknown as EntityId<any>)).toBe(true);
+    });
+  });
+
+  describe("ComponentEntities deserialization guards", () => {
+    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.singleton(Config).set({ debug: true });
+      world.sync();
+
+      const snap: any = world.serialize();
+
+      // Inject a bogus entry: a high ordinary entity id (never a component entity)
+      const bogus = 123456 as EntityId;
+      snap.componentEntities = snap.componentEntities || [];
+      snap.componentEntities.push({
+        id: bogus,
+        components: [{ type: 99, value: "should-be-ignored" }],
+      });
+
+      const restored = new World(snap);
+
+      // Real singleton still works; bogus entry was skipped without error
+      expect(restored.has(Config)).toBe(true);
+      expect(restored.get(Config)).toEqual({ debug: true });
+    });
+  });
 });