@codehz/ecs 0.6.7 → 0.6.9

package/builder.d.mts

@@ -163,13 +163,21 @@ declare class ComponentChangeset {
 //#region src/commands/command-buffer.d.ts
 /**
  * Command for deferred execution
+ * Uses discriminated union for type safety
  */
-interface Command {
-  type: "set" | "delete" | "destroy";
+type Command = {
+  type: "set";
   entityId: EntityId;
-  componentType?: EntityId<any>;
-  component?: any;
-}
+  componentType: EntityId<any>;
+  component: any;
+} | {
+  type: "delete";
+  entityId: EntityId;
+  componentType: EntityId<any>;
+} | {
+  type: "destroy";
+  entityId: EntityId;
+};
 //#endregion
 //#region src/core/types.d.ts
 /**
@@ -181,7 +189,7 @@ interface LegacyLifecycleHook<T = unknown> {
    */
   on_init?: (entityId: EntityId, componentType: EntityId<T>, component: T) => void;
   /**
-   * Called when a component is added to an entity
+   * Called when a component is updated on an entity
    */
   on_set?: (entityId: EntityId, componentType: EntityId<T>, component: T) => void;
   /**
@@ -235,6 +243,10 @@ declare class Archetype {
    * The component types that define this archetype
    */
   readonly componentTypes: EntityId<any>[];
+  /**
+   * Set version of componentTypes for O(1) lookups in hot paths
+   */
+  readonly componentTypeSet: ReadonlySet<EntityId<any>>;
   /**
    * List of entities in this archetype
    */
@@ -254,9 +266,6 @@ declare class Archetype {
    * Stored in World to avoid migration overhead when entities change archetypes
    */
   private dontFragmentRelations;
-  /**
-   * Cache for pre-computed component data sources to avoid repeated calculations
-   */
   /**
    * Multi-hooks that match this archetype
    */
@@ -267,6 +276,12 @@ declare class Archetype {
   private componentDataSourcesCache;
   constructor(componentTypes: EntityId<any>[], dontFragmentRelations: Map<EntityId, Map<EntityId<any>, any>>);
   get size(): number;
+  /**
+   * Check if the given component types match this archetype
+   * @param componentTypes - Component types to check (can be in any order)
+   * @returns true if the types match this archetype's component set
+   * @note This method handles unsorted input by internally sorting for comparison
+   */
   matches(componentTypes: EntityId<any>[]): boolean;
   addEntity(entityId: EntityId, componentData: Map<EntityId<any>, any>): void;
   private addDontFragmentRelations;
@@ -320,6 +335,8 @@ declare class Query {
   private filter;
   private cachedArchetypes;
   private isDisposed;
+  /** Cache key assigned by World for O(1) releaseQuery lookup */
+  _cacheKey: string | undefined;
   /** Cached wildcard component types for faster entity filtering */
   private wildcardTypes;
   /** Cached specific dontFragment relation types that need entity-level filtering */
@@ -401,9 +418,16 @@ type SerializedEntityId = number | string | {
   component: string;
   target: number | string | "*";
 };
+/**
+ * Serialized state of EntityIdManager
+ */
+interface SerializedEntityIdManager {
+  nextId: number;
+  freelist?: number[];
+}
 type SerializedWorld = {
   version: number;
-  entityManager: any;
+  entityManager: SerializedEntityIdManager;
   entities: SerializedEntity[];
   componentEntities?: SerializedEntity[];
 };
@@ -482,21 +506,32 @@ declare class World {
    * @overload set<T>(entityId: EntityId, componentType: EntityId<T>, component: NoInfer<T>): void
    * Adds or updates a component with data on the entity
    *
+   * @overload set<T>(componentId: ComponentId<T>, component: NoInfer<T>): void
+   * Adds or updates a singleton component (shorthand for set(componentId, componentId, component))
+   *
    * @throws {Error} If the entity does not exist
    * @throws {Error} If the component type is invalid or is a wildcard relation
    *
    * @example
    * world.set(entity, Position, { x: 10, y: 20 });
    * world.set(entity, Marker); // void component
+   * world.set(GlobalConfig, { debug: true }); // singleton component
    * world.sync(); // Apply changes
    */
   set(entityId: EntityId, componentType: EntityId<void>): void;
   set<T>(entityId: EntityId, componentType: EntityId<T>, component: NoInfer<T>): void;
+  set<T>(componentId: ComponentId<T>, component: NoInfer<T>): void;
   /**
    * Removes a component from an entity.
    * The change is buffered and takes effect after calling `world.sync()`.
    * If the entity does not exist, throws an error.
    *
+   * @overload remove<T>(entityId: EntityId, componentType: EntityId<T>): void
+   * Removes a component from an entity.
+   *
+   * @overload remove<T>(componentId: ComponentId<T>): void
+   * Removes a singleton component (shorthand for remove(componentId, componentId)).
+   *
    * @template T - The component data type
    * @param entityId - The entity identifier
    * @param componentType - The component type to remove
@@ -506,8 +541,10 @@ declare class World {
    *
    * @example
    * world.remove(entity, Position);
+   * world.remove(GlobalConfig); // Remove singleton component
    * world.sync(); // Apply changes
    */
+  remove<T>(componentId: ComponentId<T>): void;
   remove<T>(entityId: EntityId, componentType: EntityId<T>): void;
   /**
    * Deletes an entity and all its components from the world.
@@ -525,6 +562,12 @@ declare class World {
    * Checks if an entity has a specific component.
    * Immediately reflects the current state without waiting for `sync()`.
    *
+   * @overload has<T>(entityId: EntityId, componentType: EntityId<T>): boolean
+   * Checks if a specific component type is present on the entity.
+   *
+   * @overload has<T>(componentId: ComponentId<T>): boolean
+   * Checks if a singleton component has data (shorthand for has(componentId, componentId)).
+   *
    * @template T - The component data type
    * @param entityId - The entity identifier
    * @param componentType - The component type to check
@@ -534,7 +577,11 @@ declare class World {
    * if (world.has(entity, Position)) {
    *   const pos = world.get(entity, Position);
    * }
+   * if (world.has(GlobalConfig)) {
+   *   const config = world.get(GlobalConfig);
+   * }
    */
+  has<T>(componentId: ComponentId<T>): boolean;
   has<T>(entityId: EntityId, componentType: EntityId<T>): boolean;
   /**
    * Retrieves a component from an entity.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codehz/ecs",
-  "version": "0.6.7",
+  "version": "0.6.9",
   "repository": {
     "url": "https://github.com/codehz/ecs"
   },