@codehz/ecs 0.7.1 → 0.7.3

package/src/commands/buffer.ts

@@ -0,0 +1,110 @@
+import type { EntityId } from "../entity";
+
+/**
+ * Maximum number of command buffer execution iterations to prevent infinite loops
+ */
+const MAX_COMMAND_ITERATIONS = 100;
+
+/**
+ * Command for deferred execution
+ * Uses discriminated union for type safety
+ */
+export type Command =
+  | { type: "set"; entityId: EntityId; componentType: EntityId<any>; component: any }
+  | { type: "delete"; entityId: EntityId; componentType: EntityId<any> }
+  | { type: "destroy"; entityId: EntityId };
+
+/**
+ * Command buffer for deferred structural changes
+ */
+export class CommandBuffer {
+  private commands: Command[] = [];
+  private swapBuffer: Command[] = [];
+  /** Reusable map to group commands by entity, avoids per-sync allocations */
+  private entityCommands: Map<EntityId, Command[]> = new Map();
+  private executeEntityCommands: (entityId: EntityId, commands: Command[]) => void;
+
+  /**
+   * Create a command buffer with an executor function
+   */
+  constructor(executeEntityCommands: (entityId: EntityId, commands: Command[]) => void) {
+    this.executeEntityCommands = executeEntityCommands;
+  }
+
+  /**
+   * Add a component to an entity (deferred)
+   */
+  set(entityId: EntityId, componentType: EntityId<void>): void;
+  set<T>(entityId: EntityId, componentType: EntityId<T>, component: NoInfer<T>): void;
+  set(entityId: EntityId, componentType: EntityId, component?: any): void {
+    this.commands.push({ type: "set", entityId, componentType, component });
+  }
+
+  /**
+   * Remove a component from an entity (deferred)
+   */
+  remove<T>(entityId: EntityId, componentType: EntityId<T>): void {
+    this.commands.push({ type: "delete", entityId, componentType });
+  }
+
+  /**
+   * Destroy an entity (deferred)
+   */
+  delete(entityId: EntityId): void {
+    this.commands.push({ type: "destroy", entityId });
+  }
+
+  /**
+   * Execute all commands and clear the buffer
+   */
+  execute(): void {
+    let iterations = 0;
+
+    while (this.commands.length > 0) {
+      if (iterations >= MAX_COMMAND_ITERATIONS) {
+        throw new Error("Command execution exceeded maximum iterations, possible infinite loop");
+      }
+      iterations++;
+
+      // Swap buffers to avoid allocation
+      const currentCommands = this.commands;
+      this.commands = this.swapBuffer;
+
+      // Group commands by entity, reusing the persistent Map
+      const entityCommands = this.entityCommands;
+      for (const cmd of currentCommands) {
+        const existing = entityCommands.get(cmd.entityId);
+        if (existing !== undefined) {
+          existing.push(cmd);
+        } else {
+          entityCommands.set(cmd.entityId, [cmd]);
+        }
+      }
+
+      // Clear the consumed buffer for reuse
+      currentCommands.length = 0;
+      this.swapBuffer = currentCommands;
+
+      // Process each entity's commands and clear the map (but not the arrays,
+      // as callers may hold references to them after the executor returns)
+      for (const [entityId, commands] of entityCommands) {
+        this.executeEntityCommands(entityId, commands);
+      }
+      entityCommands.clear();
+    }
+  }
+
+  /**
+   * Get current commands (for testing)
+   */
+  getCommands(): Command[] {
+    return [...this.commands];
+  }
+
+  /**
+   * Clear all commands
+   */
+  clear(): void {
+    this.commands = [];
+  }
+}

package/src/commands/changeset.ts

