@codehz/ecs 0.10.0 → 0.10.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codehz/ecs",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "license": "MIT",
   "module": "src/index.ts",
   "type": "module",

package/src/__tests__/component/singleton.test.ts

@@ -3,6 +3,8 @@ import { ComponentEntityStore } from "../../component/entity-store";
 import { component, createEntityId, relation, type EntityId } from "../../entity";
 import { World } from "../../world/world";
 
+function expectType<T>(_value: T): void {}
+
 describe("World - Singleton Component", () => {
   type GlobalConfig = { debug: boolean; version: string };
   type GameState = { score: number; level: number };
@@ -26,21 +28,64 @@ describe("World - Singleton Component", () => {
     const world = new World();
     const singleton = world.singleton(GlobalConfigId);
     const Marker = component<void>();
+    const originalWarn = console.warn;
+    const warnings: string[] = [];
+
+    console.warn = (...args: unknown[]) => {
+      warnings.push(args.join(" "));
+    };
+
+    try {
+      world.set(GlobalConfigId, Marker);
+    } finally {
+      console.warn = originalWarn;
+    }
 
-    world.set(GlobalConfigId, Marker);
     world.sync();
 
     expect(world.has(GlobalConfigId, Marker)).toBe(true);
     expect(singleton.has()).toBe(false);
+    expect(warnings).toHaveLength(0);
   });
 
-  it("should reject the removed singleton data shorthand at runtime", () => {
+  it("should support the deprecated singleton data shorthand for non-number values", () => {
     const world = new World();
     const config: GlobalConfig = { debug: true, version: "1.0.0" };
+    const originalWarn = console.warn;
+    const warnings: string[] = [];
 
-    expect(() => {
-      world.set(GlobalConfigId as any, config as any);
-    }).toThrow("Invalid component type");
+    if (false) {
+      expectType<void>(world.set(GlobalConfigId, config));
+    }
+
+    console.warn = (...args: unknown[]) => {
+      warnings.push(args.join(" "));
+    };
+
+    try {
+      world.set(GlobalConfigId, config);
+    } finally {
+      console.warn = originalWarn;
+    }
+
+    world.sync();
+
+    expect(world.get(GlobalConfigId)).toEqual(config);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain("deprecated");
+    expect(warnings[0]).toContain("world.singleton(componentId).set(value)");
+  });
+
+  it("should not expose the deprecated shorthand for numeric singleton types at the type level", () => {
+    const world = new World();
+    const Score = component<number>();
+
+    if (false) {
+      // @ts-expect-error Numeric singleton shorthand is intentionally unsupported.
+      expectType<void>(world.set(Score, 123));
+    }
+
+    expect(true).toBe(true);
   });
 
   it("should manage singleton data through an explicit handle", () => {

package/src/world/operations.ts

@@ -1,5 +1,5 @@
 import type { ComponentId, EntityId } from "../entity";
-import { getDetailedIdType } from "../entity";
+import { getDetailedIdType, isComponentId } from "../entity";
 
 /**
  * Validation and overload-resolution helpers extracted from World.
@@ -51,14 +51,26 @@ export function resolveSetOperation(
   entityId: EntityId | ComponentId,
   componentTypeOrComponent?: EntityId | any,
   maybeComponent?: any,
+  argCount = 3,
   exists: (id: EntityId) => boolean = () => true, // default permissive for tests / internal
-): { entityId: EntityId; componentType: EntityId; component: any } {
+): { entityId: EntityId; componentType: EntityId; component: any; deprecatedSingletonShorthand: boolean } {
   const targetEntityId = entityId as EntityId;
+
+  if (argCount === 2 && isComponentId(targetEntityId) && typeof componentTypeOrComponent !== "number") {
+    assertEntityExists(targetEntityId, "Component entity", exists);
+    return {
+      entityId: targetEntityId,
+      componentType: targetEntityId,
+      component: componentTypeOrComponent,
+      deprecatedSingletonShorthand: true,
+    };
+  }
+
   const componentType = componentTypeOrComponent as EntityId;
   assertEntityExists(targetEntityId, "Entity", exists);
   assertSetComponentTypeValid(componentType);
 
-  return { entityId: targetEntityId, componentType, component: maybeComponent };
+  return { entityId: targetEntityId, componentType, component: maybeComponent, deprecatedSingletonShorthand: false };
 }
 
 /**

package/src/world/singleton.ts

@@ -11,8 +11,9 @@ export interface SingletonHandleOps<T> {
 /**
  * Explicit handle for a singleton component (component-as-entity).
  *
- * This provides an explicit and concise API for singleton components without
- * overloading `world.set()` semantics.
+ * This is the preferred API for singleton components.
+ * `world.set(componentId, value)` remains available only as a deprecated
+ * compatibility shorthand.
  *
  * @example
  * const config = world.singleton(Config);

package/src/world/world.ts

@@ -52,6 +52,9 @@ import { SingletonHandle } from "./singleton";
  * Manages entities and components
  */
 export class World {
+  private static readonly DEPRECATED_SINGLETON_SET_SHORTHAND_WARNING =
+    "world.set(componentId, value) for singleton components is deprecated; use world.singleton(componentId).set(value) or world.set(componentId, componentId, value) instead.";
+
   // Core data structures for entity and archetype management
   private entityIdManager = new EntityIdManager();
   private entityReferences: EntityReferencesMap = new Map();
@@ -270,46 +273,59 @@ export class World {
   }
 
   /**
-   * Adds or updates a component on an entity (or marks void component as present).
+   * Marks a void component as present on an entity.
    * The change is buffered and takes effect after calling `world.sync()`.
-   * If the entity does not exist, throws an error.
    *
-   * @overload set(entityId: EntityId, componentType: EntityId<void>): void
-   * Marks a void component as present on the entity
+   * @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, Marker);
+   * world.sync();
+   */
+  set(entityId: EntityId, componentType: EntityId<void>): void;
+  /**
+   * @deprecated Use `world.singleton(componentId).set(value)` or `world.set(componentId, componentId, value)` instead.
+   * Compatibility shorthand for singleton component data when the second argument is not a number.
    *
-   * @overload set<T>(entityId: EntityId, componentType: EntityId<T>, component: NoInfer<T>): void
-   * Adds or updates a component with data on the entity
+   * @throws {Error} If the component entity does not exist
+   *
+   * @example
+   * world.set(GlobalConfig, { debug: true });
+   * world.sync();
+   */
+  set<T>(componentId: ComponentId<T>, component: Exclude<NoInfer<T>, number>): void;
+  /**
+   * Adds or updates component data on an entity.
+   * The change is buffered and takes effect after calling `world.sync()`.
    *
    * @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.singleton(GlobalConfig).set({ debug: true }); // singleton component
-   * world.sync(); // Apply changes
+   * world.sync();
    */
-  set(entityId: EntityId, componentType: EntityId<void>): void;
   set<T>(entityId: EntityId, componentType: EntityId<T>, component: NoInfer<T>): void;
+  /** Internal implementation for `set()` overloads. */
   set(entityId: EntityId | ComponentId, componentTypeOrComponent?: EntityId | any, maybeComponent?: any): void {
     const {
       entityId: targetEntityId,
       componentType,
       component,
-    } = resolveSetOperation(entityId, componentTypeOrComponent, maybeComponent, (id) => this.exists(id));
+      deprecatedSingletonShorthand,
+    } = resolveSetOperation(entityId, componentTypeOrComponent, maybeComponent, arguments.length, (id) =>
+      this.exists(id),
+    );
+    if (deprecatedSingletonShorthand) {
+      console.warn(World.DEPRECATED_SINGLETON_SET_SHORTHAND_WARNING);
+    }
     this.commandBuffer.set(targetEntityId, componentType, component);
   }
 
   /**
    * 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
@@ -320,11 +336,22 @@ export class World {
    *
    * @example
    * world.remove(entity, Position);
+   * world.sync(); // Apply changes
+   */
+  remove<T>(entityId: EntityId, componentType: EntityId<T>): void;
+  /**
+   * Removes a singleton component (shorthand for remove(componentId, componentId)).
+   * The change is buffered and takes effect after calling `world.sync()`.
+   *
+   * @template T - The component data type
+   *
+   * @throws {Error} If the component entity does not exist
+   *
+   * @example
    * world.remove(GlobalConfig); // Remove singleton component
    * world.sync(); // Apply changes
    */
   remove<T>(componentId: ComponentId<T>): void;
-  remove<T>(entityId: EntityId, componentType: EntityId<T>): void;
   remove<T>(entityId: EntityId | ComponentId, componentType?: EntityId<T>): void {
     const { entityId: targetEntityId, componentType: targetComponentType } = resolveRemoveOperation(
       entityId,
@@ -384,15 +411,8 @@ export class World {
    *
    * 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
-   * Shorthand for checking a **singleton component** — a component that is its own
-   * entity (component-as-entity pattern). Equivalent to `has(componentId, componentId)`.
-   *
    * @template T - The component data type
-   * @param entityId - The entity identifier, or a singleton component ID
+   * @param entityId - The entity identifier
    * @param componentType - The component type to check
    * @returns `true` if the entity has the component, `false` otherwise
    *
@@ -401,17 +421,24 @@ export class World {
    * if (world.has(entity, Position)) {
    *   const pos = world.get(entity, Position);
    * }
+   */
+  has<T>(entityId: EntityId, componentType: EntityId<T>): boolean;
+  /**
+   * Checks if a **singleton component** (component-as-entity) is present.
+   * Equivalent to `has(componentId, componentId)`.
+   *
+   * Immediately reflects the current state without waiting for `sync()`.
    *
-   * // Check a singleton component (component-as-entity)
+   * @template T - The component data type
+   * @param componentId - The singleton component ID
+   * @returns `true` if the singleton component exists, `false` otherwise
+   *
+   * @example
    * if (world.has(GlobalConfig)) {
    *   const config = world.get(GlobalConfig);
    * }
-   *
-   * // Use exists() for entity liveness checks
-   * if (world.exists(entity)) { ... }
    */
   has<T>(componentId: ComponentId<T>): boolean;
-  has<T>(entityId: EntityId, componentType: EntityId<T>): boolean;
   has<T>(entityId: EntityId | ComponentId, componentType?: EntityId<T>): boolean {
     // Handle singleton component overload: has(componentId)
     if (componentType === undefined) {
@@ -445,28 +472,45 @@ export class World {
 
   /**
    * Retrieves a component from an entity.
-   * For wildcard relations, returns all relations of that type.
    * Throws an error if the component does not exist; use `has()` to check first or use `getOptional()`.
    *
-   * @overload get<T>(entityId: EntityId<T>): T
-   * When called with only an entity ID, retrieves the entity's primary component.
+   * @template T - The component data type
+   * @param entityId - The entity identifier
+   * @param componentType - The component type to retrieve
    *
-   * @overload get<T>(entityId: EntityId, componentType: WildcardRelationId<T>): [EntityId<unknown>, T][]
-   * For wildcard relations, returns an array of [target entity, component value] pairs.
+   * @throws {Error} If the entity does not exist
+   * @throws {Error} If the component does not exist on the entity
    *
-   * @overload get<T>(entityId: EntityId, componentType: EntityId<T>): T
-   * Retrieves a specific component from the entity.
+   * @example
+   * const position = world.get(entity, Position);
+   */
+  get<T>(entityId: EntityId, componentType: EntityId<T>): T;
+  /**
+   * Retrieves all relations of a given wildcard type for an entity.
+   * Returns an array of [target entity, component value] pairs.
+   *
+   * @template T - The component data type
+   * @param entityId - The entity identifier
+   * @param componentType - The wildcard relation type
+   * @returns Array of [target entity, component value] pairs
    *
    * @throws {Error} If the entity does not exist
-   * @throws {Error} If the component does not exist on the entity
    *
    * @example
-   * const position = world.get(entity, Position); // Throws if no Position
-   * const relations = world.get(entity, relation(Parent, "*")); // Wildcard relation
+   * const relations = world.get(entity, relation(Parent, "*"));
    */
-  get<T>(entityId: EntityId<T>): T;
   get<T>(entityId: EntityId, componentType: WildcardRelationId<T>): [EntityId<unknown>, T][];
-  get<T>(entityId: EntityId, componentType: EntityId<T>): T;
+  /**
+   * Retrieves the entity's primary component when called with only an entity ID.
+   *
+   * @template T - The component data type
+   * @param entityId - The entity identifier
+   * @returns The component value
+   *
+   * @throws {Error} If the entity does not exist
+   * @throws {Error} If the component does not exist on the entity
+   */
+  get<T>(entityId: EntityId<T>): T;
   get<T>(
     entityId: EntityId,
     componentType: EntityId<T> | WildcardRelationId<T> = entityId as EntityId<T>,
@@ -505,17 +549,11 @@ export class World {
   /**
    * Safely retrieves a component from an entity without throwing an error.
    * Returns `undefined` if the component does not exist.
-   * For wildcard relations, returns `undefined` if there are no relations.
    *
    * @template T - The component data type
-   * @overload getOptional<T>(entityId: EntityId<T>): { value: T } | undefined
-   * Retrieves the entity's primary component safely.
-   *
-   * @overload getOptional<T>(entityId: EntityId, componentType: WildcardRelationId<T>): { value: [EntityId<unknown>, T][] } | undefined
-   * Retrieves all matching relation values safely.
-   *
-   * @overload getOptional<T>(entityId: EntityId, componentType: EntityId<T>): { value: T } | undefined
-   * Retrieves a specific component safely.
+   * @param entityId - The entity identifier
+   * @param componentType - The component type to retrieve
+   * @returns The component value wrapped in `{ value }`, or `undefined` if absent
    *
    * @throws {Error} If the entity does not exist
    *
@@ -525,12 +563,33 @@ export class World {
    *   console.log(position.value.x);
    * }
    */
-  getOptional<T>(entityId: EntityId<T>): { value: T } | undefined;
+  getOptional<T>(entityId: EntityId, componentType: EntityId<T>): { value: T } | undefined;
+  /**
+   * Safely retrieves all matching relation values for a wildcard relation type.
+   * Returns `undefined` if there are no relations.
+   *
+   * @template T - The component data type
+   * @param entityId - The entity identifier
+   * @param componentType - The wildcard relation type
+   * @returns Array of [target, value] pairs wrapped in `{ value }`, or `undefined` if none
+   *
+   * @throws {Error} If the entity does not exist
+   */
   getOptional<T>(
     entityId: EntityId,
     componentType: WildcardRelationId<T>,
   ): { value: [EntityId<unknown>, T][] } | undefined;
-  getOptional<T>(entityId: EntityId, componentType: EntityId<T>): { value: T } | undefined;
+  /**
+   * Safely retrieves the entity's primary component without throwing an error.
+   * Returns `undefined` if the component does not exist.
+   *
+   * @template T - The component data type
+   * @param entityId - The entity identifier
+   * @returns The component value wrapped in `{ value }`, or `undefined` if absent
+   *
+   * @throws {Error} If the entity does not exist
+   */
+  getOptional<T>(entityId: EntityId<T>): { value: T } | undefined;
   getOptional<T>(
     entityId: EntityId,
     componentType: EntityId<T> | WildcardRelationId<T> = entityId as EntityId<T>,
@@ -770,21 +829,15 @@ export class World {
 
   /**
    * Registers a lifecycle hook that responds to component changes.
-   * The hook callback is invoked when components matching the specified types are added, updated, or removed.
-   * @overload hook<const T extends readonly ComponentType<any>[]>(
-   *   componentTypes: T,
-   *   hook: LifecycleHook<T> | LifecycleCallback<T>,
-   *   filter?: QueryFilter,
-   * ): () => void
-   * Registers a hook for multiple component types.
-   * The hook is triggered when entities enter/exit the matching set.
+   * The hook callback is invoked when components matching the specified types
+   * are added, updated, or removed.
    *
    * @param componentTypes - Component types that define the matching entity set
    * @param hook - Either a hook object with on_init/on_set/on_remove handlers, or a callback function
    * @param filter - Optional query-style filter applied to the hook match set
    * @returns A function that unsubscribes the hook when called
    *
-   * @throws {Error} If no required components are specified in array overload
+   * @throws {Error} If no required components are specified
    *
    * @example
    * const unsubscribe = world.hook([Position, Velocity], {
@@ -1069,32 +1122,30 @@ export class World {
 
   /**
    * Queries entities with specific components.
-   * For simpler use cases, prefer using `createQuery()` with `forEach()` which is cached and more efficient.
-   *
-   * @overload query(componentTypes: EntityId<any>[]): EntityId[]
    * Returns an array of entity IDs that have all specified components.
-   *
-   * @overload query<const T extends readonly EntityId<any>[]>(
-   *   componentTypes: T,
-   *   includeComponents: true,
-   * ): Array<{ entity: EntityId; components: ComponentTuple<T> }>
-   * Returns entities along with their component data.
+   * For simpler use cases, prefer using `createQuery()` with `forEach()` which is cached and more efficient.
    *
    * @param componentTypes - Array of component types to query
-   * @param includeComponents - If true, includes component data in results
-   * @returns Array of entity IDs or objects with entities and components
+   * @returns Array of entity IDs matching the query
    *
    * @example
-   * // Just entity IDs
    * const entities = world.query([Position, Velocity]);
+   */
+  query(componentTypes: EntityId<any>[]): EntityId[];
+  /**
+   * Queries entities with specific components and returns their component data.
+   *
+   * @template T - The tuple of component types
+   * @param componentTypes - Array of component types to query
+   * @param includeComponents - Must be `true` to include component data
+   * @returns Array of objects with entity and component data
    *
-   * // With components
+   * @example
    * const results = world.query([Position, Velocity], true);
    * results.forEach(({ entity, components: [pos, vel] }) => {
    *   pos.x += vel.x;
    * });
    */
-  query(componentTypes: EntityId<any>[]): EntityId[];
   query<const T extends readonly EntityId<any>[]>(
     componentTypes: T,
     includeComponents: true,