iris-ecs 0.0.1

package/dist/observer.js

@@ -0,0 +1,62 @@
+// ============================================================================
+// Observer API
+// ============================================================================
+/**
+ * Registers a callback to be invoked when an event of the specified type is fired.
+ *
+ * @param world - The world instance containing observer state
+ * @param eventType - The event type to listen for
+ * @param callback - Function to invoke when the event fires
+ *
+ * @example
+ * ```ts
+ * registerObserverCallback(world, "onAdd", (entity, componentId, value) => {
+ *   console.log(`Component ${componentId} added to entity ${entity}`);
+ * });
+ * ```
+ */
+export function registerObserverCallback(world, eventType, callback) {
+    world.observers[eventType].callbacks.push(callback);
+}
+/**
+ * Removes a previously registered callback for the specified event type.
+ *
+ * @param world - The world instance containing observer state
+ * @param eventType - The event type to stop listening for
+ * @param callback - The exact callback reference to remove
+ *
+ * @example
+ * ```ts
+ * const handler = (entity, componentId, value) => { ... };
+ * registerObserverCallback(world, "onAdd", handler);
+ * // Later:
+ * unregisterObserverCallback(world, "onAdd", handler);
+ * ```
+ */
+export function unregisterObserverCallback(world, eventType, callback) {
+    const meta = world.observers[eventType];
+    const idx = meta.callbacks.indexOf(callback);
+    if (idx !== -1) {
+        meta.callbacks.splice(idx, 1);
+    }
+}
+/**
+ * Dispatches an event to all registered callbacks for the specified event type.
+ *
+ * @param world - The world instance containing observer state
+ * @param eventType - The event type to dispatch
+ * @param args - Arguments to pass to each callback (varies by event type)
+ *
+ * @example
+ * ```ts
+ * fireObserverEvent(world, "onAdd", entity, componentId, componentValue);
+ * ```
+ */
+export function fireObserverEvent(world, eventType, ...args) {
+    const meta = world.observers[eventType];
+    // Iterate in reverse so callbacks can safely unregister themselves during dispatch
+    for (let i = meta.callbacks.length - 1; i >= 0; i--) {
+        meta.callbacks[i](...args);
+    }
+}
+//# sourceMappingURL=observer.js.map

package/dist/observer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer.js","sourceRoot":"","sources":["../src/observer.ts"],"names":[],"mappings":"AA+CA,+EAA+E;AAC/E,eAAe;AACf,+EAA+E;AAE/E;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,wBAAwB,CAAsB,KAAY,EAAE,SAAY,EAAE,QAAqB;IAC7G,KAAK,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;AACtD,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,0BAA0B,CACxC,KAAY,EACZ,SAAY,EACZ,QAAqB;IAErB,MAAM,IAAI,GAAG,KAAK,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;IACxC,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAE7C,IAAI,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC;QACf,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IAChC,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAAsB,KAAY,EAAE,SAAY,EAAE,GAAG,IAAsB;IAC1G,MAAM,IAAI,GAAG,KAAK,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;IAExC,mFAAmF;IACnF,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACpD,IAAI,CAAC,SAAS,CAAC,CAAC,CAAE,CAAC,GAAG,IAAI,CAAC,CAAC;IAC9B,CAAC;AACH,CAAC"}

package/dist/query.d.ts

