@codehz/ecs 0.8.1 → 0.9.0

package/src/__tests__/world/multi-component-hooks.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "bun:test";
 import { component, type EntityId } from "../../entity";
+import type { SyncDebugStats } from "../../types";
 import { World } from "../../world/world";
 
 describe("World - Multi-Component Hooks", () => {
@@ -11,6 +12,9 @@ describe("World - Multi-Component Hooks", () => {
     const setCalls: { entityId: EntityId; value: number }[] = [];
     const removeCalls: { entityId: EntityId; value: number }[] = [];
 
+    const collectedStats: SyncDebugStats[] = [];
+    using _collector = world.createDebugStatsCollector((stats) => collectedStats.push(stats));
+
     // First create an entity before registering the hook (for on_init test)
     const existingEntity = world.spawn().with(A, 100).build();
     world.sync();
@@ -64,6 +68,15 @@ describe("World - Multi-Component Hooks", () => {
     expect(removeCalls.length).toBe(2);
     expect(removeCalls[1]!.entityId).toBe(existingEntity);
     expect(removeCalls[1]!.value).toBe(100);
+
+    // Cross-verify with the new debug stats collector
+    const lastStats = collectedStats[collectedStats.length - 1];
+    expect(lastStats).toBeDefined();
+    expect(lastStats!.hooks.total).toBeGreaterThanOrEqual(1);
+    // Note: hooksExecuted counts individual invokeHook calls. The exact number
+    // can be lower than the sum of manual arrays depending on event paths.
+    // We only assert that at least some hook activity was recorded.
+    expect(lastStats!.activity.hooksExecuted).toBeGreaterThanOrEqual(1);
   });
 
   it("should throw error when hook has no required components (only optional)", () => {
@@ -499,4 +512,35 @@ describe("World - Multi-Component Hooks", () => {
     expect(world.has(entity1, A)).toBe(true);
     expect(world.has(entity2, A)).toBe(true);
   });
+
+  it("should support callback-style registration for multi-component hooks (set/remove)", () => {
+    const world = new World();
+    const A = component<number>();
+    const B = component<string>();
+
+    const calls: { event: string; entityId: EntityId; components: any[] }[] = [];
+
+    // Register callback-style hook *before* any entities to ensure runtime set/remove
+    // go through invokeHook's callback branch (init replay for existing bypasses invokeHook).
+    const unhook = world.hook([A, B], (event, entityId, a, b) => {
+      calls.push({ event, entityId, components: [a, b] });
+    });
+
+    // New entity after registration → "set" via normal trigger path + invokeHook(callback)
+    const e = world.spawn().with(A, 42).with(B, "hi").build();
+    world.sync();
+    expect(calls.some((c) => c.event === "set" && c.entityId === e)).toBe(true);
+
+    // Update also triggers set
+    world.set(e, A, 100);
+    world.sync();
+    expect(calls.some((c) => c.event === "set" && c.components[0] === 100)).toBe(true);
+
+    // Remove required component → "remove" via invokeHook(callback)
+    world.remove(e, A);
+    world.sync();
+    expect(calls.some((c) => c.event === "remove" && c.entityId === e)).toBe(true);
+
+    unhook();
+  });
 });

package/src/__tests__/world/serialize.test.ts

@@ -80,4 +80,21 @@ describe("World serialization", () => {
     const c = restored.new();
     expect(c).toBeGreaterThanOrEqual(b + 1);
   });
+
+  it("should serialize and deserialize component-relations", () => {
+    const world = new World();
+    const A = component<string>("A");
+    const B = component<number>("B");
+    const relAB = relation(A, B); // component-relation
+
+    const e = world.new();
+    world.set(e, relAB, "linked-via-comp");
+    world.sync();
+
+    const snapshot = world.serialize();
+    const restored = new World(snapshot);
+
+    expect(restored.has(e, relAB)).toBe(true);
+    expect(restored.get(e, relAB)).toBe("linked-via-comp");
+  });
 });

package/src/__tests__/world/wildcard-relation-hooks.test.ts

@@ -370,4 +370,131 @@ describe("Wildcard-Relation Hooks", () => {
     // It should still correctly report the actual removed relation
     expect(reportedRelations).toContainEqual([target, { value: "hello" }]);
   });
+
+  it("should correctly evaluate 'had before' for wildcard required component when removing a different required component", () => {
+    const world = new World();
+    const A = component<number>();
+    const RelData = component<{ value: string }>();
+    const target = world.new();
+    const wildcardRel = relation(RelData, "*");
+
+    const removeCalls: { entityId: EntityId; components: any }[] = [];
+
+    // Hook requires both A (regular) and wildcard relation
+    world.hook([A, wildcardRel], {
+      on_remove: (entityId, ...components) => {
+        removeCalls.push({ entityId, components });
+      },
+    });
+
+    const entity = world.spawn().with(A, 42).with(relation(RelData, target), { value: "hello" }).build();
+    world.sync();
+
+    // Remove the non-wildcard required component A.
+    // This exercises the path in entityHadAllComponentsBefore where for the wildcard
+    // required component, anyComponentMatches(removed, wildcard) is false (only A was removed),
+    // so we fall through to the isWildcard getOptional branch.
+    world.remove(entity, A);
+    world.sync();
+
+    expect(removeCalls.length).toBe(1);
+    expect(removeCalls[0]!.entityId).toBe(entity);
+    expect(removeCalls[0]!.components[0]).toBe(42);
+    expect(Array.isArray(removeCalls[0]!.components[1])).toBe(true);
+  });
+
+  it("should reconstruct optional wildcard relation data during on_remove of required component", () => {
+    const world = new World();
+    const A = component<number>();
+    const RelData = component<{ value: string }>();
+    const target = world.new();
+    const wildcardRel = relation(RelData, "*");
+
+    const removeCalls: { entityId: EntityId; components: any }[] = [];
+
+    // Required A + optional wildcard relation
+    world.hook([A, { optional: wildcardRel }], {
+      on_remove: (entityId, ...components) => {
+        removeCalls.push({ entityId, components });
+      },
+    });
+
+    const entity = world.spawn().with(A, 99).with(relation(RelData, target), { value: "secret" }).build();
+    world.sync();
+
+    // Removing A triggers on_remove for the hook (required lost).
+    // The collection for the optional wildcard must go through reconstructWildcardWithRemoved
+    // (the if isWildcardRelationId(optionalId) branch in collectMultiHookComponentsWithRemoved).
+    world.remove(entity, A);
+    world.sync();
+
+    expect(removeCalls.length).toBe(1);
+    expect(removeCalls[0]!.entityId).toBe(entity);
+    expect(removeCalls[0]!.components[0]).toBe(99);
+    // optional wildcard should have been reconstructed from the (now removed) data
+    const opt = removeCalls[0]!.components[1];
+    expect(opt).toBeDefined();
+    expect(Array.isArray(opt.value)).toBe(true);
+    expect(opt.value).toContainEqual([target, { value: "secret" }]);
+  });
+
+  it("should trigger on_remove via deletion fast-path for required wildcard relation hook", () => {
+    const world = new World();
+    const RelData = component<{ value: string }>();
+    const target = world.new();
+    const wildcardRel = relation(RelData, "*");
+
+    const removeCalls: { entityId: EntityId; relations: [EntityId, { value: string }][] }[] = [];
+
+    world.hook([wildcardRel], {
+      on_remove: (entityId, relations) => {
+        removeCalls.push({ entityId, relations });
+      },
+    });
+
+    const entity = world.spawn().with(relation(RelData, target), { value: "to-be-deleted" }).build();
+    world.sync();
+
+    // Directly delete the entity that owns the wildcard relation data.
+    // This exercises triggerRemoveHooksForEntityDeletion + collectComponentsFromRemoved
+    // + collectWildcardFromRemoved (required wildcard case).
+    world.delete(entity);
+    world.sync();
+
+    expect(removeCalls.length).toBe(1);
+    expect(removeCalls[0]!.entityId).toBe(entity);
+    expect(removeCalls[0]!.relations).toContainEqual([target, { value: "to-be-deleted" }]);
+  });
+
+  it("should trigger on_remove via deletion fast-path for optional wildcard in multi-hook", () => {
+    const world = new World();
+    const A = component<number>();
+    const RelData = component<{ value: string }>();
+    const target = world.new();
+    const wildcardRel = relation(RelData, "*");
+
+    const removeCalls: { entityId: EntityId; components: any }[] = [];
+
+    world.hook([A, { optional: wildcardRel }], {
+      on_remove: (entityId, ...components) => {
+        removeCalls.push({ entityId, components });
+      },
+    });
+
+    const entity = world.spawn().with(A, 123).with(relation(RelData, target), { value: "gone-soon" }).build();
+    world.sync();
+
+    // Delete the entity: fast path should use collectComponentsFromRemoved which handles
+    // optional wildcard via collectWildcardFromRemoved and returns { value: [...] } or undefined.
+    world.delete(entity);
+    world.sync();
+
+    expect(removeCalls.length).toBe(1);
+    expect(removeCalls[0]!.entityId).toBe(entity);
+    expect(removeCalls[0]!.components[0]).toBe(123);
+    const opt = removeCalls[0]!.components[1];
+    expect(opt).toBeDefined();
+    expect(Array.isArray(opt.value)).toBe(true);
+    expect(opt.value).toContainEqual([target, { value: "gone-soon" }]);
+  });
 });

