@vworlds/vecs 1.0.15 → 1.0.16

package/dist/entity/entity.lifecycle.js

@@ -0,0 +1,111 @@
+import { CleanupPolicy } from "../component_meta.js";
+import { Components } from "./entity.components.js";
+export class Lifecycle extends Components {
+    /**
+     * @internal Apply a `Destroy` command: fire `_exit` on every query, then
+     * `onRemove` on every component, emit the `destroy` event, unregister from
+     * the world, and apply incoming relationship cleanup policies.
+     */
+    _destroy() {
+        if (this._destroyed) {
+            return;
+        }
+        const ownMeta = this._ownMeta;
+        // Mark destroyed up front so a carrier cleanup that re-enters this entity's
+        // `_destroy` (possible with exotic relationship topologies under Delete)
+        // hits the guard above instead of tearing down twice.
+        this._destroyed = true;
+        if (ownMeta) {
+            const selfCarry = this._components.has(ownMeta.eid) ? 1 : 0;
+            if (ownMeta.usageCount > selfCarry) {
+                if (ownMeta.onDelete === CleanupPolicy.Throw) {
+                    // The public `destroy()` already throws when an in-use component is
+                    // destroyed; reaching here means usage grew between that check and
+                    // this deferred apply. Abort instead of throwing so a mid-drain
+                    // `_processCommandQueue` is not left half-applied, and revive the
+                    // entity since nothing has been torn down yet.
+                    this._destroyed = false;
+                    return;
+                }
+                this._applyOnDelete(ownMeta, selfCarry);
+            }
+        }
+        const entity = this;
+        this.world._notifyEntityDestroyed(entity);
+        this._components.forEach((c, eid) => {
+            const meta = this.world.entity(eid).ownMeta;
+            if (meta.isRelationship) {
+                this._removeIncoming(c.target, eid);
+            }
+            this.componentBitmask.deleteBit(meta.bitPtr);
+            this.world._notifyComponentRemoved(eid, entity);
+            meta._decrementUsage();
+            const removeHandlers = meta._onRemoveHandlers;
+            if (removeHandlers) {
+                removeHandlers.forEach((handler) => handler(entity, c));
+            }
+        });
+        this._dirtyComponentBitmask.clear();
+        this._queries.clear();
+        if (this._events) {
+            this._events.emit("destroy");
+            this._events.removeAllListeners("destroy");
+        }
+        if (ownMeta && ownMeta.usageCount === 0 && ownMeta.Class !== Object) {
+            this.world._classRegistry.delete(ownMeta.Class);
+        }
+        this.world._unregisterEntity(entity);
+        this._cleanupIncoming();
+    }
+    /**
+     * Destroy this entity.
+     *
+     * Each component fires its `onRemove` hook, the `"destroy"` event is emitted
+     * just before teardown, and the entity is unregistered from the world.
+     * After destruction the entity must not be used.
+     */
+    destroy() {
+        const ownMeta = this._ownMeta;
+        if (ownMeta &&
+            ownMeta.onDelete === CleanupPolicy.Throw &&
+            ownMeta.usageCount > (this._components.has(ownMeta.eid) ? 1 : 0)) {
+            throw new Error(`Cannot destroy entity ${this.eid}; component eid is still in use`);
+        }
+        if (this.world.deferred) {
+            this.world._enqueue({ kind: 4 /* CommandKind.Destroy */, entity: this });
+        }
+        else {
+            this._destroy();
+        }
+    }
+    // Collect carriers first, then act: the scan must not mutate `world.entities`
+    // while iterating, and `_destroy` idempotency makes overlapping Delete
+    // cascades safe. Carriers are cleaned via the internal `_remove`/`_destroy`
+    // (not the deferred-aware public methods) so `usageCount` drops synchronously
+    // and the `usageCount === 0` classRegistry cleanup in `_destroy` stays correct.
+    // Edge: if a Delete carrier is itself an in-use component key with
+    // `onDelete = Throw`, its `_destroy` safe-aborts and it survives still holding
+    // this now-destroyed component eid. This is the same exotic policy-interaction
+    // class flagged in `_cleanupIncoming`; left for the relationship/query rework.
+    _applyOnDelete(ownMeta, selfCarry) {
+        const ceid = ownMeta.eid;
+        const carriers = [];
+        let remaining = ownMeta.usageCount - selfCarry;
+        this.world.entities.forEach((e) => {
+            if (remaining > 0 && e !== this && e._get(ceid) !== undefined) {
+                carriers.push(e);
+                remaining--;
+            }
+        });
+        const shouldDelete = ownMeta.onDelete === CleanupPolicy.Delete;
+        for (const carrier of carriers) {
+            if (shouldDelete) {
+                carrier._destroy();
+            }
+            else {
+                carrier._remove(ownMeta);
+            }
+        }
+    }
+}
+//# sourceMappingURL=entity.lifecycle.js.map

