feat(world): add singleton component overloads

- Added set/remove/has overloads for singleton components
- Simplified singleton usage with componentId-only calls
- Updated documentation and examples
- Added comprehensive test coverage
- Maintained backward compatibility

Author: codehz

src/__tests__/singleton-component.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, it } from "bun:test";
+import { component } from "../core/entity";
+import { World } from "../core/world";
+
+describe("World - Singleton Component", () => {
+  type GlobalConfig = { debug: boolean; version: string };
+  type GameState = { score: number; level: number };
+
+  const GlobalConfigId = component<GlobalConfig>();
+  const GameStateId = component<GameState>();
+
+  it("should set singleton component using shorthand syntax", () => {
+    const world = new World();
+    const config: GlobalConfig = { debug: true, version: "1.0.0" };
+
+    // Use singleton syntax: set(componentId, data)
+    world.set(GlobalConfigId, config);
+    world.sync();
+
+    // Verify it was set on the component entity itself
+    expect(world.has(GlobalConfigId)).toBe(true);
+    expect(world.get(GlobalConfigId)).toEqual(config);
+  });
+
+  it("should update singleton component using shorthand syntax", () => {
+    const world = new World();
+    const config1: GlobalConfig = { debug: true, version: "1.0.0" };
+    const config2: GlobalConfig = { debug: false, version: "2.0.0" };
+
+    world.set(GlobalConfigId, config1);
+    world.sync();
+    expect(world.get(GlobalConfigId)).toEqual(config1);
+
+    world.set(GlobalConfigId, config2);
+    world.sync();
+    expect(world.get(GlobalConfigId)).toEqual(config2);
+  });
+
+  it("should be equivalent to set(comp, comp, data)", () => {
+    const world1 = new World();
+    const world2 = new World();
+    const config: GlobalConfig = { debug: true, version: "1.0.0" };
+
+    // Singleton syntax
+    world1.set(GlobalConfigId, config);
+    world1.sync();
+
+    // Traditional syntax
+    world2.set(GlobalConfigId, GlobalConfigId, config);
+    world2.sync();
+
+    // Both should have the same result
+    expect(world1.get(GlobalConfigId)).toEqual(world2.get(GlobalConfigId));
+  });
+
+  it("should work with multiple singleton components", () => {
+    const world = new World();
+    const config: GlobalConfig = { debug: true, version: "1.0.0" };
+    const state: GameState = { score: 100, level: 5 };
+
+    world.set(GlobalConfigId, config);
+    world.set(GameStateId, state);
+    world.sync();
+
+    expect(world.get(GlobalConfigId)).toEqual(config);
+    expect(world.get(GameStateId)).toEqual(state);
+  });
+
+  it("should throw error if component entity does not exist", () => {
+    const world = new World();
+    const config: GlobalConfig = { debug: true, version: "1.0.0" };
+
+    // Try to set a component on an entity that doesn't exist
+    const nonExistentEntity = 99999 as any; // Use a fake entity ID
+    expect(() => {
+      world.set(nonExistentEntity, GlobalConfigId, config);
+    }).toThrow("does not exist");
+  });
+
+  it("should check singleton component existence using shorthand syntax", () => {
+    const world = new World();
+    const config: GlobalConfig = { debug: true, version: "1.0.0" };
+
+    // Before setting, should return false
+    expect(world.has(GlobalConfigId)).toBe(false);
+
+    // Set singleton component
+    world.set(GlobalConfigId, config);
+    world.sync();
+
+    // After setting, should return true
+    expect(world.has(GlobalConfigId)).toBe(true);
+  });
+
+  it("should be equivalent to has(comp, comp)", () => {
+    const world1 = new World();
+    const world2 = new World();
+    const config: GlobalConfig = { debug: true, version: "1.0.0" };
+
+    // Singleton syntax
+    world1.set(GlobalConfigId, config);
+    world1.sync();
+
+    // Traditional syntax
+    world2.set(GlobalConfigId, GlobalConfigId, config);
+    world2.sync();
+
+    // Both should have the same result
+    expect(world1.has(GlobalConfigId)).toBe(world2.has(GlobalConfigId, GlobalConfigId));
+    expect(world1.has(GlobalConfigId)).toBe(true);
+  });
+
+  it("should remove singleton component using shorthand syntax", () => {
+    const world = new World();
+    const config: GlobalConfig = { debug: true, version: "1.0.0" };
+
+    world.set(GlobalConfigId, config);
+    world.sync();
+    expect(world.has(GlobalConfigId)).toBe(true);
+
+    // Remove using singleton syntax
+    world.remove(GlobalConfigId);
+    world.sync();
+    expect(world.has(GlobalConfigId)).toBe(false);
+  });
+
+  it("should be equivalent to remove(comp, comp)", () => {
+    const world1 = new World();
+    const world2 = new World();
+    const config: GlobalConfig = { debug: true, version: "1.0.0" };
+
+    // Set on both worlds
+    world1.set(GlobalConfigId, config);
+    world1.sync();
+    world2.set(GlobalConfigId, GlobalConfigId, config);
+    world2.sync();
+
+    // Remove using different syntax
+    world1.remove(GlobalConfigId); // Singleton syntax
+    world2.remove(GlobalConfigId, GlobalConfigId); // Traditional syntax
+    world1.sync();
+    world2.sync();
+
+    // Both should have the same result
+    expect(world1.has(GlobalConfigId)).toBe(world2.has(GlobalConfigId, GlobalConfigId));
+    expect(world1.has(GlobalConfigId)).toBe(false);
+  });
+});