@@ -0,0 +1,104 @@
+import type { EntityId } from "../entity";
+
+/**
+ * @internal Represents a set of component changes to be applied to an entity
+ */
+export class ComponentChangeset {
+  readonly adds = new Map<EntityId<any>, any>();
+  readonly removes = new Set<EntityId<any>>();
+
+  /**
+   * Add a component to the changeset
+   */
+  set<T>(componentType: EntityId<T>, component: T): void {
+    this.adds.set(componentType, component);
+    this.removes.delete(componentType); // Remove from removes if it was going to be removed
+  }
+
+  /**
+   * Remove a component from the changeset
+   */
+  delete<T>(componentType: EntityId<T>): void {
+    this.removes.add(componentType);
+    this.adds.delete(componentType); // Remove from adds if it was going to be added
+  }
+
+  /**
+   * Check if the changeset has any changes
+   */
+  hasChanges(): boolean {
+    return this.adds.size > 0 || this.removes.size > 0;
+  }
+
+  /**
+   * Clear all changes
+   */
+  clear(): void {
+    this.adds.clear();
+    this.removes.clear();
+  }
+
+  /**
+   * Merge another changeset into this one
+   */
+  merge(other: ComponentChangeset): void {
+    // Merge additions
+    for (const [componentType, component] of other.adds) {
+      this.adds.set(componentType, component);
+      this.removes.delete(componentType);
+    }
+    // Merge removals
+    for (const componentType of other.removes) {
+      this.removes.add(componentType);
+      this.adds.delete(componentType);
+    }
+  }
+
+  /**
+   * Apply the changeset to existing components and return the final state
+   */
+  applyTo(existingComponents: Map<EntityId<any>, any>): Map<EntityId<any>, any> {
+    // Apply removals
+    for (const componentType of this.removes) {
+      existingComponents.delete(componentType);
+    }
+
+    // Apply additions/updates
+    for (const [componentType, component] of this.adds) {
+      existingComponents.set(componentType, component);
+    }
+
+    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;
+  }
+}

package/src/component/entity-store.ts