@@ -0,0 +1,198 @@
+import type { EntityId } from "./encoding.js";
+import type { FilterMeta } from "./filters.js";
+import type { Observer } from "./observer.js";
+import type { World } from "./world.js";
+/**
+ * Query metadata for registry caching.
+ *
+ * Stores required and excluded components with reference to underlying filter.
+ */
+export type QueryMeta = {
+    /**
+     * Required components.
+     */
+    include: EntityId[];
+    /**
+     * Excluded components.
+     */
+    exclude: EntityId[];
+    /**
+     * Direct reference to underlying filter.
+     */
+    filter: FilterMeta;
+    /**
+     * Observer callback for filter destruction.
+     */
+    onFilterDestroy: Observer<"filterDestroyed">;
+    /**
+     * Components with added() modifier.
+     */
+    added: EntityId[];
+    /**
+     * Components with changed() modifier.
+     */
+    changed: EntityId[];
+    /**
+     * Execution tick tracking for change detection.
+     */
+    lastTick: {
+        /**
+         * Tick when query last executed outside any system.
+         */
+        self: number;
+        /**
+         * Per-system execution ticks: systemId -> tick
+         */
+        bySystemId: Map<string, number>;
+    };
+};
+export type ModifierType = "not" | "added" | "changed";
+export type NotModifier = {
+    type: "not";
+    componentId: EntityId;
+};
+export type AddedModifier = {
+    type: "added";
+    componentId: EntityId;
+};
+export type ChangedModifier = {
+    type: "changed";
+    componentId: EntityId;
+};
+export type QueryModifier = NotModifier | AddedModifier | ChangedModifier;
+/**
+ * Create exclusion modifier for query.
+ *
+ * @param componentId - Component to exclude from query results
+ * @returns Not modifier
+ *
+ * @example
+ * ```typescript
+ * fetchEntities(world, Position, not(Dead))
+ * ```
+ */
+export declare function not(componentId: EntityId): NotModifier;
+/**
+ * Create added modifier for change detection.
+ *
+ * Matches entities where component was added since last query execution.
+ *
+ * @param componentId - Component to check for addition
+ * @returns Added modifier
+ *
+ * @example
+ * for (const entity of fetchEntities(world, added(Enemy))) { ... }
+ */
+export declare function added(componentId: EntityId): AddedModifier;
+/**
+ * Create changed modifier for change detection.
+ *
+ * Matches entities where component was modified or added since last query execution.
+ *
+ * @param componentId - Component to check for changes
+ * @returns Changed modifier
+ *
+ * @example
+ * for (const entity of fetchEntities(world, changed(Health))) { ... }
+ */
+export declare function changed(componentId: EntityId): ChangedModifier;
+/**
+ * Hash query terms to unique string ID for cache lookup.
+ *
+ * @param include - Component IDs that must be present
+ * @param exclude - Component IDs that must not be present
+ * @param added - Component IDs to check for recent addition
+ * @param changed - Component IDs to check for recent modification
+ * @returns Query ID in format "+include|-exclude|~+added|~>changed"
+ *
+ * @example
+ * ```typescript
+ * const id = hashQuery([Position, Velocity], [Dead], [], []);
+ * ```
+ */
+export declare function hashQuery(include: EntityId[], exclude: EntityId[], added: EntityId[], changed: EntityId[]): string;
+/**
+ * Ensure query exists in registry, creating if necessary.
+ *
+ * @param world - World instance
+ * @param terms - Components and modifiers
+ * @returns Query metadata
+ * @throws {Error} If no included components (query must match something)
+ *
+ * @example
+ * const query = ensureQuery(world, Position, Velocity, not(Dead));
+ */
+export declare function ensureQuery(world: World, ...terms: (EntityId | QueryModifier)[]): QueryMeta;
+/**
+ * Fetch entities using pre-registered query metadata.
+ *
+ * Filters by change modifiers (added/changed) when present and updates
+ * lastTick after iteration for per-query/per-system change tracking.
+ *
+ * @param world - World instance
+ * @param queryMeta - Query metadata from ensureQuery()
+ * @returns Entity IDs in backward order (safe for deletion during iteration)
+ *
+ * @example
+ * ```typescript
+ * const query = ensureQuery(world, Position, Velocity);
+ * for (const entity of fetchEntitiesWithQuery(world, query)) {
+ *   // Process entity
+ * }
+ * ```
+ */
+export declare function fetchEntitiesWithQuery(world: World, queryMeta: QueryMeta): IterableIterator<EntityId>;
+/**
+ * Destroy query and clean up associated resources.
+ *
+ * Unregisters observer callbacks and removes from query registry.
+ *
+ * @param world - World instance
+ * @param queryMeta - Query metadata to destroy
+ *
+ * @example
+ * ```typescript
+ * const query = ensureQuery(world, Position);
+ * // ... use query ...
+ * destroyQuery(world, query);
+ * ```
+ */
+export declare function destroyQuery(world: World, queryMeta: QueryMeta): void;
+/**
+ * Fetch entities matching components and modifiers.
+ *
+ * Iterates backward for safe entity destruction during iteration.
+ * Creates/reuses cached query internally.
+ *
+ * @param world - World instance
+ * @param terms - Component IDs and query modifiers (not, added, changed)
+ * @returns Entity IDs in deletion-safe order
+ *
+ * @example
+ * ```typescript
+ * for (const entity of fetchEntities(world, Position, Velocity, not(Dead))) {
+ *   const pos = get(world, entity, Position);
+ *   // Entity can be safely destroyed here
+ * }
+ * ```
+ */
+export declare function fetchEntities(world: World, ...terms: (EntityId | QueryModifier)[]): IterableIterator<EntityId>;
+/**
+ * Fetch first entity matching components and modifiers.
+ *
+ * Useful for singleton patterns or when only one match is expected.
+ *
+ * @param world - World instance
+ * @param terms - Component IDs and query modifiers (not, added, changed)
+ * @returns First matching entity ID, or undefined if no matches
+ *
+ * @example
+ * ```typescript
+ * const player = fetchFirstEntity(world, Player, not(Dead));
+ * if (player !== undefined) {
+ *   const health = get(world, player, Health);
+ * }
+ * ```
+ */
+export declare function fetchFirstEntity(world: World, ...terms: (EntityId | QueryModifier)[]): EntityId | undefined;
+//# sourceMappingURL=query.d.ts.map

