refactor(entity): split entity.ts into focused modules

Extract entity.ts into four separate modules for better organization:
- entity-types.ts: EntityId types, constants, basic type guards
- entity-relation.ts: relation ID creation, decoding, inspection
- entity-manager.ts: EntityIdManager and ComponentIdAllocator classes
- component-registry.ts: component registration and options management

The original entity.ts now re-exports everything for backwards compatibility.

Author: codehz

src/core/component-registry.ts

@@ -0,0 +1,238 @@
+import { BitSet } from "../utils/bit-set";
+import { ComponentIdAllocator } from "./entity-manager";
+import { decodeRelationRaw } from "./entity-relation";
+import type { ComponentId, EntityId } from "./entity-types";
+import {
+  COMPONENT_ID_MAX,
+  ENTITY_ID_START,
+  isComponentId,
+  isValidComponentId,
+  WILDCARD_TARGET_ID,
+} from "./entity-types";
+
+const globalComponentIdAllocator = new ComponentIdAllocator();
+
+const ComponentIdForNames: Map<string, ComponentId<any>> = new Map();
+
+/**
+ * Component options that define intrinsic properties
+ */
+export interface ComponentOptions {
+  /**
+   * Optional name for the component (for serialization/debugging)
+   */
+  name?: string;
+  /**
+   * If true, an entity can have at most one relation per base component.
+   * When adding a new relation with the same base component, any existing relations
+   * with that base component are automatically removed.
+   * Only applicable to relation components.
+   */
+  exclusive?: boolean;
+  /**
+   * If true, when a relation target entity is deleted, all entities that reference
+   * it through this component will also be deleted (cascade delete).
+   * Only applicable to entity-relation components.
+   */
+  cascadeDelete?: boolean;
+  /**
+   * If true, relations with this component will not cause archetype fragmentation.
+   * Entities with different target entities for this relation component will be stored
+   * in the same archetype, preventing fragmentation when there are many different targets.
+   * Only applicable to relation components.
+   * Inspired by Flecs' DontFragment trait.
+   */
+  dontFragment?: boolean;
+}
+
+// Array for component names (Component ID range: 1-1023)
+const componentNames: (string | undefined)[] = new Array(COMPONENT_ID_MAX + 1);
+
+// BitSets for fast component option checks (Component ID range: 1-1023)
+const exclusiveFlags = new BitSet(COMPONENT_ID_MAX + 1);
+const cascadeDeleteFlags = new BitSet(COMPONENT_ID_MAX + 1);
+const dontFragmentFlags = new BitSet(COMPONENT_ID_MAX + 1);
+
+/**
+ * Allocate a new component ID from the global allocator.
+ * @param nameOrOptions Optional name for the component (for serialization/debugging) or options object
+ * @returns The allocated component ID
+ * @example
+ * // Just a name
+ * const Position = component<Position>("Position");
+ *
+ * // With options
+ * const ChildOf = component({ exclusive: true, cascadeDelete: true });
+ *
+ * // With name and options
+ * const ChildOf = component({ name: "ChildOf", exclusive: true });
+ */
+export function component<T = void>(nameOrOptions?: string | ComponentOptions): ComponentId<T> {
+  const id = globalComponentIdAllocator.allocate<T>();
+
+  let name: string | undefined;
+  let options: ComponentOptions | undefined;
+
+  // Parse the parameter
+  if (typeof nameOrOptions === "string") {
+    name = nameOrOptions;
+  } else if (typeof nameOrOptions === "object" && nameOrOptions !== null) {
+    options = nameOrOptions;
+    name = options.name;
+  }
+
+  // Register name if provided
+  if (name) {
+    if (ComponentIdForNames.has(name)) {
+      throw new Error(`Component name "${name}" is already registered`);
+    }
+
+    componentNames[id] = name;
+    ComponentIdForNames.set(name, id);
+  }
+
+  // Register options if provided
+  if (options) {
+    // Set bitset flags for fast lookup
+    if (options.exclusive) exclusiveFlags.set(id);
+    if (options.cascadeDelete) cascadeDeleteFlags.set(id);
+    if (options.dontFragment) dontFragmentFlags.set(id);
+  }
+
+  return id;
+}
+
+/**
+ * Get a component ID by its registered name
+ * @param name The component name
+ * @returns The component ID if found, undefined otherwise
+ */
+export function getComponentIdByName(name: string): ComponentId<any> | undefined {
+  return ComponentIdForNames.get(name);
+}
+
+/** Get a component name by its ID
+ * @param id The component ID
+ * @returns The component name if found, undefined otherwise
+ */
+export function getComponentNameById(id: ComponentId<any>): string | undefined {
+  return componentNames[id];
+}
+
+/**
+ * Get component options by its ID
+ * @param id The component ID
+ * @returns The component options
+ */
+export function getComponentOptions(id: ComponentId<any>): ComponentOptions {
+  if (!isComponentId(id)) {
+    throw new Error("Invalid component ID");
+  }
+  const hasName = componentNames[id] !== undefined;
+  const hasExclusive = exclusiveFlags.has(id);
+  const hasCascadeDelete = cascadeDeleteFlags.has(id);
+  const hasDontFragment = dontFragmentFlags.has(id);
+  return {
+    name: hasName ? componentNames[id] : undefined,
+    exclusive: hasExclusive ? true : undefined,
+    cascadeDelete: hasCascadeDelete ? true : undefined,
+    dontFragment: hasDontFragment ? true : undefined,
+  };
+}
+
+/**
+ * Check if a component is marked as exclusive
+ * @param id The component ID
+ * @returns true if the component is exclusive, false otherwise
+ */
+export function isExclusiveComponent(id: ComponentId<any>): boolean {
+  return exclusiveFlags.has(id);
+}
+
+/**
+ * Check if a component is marked as cascade delete
+ * @param id The component ID
+ * @returns true if the component is cascade delete, false otherwise
+ */
+export function isCascadeDeleteComponent(id: ComponentId<any>): boolean {
+  return cascadeDeleteFlags.has(id);
+}
+
+/**
+ * Check if a component is marked as dontFragment
+ * @param id The component ID
+ * @returns true if the component is dontFragment, false otherwise
+ */
+export function isDontFragmentComponent(id: ComponentId<any>): boolean {
+  return dontFragmentFlags.has(id);
+}
+
+/**
+ * Generic function to check relation flags with specific target conditions
+ * @param id The entity/relation ID to check
+ * @param flagBitSet The bitset for the flag
+ * @param targetCondition Function to check target ID condition
+ * @returns true if the condition is met, false otherwise
+ */
+function checkRelationFlag(
+  id: EntityId<any>,
+  flagBitSet: BitSet,
+  targetCondition: (targetId: number) => boolean,
+): boolean {
+  const decoded = decodeRelationRaw(id);
+  if (decoded === null) return false;
+  const { componentId, targetId } = decoded;
+  return isValidComponentId(componentId) && targetCondition(targetId) && flagBitSet.has(componentId);
+}
+
+/**
+ * Check if a relation ID is a dontFragment relation (entity-relation or component-relation with dontFragment component)
+ * This is an optimized function that avoids the overhead of getDetailedIdType
+ * @param id The entity/relation ID to check
+ * @returns true if this is a dontFragment relation, false otherwise
+ */
+export function isDontFragmentRelation(id: EntityId<any>): boolean {
+  return checkRelationFlag(id, dontFragmentFlags, (targetId) => targetId !== WILDCARD_TARGET_ID);
+}
+
+/**
+ * Check if an ID is a wildcard relation with dontFragment component
+ * This is an optimized function for filtering archetype component types
+ * @param id The entity/relation ID to check
+ * @returns true if this is a wildcard relation with dontFragment component, false otherwise
+ */
+export function isDontFragmentWildcard(id: EntityId<any>): boolean {
+  return checkRelationFlag(id, dontFragmentFlags, (targetId) => targetId === WILDCARD_TARGET_ID);
+}
+
+/**
+ * Check if a relation ID is an exclusive relation (entity-relation or component-relation with exclusive component)
+ * This avoids the full getDetailedIdType overhead for hot paths
+ * @param id The entity/relation ID to check
+ * @returns true if this is an exclusive relation, false otherwise
+ */
+export function isExclusiveRelation(id: EntityId<any>): boolean {
+  return checkRelationFlag(id, exclusiveFlags, (targetId) => targetId !== WILDCARD_TARGET_ID);
+}
+
+/**
+ * Check if a relation ID is a wildcard relation with exclusive component
+ */
+export function isExclusiveWildcard(id: EntityId<any>): boolean {
+  return checkRelationFlag(id, exclusiveFlags, (targetId) => targetId === WILDCARD_TARGET_ID);
+}
+
+/**
+ * Check if a relation ID is a cascade delete entity-relation
+ * This is an optimized function that avoids the overhead of getDetailedIdType
+ * Note: Cascade delete only applies to entity-relations (not component-relations or wildcards)
+ * @param id The entity/relation ID to check
+ * @returns true if this is an entity-relation with cascade delete, false otherwise
+ */
+export function isCascadeDeleteRelation(id: EntityId<any>): boolean {
+  return checkRelationFlag(
+    id,
+    cascadeDeleteFlags,
+    (targetId) => targetId !== WILDCARD_TARGET_ID && targetId >= ENTITY_ID_START,
+  );
+}