package/dist/entity/entity.lifecycle.js.map

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

package/dist/entity/entity.queries.d.ts

@@ -0,0 +1,3 @@
+import { Base } from "./entity.base.js";
+export declare class Queries extends Base {
+}

package/dist/entity/entity.queries.js

@@ -0,0 +1,33 @@
+import { Base } from "./entity.base.js";
+export class Queries extends Base {
+    /**
+     * @internal Record that this entity is now tracked by `q`. Called by
+     * `Query._enter`.
+     */
+    _addQueryMembership(q) {
+        if (q._watchesUpdates()) {
+            this._queries.add(q);
+        }
+    }
+    /**
+     * @internal Return `true` when this entity is currently tracked by `q`.
+     */
+    _isInQuery(q) {
+        return this._queries.has(q);
+    }
+    /**
+     * @internal Forget query `q` without firing exit callbacks. Called by
+     * {@link World} when a {@link Query.destroy} sweeps every entity.
+     */
+    _purgeQuery(q) {
+        this._queries.delete(q);
+    }
+    /**
+     * @internal Record that this entity is no longer tracked by `q`. Called by
+     * `Query._exit`.
+     */
+    _removeQueryMembership(q) {
+        this._queries.delete(q);
+    }
+}
+//# sourceMappingURL=entity.queries.js.map

package/dist/entity/entity.queries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity.queries.js","sourceRoot":"","sources":["../../src/entity/entity.queries.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAExC,MAAM,OAAO,OAAQ,SAAQ,IAAI;IAC/B;;;OAGG;IACI,mBAAmB,CAAC,CAAQ;QACjC,IAAI,CAAC,CAAC,eAAe,EAAE,EAAE,CAAC;YACxB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED;;OAEG;IACI,UAAU,CAAC,CAAQ;QACxB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC9B,CAAC;IAED;;;OAGG;IACI,WAAW,CAAC,CAAQ;QACzB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAC1B,CAAC;IAED;;;OAGG;IACI,sBAAsB,CAAC,CAAQ;QACpC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAC1B,CAAC;CACF"}

package/dist/entity/entity.relationships.d.ts

@@ -0,0 +1,9 @@
+import { type ComponentRef } from "../component_meta.js";
+import type { Entity } from "./entity.js";
+import { Queries } from "./entity.queries.js";
+export declare class Relationships extends Queries {
+    /** Return this entity's target through relationship `ref`, if present. */
+    parent(ref: ComponentRef): Entity | undefined;
+    /** Return entities targeting this one through relationship `ref`. */
+    children(ref: ComponentRef): ReadonlySet<Entity>;
+}

package/dist/entity/entity.relationships.js