package/dist/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAMxC;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB;;OAEG;IACH,OAAO,EAAE,QAAQ,EAAE,CAAC;IAEpB;;OAEG;IACH,OAAO,EAAE,QAAQ,EAAE,CAAC;IAEpB;;OAEG;IACH,MAAM,EAAE,UAAU,CAAC;IAEnB;;OAEG;IACH,eAAe,EAAE,QAAQ,CAAC,iBAAiB,CAAC,CAAC;IAE7C;;OAEG;IACH,KAAK,EAAE,QAAQ,EAAE,CAAC;IAElB;;OAEG;IACH,OAAO,EAAE,QAAQ,EAAE,CAAC;IAEpB;;OAEG;IACH,QAAQ,EAAE;QACR;;WAEG;QACH,IAAI,EAAE,MAAM,CAAC;QACb;;WAEG;QACH,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACjC,CAAC;CACH,CAAC;AAMF,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,OAAO,GAAG,SAAS,CAAC;AACvD,MAAM,MAAM,WAAW,GAAG;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,WAAW,EAAE,QAAQ,CAAA;CAAE,CAAC;AACjE,MAAM,MAAM,aAAa,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,QAAQ,CAAA;CAAE,CAAC;AACrE,MAAM,MAAM,eAAe,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,WAAW,EAAE,QAAQ,CAAA;CAAE,CAAC;AACzE,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,aAAa,GAAG,eAAe,CAAC;AAE1E;;;;;;;;;;GAUG;AACH,wBAAgB,GAAG,CAAC,WAAW,EAAE,QAAQ,GAAG,WAAW,CAEtD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,KAAK,CAAC,WAAW,EAAE,QAAQ,GAAG,aAAa,CAE1D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,OAAO,CAAC,WAAW,EAAE,QAAQ,GAAG,eAAe,CAE9D;AAaD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,QAAQ,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,MAAM,CAKlH;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE,CAAC,QAAQ,GAAG,aAAa,CAAC,EAAE,GAAG,SAAS,CAuE3F;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAiB,sBAAsB,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAyEtG;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,GAAG,IAAI,CAMrE;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAiB,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE,CAAC,QAAQ,GAAG,aAAa,CAAC,EAAE,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAI/G;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE,CAAC,QAAQ,GAAG,aAAa,CAAC,EAAE,GAAG,QAAQ,GAAG,SAAS,CAQ3G"}

package/dist/query.js