src/core/entity-manager.ts

@@ -0,0 +1,113 @@
+import type { ComponentId, EntityId } from "./entity-types";
+import { COMPONENT_ID_MAX, ENTITY_ID_START, isEntityId } from "./entity-types";
+
+/**
+ * Entity ID Manager for automatic allocation and freelist recycling
+ */
+export class EntityIdManager {
+  private nextId: number = ENTITY_ID_START;
+  private freelist: Set<EntityId> = new Set();
+
+  /**
+   * Allocate a new entity ID
+   * Uses freelist if available, otherwise increments counter
+   */
+  allocate(): EntityId {
+    if (this.freelist.size > 0) {
+      const id = this.freelist.values().next().value!;
+      this.freelist.delete(id);
+      return id;
+    } else {
+      const id = this.nextId;
+      this.nextId++;
+      // Check for overflow (though unlikely in practice)
+      if (this.nextId >= Number.MAX_SAFE_INTEGER) {
+        throw new Error("Entity ID overflow: reached maximum safe integer");
+      }
+      return id as EntityId;
+    }
+  }
+
+  /**
+   * Deallocate an entity ID, adding it to the freelist for reuse
+   * @param id The entity ID to deallocate
+   */
+  deallocate(id: EntityId<any>): void {
+    if (!isEntityId(id)) {
+      throw new Error("Can only deallocate valid entity IDs");
+    }
+    if (id >= this.nextId) {
+      throw new Error("Cannot deallocate an ID that was never allocated");
+    }
+    this.freelist.add(id);
+  }
+
+  /**
+   * Get the current freelist size (for debugging/monitoring)
+   */
+  getFreelistSize(): number {
+    return this.freelist.size;
+  }
+
+  /**
+   * Get the next ID that would be allocated (for debugging)
+   */
+  getNextId(): number {
+    return this.nextId;
+  }
+
+  /**
+   * Serialize internal state for persistence.
+   * Returns a plain object representing allocator state. Values may be non-JSON-serializable.
+   */
+  serializeState(): { nextId: number; freelist: number[] } {
+    return { nextId: this.nextId, freelist: Array.from(this.freelist) };
+  }
+
+  /**
+   * Restore internal state from a previously-serialized object.
+   * Overwrites the current nextId and freelist.
+   */
+  deserializeState(state: { nextId: number; freelist?: number[] }): void {
+    if (typeof state.nextId !== "number") {
+      throw new Error("Invalid state for EntityIdManager.deserializeState");
+    }
+    this.nextId = state.nextId;
+    this.freelist = new Set((state.freelist || []) as EntityId[]);
+  }
+}
+
+/**
+ * Component ID Manager for automatic allocation
+ * Components are typically registered once and not recycled
+ */
+export class ComponentIdAllocator {
+  private nextId: number = 1;
+
+  /**
+   * Allocate a new component ID
+   * Increments counter sequentially from 1
+   */
+  allocate<T = void>(): ComponentId<T> {
+    if (this.nextId > COMPONENT_ID_MAX) {
+      throw new Error(`Component ID overflow: maximum ${COMPONENT_ID_MAX} components allowed`);
+    }
+    const id = this.nextId;
+    this.nextId++;
+    return id as ComponentId<T>;
+  }
+
+  /**
+   * Get the next ID that would be allocated (for debugging)
+   */
+  getNextId(): number {
+    return this.nextId;
+  }
+
+  /**
+   * Check if more component IDs are available
+   */
+  hasAvailableIds(): boolean {
+    return this.nextId <= COMPONENT_ID_MAX;
+  }
+}