src/core/world.ts

@@ -290,19 +290,52 @@ export 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(entityId: EntityId, componentType: EntityId, component?: any): void {
-    if (!this.exists(entityId)) {
-      throw new Error(`Entity ${entityId} does not exist`);
+  set<T>(componentId: ComponentId<T>, component: NoInfer<T>): void;
+  set(entityId: EntityId | ComponentId, componentTypeOrComponent?: EntityId | any, maybeComponent?: any): void {
+    // Handle singleton component overload: set(componentId, data)
+    if (maybeComponent === undefined && componentTypeOrComponent !== undefined) {
+      const detailedType = getDetailedIdType(entityId);
+      // Check if this looks like a singleton call (2 arguments, second is not an EntityId)
+      if (detailedType.type === "component" || detailedType.type === "component-relation") {
+        // Singleton component: set(componentId, data)
+        const componentId = entityId as ComponentId;
+        const component = componentTypeOrComponent;
+        if (!this.exists(componentId)) {
+          throw new Error(`Component entity ${componentId} does not exist`);
+        }
+        const detailedComponentType = getDetailedIdType(componentId);
+        if (detailedComponentType.type === "invalid") {
+          throw new Error(`Invalid component type: ${componentId}`);
+        }
+        if (detailedComponentType.type === "wildcard-relation") {
+          throw new Error(`Cannot directly add wildcard relation components: ${componentId}`);
+        }
+        this.commandBuffer.set(componentId, componentId, component);
+        return;
+      }
+    }
+
+    // Standard overload: set(entityId, componentType, data?) or set(entityId, componentType)
+    const entityIdArg = entityId as EntityId;
+    const componentType = componentTypeOrComponent as EntityId;
+    const component = maybeComponent;
+
+    if (!this.exists(entityIdArg)) {
+      throw new Error(`Entity ${entityIdArg} does not exist`);
     }
 
     const detailedType = getDetailedIdType(componentType);
@@ -313,14 +346,20 @@ export class World {
       throw new Error(`Cannot directly add wildcard relation components: ${componentType}`);
     }
 
-    this.commandBuffer.set(entityId, componentType, component);
+    this.commandBuffer.set(entityIdArg, 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
    * @param componentType - The component type to remove
@@ -330,19 +369,33 @@ export class World {
    *
    * @example
    * world.remove(entity, Position);
+   * world.remove(GlobalConfig); // Remove singleton component
    * world.sync(); // Apply changes
    */
-  remove<T>(entityId: EntityId, componentType: EntityId<T>): void {
-    if (!this.exists(entityId)) {
-      throw new Error(`Entity ${entityId} does not exist`);
+  remove<T>(componentId: ComponentId<T>): void;
+  remove<T>(entityId: EntityId, componentType: EntityId<T>): void;
+  remove<T>(entityId: EntityId | ComponentId, componentType?: EntityId<T>): void {
+    // Handle singleton component overload: remove(componentId)
+    if (componentType === undefined) {
+      const componentId = entityId as ComponentId<T>;
+      if (!this.exists(componentId)) {
+        throw new Error(`Component entity ${componentId} does not exist`);
+      }
+      this.commandBuffer.remove(componentId, componentId);
+      return;
+    }
+
+    const entityIdArg = entityId as EntityId;
+    if (!this.exists(entityIdArg)) {
+      throw new Error(`Entity ${entityIdArg} does not exist`);
     }
 
     const detailedType = getDetailedIdType(componentType);
     if (detailedType.type === "invalid") {
       throw new Error(`Invalid component type: ${componentType}`);
     }
 
-    this.commandBuffer.remove(entityId, componentType);
+    this.commandBuffer.remove(entityIdArg, componentType);
   }
 
   /**
@@ -364,6 +417,12 @@ export 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
@@ -373,8 +432,19 @@ export class World {
    * if (world.has(entity, Position)) {
    *   const pos = world.get(entity, Position);
    * }
+   * if (world.has(GlobalConfig)) {
+   *   const config = world.get(GlobalConfig);
+   * }
    */
-  has<T>(entityId: EntityId, componentType: EntityId<T>): boolean {
+  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) {
+      const componentId = entityId as ComponentId<T>;
+      return this.componentEntityComponents.get(componentId)?.has(componentId) ?? false;
+    }
+
     if (this.isComponentEntityId(entityId)) {
       if (isWildcardRelationId(componentType)) {
         const componentId = getComponentIdFromRelationId(componentType);