@codehz/ecs 0.1.8 → 0.1.9

package/archetype.d.ts

@@ -1,5 +1,5 @@
 import type { EntityId, WildcardRelationId } from "./entity";
-import type { ComponentTuple } from "./types";
+import { type ComponentTuple, type ComponentType } from "./types";
 /**
  * Archetype class for ECS architecture
  * Represents a group of entities that share the same set of components
@@ -89,13 +89,19 @@ export declare class Archetype {
      * @param componentType The component type
      */
     getComponentData<T>(componentType: EntityId<T>): T[];
+    /**
+     * Get optional component data for all entities of a specific component type
+     * @param componentType The component type
+     * @returns An array of component data or undefined if not present
+     */
+    getOptionalComponentData<T>(componentType: EntityId<T>): T[] | undefined;
     /**
      * Get entities with their component data for specified component types
      * Optimized for bulk component access with pre-computed indices
      * @param componentTypes Array of component types to retrieve
      * @returns Array of objects with entity and component data
      */
-    getEntitiesWithComponents<const T extends readonly EntityId<any>[]>(componentTypes: T): Array<{
+    getEntitiesWithComponents<const T extends readonly ComponentType<any>[]>(componentTypes: T): Array<{
         entity: EntityId;
         components: ComponentTuple<T>;
     }>;
@@ -105,7 +111,7 @@ export declare class Archetype {
      * @param componentTypes Array of component types to retrieve
      * @param callback Function called for each entity with its components
      */
-    forEachWithComponents<const T extends readonly EntityId<any>[]>(componentTypes: T, callback: (entity: EntityId, ...components: ComponentTuple<T>) => void): void;
+    forEachWithComponents<const T extends readonly ComponentType<any>[]>(componentTypes: T, callback: (entity: EntityId, ...components: ComponentTuple<T>) => void): void;
     /**
      * Iterate over all entities with their component data
      * @param callback Function called for each entity with its component data

package/index.js

@@ -217,6 +217,11 @@ var globalComponentIdAllocator = new ComponentIdAllocator;
 function component() {
   return globalComponentIdAllocator.allocate();
 }
+// src/types.ts
+function isOptionalEntityId(type) {
+  return typeof type === "object" && type !== null && "optional" in type;
+}
+
 // src/utils.ts
 function getOrComputeCache(cache, key, compute) {
   let value = cache.get(key);
@@ -348,6 +353,9 @@ class Archetype {
     }
     return data;
   }
+  getOptionalComponentData(componentType) {
+    return this.componentData.get(componentType);
+  }
   getEntitiesWithComponents(componentTypes) {
     const result = [];
     this.forEachWithComponents(componentTypes, (entity, ...components) => {
@@ -359,6 +367,11 @@ class Archetype {
     const cacheKey = componentTypes.map((id) => id.toString()).join(",");
     const componentDataSources = getOrComputeCache(this.componentDataSourcesCache, cacheKey, () => {
       return componentTypes.map((compType) => {
+        let optional = false;
+        if (isOptionalEntityId(compType)) {
+          compType = compType.optional;
+          optional = true;
+        }
         const detailedType = getDetailedIdType(compType);
         if (detailedType.type === "wildcard-relation") {
           const componentId = detailedType.componentId;
@@ -368,17 +381,29 @@ class Archetype {
               return false;
             return detailedCt.componentId === componentId;
           });
-          return matchingRelations;
+          return optional ? matchingRelations.length > 0 ? matchingRelations : undefined : matchingRelations;
         } else {
-          return this.getComponentData(compType);
+          return optional ? this.getOptionalComponentData(compType) : this.getComponentData(compType);
         }
       });
     });
     for (let entityIndex = 0;entityIndex < this.entities.length; entityIndex++) {
       const entity = this.entities[entityIndex];
       const components = componentDataSources.map((dataSource, i) => {
-        const compType = componentTypes[i];
+        let compType = componentTypes[i];
+        let optional = false;
+        if (isOptionalEntityId(compType)) {
+          compType = compType.optional;
+          optional = true;
+        }
         if (getIdType(compType) === "wildcard-relation") {
+          if (dataSource === undefined) {
+            if (optional) {
+              return;
+            } else {
+              throw new Error(`No matching relations found for mandatory wildcard relation component type`);
+            }
+          }
           const matchingRelations = dataSource;
           const relations = [];
           for (const relType of matchingRelations) {
@@ -387,11 +412,19 @@ class Archetype {
             const decodedRel = decodeRelationId(relType);
             relations.push([decodedRel.targetId, data === MISSING_COMPONENT ? undefined : data]);
           }
-          return relations;
+          return optional ? { value: relations } : relations;
         } else {
+          if (dataSource === undefined) {
+            if (optional) {
+              return;
+            } else {
+              throw new Error(`No matching relations found for mandatory wildcard relation component type`);
+            }
+          }
           const dataArray = dataSource;
-          const data = dataArray ? dataArray[entityIndex] : undefined;
-          return data === MISSING_COMPONENT ? undefined : data;
+          const data = dataArray[entityIndex];
+          const result = data === MISSING_COMPONENT ? undefined : data;
+          return optional ? { value: result } : result;
         }
       });
       callback(entity, ...components);
@@ -1183,6 +1216,7 @@ export {
   relation,
   isWildcardRelationId,
   isRelationId,
+  isOptionalEntityId,
   isEntityId,
   isComponentId,
   inspectEntityId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codehz/ecs",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "type": "module",
   "main": "./index.js",
   "types": "./index.d.ts",

package/query.d.ts

@@ -1,7 +1,7 @@
 import { Archetype } from "./archetype";
 import type { EntityId } from "./entity";
 import { type QueryFilter } from "./query-filter";
-import type { ComponentTuple } from "./types";
+import type { ComponentTuple, ComponentType } from "./types";
 import type { World } from "./world";
 /**
  * Query class for efficient entity queries with cached archetypes
@@ -23,7 +23,7 @@ export declare class Query {
      * @param componentTypes Array of component types to retrieve
      * @returns Array of objects with entity and component data
      */
-    getEntitiesWithComponents<const T extends readonly EntityId<any>[]>(componentTypes: T): Array<{
+    getEntitiesWithComponents<const T extends readonly ComponentType<any>[]>(componentTypes: T): Array<{
         entity: EntityId;
         components: ComponentTuple<T>;
     }>;
@@ -32,7 +32,7 @@ export declare class Query {
      * @param componentTypes Array of component types to retrieve
      * @param callback Function called for each entity with its components
      */
-    forEach<const T extends readonly EntityId<any>[]>(componentTypes: T, callback: (entity: EntityId, ...components: ComponentTuple<T>) => void): void;
+    forEach<const T extends readonly ComponentType<any>[]>(componentTypes: T, callback: (entity: EntityId, ...components: ComponentTuple<T>) => void): void;
     /**
      * Get component data arrays for all matching entities
      * @param componentType The component type to retrieve

package/types.d.ts

@@ -12,9 +12,19 @@ export interface LifecycleHook<T = unknown> {
      */
     onRemoved?: (entityId: EntityId, componentType: EntityId<T>) => void;
 }
+export type ComponentType<T> = EntityId<T> | OptionalEntityId<T>;
+export type OptionalEntityId<T> = {
+    optional: EntityId<T>;
+};
+export declare function isOptionalEntityId<T>(type: ComponentType<T>): type is OptionalEntityId<T>;
+export type ComponentTypeToData<T> = T extends {
+    optional: infer U;
+} ? {
+    value: ComponentTypeToData<U>;
+} | undefined : T extends WildcardRelationId<infer U> ? [EntityId<unknown>, U][] : T extends EntityId<infer U> ? U : never;
 /**
  * Type helper for component tuples extracted from EntityId array
  */
-export type ComponentTuple<T extends readonly EntityId<any>[]> = {
-    readonly [K in keyof T]: T[K] extends WildcardRelationId<infer U> ? [EntityId<unknown>, U][] : T[K] extends EntityId<infer U> ? U : never;
+export type ComponentTuple<T extends readonly ComponentType<any>[]> = {
+    readonly [K in keyof T]: ComponentTypeToData<T[K]>;
 };