@codehz/ecs 0.7.1 → 0.7.3

package/src/entity/index.ts

@@ -0,0 +1,63 @@
+// Re-export all types and functions from split modules for backwards compatibility
+
+// Entity types and constants
+export type {
+  ComponentId,
+  ComponentRelationId,
+  EntityId,
+  EntityRelationId,
+  RelationId,
+  WildcardRelationId,
+} from "./types";
+
+export {
+  COMPONENT_ID_MAX,
+  ENTITY_ID_START,
+  INVALID_COMPONENT_ID,
+  RELATION_SHIFT,
+  WILDCARD_TARGET_ID,
+  createComponentId,
+  createEntityId,
+  isComponentId,
+  isEntityId,
+  isRelationId,
+  isValidComponentId,
+} from "./types";
+
+// Relation functions
+export {
+  decodeRelationId,
+  decodeRelationRaw,
+  getComponentIdFromRelationId,
+  getDetailedIdType,
+  getIdType,
+  getTargetIdFromRelationId,
+  inspectEntityId,
+  isAnyRelation,
+  isComponentRelation,
+  isEntityRelation,
+  isWildcardRelationId,
+  relation,
+} from "./relation";
+
+// Entity and component managers
+export { ComponentIdAllocator, EntityIdManager } from "./manager";
+
+// Component registry
+export type { ComponentOptions } from "../component/registry";
+
+export {
+  component,
+  getComponentIdByName,
+  getComponentMerge,
+  getComponentNameById,
+  getComponentOptions,
+  isCascadeDeleteComponent,
+  isCascadeDeleteRelation,
+  isDontFragmentComponent,
+  isDontFragmentRelation,
+  isDontFragmentWildcard,
+  isExclusiveComponent,
+  isExclusiveRelation,
+  isExclusiveWildcard,
+} from "../component/registry";

package/src/entity/manager.ts

