@codehz/ecs 0.10.0 → 0.10.2

package/dist/builder.d.mts

@@ -1022,8 +1022,9 @@ 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);
@@ -1050,6 +1051,7 @@ declare class SingletonHandle<T = void> {
  * Manages entities and components
  */
 declare class World {
+  private static readonly DEPRECATED_SINGLETON_SET_SHORTHAND_WARNING;
   private entityIdManager;
   private entityReferences;
   /** Sparse relation storage (for components created with `sparse: true`), shared with all Archetype instances */
@@ -1112,37 +1114,43 @@ declare class World {
    */
   exists(entityId: EntityId): boolean;
   /**
-   * 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
    *
-   * @overload set<T>(entityId: EntityId, componentType: EntityId<T>, component: NoInfer<T>): void
-   * Adds or updates a component with data on the entity
+   * @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.
+   *
+   * @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;
   /**
    * 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
@@ -1153,11 +1161,22 @@ declare 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;
   /**
    * Deletes an entity and all its components from the world.
    * The change is buffered and takes effect after calling `world.sync()`.
@@ -1191,15 +1210,8 @@ declare 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
    *
@@ -1208,55 +1220,73 @@ declare 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)`.
    *
-   * // Check a singleton component (component-as-entity)
+   * Immediately reflects the current state without waiting for `sync()`.
+   *
+   * @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;
   /**
    * 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
+   *
+   * @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: WildcardRelationId<T>): [EntityId<unknown>, T][]
-   * For wildcard relations, returns an array of [target entity, component value] pairs.
+   * @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.
    *
-   * @overload get<T>(entityId: EntityId, componentType: EntityId<T>): T
-   * Retrieves a specific component from the entity.
+   * @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;
   /**
-   * 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.
+   * Retrieves the entity's primary component when called with only an entity ID.
    *
    * @template T - The component data type
-   * @overload getOptional<T>(entityId: EntityId<T>): { value: T } | undefined
-   * Retrieves the entity's primary component safely.
+   * @param entityId - The entity identifier
+   * @returns The component value
    *
-   * @overload getOptional<T>(entityId: EntityId, componentType: WildcardRelationId<T>): { value: [EntityId<unknown>, T][] } | undefined
-   * Retrieves all matching relation values safely.
+   * @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;
+  /**
+   * Safely retrieves a component from an entity without throwing an error.
+   * Returns `undefined` if the component does not exist.
    *
-   * @overload getOptional<T>(entityId: EntityId, componentType: EntityId<T>): { value: T } | undefined
-   * Retrieves a specific component safely.
+   * @template T - The component data type
+   * @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
    *
@@ -1266,13 +1296,34 @@ declare class World {
    *   console.log(position.value.x);
    * }
    */
-  getOptional<T>(entityId: EntityId<T>): {
+  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>): {
+  /**
+   * 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;
   /**
@@ -1377,21 +1428,15 @@ declare class World {
   }): void;
   /**
    * 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], {
@@ -1526,32 +1571,30 @@ declare class World {
   getMatchingArchetypes(componentTypes: EntityId<any>[]): Archetype[];
   /**
    * 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): Array<{
     entity: EntityId;
     components: ComponentTuple<T>;

package/dist/world.mjs

@@ -626,8 +626,9 @@ var EntityBuilder = class {
 /**
 * 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);
@@ -2746,15 +2747,25 @@ function assertSetComponentTypeValid(componentType) {
 /**
 * Resolve the (entity, componentType, value) for a set() call.
 */
-function resolveSetOperation(entityId, componentTypeOrComponent, maybeComponent, exists = () => true) {
+function resolveSetOperation(entityId, componentTypeOrComponent, maybeComponent, argCount = 3, exists = () => true) {
 	const targetEntityId = 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;
 	assertEntityExists(targetEntityId, "Entity", exists);
 	assertSetComponentTypeValid(componentType);
 	return {
 		entityId: targetEntityId,
 		componentType,
-		component: maybeComponent
+		component: maybeComponent,
+		deprecatedSingletonShorthand: false
 	};
 }
 /**
@@ -2944,7 +2955,8 @@ function deserializeWorld(ctx, snapshot) {
 * World class for ECS architecture
 * Manages entities and components
 */
-var World = class {
+var World = class World {
+	static 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.";
 	entityIdManager = new EntityIdManager();
 	entityReferences = /* @__PURE__ */ new Map();
 	/** Sparse relation storage (for components created with `sparse: true`), shared with all Archetype instances */
@@ -3095,8 +3107,10 @@ var World = class {
 		if (this.componentEntities.exists(entityId)) return true;
 		return this.entityToArchetype.has(entityId);
 	}
+	/** Internal implementation for `set()` overloads. */
 	set(entityId, componentTypeOrComponent, maybeComponent) {
-		const { entityId: targetEntityId, componentType, component } = resolveSetOperation(entityId, componentTypeOrComponent, maybeComponent, (id) => this.exists(id));
+		const { entityId: targetEntityId, componentType, component, 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);
 	}
 	remove(entityId, componentType) {