@vworlds/vecs 1.0.10 → 1.0.12

package/dist/query.d.ts

@@ -1,97 +1,89 @@
-import { ArrayMap } from "./util/array_map.js";
-import { Bitset } from "./util/bitset.js";
 import { Component } from "./component.js";
 import type { Entity } from "./entity.js";
 import { type World } from "./world.js";
 import { type EntityTestFunc, type QueryDSL, type MaybeRequired } from "./dsl.js";
 export type { EntityTestFunc, QueryDSL, MaybeRequired };
-type EntityCallback = (e: Entity, snapshot?: Map<number, Component>) => void;
-type ComponentCallback = (c: Component) => void;
+/** Component class, or `{ parent: ComponentClass }` to resolve from the entity's parent. */
 type ComponentOrParent = typeof Component | {
     parent: typeof Component;
 };
+/** Resolves the component instance type for one element of a `ComponentOrParent` tuple. */
 type ComponentInstance<T> = T extends {
     parent: typeof Component;
 } ? InstanceType<T["parent"]> : T extends typeof Component ? InstanceType<T> : never;
 /**
- * A reactive, always-updated list of entities that match a given query
- * expression.
+ * A reactive, always-up-to-date set of entities matching a {@link QueryDSL}
+ * predicate.
  *
- * `Query` tracks every entity whose component set satisfies the predicate set
- * via {@link requires} or {@link query}. Entry, exit, and update callbacks
- * fire automatically when the world's command queue is processed. The tracked
- * set is exposed via {@link entities} and {@link forEach}.
+ * `Query` listens to entity / component mutations through the world's command
+ * queue and tracks which entities currently satisfy its predicate. It fires
+ * `enter`, `exit`, and `update` callbacks as the matched set changes. The
+ * tracked set is exposed via {@link entities} and {@link forEach}.
  *
- * {@link System} extends `Query` and queues callbacks for its next `_run`
- * rather than firing them immediately. Use `Query` directly when you want
- * synchronous reactive callbacks without pipeline integration.
+ * Callbacks fire **synchronously** when the world routes a command — so
+ * mutations made inside one of these callbacks are themselves observed
+ * immediately by other queries / systems.
  *
- * ### Type parameter `R`
- * Tracks which component classes are "required" (declared via {@link requires}
- * or the `_guaranteed` hint of {@link query}). Those components appear as
- * non-nullable in {@link sort}, {@link forEach}, and {@link update} callbacks.
+ * {@link System} extends `Query` and queues callbacks into an inbox replayed
+ * during `_run` instead of firing them immediately. Use `Query` directly when
+ * you want a reactive entity set without pipeline integration.
+ *
+ * @typeParam R - Component classes guaranteed present on every matched entity
+ *   (declared via {@link requires} or the `_guaranteed` hint of {@link query}).
+ *   Components in `R` appear as non-nullable in {@link sort}, {@link forEach},
+ *   and {@link update} callback tuples.
  */
 export declare class Query<R extends (typeof Component)[] = []> {
-    /** Unique name for this query, used in logs and debug output. */
+    /** Unique display name; appears in logs and debug output. */
     readonly name: string;
-    /** The world that owns this query. */
+    /** World that owns this query. */
     readonly world: World;
-    protected _entities: Set<Entity> | undefined;
-    protected _enterCallback: EntityCallback | undefined;
-    protected _exitCallback: EntityCallback | undefined;
-    /** @internal Direct component type ids that the exit callback injects; undefined when no injection. */
-    protected _exitSnapshotTypes: number[] | undefined;
-    protected _belongs: EntityTestFunc;
-    protected hasQuery: boolean;
-    /** @internal Per-component-type update callbacks. */
-    protected componentUpdateCallbacks: ArrayMap<ComponentCallback>;
-    /** @internal Bitmask of component types this query is watching for updates. */
-    protected watchlistBitmask: Bitset;
     constructor(
-    /** Unique name for this query, used in logs and debug output. */
+    /** Unique display name; appears in logs and debug output. */
     name: string, 
-    /** The world that owns this query. */
+    /** World that owns this query. */
     world: World, track?: boolean);
+    /**
+     * Read-only view of the entities currently tracked by this query.
+     *
+     * Populated as entities enter and removed as they exit. Empty unless
+     * tracking is enabled — that is the default for standalone queries created
+     * via {@link World.query}, but {@link System} requires an explicit
+     * {@link track}, {@link sort}, or `each` call.
+     */
+    get entities(): ReadonlySet<Entity>;
     /** Returns the query name. */
     toString(): string;
     /**
      * Enable entity tracking: matched entities are inserted into {@link entities}
      * as they enter and removed as they exit.
      *
-     * Idempotent. When called after {@link World.start}, immediately backfills all
-     * existing entities that currently satisfy the query predicate.
+     * Idempotent. When called after {@link World.start}, immediately backfills
+     * every existing entity that satisfies the current predicate.
      *
-     * @returns `this` for chaining.
+     * @returns This query, for chaining.
      */
     track(): this;
-    private backfill;
-    /**
-     * Read-only view of the entities currently tracked by this query.
-     *
-     * Populated as entities enter (and removed as they exit). Empty unless
-     * tracking is enabled (default for standalone queries; requires an explicit
-     * {@link track} call on {@link System | systems}).
-     */
-    get entities(): ReadonlySet<Entity>;
+    /** Returns `true` when `e` satisfies this query's predicate. */
+    belongs(e: Entity): boolean;
     /**
-     * Iterate over every entity currently tracked by this query.
+     * Iterate every entity currently tracked by this query.
      *
      * Mutations made by `callback` are buffered into the world command queue
-     * (deferred mode) and only become visible after iteration finishes. Nested
-     * iteration inside an already-deferred context (a system, another forEach)
-     * inherits the outer deferred scope and does not drain on exit.
+     * and only become visible after iteration finishes. Nested iteration inside
+     * an already-deferred context (a system, an outer `forEach`) inherits the
+     * outer scope and does not drain on exit.
      *
-     * @param callback - Called once per tracked entity, in insertion order
+     * @param callback - Invoked once per tracked entity, in insertion order
      *   (or sort order when {@link sort} is configured).
      */
     forEach(callback: (e: Entity) => void): void;
     /**
-     * Iterate over every entity currently tracked by this query, with component
-     * injection.
+     * Iterate every tracked entity with component injection.
      *
-     * Components declared via {@link requires} (or the `_guaranteed` hint of
-     * {@link query}) are non-nullable in the resolved tuple; any other requested
-     * component may be `undefined` if the entity lacks it.
+     * Components covered by {@link requires} (or the `_guaranteed` hint of
+     * {@link query}) are non-nullable in the resolved tuple; any other
+     * requested component may be `undefined` if the entity lacks it.
      *
      * @param components - Component classes to resolve from each entity.
      * @param callback - Receives the entity and a tuple of resolved component
@@ -100,37 +92,14 @@ export declare class Query<R extends (typeof Component)[] = []> {
     forEach<J extends (typeof Component)[]>(components: readonly [...J], callback: (e: Entity, resolved: {
         [K in keyof J]: MaybeRequired<J[K], R>;
     }) => void): void;
-    /** Returns `true` if the entity satisfies this query's predicate. */
-    belongs(e: Entity): boolean;
-    /**
-     * @internal Called by the world during command-queue routing when a Set
-     * command targets an entity that this query currently tracks. Default:
-     * fires the user-registered `update` callback for the component's type.
-     * `System` overrides this to push into its inbox instead.
-     */
-    notifyModified(c: Component): void;
     /**
-     * @internal Adds the entity to the tracked set, registers query membership
-     * on the entity, fires registered enter callbacks, then bridges any
-     * already-attached watched components through `notifyModified` so that
-     * `update` callbacks see the entity once on entry. `System` overrides this
-     * to push inbox events (events fire later in `_run`).
-     */
-    _enter(e: Entity): void;
-    /**
-     * @internal Removes the entity from the tracked set, deregisters query
-     * membership, and fires registered exit callbacks. `System` overrides this
-     * to also push an inbox event.
-     */
-    _exit(e: Entity): void;
-    /**
-     * Register a callback that fires when an entity **enters** this query
-     * (i.e. first satisfies the predicate) with injected components.
+     * Register a callback invoked when an entity **enters** this query (i.e.
+     * first satisfies the predicate), with injected components.
      *
      * @param inject - Ordered list of component classes (or `{ parent: C }`) to
      *   resolve from the entering entity and pass to `callback`.
      * @param callback - Receives the entity and the resolved component tuple.
-     * @returns `this` for chaining.
+     * @returns This query, for chaining.
      *
      * @example
      * ```ts
@@ -144,86 +113,81 @@ export declare class Query<R extends (typeof Component)[] = []> {
         [K in keyof J]: ComponentInstance<J[K]>;
     }) => void): this;
     /**
-     * Register a callback that fires when an entity enters this query.
+     * Register an `enter` callback without component injection.
      *
-     * @param callback - Receives only the entity (no injection).
-     * @returns `this` for chaining.
+     * @param callback - Receives only the entering entity.
+     * @returns This query, for chaining.
      */
     enter(callback: (e: Entity) => void): this;
     /**
-     * Register a callback that fires when an entity **exits** this query
-     * (its components no longer satisfy the predicate, or it was destroyed) with
+     * Register a callback invoked when an entity **exits** this query (its
+     * archetype no longer satisfies the predicate, or it was destroyed), with
      * injected components.
      *
+     * Components removed in the same frame as the exit are still resolvable
+     * because the runtime snapshots them at routing time.
+     *
      * @param inject - Component classes to resolve and inject.
      * @param callback - Receives the entity and the resolved component tuple.
-     * @returns `this` for chaining.
+     * @returns This query, for chaining.
      */
     exit<J extends ComponentOrParent[]>(inject: readonly [...J], callback: (e: Entity, injected: {
         [K in keyof J]: ComponentInstance<J[K]>;
     }) => void): this;
     /**
-     * Register a callback that fires when an entity exits this query.
+     * Register an `exit` callback without component injection.
      *
-     * @param callback - Receives only the entity.
-     * @returns `this` for chaining.
+     * @param callback - Receives only the exiting entity.
+     * @returns This query, for chaining.
      */
     exit(callback: (e: Entity) => void): this;
     /**
-     * Register a callback that fires when a component of type `ComponentClass`
-     * is modified on any entity tracked by this query.
+     * Register a callback invoked when a component of `ComponentClass` is
+     * modified on a tracked entity.
      *
-     * On a {@link Query}, callbacks fire **immediately** when the world's
-     * command queue routes the corresponding `Set` command. On a {@link System},
-     * the event is buffered in the system's inbox and the callback fires during
-     * the system's next `_run`.
+     * On a {@link Query} the callback fires **immediately** when the world
+     * routes the corresponding `Set` / `Modified` command. On a {@link System}
+     * the event is buffered in the inbox and the callback fires during the
+     * system's next `_run`.
      *
      * If no other predicate has been set on this query, the watchlist
-     * automatically expands to require `ComponentClass` (equivalent to adding
-     * it to a `requires` / `HAS` query).
+     * automatically expands so `ComponentClass` is implicitly required (the
+     * predicate becomes a `HAS` of every watched type).
      *
-     * @param ComponentClass - The component class to watch.
+     * @param ComponentClass - Component class to watch.
      * @param callback - Receives the modified component instance.
-     * @returns `this` for chaining.
+     * @returns This query, for chaining.
      *
      * @example
      * ```ts
      * world.system("RenderPosition")
-     *   .update(Position, (pos) => {
-     *     sprite.setPosition(pos.x, pos.y);
-     *   });
+     *   .update(Position, (pos) => sprite.setPosition(pos.x, pos.y));
      * ```
      */
     update<C extends typeof Component>(ComponentClass: C, callback: (c: InstanceType<C>) => void): this;
     /**
-     * Register a callback that fires when `ComponentClass` is modified, with
-     * additional components injected from the same entity.
+     * Like {@link update}, but with extra components injected from the same
+     * entity.
      *
-     * @param ComponentClass - The component class to watch.
+     * @param ComponentClass - Component class to watch.
      * @param inject - Additional component classes to resolve from the entity.
      * @param callback - Receives the modified component and the injected tuple.
-     * @returns `this` for chaining.
-     *
-     * @example
-     * ```ts
-     * world.system("SyncSprite")
-     *   .update(Position, [Sprite], (pos, [sprite]) => {
-     *     sprite.sprite.setPosition(pos.x, pos.y);
-     *   });
-     * ```
+     * @returns This query, for chaining.
      */
     update<C extends typeof Component, J extends (typeof Component)[]>(ComponentClass: C, inject: readonly [...J], callback: (c: InstanceType<C>, injected: {
         [K in keyof J]: MaybeRequired<J[K], R>;
     }) => void): this;
     /**
-     * Enable sorted entity tracking: matched entities are stored in insertion
-     * order determined by `compare`, which receives a tuple of resolved
-     * component instances for each pair of entities being ordered.
+     * Switch the tracked set to a sorted ordering: matched entities are stored
+     * in the position determined by `compare`, which receives a tuple of
+     * resolved component instances for each pair being ordered.
+     *
+     * Implies {@link track}.
      *
      * @param components - Component classes to resolve and pass to `compare`.
-     * @param compare - Returns a negative number, zero, or positive number when
-     *   `a` should sort before, equal to, or after `b`.
-     * @returns `this` for chaining.
+     * @param compare - Negative when `a` should sort before `b`, zero for
+     *   equality, positive when `a` should sort after `b`.
+     * @returns This query, for chaining.
      *
      * @example
      * ```ts
@@ -238,17 +202,18 @@ export declare class Query<R extends (typeof Component)[] = []> {
         [K in keyof J]: MaybeRequired<J[K], R>;
     }) => number): this;
     /**
-     * Set the entity membership predicate using the {@link QueryDSL} DSL.
+     * Set the entity-membership predicate using a {@link QueryDSL} expression.
      *
-     * Replaces any previous predicate. The optional `guaranteed` tuple is a
-     * pure type-level hint: it tells {@link sort} callbacks which components are
-     * guaranteed present on every matched entity, eliminating `| undefined` from
-     * those positions. It has no effect at runtime.
+     * Replaces any previous predicate. The optional `_guaranteed` tuple is a
+     * pure type-level hint: it tells {@link sort} / {@link forEach} /
+     * {@link update} callbacks which components are guaranteed present on every
+     * matched entity, eliminating `| undefined` from those positions. It has no
+     * effect at runtime.
      *
-     * @param q - A {@link QueryDSL} expression.
+     * @param q - Query expression.
      * @param _guaranteed - Component classes guaranteed present on every matched
      *   entity (type hint only — not validated at runtime).
-     * @returns `this` for chaining.
+     * @returns This query, retyped with the guaranteed tuple as its `R`.
      *
      * @example
      * ```ts
@@ -261,28 +226,26 @@ export declare class Query<R extends (typeof Component)[] = []> {
      */
     query<T extends (typeof Component)[] = []>(q: QueryDSL, _guaranteed?: readonly [...T]): Query<T>;
     /**
-     * Remove this query from the world and all entities.
+     * Shorthand for `query([...components])`: track entities that have **all**
+     * of the listed component types.
      *
-     * Every entity that currently belongs to this query has the query silently
-     * removed (no exit callbacks are fired). After this call the query is
-     * unregistered from its world and `world` is set to `undefined` by force.
+     * Equivalent to `query({ HAS: components })`. Unlike `query`, the listed
+     * components are also recorded in the type parameter `R`, so {@link sort}
+     * and {@link forEach} callbacks see them as non-nullable.
      *
-     * Calling any method on the query after `destroy()` is **undefined behavior**.
+     * @param components - Component classes to require.
+     * @returns This query, retyped with the required tuple as its `R`.
      */
-    destroy(): void;
+    requires<T extends (typeof Component)[]>(...components: [...T]): Query<T>;
     /**
-     * Shorthand for `query([...components])` — tracks entities that have
-     * **all** of the listed component types.
+     * Permanently remove this query from the world.
      *
-     * Equivalent to `query({ HAS: components })`. Unlike `query`, passing
-     * component classes here also informs the types of {@link sort} callbacks:
-     * listed components will be non-nullable in those tuples.
+     * Every entity that currently belongs to this query has the membership
+     * silently purged (no `exit` callbacks fire), the tracked set is cleared,
+     * and the `world` reference is forced to `undefined`. Calling any method on
+     * the query afterwards is **undefined behavior**.
      *
-     * @param components - One or more component classes.
-     * @returns `this` for chaining.
+     * Not supported on {@link System} — calling it on a system throws.
      */
-    requires<T extends (typeof Component)[]>(...components: [...T]): Query<T>;
-    private getComponent;
-    private getInjected;
-    private mapInjectedClassToTypes;
+    destroy(): void;
 }