@codehz/ecs 0.8.0 → 0.8.1

package/src/world/references.ts

@@ -1,8 +1,41 @@
 import type { EntityId } from "../entity";
 import { MultiMap } from "../utils/multi-map";
 
+/**
+ * Reverse reference index: maps each target entity to the set of (source entity, component) pairs
+ * that currently hold a reference to it.
+ *
+ * Used internally to support efficient entity deletion, including:
+ * - Fast-path deletion for unreferenced entities
+ * - Cascading deletes for relations marked with `cascadeDelete`
+ * - Automatic cleanup of entity-valued components and entity-relations when their target is destroyed
+ *
+ * Structure:
+ *   targetEntityId -> MultiMap<sourceEntityId, componentOrRelationId>
+ *
+ * - For plain entity-valued components (component value is an EntityId):
+ *     componentOrRelationId === the component type (which is also the entity id being pointed to)
+ * - For entity-relations (`relation(Comp, target)`):
+ *     componentOrRelationId is the encoded (negative) relation ID
+ *
+ * This index is maintained in sync with structural changes via `updateEntityReferences` in World.
+ *
+ * @internal
+ */
 export type EntityReferencesMap = Map<EntityId, MultiMap<EntityId, EntityId>>;
 
+/**
+ * Record that `sourceEntityId` holds a reference to `targetEntityId` via the given component/relation.
+ *
+ * Called when an entity-valued component or an entity-relation is added to an entity.
+ *
+ * @param entityReferences - The shared reverse index map
+ * @param sourceEntityId - The entity that contains the reference
+ * @param componentType - The component type or encoded relation ID used for the reference
+ * @param targetEntityId - The entity being referenced
+ *
+ * @internal
+ */
 export function trackEntityReference(
   entityReferences: EntityReferencesMap,
   sourceEntityId: EntityId,
@@ -15,6 +48,19 @@ export function trackEntityReference(
   entityReferences.get(targetEntityId)!.add(sourceEntityId, componentType);
 }
 
+/**
+ * Remove the record that `sourceEntityId` references `targetEntityId` via the given component/relation.
+ *
+ * Called when an entity-valued component or entity-relation is removed (or during deletion).
+ * Automatically prunes empty target entries from the map.
+ *
+ * @param entityReferences - The shared reverse index map
+ * @param sourceEntityId - The entity that no longer holds the reference
+ * @param componentType - The component type or encoded relation ID that was used
+ * @param targetEntityId - The previously referenced entity
+ *
+ * @internal
+ */
 export function untrackEntityReference(
   entityReferences: EntityReferencesMap,
   sourceEntityId: EntityId,
@@ -30,6 +76,19 @@ export function untrackEntityReference(
   }
 }
 
+/**
+ * Iterate over all (sourceEntityId, componentOrRelationId) pairs that currently reference the given target.
+ *
+ * Returns an empty iterable when the target has no incoming references.
+ * The returned iterable yields `[source, componentType]` pairs suitable for cleanup decisions
+ * (e.g. whether to cascade-delete the source or just remove the specific component/relation).
+ *
+ * @param entityReferences - The shared reverse index map
+ * @param targetEntityId - The entity whose referrers we want to inspect
+ * @returns Iterable of [sourceEntityId, componentOrRelationId]
+ *
+ * @internal
+ */
 export function getEntityReferences(
   entityReferences: EntityReferencesMap,
   targetEntityId: EntityId,

package/src/world/world.ts

@@ -444,7 +444,10 @@ export class World {
     if (archetype.componentTypeSet.has(componentType)) return true;
 
     if (isDontFragmentRelation(componentType)) {
-      return this.dontFragmentStore.get(entityId)?.has(componentType) ?? false;
+      // Use getValue; presence check via getAllForEntity only if value can legitimately be undefined
+      const val = this.dontFragmentStore.getValue(entityId, componentType);
+      if (val !== undefined) return true;
+      return this.dontFragmentStore.getAllForEntity(entityId).some(([t]) => t === componentType);
     }
 
     return false;
@@ -493,7 +496,11 @@ export class World {
     if (componentType >= 0 || componentType % RELATION_SHIFT !== 0) {
       const inArchetype = archetype.componentTypeSet.has(componentType);
       const hasDontFragment = isDontFragmentRelation(componentType);
-      const hasComponent = inArchetype || (hasDontFragment && this.dontFragmentStore.get(entityId)?.has(componentType));
+      const hasComponent =
+        inArchetype ||
+        (hasDontFragment &&
+          (this.dontFragmentStore.getValue(entityId, componentType) !== undefined ||
+            this.dontFragmentStore.getAllForEntity(entityId).some(([t]) => t === componentType)));
 
       if (!hasComponent) {
         throw new Error(