@@ -0,0 +1,115 @@
+import type { ComponentId, EntityId } from "./types";
+import { COMPONENT_ID_MAX, ENTITY_ID_START, isEntityId } from "./types";
+
+/**
+ * Entity ID Manager for automatic allocation and freelist recycling
+ */
+export class EntityIdManager {
+  private nextId: number = ENTITY_ID_START;
+  /**
+   * Free list uses a stack (LIFO) for better memory locality when reusing IDs.
+   * We use an array instead of a Set for significantly better performance.
+   */
+  private freelist: EntityId[] = [];
+
+  /**
+   * Allocate a new entity ID
+   * Uses freelist if available, otherwise increments counter
+   */
+  allocate(): EntityId {
+    if (this.freelist.length > 0) {
+      return this.freelist.pop()!;
+    } 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.push(id);
+  }
+
+  /**
+   * Get the current freelist size (for debugging/monitoring)
+   */
+  getFreelistSize(): number {
+    return this.freelist.length;
+  }
+
+  /**
+   * 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 = (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;
+  }
+}

package/src/entity/relation.ts

@@ -0,0 +1,319 @@
+import type {
+  ComponentId,
+  ComponentRelationId,
+  EntityId,
+  EntityRelationId,
+  RelationId,
+  WildcardRelationId,
+} from "./types";
+import {
+  ENTITY_ID_START,
+  isComponentId,
+  isEntityId,
+  isValidComponentId,
+  RELATION_SHIFT,
+  WILDCARD_TARGET_ID,
+} from "./types";
+
+/**
+ * Internal function to decode a relation ID into raw component and target IDs
+ * @param id The EntityId to decode
+ * @returns Object with componentId and targetId, or null if not a relation
+ */
+export function decodeRelationRaw(id: EntityId<any>): { componentId: number; targetId: number } | null {
+  if (id >= 0) return null;
+  const absId = -id;
+  const componentId = Math.floor(absId / RELATION_SHIFT);
+  const targetId = absId % RELATION_SHIFT;
+  return { componentId, targetId };
+}
+
+/**
+ * Type for relation ID based on component and target types
+ */
+type RelationIdType<T, R> =
+  R extends ComponentId<infer U>
+    ? U extends void
+      ? ComponentRelationId<T>
+      : ComponentRelationId<T extends void ? U : T>
+    : R extends EntityId<any>
+      ? EntityRelationId<T>
+      : never;
+
+/**
+ * Create a relation ID by associating a component with a target entity, component, or wildcard.
+ *
+ * Relations are encoded as negative numbers and can be used anywhere a regular component ID is accepted.
+ * Use `"*"` as the target to create a wildcard relation for querying all targets of a given relation type.
+ *
+ * @param componentId - The base component ID (must be a valid component)
+ * @param targetId - The target entity ID, component ID, or `"*"` for wildcard
+ * @returns A relation ID that encodes both the component and target
+ *
+ * @throws {Error} If `componentId` is not a valid component ID
+ * @throws {Error} If `targetId` is not a valid entity, component, or `"*"`
+ *
+ * @example
+ * const ChildOf = component();
+ * const parent = world.new();
+ *
+ * // Entity relation
+ * const childRelation = relation(ChildOf, parent);
+ * world.set(child, childRelation);
+ *
+ * // Wildcard relation (queries all targets)
+ * const allChildren = world.createQuery([relation(ChildOf, "*")]);
+ */
+export function relation<T>(componentId: ComponentId<T>, targetId: "*"): WildcardRelationId<T>;
+export function relation<T, R extends EntityId<any>>(componentId: ComponentId<T>, targetId: R): RelationIdType<T, R>;
+export function relation<T>(componentId: ComponentId<T>, targetId: EntityId<any> | "*"): EntityId<any> {
+  if (!isComponentId(componentId)) {
+    throw new Error("First argument must be a valid component ID");
+  }
+
+  let actualTargetId: number;
+  if (targetId === "*") {
+    actualTargetId = WILDCARD_TARGET_ID;
+  } else {
+    if (!isEntityId(targetId) && !isComponentId(targetId)) {
+      throw new Error("Second argument must be a valid entity ID, component ID, or '*'");
+    }
+    actualTargetId = targetId;
+  }
+
+  // Encode: negative number with component_id * 2^42 + target_id
+  return -(componentId * RELATION_SHIFT + actualTargetId) as EntityId<any>;
+}
+
+/**
+ * Check if an ID is a wildcard relation (created with `relation(componentId, "*")`).
+ *
+ * @param id - The ID to check
+ * @returns `true` if the ID is a wildcard relation, `false` otherwise
+ */
+export function isWildcardRelationId<T>(id: EntityId<T>): id is WildcardRelationId<T> {
+  const decoded = decodeRelationRaw(id);
+  return decoded !== null && decoded.targetId === WILDCARD_TARGET_ID;
+}
+
+/**
+ * Decode a relation ID into component and target IDs
+ * @param relationId The relation ID (must be negative)
+ * @returns Object with componentId, targetId, and relation type
+ */
+export function decodeRelationId(relationId: RelationId<any>): {
+  componentId: ComponentId<any>;
+  targetId: EntityId<any>;
+  type: "entity" | "component" | "wildcard";
+} {
+  const decoded = decodeRelationRaw(relationId);
+  if (decoded === null) {
+    throw new Error("ID is not a relation ID");
+  }
+
+  const { componentId: rawComponentId, targetId: rawTargetId } = decoded;
+  if (!isValidComponentId(rawComponentId)) {
+    throw new Error("Invalid component ID in relation");
+  }
+
+  const componentId = rawComponentId as ComponentId<any>;
+  const targetId = rawTargetId as EntityId<any>;
+
+  // Determine type based on targetId range
+  if (targetId === WILDCARD_TARGET_ID) {
+    return { componentId, targetId, type: "wildcard" };
+  } else if (isEntityId(targetId)) {
+    return { componentId, targetId, type: "entity" };
+  } else if (isComponentId(targetId)) {
+    return { componentId, targetId, type: "component" };
+  } else {
+    throw new Error("Invalid target ID in relation");
+  }
+}
+
+/**
+ * Get the string representation of an ID type
+ */
+export function getIdType(
+  id: EntityId<any>,
+): "component" | "entity" | "entity-relation" | "component-relation" | "wildcard-relation" | "invalid" {
+  if (isComponentId(id)) return "component";
+  if (isEntityId(id)) return "entity";
+
+  if (id < 0) {
+    const decoded = decodeRelationRaw(id as RelationId<any>);
+    if (decoded === null) return "invalid";
+
+    const { componentId: rawComponentId, targetId: rawTargetId } = decoded;
+
+    // Validate component ID
+    if (!isValidComponentId(rawComponentId)) return "invalid";
+
+    // Determine type based on targetId range
+    if (rawTargetId === WILDCARD_TARGET_ID) {
+      return "wildcard-relation";
+    } else if (isEntityId(rawTargetId as EntityId<any>)) {
+      return "entity-relation";
+    } else if (isComponentId(rawTargetId as ComponentId<any>)) {
+      return "component-relation";
+    } else {
+      return "invalid";
+    }
+  }
+
+  return "invalid"; // fallback for unknown/invalid IDs
+}
+
+/**
+ * Get detailed type information for an EntityId
+ * @param id The EntityId to analyze
+ * @returns Detailed type information including relation subtypes
+ */
+export function getDetailedIdType(id: EntityId<any>):
+  | {
+      type: "component" | "entity" | "invalid";
+      componentId?: never;
+      targetId?: never;
+    }
+  | {
+      type: "entity-relation" | "wildcard-relation";
+      componentId: ComponentId<any>;
+      targetId: EntityId<any>;
+    }
+  | {
+      type: "component-relation";
+      componentId: ComponentId<any>;
+      targetId: ComponentId<any>;
+    } {
+  if (isComponentId(id)) {
+    return { type: "component" };
+  }
+
+  if (isEntityId(id)) {
+    return { type: "entity" };
+  }
+
+  if (id < 0) {
+    const decoded = decodeRelationRaw(id as RelationId<any>);
+    if (decoded === null) {
+      return { type: "invalid" };
+    }
+
+    const { componentId: rawComponentId, targetId: rawTargetId } = decoded;
+
+    // Validate component ID
+    if (!isValidComponentId(rawComponentId)) {
+      return { type: "invalid" };
+    }
+
+    const componentId = rawComponentId as ComponentId<any>;
+    const targetId = rawTargetId as EntityId<any>;
+
+    // Determine type based on targetId range
+    if (targetId === WILDCARD_TARGET_ID) {
+      return { type: "wildcard-relation", componentId, targetId };
+    } else if (isEntityId(targetId)) {
+      return { type: "entity-relation", componentId, targetId };
+    } else if (isComponentId(targetId as any)) {
+      return { type: "component-relation", componentId, targetId: targetId as ComponentId<any> };
+    } else {
+      return { type: "invalid" };
+    }
+  }
+
+  // Unknown/invalid ID
+  return { type: "invalid" };
+}
+
+/**
+ * Inspect an EntityId and return a human-readable string representation
+ * @param id The EntityId to inspect
+ * @returns A friendly string representation of the ID
+ */
+export function inspectEntityId(id: EntityId<any>): string {
+  if (id === 0) {
+    return "Invalid Component ID (0)";
+  }
+
+  if (isComponentId(id)) {
+    return `Component ID (${id})`;
+  }
+
+  if (isEntityId(id)) {
+    return `Entity ID (${id})`;
+  }
+
+  if (id < 0) {
+    const decoded = decodeRelationRaw(id as RelationId<any>);
+    if (decoded === null) {
+      return `Invalid Relation ID (${id})`;
+    }
+
+    const { componentId: rawComponentId, targetId: rawTargetId } = decoded;
+
+    // Validate component ID
+    if (!isValidComponentId(rawComponentId)) {
+      return `Invalid Relation ID (${id})`;
+    }
+
+    // Determine target type and format output
+    const componentStr = `Component ID (${rawComponentId})`;
+    let targetStr: string;
+
+    if (rawTargetId === WILDCARD_TARGET_ID) {
+      targetStr = "Wildcard (*)";
+    } else if (isEntityId(rawTargetId as EntityId<any>)) {
+      targetStr = `Entity ID (${rawTargetId})`;
+    } else if (isComponentId(rawTargetId as ComponentId<any>)) {
+      targetStr = `Component ID (${rawTargetId})`;
+    } else {
+      return `Invalid Relation ID (${id})`;
+    }
+
+    return `Relation ID: ${componentStr} -> ${targetStr}`;
+  }
+
+  return `Unknown ID (${id})`;
+}
+
+/**
+ * Get the componentId from a relation ID without fully decoding the relation.
+ * Returns undefined for non-relation IDs or invalid component IDs.
+ */
+export function getComponentIdFromRelationId<T>(id: EntityId<T>): ComponentId<T> | undefined {
+  const decoded = decodeRelationRaw(id);
+  if (decoded === null || !isValidComponentId(decoded.componentId)) return undefined;
+  return decoded.componentId as ComponentId<T>;
+}
+
+/**
+ * Get the targetId from a relation ID without fully decoding the relation.
+ * Returns undefined for non-relation IDs.
+ */
+export function getTargetIdFromRelationId(id: EntityId<any>): EntityId<any> | undefined {
+  const decoded = decodeRelationRaw(id);
+  return decoded?.targetId as EntityId<any>;
+}
+
+/**
+ * Check if an ID is an entity-relation (relation targeting an entity, not a component or wildcard)
+ */
+export function isEntityRelation(id: EntityId<any>): boolean {
+  const decoded = decodeRelationRaw(id);
+  return decoded !== null && decoded.targetId >= ENTITY_ID_START;
+}
+
+/**
+ * Check if an ID is a component-relation (relation targeting a component)
+ */
+export function isComponentRelation(id: EntityId<any>): boolean {
+  const decoded = decodeRelationRaw(id);
+  return decoded !== null && isValidComponentId(decoded.targetId);
+}
+
+/**
+ * Check if an ID is any type of relation (entity, component, or wildcard)
+ */
+export function isAnyRelation(id: EntityId<any>): boolean {
+  return id < 0;
+}

package/src/entity/types.ts

@@ -0,0 +1,135 @@
+/**
+ * Unique symbol brand for associating component type information with EntityId
+ */
+declare const __componentTypeMarker: unique symbol;
+
+/**
+ * Unique symbol brand for tagging the kind of EntityId (e.g., 'component', 'entity-relation')
+ */
+declare const __entityIdTypeTag: unique symbol;
+
+/**
+ * Entity ID type for ECS architecture
+ * Based on 52-bit integers within safe integer range
+ * - Component IDs: 1-1023
+ * - Entity IDs: 1024+
+ * - Relation IDs: negative numbers encoding component and entity associations
+ */
+/**
+ * Branded numeric type representing an ECS identifier.
+ *
+ * - {@link ComponentId}: positive values in range `1–1023`
+ * - Entity IDs: values `1024+`
+ * - {@link RelationId}: negative values encoding `(componentId, targetId)`
+ *
+ * @template T - The data type associated with this ID
+ * @template U - Discriminant for the ID kind (e.g. `"component"`, `"entity-relation"`)
+ */
+export type EntityId<T = unknown, U = unknown> = number & {
+  readonly [__componentTypeMarker]: T;
+  readonly [__entityIdTypeTag]: U;
+};
+
+/**
+ * Component identifier. Valid values are `1` through `1023`.
+ * Created with {@link component}.
+ *
+ * @template T - The data type stored by this component (`void` for tag components)
+ */
+export type ComponentId<T = void> = EntityId<T, "component">;
+
+/**
+ * Relation identifier targeting an entity.
+ * Created with {@link relation}.
+ *
+ * @template T - The data type stored by this relation
+ */
+export type EntityRelationId<T = void> = EntityId<T, "entity-relation">;
+
+/**
+ * Relation identifier targeting another component (singleton relation).
+ * Created with {@link relation}.
+ *
+ * @template T - The data type stored by this relation
+ */
+export type ComponentRelationId<T = void> = EntityId<T, "component-relation">;
+
+/**
+ * Wildcard relation identifier used to query all targets of a given relation component.
+ * Created with `relation(componentId, "*")`.
+ *
+ * @template T - The data type stored by the relation
+ */
+export type WildcardRelationId<T = void> = EntityId<T, "wildcard-relation">;
+
+/**
+ * Union of all relation identifier kinds.
+ *
+ * @template T - The data type stored by the relation
+ */
+export type RelationId<T = void> = EntityRelationId<T> | ComponentRelationId<T> | WildcardRelationId<T>;
+
+/**
+ * Constants for ID ranges
+ */
+export const INVALID_COMPONENT_ID = 0;
+export const COMPONENT_ID_MAX = 1023;
+export const ENTITY_ID_START = 1024;
+
+/**
+ * Constants for relation ID encoding
+ */
+export const RELATION_SHIFT = 2 ** 42;
+export const WILDCARD_TARGET_ID = 0;
+
+/**
+ * Check if a component ID is valid (1-1023)
+ */
+export function isValidComponentId(componentId: number): boolean {
+  return componentId >= 1 && componentId <= COMPONENT_ID_MAX;
+}
+
+/**
+ * Check if an ID is a component ID
+ */
+export function isComponentId<T>(id: EntityId<T>): id is ComponentId<T> {
+  return id >= 1 && id <= COMPONENT_ID_MAX;
+}
+
+/**
+ * Check if an ID is an entity ID
+ */
+export function isEntityId<T>(id: EntityId<T>): id is EntityId<T> {
+  return id >= ENTITY_ID_START;
+}
+
+/**
+ * Check if an ID is a relation ID
+ */
+export function isRelationId<T>(id: EntityId<T>): id is RelationId<T> {
+  return id < 0;
+}
+
+/**
+ * Create a component ID
+ * @param id Component identifier (1-1023)
+ * @internal This function is for internal use and testing only. Use `component()` to create components.
+ * @see component
+ */
+export function createComponentId<T = void>(id: number): ComponentId<T> {
+  if (id < 1 || id > COMPONENT_ID_MAX) {
+    throw new Error(`Component ID must be between 1 and ${COMPONENT_ID_MAX}`);
+  }
+  return id as ComponentId<T>;
+}
+
+/**
+ * Create an entity ID
+ * @param id Entity identifier (starting from 1024)
+ */
+export function createEntityId(id: number): EntityId {
+  if (id < ENTITY_ID_START) {
+    throw new Error(`Entity ID must be ${ENTITY_ID_START} or greater`);
+  }
+  return id as EntityId;
+}

package/src/index.ts

@@ -0,0 +1,41 @@
+// ECS Library Entry Point - Public API
+
+// Entity ID types and utilities
+export type {
+  ComponentId,
+  ComponentOptions,
+  ComponentRelationId,
+  EntityId,
+  EntityRelationId,
+  RelationId,
+  WildcardRelationId,
+} from "./entity";
+
+export {
+  component,
+  decodeRelationId,
+  getComponentIdByName,
+  getComponentNameById,
+  isComponentId,
+  isEntityId,
+  isRelationId,
+  isWildcardRelationId,
+  relation,
+} from "./entity";
+
+// World class
+export type {
+  SerializedComponent,
+  SerializedEntity,
+  SerializedEntityId,
+  SerializedWorld,
+} from "./storage/serialization";
+export { EntityBuilder } from "./world/builder";
+export type { ComponentDef } from "./world/builder";
+export { World } from "./world/world";
+
+// Query class
+export { Query } from "./query/query";
+
+// Type utilities
+export type { ComponentTuple, ComponentType, LifecycleCallback, LifecycleHook } from "./types";