@codehz/ecs 0.8.2 → 0.10.0

package/src/world/commands.ts

@@ -1,14 +1,14 @@
 import type { Archetype } from "../archetype/archetype";
-import type { DontFragmentStore } from "../archetype/store";
+import type { SparseStore } from "../archetype/store";
 import type { Command } from "../commands/buffer";
 import type { ComponentChangeset } from "../commands/changeset";
 import { normalizeComponentTypes } from "../component/type-utils";
 import {
   getComponentIdFromRelationId,
   getComponentMerge,
-  isDontFragmentComponent,
-  isDontFragmentRelation,
-  isDontFragmentWildcard,
+  isSparseComponent,
+  isSparseRelation,
+  isSparseWildcard,
   isWildcardRelationId,
   relation,
   type ComponentId,
@@ -16,7 +16,7 @@ import {
 } from "../entity";
 
 export interface CommandProcessorContext {
-  dontFragmentStore: DontFragmentStore;
+  sparseStore: SparseStore;
   ensureArchetype: (componentTypes: Iterable<EntityId<any>>) => Archetype;
 }
 
@@ -59,8 +59,8 @@ function processSetCommand(
     // Handle exclusive relations by removing existing relations with the same base component
     handleExclusiveRelation(entityId, currentArchetype, componentId);
 
-    // For dontFragment relations, ensure wildcard marker is in archetype signature
-    if (isDontFragmentComponent(componentId)) {
+    // For sparse relations, ensure wildcard marker is in archetype signature
+    if (isSparseComponent(componentId)) {
       const wildcardMarker = relation(componentId, "*");
       // Add wildcard marker to changeset if not already in archetype
       if (!currentArchetype.componentTypeSet.has(wildcardMarker)) {
@@ -111,10 +111,10 @@ export function removeMatchingRelations(
     }
   }
 
-  // Check dontFragment relations stored on entity
-  const dontFragmentData = archetype.getEntityDontFragmentRelations(entityId);
-  if (dontFragmentData) {
-    for (const componentType of dontFragmentData.keys()) {
+  // Check sparse relations stored on entity
+  const sparseData = archetype.getEntitySparseRelations(entityId);
+  if (sparseData) {
+    for (const componentType of sparseData.keys()) {
       if (getComponentIdFromRelationId(componentType) === baseComponentId) {
         changeset.delete(componentType);
       }
@@ -130,8 +130,8 @@ function removeWildcardRelations(
 ): void {
   removeMatchingRelations(entityId, currentArchetype, baseComponentId, changeset);
 
-  // If removing dontFragment relations, also remove the wildcard marker
-  if (isDontFragmentComponent(baseComponentId)) {
+  // If removing sparse relations, also remove the wildcard marker
+  if (isSparseComponent(baseComponentId)) {
     changeset.delete(relation(baseComponentId, "*"));
   }
 }
@@ -143,7 +143,7 @@ export function maybeRemoveWildcardMarker(
   componentId: ComponentId<any> | undefined,
   changeset: ComponentChangeset,
 ): void {
-  if (componentId === undefined || !isDontFragmentComponent(componentId)) {
+  if (componentId === undefined || !isSparseComponent(componentId)) {
     return;
   }
 
@@ -160,9 +160,9 @@ export function maybeRemoveWildcardMarker(
     }
   }
 
-  const dontFragmentData = archetype.getEntityDontFragmentRelations(entityId);
-  if (dontFragmentData) {
-    for (const otherComponentType of dontFragmentData.keys()) {
+  const sparseData = archetype.getEntitySparseRelations(entityId);
+  if (sparseData) {
+    for (const otherComponentType of sparseData.keys()) {
       if (otherComponentType === removedComponentType) continue;
       if (changeset.removes.has(otherComponentType)) continue;
 
@@ -173,7 +173,7 @@ 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)
+  // (common in exclusive sparse 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) {
@@ -189,7 +189,7 @@ function hasEntityComponent(archetype: Archetype, entityId: EntityId, componentT
     return true;
   }
 
-  return archetype.getEntityDontFragmentRelations(entityId)?.has(componentType) ?? false;
+  return archetype.getEntitySparseRelations(entityId)?.has(componentType) ?? false;
 }
 
 function pruneMissingRemovals(changeset: ComponentChangeset, archetype: Archetype, entityId: EntityId): void {
@@ -210,13 +210,13 @@ function pruneMissingRemovals(changeset: ComponentChangeset, archetype: Archetyp
 
 function hasArchetypeStructuralChange(changeset: ComponentChangeset, currentArchetype: Archetype): boolean {
   for (const componentType of changeset.removes) {
-    if (!isDontFragmentRelation(componentType) && currentArchetype.componentTypeSet.has(componentType)) {
+    if (!isSparseRelation(componentType) && currentArchetype.componentTypeSet.has(componentType)) {
       return true;
     }
   }
 
   for (const componentType of changeset.adds.keys()) {
-    if (!isDontFragmentRelation(componentType) && !currentArchetype.componentTypeSet.has(componentType)) {
+    if (!isSparseRelation(componentType) && !currentArchetype.componentTypeSet.has(componentType)) {
       return true;
     }
   }
@@ -228,13 +228,13 @@ function buildFinalRegularComponentTypes(currentArchetype: Archetype, changeset:
   const finalRegularTypes = new Set(currentArchetype.componentTypes);
 
   for (const componentType of changeset.removes) {
-    if (!isDontFragmentRelation(componentType)) {
+    if (!isSparseRelation(componentType)) {
       finalRegularTypes.delete(componentType);
     }
   }
 
   for (const [componentType] of changeset.adds) {
-    if (!isDontFragmentRelation(componentType)) {
+    if (!isSparseRelation(componentType)) {
       finalRegularTypes.add(componentType);
     }
   }
@@ -269,16 +269,16 @@ export function applyChangeset(
     return newArchetype;
   }
 
-  // No archetype move needed: only component payload updates and/or dontFragment relation updates.
+  // No archetype move needed: only component payload updates and/or sparse relation updates.
   if (removedComponents !== null) {
-    applyDontFragmentChanges(ctx.dontFragmentStore, entityId, changeset, removedComponents);
+    applySparseChanges(ctx.sparseStore, entityId, changeset, removedComponents);
   } else {
-    applyDontFragmentChangesNoHooks(ctx.dontFragmentStore, entityId, changeset);
+    applySparseChangesNoHooks(ctx.sparseStore, entityId, changeset);
   }
 
   // Direct update for regular components in archetype
   for (const [componentType, component] of changeset.adds) {
-    if (isDontFragmentRelation(componentType)) {
+    if (isSparseRelation(componentType)) {
       continue;
     }
     currentArchetype.set(entityId, componentType, component);
@@ -287,52 +287,40 @@ export function applyChangeset(
   return currentArchetype;
 }
 
-/**
- * No-hooks variant of applyDontFragmentChanges that skips tracking removed component data.
- *
- * Rewritten for the new DontFragmentStore interface (ComponentId-primary storage).
- */
-function applyDontFragmentChanges(
-  dontFragmentRelations: DontFragmentStore,
+function applySparseChanges(
+  sparseStore: SparseStore,
   entityId: EntityId,
   changeset: ComponentChangeset,
   removedComponents: Map<EntityId<any>, any>,
 ): void {
   for (const componentType of changeset.removes) {
-    if (isDontFragmentRelation(componentType)) {
-      const removedValue = dontFragmentRelations.getValue(entityId, componentType);
+    if (isSparseRelation(componentType)) {
+      const removedValue = sparseStore.getValue(entityId, componentType);
       // Record for hooks if we are actually removing something
-      if (
-        removedValue !== undefined ||
-        dontFragmentRelations.getAllForEntity(entityId).some(([t]) => t === componentType)
-      ) {
+      if (removedValue !== undefined || sparseStore.getAllForEntity(entityId).some(([t]) => t === componentType)) {
         removedComponents.set(componentType, removedValue);
       }
-      dontFragmentRelations.deleteValue(entityId, componentType);
+      sparseStore.deleteValue(entityId, componentType);
     }
   }
 
   for (const [componentType, component] of changeset.adds) {
-    if (isDontFragmentRelation(componentType)) {
-      dontFragmentRelations.setValue(entityId, componentType, component);
+    if (isSparseRelation(componentType)) {
+      sparseStore.setValue(entityId, componentType, component);
     }
   }
 }
 
-function applyDontFragmentChangesNoHooks(
-  dontFragmentRelations: DontFragmentStore,
-  entityId: EntityId,
-  changeset: ComponentChangeset,
-): void {
+function applySparseChangesNoHooks(sparseStore: SparseStore, entityId: EntityId, changeset: ComponentChangeset): void {
   for (const componentType of changeset.removes) {
-    if (isDontFragmentRelation(componentType)) {
-      dontFragmentRelations.deleteValue(entityId, componentType);
+    if (isSparseRelation(componentType)) {
+      sparseStore.deleteValue(entityId, componentType);
     }
   }
 
   for (const [componentType, component] of changeset.adds) {
-    if (isDontFragmentRelation(componentType)) {
-      dontFragmentRelations.setValue(entityId, componentType, component);
+    if (isSparseRelation(componentType)) {
+      sparseStore.setValue(entityId, componentType, component);
     }
   }
 }
@@ -341,14 +329,14 @@ export function filterRegularComponentTypes(componentTypes: Iterable<EntityId<an
   const regularTypes: EntityId<any>[] = [];
 
   for (const componentType of componentTypes) {
-    // Keep wildcard markers for dontFragment components (they mark the archetype)
-    if (isDontFragmentWildcard(componentType)) {
+    // Keep wildcard markers for sparse components (they mark the archetype)
+    if (isSparseWildcard(componentType)) {
       regularTypes.push(componentType);
       continue;
     }
 
-    // Skip specific dontFragment relations from archetype signature
-    if (isDontFragmentRelation(componentType)) {
+    // Skip specific sparse relations from archetype signature
+    if (isSparseRelation(componentType)) {
       continue;
     }
 

package/src/world/debug-stats.ts

@@ -0,0 +1,147 @@
+import type { DebugStatsCollector, SyncDebugStats } from "../types";
+import { debugHookExecutionCounter } from "./hooks";
+
+/**
+ * Manages debug stats collectors and transient activity counters for World#sync().
+ *
+ * Extracted from World to shrink the main class while keeping the entire debug/observability
+ * path isolated, zero-cost when no collectors are active, and easy to test/maintain.
+ *
+ * Follows the same context/callback injection style as ArchetypeManager, CommandProcessorContext,
+ * and HooksContext to avoid tight coupling.
+ *
+ * All collectors receive the *exact same* stats object for a given sync (as before).
+ * Exceptions in user callbacks are swallowed (as before).
+ */
+export class DebugStatsManager {
+  private readonly collectors = new Set<(stats: SyncDebugStats) => void>();
+
+  // Transient activity counters for the current armed sync (reset each time collectors are present)
+  private migrations = 0;
+  private archetypesCreated = 0;
+  private archetypesRemoved = 0;
+
+  /** Fast check used to arm timing + reset + counting in hot paths. */
+  hasActiveCollectors(): boolean {
+    return this.collectors.size > 0;
+  }
+
+  /**
+   * Registers a collector. Returns a disposable handle (supports `using`).
+   * Collection stops when the handle is disposed.
+   */
+  createCollector(callback: (stats: SyncDebugStats) => void): DebugStatsCollector {
+    this.collectors.add(callback);
+
+    return {
+      [Symbol.dispose]: () => {
+        this.collectors.delete(callback);
+      },
+    };
+  }
+
+  // ------------------------------------------------------------------
+  // Recording hooks (called from ArchetypeManager ctx and command apply paths)
+  // These are cheap no-ops when no collectors are active.
+  // ------------------------------------------------------------------
+
+  recordArchetypeCreated(): void {
+    if (this.hasActiveCollectors()) {
+      this.archetypesCreated++;
+    }
+  }
+
+  recordArchetypeRemoved(): void {
+    if (this.hasActiveCollectors()) {
+      this.archetypesRemoved++;
+    }
+  }
+
+  incrementMigrations(): void {
+    if (this.hasActiveCollectors()) {
+      this.migrations++;
+    }
+  }
+
+  /** Reset all activity counters + the shared hook execution counter. Called at start of an armed sync. */
+  resetActivity(): void {
+    this.migrations = 0;
+    this.archetypesCreated = 0;
+    this.archetypesRemoved = 0;
+    debugHookExecutionCounter.value = 0;
+  }
+
+  /**
+   * Build and deliver a SyncDebugStats payload to every active collector.
+   * World supplies the pre-computed snapshot numbers (keeps debug manager decoupled from
+   * internal World maps/registries while preserving exact original stats shape and values).
+   */
+  deliver(
+    timings: {
+      syncStart: number;
+      syncEnd: number;
+      commandBufferStart: number;
+      commandBufferEnd: number;
+      commandIterations: number;
+    },
+    data: {
+      entityCount: number;
+      freelistSize: number;
+      nextId: number;
+      archetypeCount: number;
+      emptyArchetypes: number;
+      archetypesByComponentSize: number;
+      cachedQueryCount: number;
+      registeredQueryCount: number;
+      hookCount: number;
+      entityReferencesSize: number;
+      entityToReferencingArchetypesSize: number;
+    },
+  ): void {
+    const stats: SyncDebugStats = {
+      timestamps: {
+        syncStart: timings.syncStart,
+        syncEnd: timings.syncEnd,
+        commandBufferStart: timings.commandBufferStart,
+        commandBufferEnd: timings.commandBufferEnd,
+      },
+      commandIterations: timings.commandIterations,
+
+      entities: {
+        total: data.entityCount,
+        freelistSize: data.freelistSize,
+        nextId: data.nextId,
+      },
+      archetypes: {
+        total: data.archetypeCount,
+        empty: data.emptyArchetypes,
+      },
+      queries: {
+        cached: data.cachedQueryCount,
+        registered: data.registeredQueryCount,
+      },
+      hooks: {
+        total: data.hookCount,
+      },
+      indices: {
+        entityReferences: data.entityReferencesSize,
+        entityToReferencingArchetypes: data.entityToReferencingArchetypesSize,
+        archetypesByComponent: data.archetypesByComponentSize,
+      },
+      activity: {
+        migrations: this.migrations,
+        hooksExecuted: debugHookExecutionCounter.value,
+        archetypesCreated: this.archetypesCreated,
+        archetypesRemoved: this.archetypesRemoved,
+      },
+    };
+
+    for (const cb of this.collectors) {
+      try {
+        cb(stats);
+      } catch {
+        // Intentionally ignore user callback errors (preserves original behavior)
+      }
+    }
+  }
+}

package/src/world/hooks.ts

@@ -7,6 +7,12 @@ import {
 } from "../entity";
 import { isOptionalEntityId, type ComponentType, type LifecycleHookEntry } from "../types";
 
+/**
+ * Debug-only counter incremented on every invokeHook call when armed.
+ * World reads and resets this during armed syncs.
+ */
+export const debugHookExecutionCounter = { value: 0 };
+
 /**
  * Unified hook invocation: prefers entry.callback (callback style) over hook.on_* (object style).
  */
@@ -16,6 +22,8 @@ function invokeHook(
   entityId: EntityId,
   components: any[],
 ): void {
+  debugHookExecutionCounter.value++;
+
   if (entry.callback) {
     entry.callback(event as any, entityId, ...components);
     return;

package/src/world/operations.ts

@@ -0,0 +1,88 @@
+import type { ComponentId, EntityId } from "../entity";
+import { getDetailedIdType } from "../entity";
+
+/**
+ * Validation and overload-resolution helpers extracted from World.
+ *
+ * These were previously private methods on World. Moving them reduces line count
+ * in the core class with almost zero coupling (the only dep is a liveness predicate
+ * for assertEntityExists, supplied by the caller).
+ *
+ * Pure type checks (assert*TypeValid) and the resolve* helpers for set/remove
+ * overloads live here.
+ */
+
+/**
+ * Assert that an entity (or component-entity) is alive in the world.
+ * The caller supplies the liveness check (World.exists or equivalent) to keep
+ * this module free of direct references to stores.
+ */
+export function assertEntityExists(
+  entityId: EntityId,
+  label: "Entity" | "Component entity",
+  exists: (id: EntityId) => boolean,
+): void {
+  if (!exists(entityId)) {
+    throw new Error(`${label} ${entityId} does not exist`);
+  }
+}
+
+export function assertComponentTypeValid(componentType: EntityId): void {
+  const detailedType = getDetailedIdType(componentType);
+  if (detailedType.type === "invalid") {
+    throw new Error(`Invalid component type: ${componentType}`);
+  }
+}
+
+export function assertSetComponentTypeValid(componentType: EntityId): void {
+  const detailedType = getDetailedIdType(componentType);
+  if (detailedType.type === "invalid") {
+    throw new Error(`Invalid component type: ${componentType}`);
+  }
+  if (detailedType.type === "wildcard-relation") {
+    throw new Error(`Cannot directly add wildcard relation components: ${componentType}`);
+  }
+}
+
+/**
+ * Resolve the (entity, componentType, value) for a set() call.
+ */
+export function resolveSetOperation(
+  entityId: EntityId | ComponentId,
+  componentTypeOrComponent?: EntityId | any,
+  maybeComponent?: any,
+  exists: (id: EntityId) => boolean = () => true, // default permissive for tests / internal
+): { entityId: EntityId; componentType: EntityId; component: any } {
+  const targetEntityId = entityId as EntityId;
+  const componentType = componentTypeOrComponent as EntityId;
+  assertEntityExists(targetEntityId, "Entity", exists);
+  assertSetComponentTypeValid(componentType);
+
+  return { entityId: targetEntityId, componentType, component: maybeComponent };
+}
+
+/**
+ * Resolve the (entity, componentType) for a remove() call, handling the
+ * singleton component overload (remove(componentId)).
+ */
+export function resolveRemoveOperation<T>(
+  entityId: EntityId | ComponentId,
+  componentType?: EntityId<T>,
+  exists: (id: EntityId) => boolean = () => true,
+): { entityId: EntityId; componentType: EntityId } {
+  // Handle singleton component overload: remove(componentId)
+  if (componentType === undefined) {
+    const componentId = entityId as ComponentId<T>;
+    assertEntityExists(componentId, "Component entity", exists);
+    return { entityId: componentId, componentType: componentId };
+  }
+
+  const targetEntityId = entityId as EntityId;
+  assertEntityExists(targetEntityId, "Entity", exists);
+  assertComponentTypeValid(componentType);
+
+  return { entityId: targetEntityId, componentType };
+}
+
+// Re-export the type for callers that need it in signatures (ComponentId lives in entity)
+export type { ComponentId } from "../entity";

package/src/world/serialization.ts

@@ -3,7 +3,7 @@ import type { ComponentEntityStore } from "../component/entity-store";
 import { getDetailedIdType, type EntityId, type EntityIdManager } from "../entity";
 import {
   decodeSerializedId,
-  encodeEntityId,
+  encodeEntityIdCached,
   type SerializedComponent,
   type SerializedEntity,
   type SerializedWorld,
@@ -18,29 +18,25 @@ export function serializeWorld(
   componentEntities: ComponentEntityStore,
   entityIdManager: EntityIdManager,
 ): SerializedWorld {
+  // ID cache turns repeated encode work (especially component type IDs) into O(#unique IDs)
+  const idCache = new Map<any, any>();
+
   const entities: SerializedEntity[] = [];
 
   for (const archetype of archetypes) {
-    const dumpedEntities = archetype.dump();
-    for (const { entity, components } of dumpedEntities) {
-      entities.push({
-        id: encodeEntityId(entity),
-        components: Array.from(components.entries()).map(([rawType, value]) => ({
-          type: encodeEntityId(rawType),
-          value: value === MISSING_COMPONENT ? undefined : value,
-        })),
-      });
-    }
+    // Pre-encode this archetype's component type IDs exactly once (big win when many entities share the archetype)
+    const encodedComponentTypes = archetype.componentTypes.map((t) => encodeEntityIdCached(t, idCache));
+
+    // The append method will use the bulk helper internally when a pre-fetched map is supplied.
+    // For now we rely on the per-entity fallback inside the archetype (already much cheaper than old dump path).
+    archetype.appendSerializedEntities(entities, (id) => encodeEntityIdCached(id, idCache), encodedComponentTypes);
   }
 
   const componentEntitiesArr: SerializedEntity[] = [];
   for (const [entityId, components] of componentEntities.entries()) {
     componentEntitiesArr.push({
-      id: encodeEntityId(entityId),
-      components: Array.from(components.entries()).map(([rawType, value]) => ({
-        type: encodeEntityId(rawType),
-        value: value === MISSING_COMPONENT ? undefined : value,
-      })),
+      id: encodeEntityIdCached(entityId, idCache),
+      components: serializeComponentsFromMap(components, idCache),
     });
   }
 
@@ -52,6 +48,21 @@ export function serializeWorld(
   };
 }
 
+/** Small helper to avoid duplicating the "Map → SerializedComponent[] with cache" pattern. */
+function serializeComponentsFromMap(
+  components: Map<EntityId<any>, any>,
+  idCache: Map<any, any>,
+): SerializedComponent[] {
+  const result: SerializedComponent[] = [];
+  for (const [rawType, value] of components) {
+    result.push({
+      type: encodeEntityIdCached(rawType, idCache),
+      value: value === MISSING_COMPONENT ? undefined : value,
+    });
+  }
+  return result;
+}
+
 /**
  * Context needed by `deserializeWorld` to populate world-internal state.
  * Defined as an interface to avoid a circular import between world.ts and this module.
@@ -96,14 +107,17 @@ export function deserializeWorld(ctx: WorldDeserializationContext, snapshot: Ser
       const componentsArray: SerializedComponent[] = entry.components || [];
 
       const componentMap = new Map<EntityId<any>, any>();
-      const componentTypes: EntityId<any>[] = [];
 
       for (const componentEntry of componentsArray) {
         const componentType = decodeSerializedId(componentEntry.type);
         componentMap.set(componentType, componentEntry.value);
-        componentTypes.push(componentType);
       }
 
+      // Build the list of component types from the map we just populated (no redundant push loop)
+      const componentTypes = Array.from(componentMap.keys());
+
+      // ensureArchetype is internally memoized (getOrCompute on signature), so repeated calls
+      // for the same component set are cheap after the first archetype is created.
       const archetype = ctx.ensureArchetype(componentTypes);
       archetype.addEntity(entityId, componentMap);
       ctx.setEntityToArchetype(entityId, archetype);

package/src/world/singleton.ts

@@ -0,0 +1,51 @@
+import type { ComponentId } from "../entity";
+
+export interface SingletonHandleOps<T> {
+  has(): boolean;
+  get(): T;
+  getOptional(): { value: T } | undefined;
+  remove(): void;
+  set(value: T | undefined): void;
+}
+
+/**
+ * Explicit handle for a singleton component (component-as-entity).
+ *
+ * This provides an explicit and concise API for singleton components without
+ * overloading `world.set()` semantics.
+ *
+ * @example
+ * const config = world.singleton(Config);
+ * config.set({ debug: true });
+ * world.sync();
+ * console.log(config.get());
+ */
+export class SingletonHandle<T = void> {
+  readonly componentId: ComponentId<T>;
+  private readonly ops: SingletonHandleOps<T>;
+
+  constructor(componentId: ComponentId<T>, ops: SingletonHandleOps<T>) {
+    this.componentId = componentId;
+    this.ops = ops;
+  }
+
+  has(): boolean {
+    return this.ops.has();
+  }
+
+  get(): T {
+    return this.ops.get();
+  }
+
+  getOptional(): { value: T } | undefined {
+    return this.ops.getOptional();
+  }
+
+  remove(): void {
+    this.ops.remove();
+  }
+
+  set(...args: T extends void ? [] : [value: NoInfer<T>]): void {
+    this.ops.set(args[0] as T | undefined);
+  }
+}