@@ -0,0 +1,223 @@
+import { hasWildcardRelation } from "../archetype/helpers";
+import type { Command } from "../commands/buffer";
+import {
+  getComponentIdFromRelationId,
+  getComponentMerge,
+  getDetailedIdType,
+  isWildcardRelationId,
+  type ComponentId,
+  type EntityId,
+  type WildcardRelationId,
+} from "../entity";
+
+/**
+ * Manages component entity (singleton) storage.
+ *
+ * Component entities use a flat Map-based storage rather than the Archetype-based
+ * storage used for regular entities. Their IDs are in the component ID range
+ * (or are relation IDs), distinguishing them from regular entity IDs.
+ */
+export class ComponentEntityStore {
+  private readonly componentEntityComponents: Map<EntityId, Map<EntityId<any>, any>> = new Map();
+  private readonly relationEntityIdsByTarget: Map<EntityId, Set<EntityId>> = new Map();
+
+  /**
+   * Check if an entity ID is a component entity type.
+   * Returns true for component IDs, component-relation IDs, and entity-relation IDs —
+   * i.e. anything that is NOT a plain entity or an invalid ID.
+   */
+  exists(entityId: EntityId): boolean {
+    const detailed = getDetailedIdType(entityId);
+    return detailed.type !== "entity" && detailed.type !== "invalid";
+  }
+
+  /**
+   * Check if a component entity has a specific component.
+   */
+  has(entityId: EntityId, componentType: EntityId<any>): boolean {
+    return this.componentEntityComponents.get(entityId)?.has(componentType) ?? false;
+  }
+
+  /**
+   * Check if a singleton component has data — the has(componentId) overload.
+   * In singleton usage the entity ID and the component type are the same value.
+   */
+  hasSingleton(componentId: EntityId<any>): boolean {
+    return this.componentEntityComponents.get(componentId)?.has(componentId) ?? false;
+  }
+
+  /**
+   * Check if a component entity has any wildcard relations matching a component ID.
+   */
+  hasWildcard(entityId: EntityId, componentId: ComponentId<any>): boolean {
+    const data = this.componentEntityComponents.get(entityId);
+    if (!data) return false;
+    return hasWildcardRelation(data, componentId);
+  }
+
+  /**
+   * Get a component value from a component entity.
+   * Throws if the component does not exist.
+   */
+  get<T>(entityId: EntityId, componentType: EntityId<T>): T {
+    const data = this.componentEntityComponents.get(entityId);
+    if (!data || !data.has(componentType)) {
+      throw new Error(
+        `Entity ${entityId} does not have component ${componentType}. Use has() to check component existence before calling get().`,
+      );
+    }
+    return data.get(componentType) as T;
+  }
+
+  /**
+   * Get an optional component value from a component entity.
+   * Returns undefined if the component does not exist.
+   */
+  getOptional<T>(entityId: EntityId, componentType: EntityId<T>): { value: T } | undefined {
+    const data = this.componentEntityComponents.get(entityId);
+    if (!data || !data.has(componentType)) return undefined;
+    return { value: data.get(componentType) as T };
+  }
+
+  /**
+   * Get all wildcard relations of a given type from a component entity.
+   */
+  getWildcard<T>(entityId: EntityId, wildcardComponentType: WildcardRelationId<T>): [EntityId<unknown>, T][] {
+    const componentId = getComponentIdFromRelationId(wildcardComponentType);
+    const data = this.componentEntityComponents.get(entityId);
+    if (componentId === undefined || !data) return [];
+
+    const relations: [EntityId<unknown>, T][] = [];
+    for (const [key, value] of data.entries()) {
+      if (getComponentIdFromRelationId(key) !== componentId) continue;
+      const detailed = getDetailedIdType(key);
+      if (detailed.type === "entity-relation" || detailed.type === "component-relation") {
+        relations.push([detailed.targetId, value as T]);
+      }
+    }
+    return relations;
+  }
+
+  /**
+   * Clear all data for a component entity.
+   */
+  clear(entityId: EntityId): void {
+    if (this.componentEntityComponents.delete(entityId)) {
+      this.unregisterRelationEntityId(entityId);
+    }
+  }
+
+  /**
+   * Cleanup all component entities that reference a given target entity.
+   * Called when a target entity is destroyed.
+   */
+  cleanupReferencesTo(targetId: EntityId): void {
+    const relationEntities = this.relationEntityIdsByTarget.get(targetId);
+    if (!relationEntities) return;
+    for (const relationEntityId of relationEntities) {
+      this.componentEntityComponents.delete(relationEntityId);
+    }
+    this.relationEntityIdsByTarget.delete(targetId);
+  }
+
+  /**
+   * Execute a batch of commands for a component entity.
+   */
+  executeCommands(entityId: EntityId, commands: Command[]): void {
+    if (commands.some((cmd) => cmd.type === "destroy")) {
+      this.clear(entityId);
+      return;
+    }
+
+    const pendingSetValues = new Map<EntityId<any>, any>();
+
+    for (const command of commands) {
+      if (command.type === "set" && command.componentType) {
+        const merge = getComponentMerge(command.componentType);
+        let nextValue = command.component;
+        if (merge !== undefined && pendingSetValues.has(command.componentType)) {
+          const prevValue = pendingSetValues.get(command.componentType);
+          nextValue = merge(prevValue, command.component);
+        }
+        pendingSetValues.set(command.componentType, nextValue);
+
+        let data = this.componentEntityComponents.get(entityId);
+        if (!data) {
+          data = new Map();
+          this.componentEntityComponents.set(entityId, data);
+          this.registerRelationEntityId(entityId);
+        }
+        data.set(command.componentType, nextValue);
+      } else if (command.type === "delete" && command.componentType) {
+        const data = this.componentEntityComponents.get(entityId);
+
+        if (isWildcardRelationId(command.componentType)) {
+          const componentId = getComponentIdFromRelationId(command.componentType);
+          if (componentId !== undefined) {
+            if (data) {
+              for (const key of Array.from(data.keys())) {
+                if (getComponentIdFromRelationId(key) === componentId) {
+                  data.delete(key);
+                }
+              }
+            }
+            for (const key of Array.from(pendingSetValues.keys())) {
+              if (getComponentIdFromRelationId(key) === componentId) {
+                pendingSetValues.delete(key);
+              }
+            }
+          }
+        } else {
+          data?.delete(command.componentType);
+          pendingSetValues.delete(command.componentType);
+        }
+
+        if (data?.size === 0) {
+          this.clear(entityId);
+        }
+      }
+    }
+  }
+
+  /**
+   * Initialize a component entity from a deserialization snapshot.
+   */
+  initFromSnapshot(entityId: EntityId, componentMap: Map<EntityId<any>, any>): void {
+    this.componentEntityComponents.set(entityId, componentMap);
+    this.registerRelationEntityId(entityId);
+  }
+
+  /**
+   * Iterate over all component entity entries.
+   * Used for serialization.
+   */
+  entries(): IterableIterator<[EntityId, Map<EntityId<any>, any>]> {
+    return this.componentEntityComponents.entries();
+  }
+
+  private registerRelationEntityId(entityId: EntityId): void {
+    const detailed = getDetailedIdType(entityId);
+    if (detailed.type !== "entity-relation") return;
+    const targetId = detailed.targetId;
+    if (targetId === undefined) return;
+    const existing = this.relationEntityIdsByTarget.get(targetId);
+    if (existing) {
+      existing.add(entityId);
+      return;
+    }
+    this.relationEntityIdsByTarget.set(targetId, new Set([entityId]));
+  }
+
+  private unregisterRelationEntityId(entityId: EntityId): void {
+    const detailed = getDetailedIdType(entityId);
+    if (detailed.type !== "entity-relation") return;
+    const targetId = detailed.targetId;
+    if (targetId === undefined) return;
+    const existing = this.relationEntityIdsByTarget.get(targetId);
+    if (!existing) return;
+    existing.delete(entityId);
+    if (existing.size === 0) {
+      this.relationEntityIdsByTarget.delete(targetId);
+    }
+  }
+}