@@ -0,0 +1,299 @@
+import { ensureFilter, iterateFilterEntities } from "./filters.js";
+import { registerObserverCallback, unregisterObserverCallback } from "./observer.js";
+/**
+ * Create exclusion modifier for query.
+ *
+ * @param componentId - Component to exclude from query results
+ * @returns Not modifier
+ *
+ * @example
+ * ```typescript
+ * fetchEntities(world, Position, not(Dead))
+ * ```
+ */
+export function not(componentId) {
+    return { type: "not", componentId };
+}
+/**
+ * Create added modifier for change detection.
+ *
+ * Matches entities where component was added since last query execution.
+ *
+ * @param componentId - Component to check for addition
+ * @returns Added modifier
+ *
+ * @example
+ * for (const entity of fetchEntities(world, added(Enemy))) { ... }
+ */
+export function added(componentId) {
+    return { type: "added", componentId };
+}
+/**
+ * Create changed modifier for change detection.
+ *
+ * Matches entities where component was modified or added since last query execution.
+ *
+ * @param componentId - Component to check for changes
+ * @returns Changed modifier
+ *
+ * @example
+ * for (const entity of fetchEntities(world, changed(Health))) { ... }
+ */
+export function changed(componentId) {
+    return { type: "changed", componentId };
+}
+/**
+ * Check if argument is a query modifier (not, added, changed) vs plain component ID.
+ */
+function isModifier(arg) {
+    return typeof arg === "object" && arg !== null && "type" in arg && "componentId" in arg;
+}
+// ============================================================================
+// Query Hashing
+// ============================================================================
+/**
+ * Hash query terms to unique string ID for cache lookup.
+ *
+ * @param include - Component IDs that must be present
+ * @param exclude - Component IDs that must not be present
+ * @param added - Component IDs to check for recent addition
+ * @param changed - Component IDs to check for recent modification
+ * @returns Query ID in format "+include|-exclude|~+added|~>changed"
+ *
+ * @example
+ * ```typescript
+ * const id = hashQuery([Position, Velocity], [Dead], [], []);
+ * ```
+ */
+export function hashQuery(include, exclude, added, changed) {
+    // Sort to ensure consistent hashing regardless of term order
+    const join = (arr) => arr.toSorted((a, b) => a - b).join(":");
+    return `+${join(include)}|-${join(exclude)}|~+${join(added)}|~>${join(changed)}`;
+}
+// ============================================================================
+// Query Registry Operations
+// ============================================================================
+/**
+ * Ensure query exists in registry, creating if necessary.
+ *
+ * @param world - World instance
+ * @param terms - Components and modifiers
+ * @returns Query metadata
+ * @throws {Error} If no included components (query must match something)
+ *
+ * @example
+ * const query = ensureQuery(world, Position, Velocity, not(Dead));
+ */
+export function ensureQuery(world, ...terms) {
+    const include = [];
+    const exclude = [];
+    const added = [];
+    const changed = [];
+    // Separate terms into categories based on modifier type
+    for (const term of terms) {
+        if (isModifier(term)) {
+            switch (term.type) {
+                case "not":
+                    exclude.push(term.componentId);
+                    break;
+                case "added":
+                    added.push(term.componentId);
+                    break;
+                case "changed":
+                    changed.push(term.componentId);
+                    break;
+            }
+        }
+        else {
+            include.push(term);
+        }
+    }
+    // Filter must include added/changed components since they must be present on entity
+    const filterInclude = include.concat(added, changed);
+    if (filterInclude.length === 0) {
+        throw new Error("Query must include at least one component");
+    }
+    const queryId = hashQuery(include, exclude, added, changed);
+    let queryMeta = world.queries.byId.get(queryId);
+    if (!queryMeta) {
+        const filterMeta = ensureFilter(world, { include: filterInclude, exclude });
+        queryMeta = {
+            include,
+            exclude,
+            added,
+            changed,
+            filter: filterMeta,
+            lastTick: {
+                self: 0,
+                bySystemId: new Map(),
+            },
+            // Callback to clean up query when its underlying filter is destroyed
+            onFilterDestroy: (destroyedFilter) => {
+                if (destroyedFilter !== filterMeta) {
+                    return;
+                }
+                // Self-cleanup: unregister callback and remove from registry
+                unregisterObserverCallback(world, "filterDestroyed", queryMeta.onFilterDestroy);
+                world.queries.byId.delete(queryId);
+            },
+        };
+        world.queries.byId.set(queryId, queryMeta);
+        // Register for filter destruction events to enable automatic cleanup
+        registerObserverCallback(world, "filterDestroyed", queryMeta.onFilterDestroy);
+    }
+    return queryMeta;
+}
+/**
+ * Fetch entities using pre-registered query metadata.
+ *
+ * Filters by change modifiers (added/changed) when present and updates
+ * lastTick after iteration for per-query/per-system change tracking.
+ *
+ * @param world - World instance
+ * @param queryMeta - Query metadata from ensureQuery()
+ * @returns Entity IDs in backward order (safe for deletion during iteration)
+ *
+ * @example
+ * ```typescript
+ * const query = ensureQuery(world, Position, Velocity);
+ * for (const entity of fetchEntitiesWithQuery(world, query)) {
+ *   // Process entity
+ * }
+ * ```
+ */
+export function* fetchEntitiesWithQuery(world, queryMeta) {
+    const hasChangeModifiers = queryMeta.added.length > 0 || queryMeta.changed.length > 0;
+    // Fast path: no change modifiers
+    if (!hasChangeModifiers) {
+        yield* iterateFilterEntities(queryMeta.filter);
+        return;
+    }
+    // Slow path: filter by change detection using archetype-local tick arrays.
+    // Each component tracks when it was added/changed per-entity via tick timestamps.
+    const { systemId, tick } = world.execution;
+    // Get lastTick for this execution context (global or per-system)
+    const lastTick = systemId === null ? queryMeta.lastTick.self : (queryMeta.lastTick.bySystemId.get(systemId) ?? 0);
+    const archetypes = queryMeta.filter.archetypes;
+    // Pre-allocated arrays reused across archetypes to avoid allocation in hot loop
+    const addedTickArrays = [];
+    const changedTickArrays = [];
+    // Use try/finally to ensure lastTick updates even on early exit (break/return/throw).
+    try {
+        for (let a = 0; a < archetypes.length; a++) {
+            const archetype = archetypes[a];
+            const entities = archetype.entities;
+            // Pre-fetch tick arrays for this archetype (one Map lookup per component per archetype)
+            addedTickArrays.length = 0;
+            for (let j = 0; j < queryMeta.added.length; j++) {
+                const ticks = archetype.ticks.get(queryMeta.added[j]);
+                if (ticks)
+                    addedTickArrays.push(ticks.added);
+            }
+            changedTickArrays.length = 0;
+            for (let j = 0; j < queryMeta.changed.length; j++) {
+                const ticks = archetype.ticks.get(queryMeta.changed[j]);
+                if (ticks)
+                    changedTickArrays.push(ticks.changed);
+            }
+            // Iterate entities backward (deletion-safe)
+            entityLoop: for (let i = entities.length - 1; i >= 0; i--) {
+                const entityId = entities[i];
+                // Check added modifiers: skip if component wasn't added in (lastTick, tick] range
+                for (let j = 0; j < addedTickArrays.length; j++) {
+                    const addedTick = addedTickArrays[j][i];
+                    if (addedTick <= lastTick || addedTick > tick) {
+                        continue entityLoop;
+                    }
+                }
+                // Check changed modifiers: skip if component wasn't modified in (lastTick, tick] range
+                for (let j = 0; j < changedTickArrays.length; j++) {
+                    const changedTick = changedTickArrays[j][i];
+                    if (changedTick <= lastTick || changedTick > tick) {
+                        continue entityLoop;
+                    }
+                }
+                yield entityId;
+            }
+        }
+    }
+    finally {
+        // Update lastTick after iteration completes (or on break/return/throw).
+        // This ensures subsequent iterations only see changes since this execution.
+        if (systemId === null) {
+            queryMeta.lastTick.self = tick;
+        }
+        else {
+            queryMeta.lastTick.bySystemId.set(systemId, tick);
+        }
+    }
+}
+/**
+ * Destroy query and clean up associated resources.
+ *
+ * Unregisters observer callbacks and removes from query registry.
+ *
+ * @param world - World instance
+ * @param queryMeta - Query metadata to destroy
+ *
+ * @example
+ * ```typescript
+ * const query = ensureQuery(world, Position);
+ * // ... use query ...
+ * destroyQuery(world, query);
+ * ```
+ */
+export function destroyQuery(world, queryMeta) {
+    const queryId = hashQuery(queryMeta.include, queryMeta.exclude, queryMeta.added, queryMeta.changed);
+    unregisterObserverCallback(world, "filterDestroyed", queryMeta.onFilterDestroy);
+    world.queries.byId.delete(queryId);
+}
+// ============================================================================
+// Query Iteration
+// ============================================================================
+/**
+ * Fetch entities matching components and modifiers.
+ *
+ * Iterates backward for safe entity destruction during iteration.
+ * Creates/reuses cached query internally.
+ *
+ * @param world - World instance
+ * @param terms - Component IDs and query modifiers (not, added, changed)
+ * @returns Entity IDs in deletion-safe order
+ *
+ * @example
+ * ```typescript
+ * for (const entity of fetchEntities(world, Position, Velocity, not(Dead))) {
+ *   const pos = get(world, entity, Position);
+ *   // Entity can be safely destroyed here
+ * }
+ * ```
+ */
+export function* fetchEntities(world, ...terms) {
+    const queryMeta = ensureQuery(world, ...terms);
+    yield* fetchEntitiesWithQuery(world, queryMeta);
+}
+/**
+ * Fetch first entity matching components and modifiers.
+ *
+ * Useful for singleton patterns or when only one match is expected.
+ *
+ * @param world - World instance
+ * @param terms - Component IDs and query modifiers (not, added, changed)
+ * @returns First matching entity ID, or undefined if no matches
+ *
+ * @example
+ * ```typescript
+ * const player = fetchFirstEntity(world, Player, not(Dead));
+ * if (player !== undefined) {
+ *   const health = get(world, player, Health);
+ * }
+ * ```
+ */
+export function fetchFirstEntity(world, ...terms) {
+    const queryMeta = ensureQuery(world, ...terms);
+    for (const entityId of fetchEntitiesWithQuery(world, queryMeta)) {
+        return entityId;
+    }
+    return undefined;
+}
+//# sourceMappingURL=query.js.map

package/dist/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"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"}