@codehz/ecs 0.8.0 → 0.8.1

package/src/archetype/archetype.ts

@@ -9,13 +9,7 @@ import {
 } from "../entity";
 import { isOptionalEntityId, type ComponentTuple, type ComponentType, type LifecycleHookEntry } from "../types";
 import { getOrCompute } from "../utils/utils";
-import {
-  buildCacheKey,
-  buildSingleComponent,
-  findMatchingDontFragmentRelations,
-  getWildcardRelationDataSource,
-  isRelationType,
-} from "./helpers";
+import { buildCacheKey, buildSingleComponent, getWildcardRelationDataSource, isRelationType } from "./helpers";
 import type { DontFragmentStore } from "./store";
 
 /**
@@ -56,9 +50,9 @@ export class Archetype {
   private entityToIndex: Map<EntityId, number> = new Map();
 
   /**
-   * DontFragmentStore for relation data keyed by entity ID.
-   * This allows entities with different relation targets to share the same archetype
-   * without migration overhead when entities change archetypes.
+   * DontFragmentStore (keyed primarily by relation ComponentId).
+   * Uses optimized RelationEntry (single/multi) for the common exclusive case.
+   * See store.ts for implementation details.
    */
   private dontFragmentRelations: DontFragmentStore;
 
@@ -118,20 +112,14 @@ export class Archetype {
   }
 
   private addDontFragmentRelations(entityId: EntityId, componentData: Map<EntityId<any>, any>): void {
-    const dontFragmentData = new Map<EntityId<any>, any>();
-
     for (const [componentType, data] of componentData) {
       if (this.componentTypeSet.has(componentType)) continue;
 
       const detailedType = getDetailedIdType(componentType);
       if (isRelationType(detailedType) && isDontFragmentComponent(detailedType.componentId!)) {
-        dontFragmentData.set(componentType, data);
+        this.dontFragmentRelations.setValue(entityId, componentType, data);
       }
     }
-
-    if (dontFragmentData.size > 0) {
-      this.dontFragmentRelations.set(entityId, dontFragmentData);
-    }
   }
 
   getEntity(entityId: EntityId): Map<EntityId<any>, any> | undefined {
@@ -147,18 +135,29 @@ export class Archetype {
     }
 
     // Add dontFragment relations
-    const dontFragmentData = this.dontFragmentRelations.get(entityId);
-    if (dontFragmentData) {
-      for (const [componentType, data] of dontFragmentData) {
-        entityData.set(componentType, data);
-      }
+    const dontFragmentTuples = this.dontFragmentRelations.getAllForEntity(entityId);
+    for (const [componentType, data] of dontFragmentTuples) {
+      entityData.set(componentType, data);
     }
 
     return entityData;
   }
 
+  /**
+   * 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.
+   */
   getEntityDontFragmentRelations(entityId: EntityId): Map<EntityId<any>, any> | undefined {
-    return this.dontFragmentRelations.get(entityId);
+    const tuples = this.dontFragmentRelations.getAllForEntity(entityId);
+    if (tuples.length === 0) return undefined;
+
+    const map = new Map<EntityId<any>, any>();
+    for (const [relType, data] of tuples) {
+      map.set(relType, data);
+    }
+    return map;
   }
 
   dump(): Array<{ entity: EntityId; components: Map<EntityId<any>, any> }> {
@@ -170,11 +169,9 @@ export class Archetype {
         components.set(componentType, data === MISSING_COMPONENT ? undefined : data);
       }
 
-      const dontFragmentData = this.dontFragmentRelations.get(entity);
-      if (dontFragmentData) {
-        for (const [componentType, data] of dontFragmentData) {
-          components.set(componentType, data);
-        }
+      const dontFragmentTuples = this.dontFragmentRelations.getAllForEntity(entity);
+      for (const [componentType, data] of dontFragmentTuples) {
+        components.set(componentType, data);
       }
 
       return { entity, components };
@@ -192,13 +189,11 @@ export class Archetype {
     }
 
     // Include dontFragment relations
-    const dontFragmentData = this.dontFragmentRelations.get(entityId);
-    if (dontFragmentData) {
-      for (const [componentType, data] of dontFragmentData) {
-        removedData.set(componentType, data);
-      }
-      this.dontFragmentRelations.delete(entityId);
+    const dontFragmentTuples = this.dontFragmentRelations.getAllForEntity(entityId);
+    for (const [componentType, data] of dontFragmentTuples) {
+      removedData.set(componentType, data);
     }
+    this.dontFragmentRelations.deleteEntity(entityId);
 
     this.entityToIndex.delete(entityId);
 
@@ -262,9 +257,10 @@ export class Archetype {
       }
     }
 
-    // Check dontFragment relations
+    // Check dontFragment relations (now uses the efficient per-component path)
     if (componentId !== undefined) {
-      findMatchingDontFragmentRelations(this.dontFragmentRelations.get(entityId), componentId, relations);
+      const matches = this.dontFragmentRelations.getRelationsForComponent(entityId, componentId);
+      for (const m of matches) relations.push(m);
     }
 
     return relations;
@@ -279,9 +275,14 @@ export class Archetype {
       return data as T;
     }
 
-    const dontFragmentData = this.dontFragmentRelations.get(entityId);
-    if (dontFragmentData?.has(componentType)) {
-      return dontFragmentData.get(componentType);
+    const value = this.dontFragmentRelations.getValue(entityId, componentType);
+    if (
+      value !== undefined ||
+      this.dontFragmentRelations.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);
     }
 
     throw new Error(`Component type ${componentType} not found for entity ${entityId}`);
@@ -299,11 +300,15 @@ export class Archetype {
       return { value: data as T };
     }
 
-    const dontFragmentData = this.dontFragmentRelations.get(entityId);
-    if (dontFragmentData?.has(componentType)) {
-      return { value: dontFragmentData.get(componentType) };
+    const value = this.dontFragmentRelations.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);
+    if (all.some(([t]) => t === componentType)) {
+      return { value: this.dontFragmentRelations.getValue(entityId, componentType) };
     }
-
     return undefined;
   }
 
@@ -320,12 +325,7 @@ export class Archetype {
 
     const detailedType = getDetailedIdType(componentType);
     if (isRelationType(detailedType) && isDontFragmentComponent(detailedType.componentId!)) {
-      let dontFragmentData = this.dontFragmentRelations.get(entityId);
-      if (!dontFragmentData) {
-        dontFragmentData = new Map();
-        this.dontFragmentRelations.set(entityId, dontFragmentData);
-      }
-      dontFragmentData.set(componentType, data);
+      this.dontFragmentRelations.setValue(entityId, componentType, data);
       return;
     }
 
@@ -436,12 +436,20 @@ export class Archetype {
 
   forEach(callback: (entityId: EntityId, components: Map<EntityId<any>, any>) => void): void {
     for (let i = 0; i < this.entities.length; i++) {
+      const entity = this.entities[i]!;
       const components = new Map<EntityId<any>, any>();
       for (const componentType of this.componentTypes) {
         const data = this.getComponentData(componentType)[i];
         components.set(componentType, data === MISSING_COMPONENT ? undefined : data);
       }
-      callback(this.entities[i]!, components);
+
+      // Append dontFragment relations (Y-class path, acceptable cost)
+      const dontFragmentTuples = this.dontFragmentRelations.getAllForEntity(entity);
+      for (const [componentType, data] of dontFragmentTuples) {
+        components.set(componentType, data);
+      }
+
+      callback(entity, components);
     }
   }
 
@@ -454,19 +462,15 @@ export class Archetype {
       }
     }
 
-    // Check dontFragment relations
+    // Check dontFragment 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 entityDontFragmentRelations = this.dontFragmentRelations.get(entityId);
-      if (entityDontFragmentRelations) {
-        for (const relationType of entityDontFragmentRelations.keys()) {
-          const detailedType = getDetailedIdType(relationType);
-          if (isRelationType(detailedType) && detailedType.componentId === componentId) {
-            return true;
-          }
-        }
+      const rels = this.dontFragmentRelations.getRelationsForComponent(entityId, componentId);
+      if (rels.length > 0) {
+        return true;
       }
     }
-
     return false;
   }
 }

package/src/archetype/helpers.ts

@@ -67,7 +67,10 @@ export function matchesRelationComponentId(componentType: EntityId<any>, compone
 }
 
 /**
- * Find all relations in dontFragment data that match a component ID
+ * 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,
@@ -105,13 +108,14 @@ export function getWildcardRelationDataSource(
 }
 
 /**
- * Build wildcard relation value from matching relations
+ * Build wildcard relation value from matching relations.
+ * Now receives the DontFragmentStore directly for efficient per-component lookups.
  */
 export function buildWildcardRelationValue(
   wildcardRelationType: WildcardRelationId<any>,
   matchingRelations: EntityId<any>[] | undefined,
   getDataAtIndex: (relType: EntityId<any>) => any,
-  dontFragmentData: Map<EntityId<any>, any> | undefined,
+  dontFragmentStore: DontFragmentStore,
   entityId: EntityId,
   optional: boolean,
 ): any {
@@ -125,9 +129,12 @@ export function buildWildcardRelationValue(
     relations.push([targetId, data === MISSING_COMPONENT ? undefined : data]);
   }
 
-  // Add dontFragment relations
+  // Add dontFragment relations using the efficient store API (key win for X-class workload)
   if (targetComponentId !== undefined) {
-    findMatchingDontFragmentRelations(dontFragmentData, targetComponentId, relations);
+    const dfMatches = dontFragmentStore.getRelationsForComponent(entityId, targetComponentId);
+    for (const m of dfMatches) {
+      relations.push(m);
+    }
   }
 
   if (relations.length === 0) {
@@ -176,7 +183,7 @@ export function buildSingleComponent(
       actualType as WildcardRelationId<any>,
       dataSource as EntityId<any>[] | undefined,
       (relType) => getComponentData(relType)[entityIndex],
-      dontFragmentRelations.get(entityId),
+      dontFragmentRelations,
       entityId,
       optional,
     );

package/src/archetype/store.ts

@@ -1,33 +1,240 @@
 import type { EntityId } from "../entity";
+import { getComponentIdFromRelationId, getTargetIdFromRelationId } from "../entity";
 
 /**
- * Minimal interface for storing dontFragment relation data keyed by entity ID.
+ * Internal representation for the relations an entity has under one component kind.
+ * 'single' is the optimized form for exclusive relations (vast majority of cases).
+ */
+type RelationEntry =
+  | { type: "single"; relationType: EntityId<any>; target: EntityId; data: any }
+  | { type: "multi"; targets: Map<EntityId, { relationType: EntityId<any>; data: any }> };
+
+/**
+ * Interface for storing dontFragment relation data.
  *
- * Using an interface here decouples `Archetype` (and `world-commands.ts`) from
- * the concrete `Map` used by `World`, making archetypes independently testable.
+ * 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.).
+ *
+ * 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.
  */
 export interface DontFragmentStore {
-  get(entityId: EntityId): Map<EntityId<any>, any> | undefined;
-  set(entityId: EntityId, data: Map<EntityId<any>, any>): void;
-  delete(entityId: EntityId): void;
+  // High-frequency operations (used by get/set/getOptional and 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)
+  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)
+  getAllForEntity(entityId: EntityId): Array<[relationType: EntityId<any>, data: any]>;
+  deleteEntity(entityId: EntityId): void;
 }
 
 /**
- * Default implementation backed by a plain `Map`.
- * Created once by `World` and shared with every `Archetype`.
+ * Production implementation of DontFragmentStore.
+ *
+ * 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.
+ * - entityIndex: entityId → Set<baseComponentId>
+ *   Lightweight reverse index.
  */
 export class DontFragmentStoreImpl implements DontFragmentStore {
-  private readonly data: Map<EntityId, Map<EntityId<any>, any>> = new Map();
+  /**
+   * Primary storage, keyed by the base relation component ID.
+   */
+  private byComponent = new Map<
+    EntityId<any>, // base componentId
+    Map<EntityId, RelationEntry>
+  >();
+
+  /**
+   * Reverse index: which base component kinds an entity participates in.
+   * Used only by the infrequent getAllForEntity / deleteEntity paths.
+   */
+  private entityIndex = new Map<EntityId, Set<EntityId<any>>>();
+
+  getValue(entityId: EntityId, relationType: EntityId<any>): any | undefined {
+    const componentId = getComponentIdFromRelationId(relationType);
+    if (componentId === undefined) return undefined;
+
+    const entities = this.byComponent.get(componentId);
+    if (!entities) return undefined;
 
-  get(entityId: EntityId): Map<EntityId<any>, any> | undefined {
-    return this.data.get(entityId);
+    const entry = entities.get(entityId);
+    if (!entry) return undefined;
+
+    const targetId = getTargetIdFromRelationId(relationType)!;
+
+    if (entry.type === "single") {
+      return entry.target === targetId ? entry.data : undefined;
+    } else {
+      const item = entry.targets.get(targetId);
+      return item ? item.data : undefined;
+    }
   }
 
-  set(entityId: EntityId, data: Map<EntityId<any>, any>): void {
-    this.data.set(entityId, data);
+  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");
+    }
+
+    let entities = this.byComponent.get(componentId);
+    if (!entities) {
+      entities = new Map();
+      this.byComponent.set(componentId, entities);
+    }
+
+    const targetId = getTargetIdFromRelationId(relationType)!;
+    let entry = entities.get(entityId);
+
+    if (!entry) {
+      // First relation for this (entity, component) — use single form (big win for exclusive)
+      entry = { type: "single", relationType, target: targetId, data };
+      entities.set(entityId, entry);
+    } else if (entry.type === "single") {
+      if (entry.target === targetId) {
+        entry.data = data;
+        entry.relationType = relationType; // update in case it changed
+      } else {
+        // Promote to multi
+        const targets = new Map();
+        targets.set(entry.target, { relationType: entry.relationType, data: entry.data });
+        targets.set(targetId, { relationType, data });
+        entities.set(entityId, { type: "multi", targets });
+      }
+    } else {
+      entry.targets.set(targetId, { relationType, data });
+    }
+
+    // Maintain reverse index
+    let components = this.entityIndex.get(entityId);
+    if (!components) {
+      components = new Set();
+      this.entityIndex.set(entityId, components);
+    }
+    components.add(componentId);
   }
 
-  delete(entityId: EntityId): void {
-    this.data.delete(entityId);
+  deleteValue(entityId: EntityId, relationType: EntityId<any>): boolean {
+    const componentId = getComponentIdFromRelationId(relationType);
+    if (componentId === undefined) return false;
+
+    const entities = this.byComponent.get(componentId);
+    if (!entities) return false;
+
+    const entry = entities.get(entityId);
+    if (!entry) return false;
+
+    const targetId = getTargetIdFromRelationId(relationType)!;
+    let existed = false;
+
+    if (entry.type === "single") {
+      if (entry.target === targetId) {
+        existed = true;
+        entities.delete(entityId);
+      }
+    } else {
+      existed = entry.targets.delete(targetId);
+      if (entry.targets.size === 0) {
+        entities.delete(entityId);
+      } else if (entry.targets.size === 1) {
+        // Demote to single
+        const [first] = entry.targets.entries();
+        const [t, item] = first!;
+        entities.set(entityId, { type: "single", relationType: item.relationType, target: t, data: item.data });
+      }
+    }
+
+    if (!entities.has(entityId) && entities.size === 0) {
+      this.byComponent.delete(componentId);
+    }
+
+    // Update reverse index
+    const components = this.entityIndex.get(entityId);
+    if (components && !entities.has(entityId)) {
+      components.delete(componentId);
+      if (components.size === 0) {
+        this.entityIndex.delete(entityId);
+      }
+    }
+
+    return existed;
+  }
+
+  hasAnyForComponent(componentId: EntityId<any>): boolean {
+    const entities = this.byComponent.get(componentId);
+    return entities !== undefined && entities.size > 0;
+  }
+
+  getRelationsForComponent(entityId: EntityId, componentId: EntityId<any>): [EntityId, any][] {
+    const result: [EntityId, any][] = [];
+
+    const entities = this.byComponent.get(componentId);
+    if (!entities) return result;
+
+    const entry = entities.get(entityId);
+    if (!entry) return result;
+
+    if (entry.type === "single") {
+      result.push([entry.target, entry.data]);
+    } else {
+      for (const [target, item] of entry.targets) {
+        result.push([target, item.data]);
+      }
+    }
+
+    return result;
+  }
+
+  getAllForEntity(entityId: EntityId): Array<[relationType: EntityId<any>, data: any]> {
+    const components = this.entityIndex.get(entityId);
+    if (!components || components.size === 0) return [];
+
+    const result: Array<[EntityId<any>, any]> = [];
+
+    for (const componentId of components) {
+      const entities = this.byComponent.get(componentId);
+      const entry = entities?.get(entityId);
+      if (entry) {
+        if (entry.type === "single") {
+          result.push([entry.relationType, entry.data]);
+        } else {
+          for (const item of entry.targets.values()) {
+            result.push([item.relationType, item.data]);
+          }
+        }
+      }
+    }
+
+    return result;
+  }
+
+  deleteEntity(entityId: EntityId): void {
+    const components = this.entityIndex.get(entityId);
+    if (!components) return;
+
+    for (const componentId of components) {
+      const entities = this.byComponent.get(componentId);
+      if (entities) {
+        entities.delete(entityId);
+        if (entities.size === 0) {
+          this.byComponent.delete(componentId);
+        }
+      }
+    }
+
+    this.entityIndex.delete(entityId);
   }
 }

package/src/world/commands.ts

@@ -172,6 +172,15 @@ export function maybeRemoveWildcardMarker(
     }
   }
 
+  // Also check if this changeset itself is adding another relation of the same kind
+  // (common in exclusive dontFragment flips: remove old target + add new target in one batch)
+  for (const addedType of changeset.adds.keys()) {
+    if (addedType === removedComponentType) continue;
+    if (getComponentIdFromRelationId(addedType) === componentId) {
+      return; // Replacement is being added in the same changeset, keep the marker
+    }
+  }
+
   changeset.delete(wildcardMarker);
 }
 
@@ -280,6 +289,8 @@ export function applyChangeset(
 
 /**
  * No-hooks variant of applyDontFragmentChanges that skips tracking removed component data.
+ *
+ * Rewritten for the new DontFragmentStore interface (ComponentId-primary storage).
  */
 function applyDontFragmentChanges(
   dontFragmentRelations: DontFragmentStore,
@@ -287,35 +298,25 @@ function applyDontFragmentChanges(
   changeset: ComponentChangeset,
   removedComponents: Map<EntityId<any>, any>,
 ): void {
-  // Get or create the entity's dontFragment relations map
-  let entityRelations = dontFragmentRelations.get(entityId);
-
   for (const componentType of changeset.removes) {
     if (isDontFragmentRelation(componentType)) {
-      if (entityRelations) {
-        const removedValue = entityRelations.get(componentType);
-        if (removedValue !== undefined || entityRelations.has(componentType)) {
-          removedComponents.set(componentType, removedValue);
-          entityRelations.delete(componentType);
-        }
+      const removedValue = dontFragmentRelations.getValue(entityId, componentType);
+      // Record for hooks if we are actually removing something
+      if (
+        removedValue !== undefined ||
+        dontFragmentRelations.getAllForEntity(entityId).some(([t]) => t === componentType)
+      ) {
+        removedComponents.set(componentType, removedValue);
       }
+      dontFragmentRelations.deleteValue(entityId, componentType);
     }
   }
 
   for (const [componentType, component] of changeset.adds) {
     if (isDontFragmentRelation(componentType)) {
-      if (!entityRelations) {
-        entityRelations = new Map();
-        dontFragmentRelations.set(entityId, entityRelations);
-      }
-      entityRelations.set(componentType, component);
+      dontFragmentRelations.setValue(entityId, componentType, component);
     }
   }
-
-  // Clean up empty map
-  if (entityRelations && entityRelations.size === 0) {
-    dontFragmentRelations.delete(entityId);
-  }
 }
 
 function applyDontFragmentChangesNoHooks(
@@ -323,30 +324,17 @@ function applyDontFragmentChangesNoHooks(
   entityId: EntityId,
   changeset: ComponentChangeset,
 ): void {
-  let entityRelations = dontFragmentRelations.get(entityId);
-
   for (const componentType of changeset.removes) {
     if (isDontFragmentRelation(componentType)) {
-      if (entityRelations) {
-        entityRelations.delete(componentType);
-      }
+      dontFragmentRelations.deleteValue(entityId, componentType);
     }
   }
 
   for (const [componentType, component] of changeset.adds) {
     if (isDontFragmentRelation(componentType)) {
-      if (!entityRelations) {
-        entityRelations = new Map();
-        dontFragmentRelations.set(entityId, entityRelations);
-      }
-      entityRelations.set(componentType, component);
+      dontFragmentRelations.setValue(entityId, componentType, component);
     }
   }
-
-  // Clean up empty map
-  if (entityRelations && entityRelations.size === 0) {
-    dontFragmentRelations.delete(entityId);
-  }
 }
 
 export function filterRegularComponentTypes(componentTypes: Iterable<EntityId<any>>): EntityId<any>[] {