@@ -0,0 +1,74 @@
+import { CleanupPolicy } from "../component_meta.js";
+import { ArrayMap } from "../util/array_map.js";
+import { DenseSet } from "../util/dense_set.js";
+import { Queries } from "./entity.queries.js";
+export class Relationships extends Queries {
+    /** Return this entity's target through relationship `ref`, if present. */
+    parent(ref) {
+        return this._components.get(this.world.entity(ref).eid)?.target;
+    }
+    /** Return entities targeting this one through relationship `ref`. */
+    children(ref) {
+        return this._incoming?.get(this.world.entity(ref).eid) ?? Relationships._emptyIncoming;
+    }
+    /**
+     * @internal Fast child set lookup by relationship eid — skips ref -> eid
+     * resolution. Used by the `source` predicate and fan-out invoker.
+     */
+    _childrenByEid(relEid) {
+        return this._incoming?.get(relEid);
+    }
+    /** @internal */
+    _addIncoming(target, relEid) {
+        if (!target || target._destroyed) {
+            return;
+        }
+        let sources = target._incoming?.get(relEid);
+        if (!sources) {
+            sources = new DenseSet();
+            (target._incoming ?? (target._incoming = new ArrayMap())).set(relEid, sources);
+        }
+        sources.add(this);
+    }
+    /** @internal */
+    _cleanupIncoming() {
+        this._incoming?.forEach((sources, relEid) => {
+            const relEntity = this.world.getEntity(relEid);
+            if (!relEntity) {
+                return;
+            }
+            const policy = relEntity.ownMeta.onDeleteTarget;
+            for (const source of [...sources]) {
+                if (policy === CleanupPolicy.Delete) {
+                    // If source is also an in-use component entity with onDelete Throw,
+                    // this exotic cascade can still throw; revisit with the relationship rework.
+                    source.destroy();
+                }
+                else {
+                    source.remove(relEid);
+                }
+            }
+        });
+        this._incoming = undefined;
+    }
+    /** @internal */
+    _removeIncoming(target, relEid) {
+        const sources = target?._incoming?.get(relEid);
+        if (!sources) {
+            return;
+        }
+        sources.delete(this);
+        if (sources.size === 0) {
+            target._incoming.delete(relEid);
+        }
+    }
+    /** @internal */
+    _updateIncoming(meta, oldTarget, newTarget) {
+        if (!meta.isRelationship || oldTarget === newTarget) {
+            return;
+        }
+        this._removeIncoming(oldTarget, meta.eid);
+        this._addIncoming(newTarget, meta.eid);
+    }
+}
+//# sourceMappingURL=entity.relationships.js.map

package/dist/entity/entity.relationships.js.map

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

package/dist/entity/index.d.ts

@@ -0,0 +1,2 @@
+export { Entity, type EntityClass } from "./entity.js";
+export { Identity } from "./entity.identity.js";

package/dist/entity/index.js

@@ -0,0 +1,3 @@
+export { Entity } from "./entity.js";
+export { Identity } from "./entity.identity.js";
+//# sourceMappingURL=index.js.map

package/dist/entity/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/entity/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAoB,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/filter.d.ts

@@ -1,7 +1,9 @@
-import { type ComponentClass } from "./component.js";
-import type { Entity } from "./entity.js";
-import type { World } from "./world.js";
-import { type MaybeRequired, type QueryDSL } from "./dsl.js";
+import { type ComponentType } from "./component.js";
+import { Entity } from "./entity/index.js";
+import type { World } from "./world/index.js";
+import { type QueryDSL } from "./dsl.js";
+import type { Term } from "./terms/term.js";
+import { Iter, type FanInjectTuple, type MaybeResolvedInjectTuple } from "./inject.js";
 /**
  * A non-reactive, one-shot entity filter.
  *
@@ -35,13 +37,15 @@ import { type MaybeRequired, type QueryDSL } from "./dsl.js";
  *   manually via the `_guaranteed` argument. Components in `R` are non-nullable
  *   in `forEach` callback tuples.
  */
