@codehz/ecs 0.9.0 → 0.10.0

package/src/world/command-executor.ts

@@ -0,0 +1,258 @@
+import type { Archetype } from "../archetype/archetype";
+import type { SparseStore } from "../archetype/store";
+import type { Command } from "../commands/buffer";
+import { ComponentChangeset } from "../commands/changeset";
+import type { ComponentEntityStore } from "../component/entity-store";
+import {
+  getComponentIdFromRelationId,
+  getTargetIdFromRelationId,
+  isEntityRelation,
+  isExclusiveComponent,
+  type EntityId,
+} from "../entity";
+import type { LifecycleHookEntry } from "../types";
+import {
+  applyChangeset,
+  maybeRemoveWildcardMarker,
+  processCommands,
+  removeMatchingRelations,
+  type CommandProcessorContext,
+} from "./commands";
+import type { triggerLifecycleHooks } from "./hooks";
+import { type HooksContext } from "./hooks";
+import { trackEntityReference, untrackEntityReference, type EntityReferencesMap } from "./references";
+
+/**
+ * Dependencies provided by World to the CommandExecutor.
+ * Keeps the executor decoupled while allowing efficient hot-path access
+ * (maps passed by reference where hot code already expects them).
+ */
+export interface CommandExecutorContext {
+  /** For component-entity (singleton) fast path in execute */
+  componentEntities: ComponentEntityStore;
+
+  /** Reverse reference index for cascades and entity-valued components */
+  entityReferences: EntityReferencesMap;
+
+  /** For the no-hooks fast path guard */
+  hooks: Set<LifecycleHookEntry>;
+
+  /** Direct map access (hot path in applyChangeset and various places) */
+  entityToArchetype: Map<EntityId, Archetype>;
+
+  /** Archetype creation/lookup (passed through CommandProcessorContext) */
+  ensureArchetype: (componentTypes: Iterable<EntityId<any>>) => Archetype;
+
+  /** Sparse store (needed for CommandProcessorContext) */
+  sparseStore: SparseStore;
+
+  /** Factories for the HooksContext (used by triggerLifecycleHooks) */
+  has: (entityId: EntityId, componentType: EntityId<any>) => boolean;
+  get: <T>(entityId: EntityId, componentType: EntityId<T>) => T;
+  getOptional: <T>(entityId: EntityId, componentType: EntityId<T>) => { value: T } | undefined;
+
+  /** Destroy fast-path delegation (BFS + cascade logic stays in World) */
+  destroyEntityImmediate: (entityId: EntityId) => void;
+
+  /** Debug migration counter (now routed through DebugStatsManager) */
+  incrementMigrations: () => void;
+
+  /** Hook triggering (the function from hooks.ts) */
+  triggerLifecycleHooks: typeof triggerLifecycleHooks;
+
+  /** Remove hook fast path for full entity deletion (used by destroy paths in World) */
+  triggerRemoveHooksForEntityDeletion: (
+    entityId: EntityId,
+    removedComponents: Map<EntityId<any>, any>,
+    oldArchetype: Archetype,
+  ) => void;
+}
+
+/**
+ * Encapsulates the command execution pipeline, reusable changesets,
+ * and related orchestration that was previously private methods + fields on World.
+ *
+ * Responsibilities:
+ * - executeEntityCommands (routing for singletons / destroy / structural changes)
+ * - applyEntityCommands (changeset processing + exclusive relations + apply + refs + hooks)
+ * - removeComponentImmediate (used by cascade deletion)
+ * - updateEntityReferences (keeps the reverse index in sync)
+ *
+ * This extraction significantly reduces World line count while preserving
+ * every fast-path branch and allocation-avoidance characteristic.
+ */
+export class CommandExecutor {
+  private readonly _changeset = new ComponentChangeset();
+  private readonly _removeChangeset = new ComponentChangeset();
+
+  private readonly _commandCtx: CommandProcessorContext;
+  private readonly _hooksCtx: HooksContext;
+
+  constructor(private readonly ctx: CommandExecutorContext) {
+    this._commandCtx = {
+      sparseStore: ctx.sparseStore,
+      ensureArchetype: ctx.ensureArchetype,
+    };
+
+    this._hooksCtx = {
+      multiHooks: ctx.hooks,
+      has: ctx.has,
+      get: ctx.get,
+      getOptional: ctx.getOptional,
+    };
+  }
+
+  /**
+   * Entry point used by the CommandBuffer.
+   * Routes to singleton handling, destroy fast path, or structural apply.
+   */
+  executeEntityCommands(entityId: EntityId, commands: Command[]): void {
+    this._changeset.clear();
+
+    // 1. Route: component entities use flat-map storage
+    if (this.ctx.componentEntities.exists(entityId)) {
+      this.ctx.componentEntities.executeCommands(entityId, commands);
+      return;
+    }
+
+    // 2. Route: destroy uses fast path (BFS/cascade stays in World)
+    if (commands.some((cmd) => cmd.type === "destroy")) {
+      this.ctx.destroyEntityImmediate(entityId);
+      return;
+    }
+
+    // 3. Apply structural changes
+    this.applyEntityCommands(entityId, commands);
+  }
+
+  private applyEntityCommands(entityId: EntityId, commands: Command[]): void {
+    const currentArchetype = this.ctx.entityToArchetype.get(entityId);
+    if (!currentArchetype) return;
+
+    const changeset = this._changeset;
+    processCommands(entityId, currentArchetype, commands, changeset, (eid, arch, compId) => {
+      if (isExclusiveComponent(compId)) {
+        removeMatchingRelations(eid, arch, compId, changeset);
+      }
+    });
+
+    const hasStructuralChange = changeset.removes.size > 0 || changeset.adds.size > 0;
+
+    if (this.ctx.hooks.size === 0) {
+      // Fast path: no hooks, skip removedComponents map allocation and hook triggering
+      const newArchetype = applyChangeset(
+        this._commandCtx,
+        entityId,
+        currentArchetype,
+        changeset,
+        this.ctx.entityToArchetype,
+        null,
+      );
+      if (hasStructuralChange) {
+        this.updateEntityReferences(entityId, changeset);
+      }
+      if (newArchetype !== currentArchetype) {
+        this.ctx.incrementMigrations();
+      }
+      return;
+    }
+
+    const removedComponents = new Map<EntityId<any>, any>();
+    const newArchetype = applyChangeset(
+      this._commandCtx,
+      entityId,
+      currentArchetype,
+      changeset,
+      this.ctx.entityToArchetype,
+      removedComponents,
+    );
+
+    if (hasStructuralChange) {
+      this.updateEntityReferences(entityId, changeset);
+    }
+
+    if (newArchetype !== currentArchetype) {
+      this.ctx.incrementMigrations();
+    }
+
+    this.ctx.triggerLifecycleHooks(
+      this._hooksCtx,
+      entityId,
+      changeset.adds,
+      removedComponents,
+      currentArchetype,
+      newArchetype,
+    );
+  }
+
+  /**
+   * Immediate (non-buffered) component removal used during cascade deletion.
+   * Called from destroy* paths (which remain in World).
+   */
+  removeComponentImmediate(entityId: EntityId, componentType: EntityId<any>, targetEntityId: EntityId): void {
+    const sourceArchetype = this.ctx.entityToArchetype.get(entityId);
+    if (!sourceArchetype) return;
+
+    const changeset = this._removeChangeset;
+    changeset.clear();
+    changeset.delete(componentType);
+    maybeRemoveWildcardMarker(
+      entityId,
+      sourceArchetype,
+      componentType,
+      getComponentIdFromRelationId(componentType),
+      changeset,
+    );
+
+    const removedComponent = sourceArchetype.get(entityId, componentType);
+    const newArchetype = applyChangeset(
+      this._commandCtx,
+      entityId,
+      sourceArchetype,
+      changeset,
+      this.ctx.entityToArchetype,
+      null,
+    );
+    untrackEntityReference(this.ctx.entityReferences, entityId, componentType, targetEntityId);
+
+    this.ctx.triggerLifecycleHooks(
+      this._hooksCtx,
+      entityId,
+      new Map(),
+      new Map([[componentType, removedComponent]]),
+      sourceArchetype,
+      newArchetype,
+    );
+  }
+
+  /**
+   * Keeps the entity reference reverse index in sync after structural changes.
+   * Called from apply paths.
+   */
+  updateEntityReferences(entityId: EntityId, changeset: ComponentChangeset): void {
+    for (const componentType of changeset.removes) {
+      if (isEntityRelation(componentType)) {
+        const targetId = getTargetIdFromRelationId(componentType)!;
+        untrackEntityReference(this.ctx.entityReferences, entityId, componentType, targetId);
+      } else if (componentType >= 1024) {
+        untrackEntityReference(this.ctx.entityReferences, entityId, componentType, componentType);
+      }
+    }
+
+    for (const [componentType] of changeset.adds) {
+      if (isEntityRelation(componentType)) {
+        const targetId = getTargetIdFromRelationId(componentType)!;
+        trackEntityReference(this.ctx.entityReferences, entityId, componentType, targetId);
+      } else if (componentType >= 1024) {
+        trackEntityReference(this.ctx.entityReferences, entityId, componentType, componentType);
+      }
+    }
+  }
+
+  /**
+   * Exposed for any future direct needs (currently not required outside the executor).
+   */
+  getHooksContext(): HooksContext {
+    return this._hooksCtx;
+  }
+}

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/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/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);
+  }
+}