@codehz/ecs 0.3.5 → 0.3.6

package/archetype.d.ts

@@ -117,6 +117,14 @@ export declare class Archetype {
      * @returns An array of component data or undefined if not present
      */
     getOptionalComponentData<T>(componentType: EntityId<T>): T[] | undefined;
+    /**
+     * Helper: compute or return cached data sources for provided componentTypes
+     */
+    private getCachedComponentDataSources;
+    /**
+     * Helper: build component tuples for a specific entity index using precomputed data sources
+     */
+    private buildComponentsForIndex;
     /**
      * Get entities with their component data for specified component types
      * Optimized for bulk component access with pre-computed indices
@@ -127,6 +135,15 @@ export declare class Archetype {
         entity: EntityId;
         components: ComponentTuple<T>;
     }>;
+    /**
+     * Iterate over entities with their component data for specified component types
+     * implemented as a generator returning each entity/components pair lazily
+     * @param componentTypes Array of component types to retrieve
+     */
+    iterateWithComponents<const T extends readonly ComponentType<any>[]>(componentTypes: T): IterableIterator<{
+        entity: EntityId;
+        components: ComponentTuple<T>;
+    }>;
     /**
      * Iterate over entities with their component data for specified component types
      * Optimized for bulk component access

package/index.js

@@ -402,16 +402,9 @@ class Archetype {
   getOptionalComponentData(componentType) {
     return this.componentData.get(componentType);
   }
-  getEntitiesWithComponents(componentTypes) {
-    const result = [];
-    this.forEachWithComponents(componentTypes, (entity, ...components) => {
-      result.push({ entity, components });
-    });
-    return result;
-  }
-  forEachWithComponents(componentTypes, callback) {
+  getCachedComponentDataSources(componentTypes) {
     const cacheKey = componentTypes.map((id) => isOptionalEntityId(id) ? `opt(${id.optional})` : `${id}`).join(",");
-    const componentDataSources = getOrComputeCache(this.componentDataSourcesCache, cacheKey, () => {
+    return getOrComputeCache(this.componentDataSourcesCache, cacheKey, () => {
       return componentTypes.map((compType) => {
         let optional = false;
         if (isOptionalEntityId(compType)) {
@@ -433,46 +426,67 @@ class Archetype {
         }
       });
     });
-    for (let entityIndex = 0;entityIndex < this.entities.length; entityIndex++) {
-      const entity = this.entities[entityIndex];
-      const components = componentDataSources.map((dataSource, 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) {
-            const dataArray = this.getComponentData(relType);
-            const data = dataArray[entityIndex];
-            const decodedRel = decodeRelationId(relType);
-            relations.push([decodedRel.targetId, data === MISSING_COMPONENT ? undefined : data]);
-          }
-          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`);
-            }
+  }
+  buildComponentsForIndex(componentTypes, componentDataSources, entityIndex) {
+    return componentDataSources.map((dataSource, 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 dataArray = dataSource;
+        }
+        const matchingRelations = dataSource;
+        const relations = [];
+        for (const relType of matchingRelations) {
+          const dataArray = this.getComponentData(relType);
           const data = dataArray[entityIndex];
-          const result = data === MISSING_COMPONENT ? undefined : data;
-          return optional ? { value: result } : result;
+          const decodedRel = decodeRelationId(relType);
+          relations.push([decodedRel.targetId, data === MISSING_COMPONENT ? undefined : data]);
         }
-      });
+        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[entityIndex];
+        const result = data === MISSING_COMPONENT ? undefined : data;
+        return optional ? { value: result } : result;
+      }
+    });
+  }
+  getEntitiesWithComponents(componentTypes) {
+    const result = [];
+    this.forEachWithComponents(componentTypes, (entity, ...components) => {
+      result.push({ entity, components });
+    });
+    return result;
+  }
+  *iterateWithComponents(componentTypes) {
+    const componentDataSources = this.getCachedComponentDataSources(componentTypes);
+    for (let entityIndex = 0;entityIndex < this.entities.length; entityIndex++) {
+      const entity = this.entities[entityIndex];
+      const components = this.buildComponentsForIndex(componentTypes, componentDataSources, entityIndex);
+      yield { entity, components };
+    }
+  }
+  forEachWithComponents(componentTypes, callback) {
+    const componentDataSources = this.getCachedComponentDataSources(componentTypes);
+    for (let entityIndex = 0;entityIndex < this.entities.length; entityIndex++) {
+      const entity = this.entities[entityIndex];
+      const components = this.buildComponentsForIndex(componentTypes, componentDataSources, entityIndex);
       callback(entity, ...components);
     }
   }
@@ -756,6 +770,14 @@ class Query {
       archetype.forEachWithComponents(componentTypes, callback);
     }
   }
+  *iterate(componentTypes) {
+    if (this.isDisposed) {
+      throw new Error("Query has been disposed");
+    }
+    for (const archetype of this.cachedArchetypes) {
+      yield* archetype.iterateWithComponents(componentTypes);
+    }
+  }
   getComponentData(componentType) {
     if (this.isDisposed) {
       throw new Error("Query has been disposed");

package/package.json

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

package/query.d.ts

@@ -32,6 +32,14 @@ export declare class Query {
      * @param callback Function called for each entity with its components
      */
     forEach<const T extends readonly ComponentType<any>[]>(componentTypes: T, callback: (entity: EntityId, ...components: ComponentTuple<T>) => void): void;
+    /**
+     * Iterate over entities with their component data (generator)
+     * @param componentTypes Array of component types to retrieve
+     */
+    iterate<const T extends readonly ComponentType<any>[]>(componentTypes: T): IterableIterator<{
+        entity: EntityId;
+        components: ComponentTuple<T>;
+    }>;
     /**
      * Get component data arrays for all matching entities
      * @param componentType The component type to retrieve