-export declare class Filter<R extends ComponentClass[] = []> {
+export declare class Filter<R extends ComponentType[] = []> {
     /** World this filter reads entities from. */
     readonly world: World;
     private readonly _belongs;
+    private readonly _dsl;
     constructor(
     /** World this filter reads entities from. */
     world: World, dsl: QueryDSL);
+    get rootTerm(): Term | undefined;
     /**
      * Walk all current world entities and call `callback` for each one that
      * satisfies the filter's DSL.
@@ -57,11 +61,26 @@ export declare class Filter<R extends ComponentClass[] = []> {
      * non-nullable in the resolved tuple; any other component class may be
      * `undefined` if the entity does not have it.
      *
+     * The resolved tuple is reused for every matching entity. Read or
+     * destructure it inside the callback; do not retain the tuple array.
+     *
      * @param components - Component classes to resolve from each matching entity.
      * @param callback - Receives the entity and a tuple of resolved component
      *   instances.
      */
-    forEach<J extends ComponentClass[]>(components: readonly [...J], callback: (e: Entity, resolved: {
-        [K in keyof J]: MaybeRequired<J[K], R>;
-    }) => void): void;
+    forEach<J extends FanInjectTuple>(components: readonly [...J], callback: (e: Entity, resolved: MaybeResolvedInjectTuple<J, R>) => void): void;
+    /**
+     * As above, but pass `Entity` first to make the entity-first signature
+     * explicit. Identical behavior to the no-marker form.
+     */
+    forEach<J extends FanInjectTuple>(cursor: typeof Entity, components: readonly [...J], callback: (e: Entity, resolved: MaybeResolvedInjectTuple<J, R>) => void): void;
+    /**
+     * As above, but pass `Iter` first to receive a reused {@link Iter}
+     * cursor instead of the bare entity. The cursor exposes the visited entity
+     * (`it.entity`) and, in `it.src`, the source entity each resolved component
+     * was read from (the visited entity for direct components, the relationship
+     * target for `up`-injected ones).
+     */
+    forEach<J extends FanInjectTuple>(cursor: typeof Iter, components: readonly [...J], callback: (it: Iter, resolved: MaybeResolvedInjectTuple<J, R>) => void): void;
+    private _forEachMatch;
 }

package/dist/filter.js

@@ -1,4 +1,5 @@
-import { _buildEntityTest } from "./dsl.js";
+import { _compile } from "./dsl.js";
+import { isCursorMarker, makeInjectedInvoker, wantsIter, } from "./inject.js";
 /**
  * A non-reactive, one-shot entity filter.
  *
@@ -37,26 +38,40 @@ export class Filter {
     /** World this filter reads entities from. */
     world, dsl) {
         this.world = world;
-        this._belongs = _buildEntityTest(world, dsl);
+        this._dsl = dsl;
+        this._belongs = _compile(world, dsl);
     }
