@codehz/ecs 0.8.2 → 0.10.0

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,
     );

package/src/archetype/store.ts

@@ -10,46 +10,49 @@ type RelationEntry =
   | { type: "multi"; targets: Map<EntityId, { relationType: EntityId<any>; data: any }> };
 
 /**
- * Interface for storing dontFragment relation data.
+ * Interface for the sparse side store used by components declared with `sparse: true`
+ * (or the legacy `dontFragment: true` alias).
  *
- * Storage is now primarily keyed by relation ComponentId (the "kind" of relation)
- * rather than by entity. This provides O(1) or near-O(1) answers for the hot
- * wildcard-related paths (hasRelationWithComponentId, wildcard materialization
- * during iteration, hook matching, etc.).
+ * Relation data for these components lives here instead of in archetype columns,
+ * preventing fragmentation for high-cardinality or frequently-changing relations.
  *
- * A lightweight reverse index (entity -> Set of base ComponentIds) is maintained
- * to efficiently support the infrequent "get all dontFragment data for this entity"
- * operations (removeEntity, dump, getEntity, serialization).
- *
- * The interface no longer leaks internal Map structures. Callers work with
- * semantic operations only.
+ * Storage is primarily keyed by base relation ComponentId. This enables efficient
+ * per-component lookups required by wildcard queries (relation(Comp, "*")) and
+ * archetype filtering, while still supporting full-entity enumeration when needed.
  */
-export interface DontFragmentStore {
-  // High-frequency operations (used by get/set/getOptional and structural changes)
+export interface SparseStore {
+  // High-frequency per-(entity, relation) operations (get/set/has/remove, structural changes)
   getValue(entityId: EntityId, relationType: EntityId<any>): any | undefined;
   setValue(entityId: EntityId, relationType: EntityId<any>, data: any): void;
   deleteValue(entityId: EntityId, relationType: EntityId<any>): boolean;
 
-  // Wildcard / filtering hot paths (X-class priority)
+  // Hot paths for wildcard queries and archetype filtering (per-component lookups)
   hasAnyForComponent(componentId: EntityId<any>): boolean;
   getRelationsForComponent(entityId: EntityId, componentId: EntityId<any>): [target: EntityId, data: any][];
 
-  // Low-frequency "get everything for entity" paths (Y-class, acceptable cost)
+  // Entity-wide enumeration paths (used for snapshots, serialization, forEach, and rare presence checks)
   getAllForEntity(entityId: EntityId): Array<[relationType: EntityId<any>, data: any]>;
   deleteEntity(entityId: EntityId): void;
+
+  /**
+   * @internal Bulk helper for serialization of many entities.
+   * Default implementation simply loops getAllForEntity; subclasses / future
+   * implementations can provide a more efficient fused walk.
+   */
+  getAllForEntities(entityIds: readonly EntityId[]): Map<EntityId, Array<[EntityId<any>, any]>>;
 }
 
 /**
- * Production implementation of DontFragmentStore.
+ * Production implementation of SparseStore.
  *
  * Internal layout (optimized):
  * - byComponent: baseComponentId → (entityId → RelationEntry)
  *   RelationEntry uses a single-value form for the common exclusive case (1 target),
- *   avoiding Map allocation entirely for the vast majority of dontFragment usage.
+ *   avoiding Map allocation for the vast majority of usage.
  * - entityIndex: entityId → Set<baseComponentId>
  *   Lightweight reverse index.
  */
-export class DontFragmentStoreImpl implements DontFragmentStore {
+export class SparseStoreImpl implements SparseStore {
   /**
    * Primary storage, keyed by the base relation component ID.
    */
@@ -60,7 +63,8 @@ export class DontFragmentStoreImpl implements DontFragmentStore {
 
   /**
    * Reverse index: which base component kinds an entity participates in.
-   * Used only by the infrequent getAllForEntity / deleteEntity paths.
+   * Only required to support getAllForEntity and deleteEntity efficiently.
+   * The primary storage (byComponent) is deliberately not optimized for these operations.
    */
   private entityIndex = new Map<EntityId, Set<EntityId<any>>>();
 
@@ -87,7 +91,7 @@ export class DontFragmentStoreImpl implements DontFragmentStore {
   setValue(entityId: EntityId, relationType: EntityId<any>, data: any): void {
     const componentId = getComponentIdFromRelationId(relationType);
     if (componentId === undefined) {
-      throw new Error("setValue called with a non-relation type on DontFragmentStore");
+      throw new Error("setValue called with a non-relation type on SparseStore");
     }
 
     let entities = this.byComponent.get(componentId);
@@ -237,4 +241,15 @@ export class DontFragmentStoreImpl implements DontFragmentStore {
 
     this.entityIndex.delete(entityId);
   }
+
+  getAllForEntities(entityIds: readonly EntityId[]): Map<EntityId, Array<[EntityId<any>, any]>> {
+    const result = new Map<EntityId, Array<[EntityId<any>, any]>>();
+    for (const eid of entityIds) {
+      const data = this.getAllForEntity(eid);
+      if (data.length > 0) {
+        result.set(eid, data);
+      }
+    }
+    return result;
+  }
 }

package/src/commands/buffer.ts

@@ -55,9 +55,10 @@ export class CommandBuffer {
   }
 
   /**
-   * Execute all commands and clear the buffer
+   * Execute all commands and clear the buffer.
+   * Returns the number of iterations performed (for debug stats).
    */
-  execute(): void {
+  execute(): number {
     let iterations = 0;
 
     while (this.commands.length > 0) {
@@ -92,6 +93,8 @@ export class CommandBuffer {
       }
       entityCommands.clear();
     }
+
+    return iterations;
   }
 
   /**

package/src/commands/changeset.ts

@@ -70,35 +70,4 @@ export class ComponentChangeset {
 
     return existingComponents;
   }
-
-  /**
-   * Get the final component types after applying the changeset
-   * @param existingComponentTypes - The current component types on the entity
-   * @returns The final component types or undefined if no changes
-   */
-  getFinalComponentTypes(existingComponentTypes: EntityId<any>[]): EntityId<any>[] | undefined {
-    const finalComponentTypes = new Set<EntityId<any>>(existingComponentTypes);
-    let changed = false;
-
-    // Apply removals
-    for (const componentType of this.removes) {
-      if (!finalComponentTypes.has(componentType)) {
-        this.removes.delete(componentType);
-        continue; // Component not present, skip
-      }
-      changed = true;
-      finalComponentTypes.delete(componentType);
-    }
-
-    // Apply additions
-    for (const componentType of this.adds.keys()) {
-      if (finalComponentTypes.has(componentType)) {
-        continue; // Component already present, skip
-      }
-      changed = true;
-      finalComponentTypes.add(componentType);
-    }
-
-    return changed ? Array.from(finalComponentTypes) : undefined;
-  }
 }