package/src/archetype/archetype.ts

@@ -4,13 +4,14 @@ import {
   getComponentIdFromRelationId,
   getDetailedIdType,
   getIdType,
-  isDontFragmentComponent,
+  isSparseComponent,
   isWildcardRelationId,
 } from "../entity";
+import type { SerializedComponent, SerializedEntity, SerializedEntityId } from "../storage/serialization";
 import { isOptionalEntityId, type ComponentTuple, type ComponentType, type LifecycleHookEntry } from "../types";
 import { getOrCompute } from "../utils/utils";
 import { buildCacheKey, buildSingleComponent, getWildcardRelationDataSource, isRelationType } from "./helpers";
-import type { DontFragmentStore } from "./store";
+import type { SparseStore } from "./store";
 
 /**
  * Special value to represent missing component data
@@ -50,11 +51,10 @@ export class Archetype {
   private entityToIndex: Map<EntityId, number> = new Map();
 
   /**
-   * DontFragmentStore (keyed primarily by relation ComponentId).
-   * Uses optimized RelationEntry (single/multi) for the common exclusive case.
+   * SparseStore used for relations declared with `sparse: true`.
    * See store.ts for implementation details.
    */
-  private dontFragmentRelations: DontFragmentStore;
+  private sparseRelations: SparseStore;
 
   /**
    * Multi-hooks that match this archetype
@@ -66,10 +66,10 @@ export class Archetype {
    */
   private componentDataSourcesCache: Map<string, (any[] | EntityId<any>[] | undefined)[]> = new Map();
 