-    forEach(componentsOrCallback, callback) {
+    get rootTerm() {
+        return this.world._getCachedTerm(this._dsl);
+    }
+    forEach(arg0, arg1, arg2) {
+        // Bare `forEach(callback)`: a function that is not a cursor marker.
+        if (typeof arg0 === "function" && !isCursorMarker(arg0)) {
+            const callback = arg0;
+            this.world.defer(() => {
+                this._forEachMatch(callback);
+            });
+            return;
+        }
+        const useIter = wantsIter(arg0);
+        const components = (isCursorMarker(arg0) ? arg1 : arg0);
+        const callback = (isCursorMarker(arg0) ? arg2 : arg1);
         this.world.defer(() => {
-            if (typeof componentsOrCallback === "function") {
-                this.world.entities.forEach((e) => {
-                    if (this._belongs(e)) {
-                        componentsOrCallback(e);
-                    }
-                });
+            const invoke = makeInjectedInvoker(this.world, components, useIter, callback);
+            this._forEachMatch(invoke);
+        });
+    }
+    _forEachMatch(callback) {
+        const rootTerm = this.rootTerm;
+        if (rootTerm) {
+            for (const entity of rootTerm) {
+                callback(entity);
             }
-            else {
-                const types = componentsOrCallback.map((C) => this.world.getComponentType(C));
-                this.world.entities.forEach((e) => {
-                    if (!this._belongs(e)) {
-                        return;
-                    }
-                    const resolved = types.map((t) => e.get(t));
-                    callback(e, resolved);
-                });
+            return;
+        }
+        this.world.entities.forEach((e) => {
+            if (this._belongs(e)) {
+                callback(e);
             }
         });
     }

package/dist/filter.js.map

@@ -1 +1 @@
-{"version":3,"file":"filter.js","sourceRoot":"","sources":["../src/filter.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,gBAAgB,EAA0D,MAAM,UAAU,CAAC;AAEpG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,OAAO,MAAM;IAGjB;IACE,6CAA6C;IAC7B,KAAY,EAC5B,GAAa;QADG,UAAK,GAAL,KAAK,CAAO;QAG5B,IAAI,CAAC,QAAQ,GAAG,gBAAgB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC/C,CAAC;IA2BM,OAAO,CACZ,oBAA6D,EAC7D,QAAoF;QAEpF,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE;YACpB,IAAI,OAAO,oBAAoB,KAAK,UAAU,EAAE,CAAC;gBAC/C,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE;oBAChC,IAAI,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;wBACrB,oBAAoB,CAAC,CAAC,CAAC,CAAC;oBAC1B,CAAC;gBACH,CAAC,CAAC,CAAC;YACL,CAAC;iBAAM,CAAC;gBACN,MAAM,KAAK,GAAG,oBAAoB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;gBAC9E,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE;oBAChC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;wBACtB,OAAO;oBACT,CAAC;oBACD,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;oBAC5C,QAAS,CAAC,CAAC,EAAE,QAAe,CAAC,CAAC;gBAChC,CAAC,CAAC,CAAC;YACL,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}
+{"version":3,"file":"filter.js","sourceRoot":"","sources":["../src/filter.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,QAAQ,EAAsC,MAAM,UAAU,CAAC;AAExE,OAAO,EACL,cAAc,EAEd,mBAAmB,EACnB,SAAS,GAIV,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,OAAO,MAAM;IAIjB;IACE,6CAA6C;IAC7B,KAAY,EAC5B,GAAa;QADG,UAAK,GAAL,KAAK,CAAO;QAG5B,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC;QAChB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACvC,CAAC;IAED,IAAW,QAAQ;QACjB,OAAO,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9C,CAAC;IAqDM,OAAO,CAAC,IAAa,EAAE,IAAc,EAAE,IAAc;QAC1D,oEAAoE;QACpE,IAAI,OAAO,IAAI,KAAK,UAAU,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;YACxD,MAAM,QAAQ,GAAG,IAA2B,CAAC;YAC7C,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE;gBACpB,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;YAC/B,CAAC,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QACD,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;QAChC,MAAM,UAAU,GAAG,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAgC,CAAC;QACvF,MAAM,QAAQ,GAAG,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAG3C,CAAC;QACV,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE;YACpB,MAAM,MAAM,GAAG,mBAAmB,CAAC,IAAI,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;YAC9E,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;QAC7B,CAAC,CAAC,CAAC;IACL,CAAC;IAEO,aAAa,CAAC,QAA6B;QACjD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC/B,IAAI,QAAQ,EAAE,CAAC;YACb,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;gBAC9B,QAAQ,CAAC,MAAM,CAAC,CAAC;YACnB,CAAC;YACD,OAAO;QACT,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE;YAChC,IAAI,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;gBACrB,QAAQ,CAAC,CAAC,CAAC,CAAC;YACd,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/index.d.ts

@@ -1,9 +1,17 @@
-export { type System, type SystemQuery } from "./system.js";
-export { Query } from "./query.js";
-export { World } from "./world.js";
+export { System, type SystemQuery } from "./system.js";
+export { Query, GroupedQuery, Group, Iter, type EntityTestFunc, type MaybeRequired, type QueryDSL, type DownInject, type FanInjectElement, type FanInjectTuple, type InjectElement, type InjectTuple, type MaybeResolvedInjectTuple, type RequiredResolvedInjectTuple, type UpInject, } from "./query/index.js";
+export { DEFAULT_POOLS, World, type WorldOptions } from "./world/index.js";
 export { Filter } from "./filter.js";
-export { type Component, type ComponentClass, type ComponentMeta } from "./component.js";
-export { type Entity } from "./entity.js";
+export { ChildOf, Relationship, SilenceSource } from "./relationship.js";
+export { CleanupPolicy, Component, type ComponentInstance, type ComponentClass, type ComponentMeta, type ComponentRef, } from "./component.js";
+export { Entity, type EntityClass, Identity } from "./entity/index.js";
+export { Module } from "./module.js";
+export { IdentityModule } from "./modules/identity.js";
+export { Singleton, SingletonModule } from "./modules/singleton.js";
 export { type IPhase } from "./phase.js";
+export { getDSLKey } from "./dsl.js";
+export { Term, TermEventKind, type TermConsumer } from "./terms/term.js";
 export { IntervalTickSource, RateTickSource, type ITickSource } from "./timer.js";
+export { ArrayMap } from "./util/array_map.js";
 export { Bitset } from "./util/bitset.js";
+export { type IdPoolConfig } from "./util/id_pool.js";

package/dist/index.js

@@ -1,6 +1,16 @@
-export { Query } from "./query.js";
-export { World } from "./world.js";
+export { System } from "./system.js";
+export { Query, GroupedQuery, Group, Iter, } from "./query/index.js";
+export { DEFAULT_POOLS, World } from "./world/index.js";
 export { Filter } from "./filter.js";
+export { ChildOf, Relationship, SilenceSource } from "./relationship.js";
+export { CleanupPolicy, Component, } from "./component.js";
+export { Entity, Identity } from "./entity/index.js";
+export { Module } from "./module.js";
+export { IdentityModule } from "./modules/identity.js";
+export { Singleton, SingletonModule } from "./modules/singleton.js";
+export { getDSLKey } from "./dsl.js";
+export { Term } from "./terms/term.js";
 export { IntervalTickSource, RateTickSource } from "./timer.js";
+export { ArrayMap } from "./util/array_map.js";
 export { Bitset } from "./util/bitset.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAIrC,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAoB,MAAM,YAAY,CAAC;AAClF,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAoB,MAAM,aAAa,CAAC;AACvD,OAAO,EACL,KAAK,EACL,YAAY,EACZ,KAAK,EACL,IAAI,GAYL,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,KAAK,EAAqB,MAAM,kBAAkB,CAAC;AAC3E,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,EACL,aAAa,EACb,SAAS,GAKV,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,MAAM,EAAoB,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEpE,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,IAAI,EAAoC,MAAM,iBAAiB,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAoB,MAAM,YAAY,CAAC;AAClF,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/inject.d.ts

@@ -0,0 +1,80 @@
+import { type ComponentInstance, type ComponentRef, type ComponentType } from "./component.js";
+import { Entity } from "./entity/index.js";
+import { type World } from "./world/index.js";
+import { type MaybeRequired } from "./dsl.js";
+export type UpInject<J extends readonly ComponentType[] = readonly ComponentType[]> = {
+    up: readonly [ComponentRef, readonly [...J]];
+};
+export type DownInject<J extends readonly ComponentType[] = readonly ComponentType[]> = {
+    down: readonly [ComponentRef, readonly [...J]];
+};
+export type InjectElement = ComponentType | UpInject;
+export type InjectTuple = readonly InjectElement[];
+export type FanInjectElement = InjectElement | DownInject;
+export type FanInjectTuple = readonly FanInjectElement[];
+export type ResolvedInjectTerm = number | {
+    up: readonly [number, readonly number[]];
+} | {
+    down: readonly [number, readonly number[]];
+};
+/** Resolves the component instance type for one injected component class. */
+type ResolvedComponentInstance<T> = T extends ComponentType ? InstanceType<T> : never;
+type OptionalResolvedComponentInstances<J extends readonly ComponentType[]> = {
+    [K in keyof J]: InstanceType<J[K]> | undefined;
+};
+type MaybeResolvedInjectElement<T, R extends ComponentType[]> = T extends ComponentType ? [MaybeRequired<T, R>] : T extends UpInject<infer J> ? OptionalResolvedComponentInstances<J> : T extends DownInject<infer J> ? OptionalResolvedComponentInstances<J> : [];
+type RequiredResolvedInjectElement<T> = T extends ComponentType ? [ResolvedComponentInstance<T>] : T extends UpInject<infer J> ? OptionalResolvedComponentInstances<J> : T extends DownInject<infer J> ? OptionalResolvedComponentInstances<J> : [];
+export type MaybeResolvedInjectTuple<J extends FanInjectTuple, R extends ComponentType[]> = J extends readonly [infer First, ...infer Rest extends FanInjectTuple] ? [...MaybeResolvedInjectElement<First, R>, ...MaybeResolvedInjectTuple<Rest, R>] : [];
+export type RequiredResolvedInjectTuple<J extends InjectTuple> = J extends readonly [
+    infer First,
+    ...infer Rest extends InjectTuple
+] ? [...RequiredResolvedInjectElement<First>, ...RequiredResolvedInjectTuple<Rest>] : [];
+export declare function mapInject(world: World, inject: readonly FanInjectElement[]): ResolvedInjectTerm[];
+export declare function injectArity(inject: readonly ResolvedInjectTerm[]): number;
+export declare function getInjected(e: Entity, inject: readonly ResolvedInjectTerm[], requireDirectComponents: boolean, out: (ComponentInstance | undefined)[], exitSnapshot?: Map<number, ComponentInstance>): void;
+export declare function getInjectedWithSrc(e: Entity, inject: readonly ResolvedInjectTerm[], out: (ComponentInstance | undefined)[], src: (Entity | undefined)[], requireDirectComponents?: boolean, exitSnapshot?: Map<number, ComponentInstance>): void;
+export declare function directInjectEids(inject: readonly ResolvedInjectTerm[]): number[];
+/**
+ * Per-iteration cursor passed to `each` / `forEach` / `enter` / `exit` /
+ * `update` / `sort` callbacks when the caller opts in by passing `Iter` as
+ * the first argument:
+ *
+ * ```ts
+ * system.each(Iter, [Body, { up: [ChildOf, [Position]] }], (it, [body, pos]) => {
+ *   it.entity;  // the visited entity
+ *   it.src[0];  // entity `body` was read from (the visited entity)
+ *   it.src[1];  // entity `pos` was read from (the ChildOf target), or undefined
+ * });
+ * ```
+ *
+ * A single instance is created when the iteration is set up and mutated before
+ * every callback, so it allocates nothing per entity. Read what you need inside
+ * the callback; do not retain the cursor or its {@link src} array across
+ * callbacks.
+ */
+export declare class Iter {
+    /** The entity currently being visited. */
+    entity: Entity;
+    /**
+     * Source entity for each injected component, in the same order as the
+     * resolved tuple: the visited entity for a directly-injected component, or
+     * the relationship target for an `up`-injected one (`undefined` when the
+     * entity has no such relationship or target).
+     */
+    readonly src: (Entity | undefined)[];
+    constructor(arity: number);
+}
+export declare function isCursorMarker(x: unknown): x is typeof Entity | typeof Iter;
+export declare function wantsIter(x: unknown): x is typeof Iter;
+/**
+ * Iterate `entities`, resolving injected components per the `forEach` /
+ * `each` argument grammar (bare callback, `[components]`, `Entity`/`Iter`
+ * cursor markers). Runs inside a deferred scope so mutations made by the
+ * callback are buffered and applied after iteration finishes.
+ *
+ * Shared by {@link Query.forEach} and {@link Group.forEach} so both honour the
+ * same injection and deferral semantics.
+ */
+export declare function forEachInjected(world: World, entities: Iterable<Entity>, arg0: unknown, arg1?: unknown, arg2?: unknown): void;
+export declare function makeInjectedInvoker(world: World, components: readonly FanInjectElement[], useIter: boolean, callback: (eOrIt: unknown, resolved: unknown) => void): (e: Entity) => void;
+export {};