@codehz/ecs 0.10.0 → 0.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codehz/ecs",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "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();
@@ -277,6 +280,10 @@ export class World {
    * @overload set(entityId: EntityId, componentType: EntityId<void>): void
    * Marks a void component as present on the entity
    *
+   * @overload set<T>(componentId: ComponentId<T>, component: Exclude<NoInfer<T>, number>): 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
    *
@@ -287,16 +294,25 @@ export class World {
    * world.set(entity, Position, { x: 10, y: 20 });
    * world.set(entity, Marker); // void component
    * world.singleton(GlobalConfig).set({ debug: true }); // singleton component
+   * world.set(GlobalConfig, { debug: true }); // deprecated singleton compatibility shorthand
    * world.sync(); // Apply changes
    */
   set(entityId: EntityId, componentType: EntityId<void>): void;
+  /** @deprecated Use `world.singleton(componentId).set(value)` or `world.set(componentId, componentId, value)` instead. */
+  set<T>(componentId: ComponentId<T>, component: Exclude<NoInfer<T>, number>): void;
   set<T>(entityId: EntityId, componentType: EntityId<T>, component: NoInfer<T>): void;
   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);
   }