-  constructor(componentTypes: EntityId<any>[], dontFragmentRelations: DontFragmentStore) {
+  constructor(componentTypes: EntityId<any>[], sparseStore: SparseStore) {
     this.componentTypes = normalizeComponentTypes(componentTypes);
     this.componentTypeSet = new Set(this.componentTypes);
-    this.dontFragmentRelations = dontFragmentRelations;
+    this.sparseRelations = sparseStore;
 
     for (const componentType of this.componentTypes) {
       this.componentData.set(componentType, []);
@@ -107,17 +107,17 @@ export class Archetype {
       this.getComponentData(componentType).push(!componentData.has(componentType) ? MISSING_COMPONENT : data);
     }
 
-    // Add dontFragment relations separately
-    this.addDontFragmentRelations(entityId, componentData);
+    // Add sparse-stored relations separately
+    this.addSparseRelations(entityId, componentData);
   }
 
-  private addDontFragmentRelations(entityId: EntityId, componentData: Map<EntityId<any>, any>): void {
+  private addSparseRelations(entityId: EntityId, componentData: Map<EntityId<any>, any>): void {
     for (const [componentType, data] of componentData) {
       if (this.componentTypeSet.has(componentType)) continue;
 
       const detailedType = getDetailedIdType(componentType);
-      if (isRelationType(detailedType) && isDontFragmentComponent(detailedType.componentId!)) {
-        this.dontFragmentRelations.setValue(entityId, componentType, data);
+      if (isRelationType(detailedType) && isSparseComponent(detailedType.componentId!)) {
+        this.sparseRelations.setValue(entityId, componentType, data);
       }
     }
   }
@@ -134,9 +134,9 @@ export class Archetype {
       entityData.set(componentType, data === MISSING_COMPONENT ? undefined : data);
     }
 
-    // Add dontFragment relations
-    const dontFragmentTuples = this.dontFragmentRelations.getAllForEntity(entityId);
-    for (const [componentType, data] of dontFragmentTuples) {
+    // Add sparse-stored relations
+    const sparseTuples = this.sparseRelations.getAllForEntity(entityId);
+    for (const [componentType, data] of sparseTuples) {
       entityData.set(componentType, data);
     }
 
@@ -144,13 +144,11 @@ export class Archetype {
   }
 
   /**
-   * Returns all dontFragment relations for the given entity as an array of tuples.
-   * This is a compatibility adapter during the store refactor.
-   *
-   * Prefer the new DontFragmentStore methods when possible.
+   * Returns all sparse-stored relations for the given entity.
+   * Internal helper used by command processing and tests.
    */
-  getEntityDontFragmentRelations(entityId: EntityId): Map<EntityId<any>, any> | undefined {
-    const tuples = this.dontFragmentRelations.getAllForEntity(entityId);
+  getEntitySparseRelations(entityId: EntityId): Map<EntityId<any>, any> | undefined {
+    const tuples = this.sparseRelations.getAllForEntity(entityId);
     if (tuples.length === 0) return undefined;
 
     const map = new Map<EntityId<any>, any>();
@@ -169,8 +167,8 @@ export class Archetype {
         components.set(componentType, data === MISSING_COMPONENT ? undefined : data);
       }
 
-      const dontFragmentTuples = this.dontFragmentRelations.getAllForEntity(entity);
-      for (const [componentType, data] of dontFragmentTuples) {
+      const sparseTuples = this.sparseRelations.getAllForEntity(entity);
+      for (const [componentType, data] of sparseTuples) {
         components.set(componentType, data);
       }
 
@@ -178,6 +176,61 @@ export class Archetype {
     });
   }
 
+  /**
+   * @internal Serialization fast-path.
+   *
+   * Appends SerializedEntity records directly from the archetype's column storage
+   * (componentData arrays) plus sparse relations, avoiding per-entity Map
+   * allocation and repeated Array.from(entries()).
+   *
+   * Component type IDs should be pre-encoded by the caller (once per archetype)
+   * and passed in `encodedComponentTypes` (same order and length as this.componentTypes).
+   *
+   * The provided `encode` function should be the cached variant for best performance
+   * on entity IDs and any sparse relation type IDs.
+   *
+   * `sparseByEntity` is an optional pre-fetched map from a bulk
+   * `SparseStore.getAllForEntities` call (further reduces per-entity calls).
+   */
+  appendSerializedEntities(
+    out: SerializedEntity[],
+    encode: (id: EntityId<any>) => SerializedEntityId,
+    encodedComponentTypes: SerializedEntityId[],
+    sparseByEntity?: Map<EntityId, Array<[EntityId<any>, any]>>,
+  ): void {
+    if (encodedComponentTypes.length !== this.componentTypes.length) {
+      throw new Error("encodedComponentTypes length must match archetype componentTypes");
+    }
+
+    for (let i = 0; i < this.entities.length; i++) {
+      const entity = this.entities[i]!;
+
+      const components: SerializedComponent[] = [];
+      // Regular (non-sparse) components from column arrays
+      for (let c = 0; c < this.componentTypes.length; c++) {
+        const data = this.getComponentData(this.componentTypes[c]!)[i];
+        components.push({
+          type: encodedComponentTypes[c]!,
+          value: data === MISSING_COMPONENT ? undefined : data,
+        });
+      }
+
+      // Append any sparse relations for this entity (usually small or zero)
+      const sparseTuples = sparseByEntity?.get(entity) ?? this.sparseRelations.getAllForEntity(entity);
+      for (const [componentType, data] of sparseTuples) {
+        components.push({
+          type: encode(componentType),
+          value: data,
+        });
+      }
+
+      out.push({
+        id: encode(entity),
+        components,
+      });
+    }
+  }
+
   removeEntity(entityId: EntityId): Map<EntityId<any>, any> | undefined {
     const index = this.entityToIndex.get(entityId);
     if (index === undefined) return undefined;
@@ -188,12 +241,12 @@ export class Archetype {
       removedData.set(componentType, this.getComponentData(componentType)[index]);
     }
 
-    // Include dontFragment relations
-    const dontFragmentTuples = this.dontFragmentRelations.getAllForEntity(entityId);
-    for (const [componentType, data] of dontFragmentTuples) {
+    // Include sparse relations
+    const sparseTuples = this.sparseRelations.getAllForEntity(entityId);
+    for (const [componentType, data] of sparseTuples) {
       removedData.set(componentType, data);
     }
-    this.dontFragmentRelations.deleteEntity(entityId);
+    this.sparseRelations.deleteEntity(entityId);
 
     this.entityToIndex.delete(entityId);
 
@@ -257,9 +310,9 @@ export class Archetype {
       }
     }
 
-    // Check dontFragment relations (now uses the efficient per-component path)
+    // Check sparse relations (now uses the efficient per-component path)
     if (componentId !== undefined) {
-      const matches = this.dontFragmentRelations.getRelationsForComponent(entityId, componentId);
+      const matches = this.sparseRelations.getRelationsForComponent(entityId, componentId);
       for (const m of matches) relations.push(m);
     }
 
@@ -275,14 +328,11 @@ export class Archetype {
       return data as T;
     }
 
-    const value = this.dontFragmentRelations.getValue(entityId, componentType);
-    if (
-      value !== undefined ||
-      this.dontFragmentRelations.getAllForEntity(entityId).some(([t]) => t === componentType)
-    ) {
+    const value = this.sparseRelations.getValue(entityId, componentType);
+    if (value !== undefined || this.sparseRelations.getAllForEntity(entityId).some(([t]) => t === componentType)) {
       // Note: the extra check above handles the (rare) case where `undefined` is a legitimate stored value.
       // For the common case we just return whatever getValue gave us.
-      return this.dontFragmentRelations.getValue(entityId, componentType);
+      return this.sparseRelations.getValue(entityId, componentType);
     }
 
     throw new Error(`Component type ${componentType} not found for entity ${entityId}`);
@@ -300,14 +350,14 @@ export class Archetype {
       return { value: data as T };
     }
 
-    const value = this.dontFragmentRelations.getValue(entityId, componentType);
+    const value = this.sparseRelations.getValue(entityId, componentType);
     // We use getAllForEntity only as a presence check when the value itself might be undefined.
     if (value !== undefined) {
       return { value };
     }
-    const all = this.dontFragmentRelations.getAllForEntity(entityId);
+    const all = this.sparseRelations.getAllForEntity(entityId);
     if (all.some(([t]) => t === componentType)) {
-      return { value: this.dontFragmentRelations.getValue(entityId, componentType) };
+      return { value: this.sparseRelations.getValue(entityId, componentType) };
     }
     return undefined;
   }
@@ -324,8 +374,8 @@ export class Archetype {
     }
 
     const detailedType = getDetailedIdType(componentType);
-    if (isRelationType(detailedType) && isDontFragmentComponent(detailedType.componentId!)) {
-      this.dontFragmentRelations.setValue(entityId, componentType, data);
+    if (isRelationType(detailedType) && isSparseComponent(detailedType.componentId!)) {
+      this.sparseRelations.setValue(entityId, componentType, data);
       return;
     }
 
@@ -387,7 +437,7 @@ export class Archetype {
         entityIndex,
         entityId,
         (type) => this.getComponentData(type),
-        this.dontFragmentRelations,
+        this.sparseRelations,
       ),
     ) as ComponentTuple<T>;
   }
@@ -443,9 +493,9 @@ export class Archetype {
         components.set(componentType, data === MISSING_COMPONENT ? undefined : data);
       }
 
-      // Append dontFragment relations (Y-class path, acceptable cost)
-      const dontFragmentTuples = this.dontFragmentRelations.getAllForEntity(entity);
-      for (const [componentType, data] of dontFragmentTuples) {
+      // Append sparse relations (entity-wide enumeration; acceptable cost for forEach)
+      const sparseTuples = this.sparseRelations.getAllForEntity(entity);
+      for (const [componentType, data] of sparseTuples) {
         components.set(componentType, data);
       }
 
@@ -462,11 +512,11 @@ export class Archetype {
       }
     }
 
-    // Check dontFragment relations only for entities that actually belong to *this* archetype.
+    // Check sparse relations only for entities that actually belong to *this* archetype.
     // We must not use the global hasAnyForComponent here, otherwise unrelated archetypes
     // can be incorrectly pulled into wildcard queries when any entity in the world has the relation.
     for (const entityId of this.entities) {
-      const rels = this.dontFragmentRelations.getRelationsForComponent(entityId, componentId);
+      const rels = this.sparseRelations.getRelationsForComponent(entityId, componentId);
       if (rels.length > 0) {
         return true;
       }

package/src/archetype/helpers.ts

@@ -8,7 +8,7 @@ import {
 } from "../entity";
 import { isOptionalEntityId, type ComponentType } from "../types";
 import { MISSING_COMPONENT } from "./archetype";
-import type { DontFragmentStore } from "./store";
+import type { SparseStore } from "./store";
 
 type DetailedIdType = ReturnType<typeof getDetailedIdType>;
 
@@ -66,28 +66,6 @@ export function matchesRelationComponentId(componentType: EntityId<any>, compone
   return isRelationType(detailedType) && detailedType.componentId === componentId;
 }
 
-/**
- * Find all relations in dontFragment data that match a component ID.
- *
- * @deprecated Prefer calling `DontFragmentStore.getRelationsForComponent` directly.
- * This helper is kept temporarily for any remaining call sites during the refactor.
- */
-export function findMatchingDontFragmentRelations(
-  dontFragmentData: Map<EntityId<any>, any> | undefined,
-  componentId: EntityId<any>,
-  relations: [EntityId<unknown>, any][] = [],
-): [EntityId<unknown>, any][] {
-  if (!dontFragmentData) return relations;
-
-  for (const [relType, data] of dontFragmentData) {
-    const relDetailed = getDetailedIdType(relType);
-    if (isRelationType(relDetailed) && relDetailed.componentId === componentId) {
-      relations.push([relDetailed.targetId, data]);
-    }
-  }
-  return relations;
-}
-
 /**
  * Build cache key for component types
  */
@@ -109,13 +87,13 @@ export function getWildcardRelationDataSource(
 
 /**
  * Build wildcard relation value from matching relations.
- * Now receives the DontFragmentStore directly for efficient per-component lookups.
+ * Receives the SparseStore directly for efficient per-component lookups.
  */
 export function buildWildcardRelationValue(
   wildcardRelationType: WildcardRelationId<any>,
   matchingRelations: EntityId<any>[] | undefined,
   getDataAtIndex: (relType: EntityId<any>) => any,
-  dontFragmentStore: DontFragmentStore,
+  sparseStore: SparseStore,
   entityId: EntityId,
   optional: boolean,
 ): any {
@@ -129,9 +107,9 @@ export function buildWildcardRelationValue(
     relations.push([targetId, data === MISSING_COMPONENT ? undefined : data]);
   }
 
-  // Add dontFragment relations using the efficient store API (key win for X-class workload)
+  // Add sparse relations using the efficient store API (critical for wildcard query performance)
   if (targetComponentId !== undefined) {
-    const dfMatches = dontFragmentStore.getRelationsForComponent(entityId, targetComponentId);
+    const dfMatches = sparseStore.getRelationsForComponent(entityId, targetComponentId);
     for (const m of dfMatches) {
       relations.push(m);
     }
@@ -173,7 +151,7 @@ export function buildSingleComponent(
   entityIndex: number,
   entityId: EntityId,
   getComponentData: (type: EntityId<any>) => any[],
-  dontFragmentRelations: DontFragmentStore,
+  sparseRelations: SparseStore,
 ): any {
   const optional = isOptionalEntityId(compType);
   const actualType = optional ? compType.optional : compType;
@@ -183,7 +161,7 @@ export function buildSingleComponent(
       actualType as WildcardRelationId<any>,
       dataSource as EntityId<any>[] | undefined,
       (relType) => getComponentData(relType)[entityIndex],
-      dontFragmentRelations,
+      sparseRelations,
       entityId,
       optional,
     );