@vworlds/vecs 1.0.10 → 1.0.12

package/dist/command.d.ts

@@ -1,46 +1 @@
-import type { Component } from "./component.js";
-import type { Entity } from "./entity.js";
-export declare const enum CommandKind {
-    CreateEntity = 0,
-    Set = 1,
-    Modified = 2,
-    Remove = 3,
-    Destroy = 4,
-    SetParent = 5
-}
-/**
- * Command kinds emitted by {@link Entity} and routed by {@link World}.
- *
- * Commands are produced by `entity.add` / `entity.set` / `entity.remove` /
- * `entity.destroy` (and `Component.modified`). In deferred mode they are
- * pushed onto the world's command queue and processed at well-defined
- * boundaries (after each system run, on `flush()`, on the next `runPhase`,
- * etc.). Outside deferred mode they execute inline.
- *
- * @internal
- */
-export type Command = {
-    kind: CommandKind.CreateEntity;
-    entity: Entity;
-} | {
-    kind: CommandKind.Set;
-    entity: Entity;
-    type: number;
-    /** Properties to assign. `undefined` for `entity.add(C)` (ensure-exists, no data). */
-    props: Partial<Component> | undefined;
-} | {
-    kind: CommandKind.Modified;
-    entity: Entity;
-    type: number;
-} | {
-    kind: CommandKind.Remove;
-    entity: Entity;
-    type: number;
-} | {
-    kind: CommandKind.Destroy;
-    entity: Entity;
-} | {
-    kind: CommandKind.SetParent;
-    entity: Entity;
-    parent: Entity | undefined;
-};
+export {};

package/dist/component.d.ts

@@ -1,63 +1,68 @@
-import { BitPtr, Bitset } from "./util/bitset.js";
+import { BitPtr } from "./util/bitset.js";
 import type { Entity } from "./entity.js";
-import { type World } from "./world.js";
 /**
- * Lifecycle hook for a component type. Obtained via {@link World.hook}.
+ * Lifecycle hook for a registered component class. Obtained via
+ * {@link World.hook}.
  *
- * Hooks let you react to component lifecycle events without building a full
- * {@link System}. Each call returns the same `Hook` so the methods can be
- * chained:
+ * Hooks are a lightweight alternative to building a {@link System} when all
+ * you need is a callback on add / remove / set for a single component type.
+ * The same `Hook` is returned on every call to `world.hook(C)`, so registration
+ * methods chain:
  *
  * ```ts
  * world.hook(Sprite)
- *   .onAdd(c  => initSprite(c))
+ *   .onAdd(c => initSprite(c))
  *   .onRemove(c => destroySprite(c))
- *   .onSet(c  => syncSprite(c));
+ *   .onSet(c => syncSprite(c));
  * ```
  *
- * Callbacks are invoked synchronously during {@link World.runPhase} when
- * archetype changes are flushed.
+ * Callbacks fire synchronously when the corresponding entity command is
+ * applied: inline outside deferred mode, or while the world drains its command
+ * queue inside a system / `forEach` / `defer` block.
  *
- * @typeParam C - The `Component` subclass this hook is bound to.
+ * @typeParam C - Component subclass this hook is bound to.
  */
 export interface Hook<C extends Component = Component> {
     /**
-     * Register a callback that fires when a component of this type is added to
-     * an entity.
+     * Register a handler invoked when a component of this type is first attached
+     * to an entity (`entity.add(C)` or `entity.set(C, ...)` on an entity that
+     * does not yet have the component).
      *
-     * @param handler - Receives the newly created component instance.
-     * @returns `this` for chaining.
+     * @param handler - Receives the freshly created component instance.
+     * @returns This hook, for chaining.
      */
     onAdd(handler: (c: C) => void): Hook<C>;
     /**
-     * Register a callback that fires when a component of this type is removed
-     * from an entity (including when the entity is destroyed).
+     * Register a handler invoked when a component of this type is removed from
+     * an entity (explicit `entity.remove(C)` or implicit removal during
+     * `entity.destroy()`).
      *
-     * @param handler - Receives the component instance being removed.
-     * @returns `this` for chaining.
+     * @param handler - Receives the component instance that was removed.
+     * @returns This hook, for chaining.
      */
     onRemove(handler: (c: C) => void): Hook<C>;
     /**
-     * Register a callback that fires when {@link Component.modified} is called
-     * on a component of this type.
+     * Register a handler invoked when a component's data has been marked as
+     * changed (`component.modified()` or `entity.modified(c)`), and when
+     * `entity.set(C, props)` is called on an entity that already has the
+     * component.
      *
-     * @param handler - Receives the component instance that changed.
-     * @returns `this` for chaining.
+     * @param handler - Receives the component instance whose data changed.
+     * @returns This hook, for chaining.
      */
     onSet(handler: (c: C) => void): Hook<C>;
 }
 /**
- * Internal bookkeeping record for a registered component class.
+ * Bookkeeping record produced for each component class registered via
+ * {@link World.registerComponent}.
  *
- * Every component class that is passed to {@link World.registerComponent} gets
- * a `ComponentMeta` that maps it to a numeric type id, a string name, and a
- * pre-computed {@link BitPtr} used for fast archetype checks.
- *
- * `ComponentMeta` also implements {@link Hook}, so you can attach lifecycle
- * callbacks directly on the meta object (as `World.hook()` returns it).
+ * Holds the constructor, numeric type id, display name, and pre-computed
+ * {@link BitPtr} used by archetype checks. Implements {@link Hook}, so the
+ * lifecycle handlers attached via `world.hook(C)` are stored directly on the
+ * meta object.
  */
 export declare class ComponentMeta implements Hook<Component> {
-    /** The component class constructor. */
+    /** The component class constructor this meta represents. */
     readonly Class: typeof Component;
     /** Numeric type id assigned at registration time. */
     readonly type: number;
@@ -65,15 +70,10 @@ export declare class ComponentMeta implements Hook<Component> {
     readonly componentName: string;
     /** Pre-computed bit-pointer into the entity archetype {@link Bitset}. */
     readonly bitPtr: BitPtr;
-    /** @internal */
-    _onAddHandler: ((c: Component) => void) | undefined;
-    /** @internal */
-    _onRemoveHandler: ((c: Component) => void) | undefined;
-    /** @internal */
-    _onSetHandler: ((c: Component) => void) | undefined;
     /**
-     * Type ids of components that cannot coexist with this one on the same entity.
-     * Set via {@link World.setExclusiveComponents}. `undefined` means no restrictions.
+     * Type ids of components that cannot coexist with this one on the same
+     * entity. Set via {@link World.setExclusiveComponents}; `undefined` means
+     * no restriction.
      */
     exclusive: number[] | undefined;
     constructor(Class: typeof Component, type: number, componentName: string);
@@ -86,12 +86,12 @@ export declare class ComponentMeta implements Hook<Component> {
 }
 /** A component class constructor or its numeric type id. */
 export type ComponentClassOrType = number | typeof Component;
-/** An array of component class constructors or type ids. */
-export type ComponentClassArray = ComponentClassOrType[];
 /**
  * Base class for all ECS components.
  *
- * Extend this class to define data that can be attached to an {@link Entity}:
+ * Subclass `Component` to declare data that can be attached to an
+ * {@link Entity}. Instances are constructed by the world when
+ * {@link Entity.add} or {@link Entity.set} runs — never instantiate manually.
  *
  * ```ts
  * class Position extends Component {
@@ -103,20 +103,18 @@ export type ComponentClassArray = ComponentClassOrType[];
  * entity.set(Position, { x: 100 });
  * ```
  *
- * A component instance is always bound to a single entity and is created by
- * the world when {@link Entity.add} is called.
+ * Each instance is bound to a single entity via {@link entity}; that link is
+ * permanent for the component's lifetime.
  */
 export declare class Component {
     /** The entity this component belongs to. */
     readonly entity: Entity;
-    /** Registration metadata (type id, name, bit-pointer). */
+    /** Registration metadata (type id, display name, bit-pointer). */
     readonly meta: ComponentMeta;
-    /** @internal */
-    _dirty: boolean;
     constructor(
     /** The entity this component belongs to. */
     entity: Entity, 
-    /** Registration metadata (type id, name, bit-pointer). */
+    /** Registration metadata (type id, display name, bit-pointer). */
     meta: ComponentMeta);
     /** Numeric type id — shorthand for `this.meta.type`. */
     get type(): number;
@@ -125,18 +123,12 @@ export declare class Component {
     /**
      * Notify the world that this component's data has changed.
      *
-     * Queues the component for delivery to all {@link System.update} callbacks
-     * that watch this component type. Call this after mutating the component's
-     * fields to ensure systems react to the new values.
+     * Queues a modified event that fires `update` callbacks on every system /
+     * query that watches this component type, plus the component's `onSet`
+     * hook. Repeated calls before the world drains its queue are coalesced
+     * into one delivery.
      */
     modified(): void;
-    /** Returns the component's registered name, e.g. `"Position"`. */
+    /** Returns the component's registered display name (e.g. `"Position"`). */
     toString(): string;
 }
-/**
- * Compute a {@link Bitset} that has a bit set for every component class or
- * type id in `classes`.
- *
- * @internal Used internally to build archetype masks for system queries.
- */
-export declare function calculateComponentBitmask(classes: ComponentClassArray, world: World): Bitset;

package/dist/component.js

@@ -1,19 +1,19 @@
 import { BitPtr, Bitset } from "./util/bitset.js";
 /**
- * Internal bookkeeping record for a registered component class.
+ * Bookkeeping record produced for each component class registered via
+ * {@link World.registerComponent}.
  *
- * Every component class that is passed to {@link World.registerComponent} gets
- * a `ComponentMeta` that maps it to a numeric type id, a string name, and a
- * pre-computed {@link BitPtr} used for fast archetype checks.
- *
- * `ComponentMeta` also implements {@link Hook}, so you can attach lifecycle
- * callbacks directly on the meta object (as `World.hook()` returns it).
+ * Holds the constructor, numeric type id, display name, and pre-computed
+ * {@link BitPtr} used by archetype checks. Implements {@link Hook}, so the
+ * lifecycle handlers attached via `world.hook(C)` are stored directly on the
+ * meta object.
  */
 export class ComponentMeta {
     constructor(Class, type, componentName) {
         /**
-         * Type ids of components that cannot coexist with this one on the same entity.
-         * Set via {@link World.setExclusiveComponents}. `undefined` means no restrictions.
+         * Type ids of components that cannot coexist with this one on the same
+         * entity. Set via {@link World.setExclusiveComponents}; `undefined` means
+         * no restriction.
          */
         this.exclusive = undefined;
         this.Class = Class;
@@ -23,24 +23,26 @@ export class ComponentMeta {
     }
     /** @inheritdoc */
     onAdd(handler) {
-        this._onAddHandler = handler;
+        (this._onAddHandlers ?? (this._onAddHandlers = [])).unshift(handler);
         return this;
     }
     /** @inheritdoc */
     onRemove(handler) {
-        this._onRemoveHandler = handler;
+        (this._onRemoveHandlers ?? (this._onRemoveHandlers = [])).unshift(handler);
         return this;
     }
     /** @inheritdoc */
     onSet(handler) {
-        this._onSetHandler = handler;
+        (this._onSetHandlers ?? (this._onSetHandlers = [])).unshift(handler);
         return this;
     }
 }
 /**
  * Base class for all ECS components.
  *
- * Extend this class to define data that can be attached to an {@link Entity}:
+ * Subclass `Component` to declare data that can be attached to an
+ * {@link Entity}. Instances are constructed by the world when
+ * {@link Entity.add} or {@link Entity.set} runs — never instantiate manually.
  *
  * ```ts
  * class Position extends Component {
@@ -52,18 +54,18 @@ export class ComponentMeta {
  * entity.set(Position, { x: 100 });
  * ```
  *
- * A component instance is always bound to a single entity and is created by
- * the world when {@link Entity.add} is called.
+ * Each instance is bound to a single entity via {@link entity}; that link is
+ * permanent for the component's lifetime.
  */
 export class Component {
     constructor(
     /** The entity this component belongs to. */
     entity, 
-    /** Registration metadata (type id, name, bit-pointer). */
+    /** Registration metadata (type id, display name, bit-pointer). */
     meta) {
         this.entity = entity;
         this.meta = meta;
-        /** @internal */
+        /** @internal Set by {@link Entity.modified} to coalesce repeated calls until the world routes the modified command. */
         this._dirty = false;
     }
     /** Numeric type id — shorthand for `this.meta.type`. */
@@ -77,25 +79,29 @@ export class Component {
     /**
      * Notify the world that this component's data has changed.
      *
-     * Queues the component for delivery to all {@link System.update} callbacks
-     * that watch this component type. Call this after mutating the component's
-     * fields to ensure systems react to the new values.
+     * Queues a modified event that fires `update` callbacks on every system /
+     * query that watches this component type, plus the component's `onSet`
+     * hook. Repeated calls before the world drains its queue are coalesced
+     * into one delivery.
      */
     modified() {
         this.entity.modified(this);
     }
-    /** Returns the component's registered name, e.g. `"Position"`. */
+    /** Returns the component's registered display name (e.g. `"Position"`). */
     toString() {
         return this.meta.componentName;
     }
 }
 /**
- * Compute a {@link Bitset} that has a bit set for every component class or
- * type id in `classes`.
+ * Compute a {@link Bitset} with one bit set for every component class or
+ * numeric type id in `classes`.
+ *
+ * @internal Used to build archetype masks for `HAS` / `HAS_ONLY` queries.
  *
- * @internal Used internally to build archetype masks for system queries.
+ * @param classes - Component classes or type ids to include.
+ * @param world - World used to resolve classes to type ids.
  */
-export function calculateComponentBitmask(classes, world) {
+export function _calculateComponentBitmask(classes, world) {
     const bitmask = new Bitset();
     classes.forEach((C) => {
         bitmask.add(world.getComponentType(C));

package/dist/component.js.map

@@ -1 +1 @@
-{"version":3,"file":"component.js","sourceRoot":"","sources":["../src/component.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAoDlD;;;;;;;;;GASG;AACH,MAAM,OAAO,aAAa;IAqBxB,YAAY,KAAuB,EAAE,IAAY,EAAE,aAAqB;QANxE;;;WAGG;QACI,cAAS,GAAyB,SAAS,CAAC;QAGjD,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QACnC,IAAI,CAAC,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,kBAAkB;IACX,KAAK,CAAC,OAA+B;QAC1C,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,kBAAkB;IACX,QAAQ,CAAC,OAA+B;QAC7C,IAAI,CAAC,gBAAgB,GAAG,OAAO,CAAC;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,kBAAkB;IACX,KAAK,CAAC,OAA+B;QAC1C,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAQD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,OAAO,SAAS;IAIpB;IACE,4CAA4C;IAC5B,MAAc;IAC9B,0DAA0D;IAC1C,IAAmB;QAFnB,WAAM,GAAN,MAAM,CAAQ;QAEd,SAAI,GAAJ,IAAI,CAAe;QAPrC,gBAAgB;QACT,WAAM,GAAY,KAAK,CAAC;IAO5B,CAAC;IAEJ,wDAAwD;IACxD,IAAW,IAAI;QACb,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;IACxB,CAAC;IAED,mEAAmE;IACnE,IAAW,MAAM;QACf,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;IAC1B,CAAC;IAED;;;;;;OAMG;IACI,QAAQ;QACb,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED,kEAAkE;IAC3D,QAAQ;QACb,OAAO,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC;IACjC,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CAAC,OAA4B,EAAE,KAAY;IAClF,MAAM,OAAO,GAAG,IAAI,MAAM,EAAE,CAAC;IAC7B,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE;QACpB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"component.js","sourceRoot":"","sources":["../src/component.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AA2DlD;;;;;;;;GAQG;AACH,MAAM,OAAO,aAAa;IAwBxB,YAAY,KAAuB,EAAE,IAAY,EAAE,aAAqB;QAdxE;;;;WAIG;QACI,cAAS,GAAyB,SAAS,CAAC;QAUjD,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QACnC,IAAI,CAAC,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,kBAAkB;IACX,KAAK,CAAC,OAA+B;QAC1C,CAAC,IAAI,CAAC,cAAc,KAAnB,IAAI,CAAC,cAAc,GAAK,EAAE,EAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAC9C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,kBAAkB;IACX,QAAQ,CAAC,OAA+B;QAC7C,CAAC,IAAI,CAAC,iBAAiB,KAAtB,IAAI,CAAC,iBAAiB,GAAK,EAAE,EAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACjD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,kBAAkB;IACX,KAAK,CAAC,OAA+B;QAC1C,CAAC,IAAI,CAAC,cAAc,KAAnB,IAAI,CAAC,cAAc,GAAK,EAAE,EAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAC9C,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAYD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,SAAS;IAIpB;IACE,4CAA4C;IAC5B,MAAc;IAC9B,kEAAkE;IAClD,IAAmB;QAFnB,WAAM,GAAN,MAAM,CAAQ;QAEd,SAAI,GAAJ,IAAI,CAAe;QAPrC,uHAAuH;QAChH,WAAM,GAAY,KAAK,CAAC;IAO5B,CAAC;IAEJ,wDAAwD;IACxD,IAAW,IAAI;QACb,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;IACxB,CAAC;IAED,mEAAmE;IACnE,IAAW,MAAM;QACf,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;IAC1B,CAAC;IAED;;;;;;;OAOG;IACI,QAAQ;QACb,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED,2EAA2E;IACpE,QAAQ;QACb,OAAO,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC;IACjC,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,0BAA0B,CAAC,OAA4B,EAAE,KAAY;IACnF,MAAM,OAAO,GAAG,IAAI,MAAM,EAAE,CAAC;IAC7B,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE;QACpB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/dsl.d.ts

@@ -1,30 +1,34 @@
 import { Component, ComponentClassArray, ComponentClassOrType } from "./component.js";
 import type { Entity } from "./entity.js";
-import type { World } from "./world.js";
-/** A function that tests whether a given entity belongs to a query. */
+/**
+ * A predicate that decides whether a given entity belongs to a query.
+ *
+ * Pass one directly inside {@link QueryDSL} to express membership rules that
+ * the structured operators cannot reach.
+ */
 export type EntityTestFunc = (e: Entity) => boolean;
 /**
- * A composable query expression used to declare which entities a
- * {@link Query} or {@link System} should track.
+ * A composable expression describing which entities a {@link Query},
+ * {@link System}, or {@link Filter} should match.
  *
- * Queries can be nested arbitrarily:
+ * Operators can be nested arbitrarily:
  *
  * ```ts
- * // Entities that have Position AND (Sprite OR Container):
+ * // Position AND (Sprite OR Container):
  * world.system("render").query({
- *   AND: [Position, { OR: [Sprite, Container] }]
+ *   AND: [Position, { OR: [Sprite, Container] }],
  * });
  *
- * // Entities that have a parent with Player AND Container:
+ * // Parent has Player AND Container:
  * world.system("attach").query({
- *   PARENT: { AND: [Player, Container] }
+ *   PARENT: { AND: [Player, Container] },
  * });
  * ```
  *
- * Short forms:
- * - A single class or type id is equivalent to `{ HAS: [C] }`.
- * - An array `[A, B]` is equivalent to `{ HAS: [A, B] }`.
- * - Pass an {@link EntityTestFunc} directly for fully custom membership logic.
+ * Short forms recognized by `query` / `filter`:
+ * - A single class or numeric type id is shorthand for `{ HAS: [C] }`.
+ * - An array `[A, B]` is shorthand for `{ HAS: [A, B] }`.
+ * - An {@link EntityTestFunc} is invoked directly for fully custom logic.
  */
 export type QueryDSL = ComponentClassArray | ComponentClassOrType | EntityTestFunc | {
     HAS: ComponentClassArray | ComponentClassOrType;
@@ -39,24 +43,30 @@ export type QueryDSL = ComponentClassArray | ComponentClassOrType | EntityTestFu
 } | {
     PARENT: QueryDSL;
 };
-export declare function HAS(world: World, ...components: ComponentClassArray): EntityTestFunc;
 /**
- * Resolves component nullability based on what was declared in `requires` (or
- * the `_guaranteed` hint). Components in `R` are non-nullable; others are
- * `InstanceType<C> | undefined`.
+ * Resolve component nullability based on what was declared in `requires` (or
+ * the `_guaranteed` hint).
+ *
+ * Components in `R` resolve to `InstanceType<C>`; every other component class
+ * resolves to `InstanceType<C> | undefined`.
+ *
+ * @typeParam C - Component class being injected.
+ * @typeParam R - Tuple of component classes guaranteed present.
  */
 export type MaybeRequired<C, R extends (typeof Component)[]> = C extends typeof Component ? C extends R[number] ? InstanceType<C> : InstanceType<C> | undefined : never;
 /**
- * Statically extracts the component classes that are **guaranteed present** on
+ * Statically extract the component classes that are **guaranteed present** on
  * every entity matched by a {@link QueryDSL} expression.
  *
  * Rules:
  * - Plain class `C` → `[C]`
  * - Plain array `[A, B]` → `[A, B]`
- * - `{HAS: ...}` / `{HAS_ONLY: ...}` → recurse into the payload
- * - `{AND: [q1, q2, ...]}` → concatenation of each branch's extraction
- * - `{OR: ...}` / `{NOT: ...}` / `{PARENT: ...}` → `[]` (no guarantee)
+ * - `{ HAS: ... }` / `{ HAS_ONLY: ... }` → recurse into the payload
+ * - `{ AND: [q1, q2, ...] }` → concatenate each branch's extraction
+ * - `{ OR: ... }` / `{ NOT: ... }` / `{ PARENT: ... }` → `[]` (no guarantee)
  * - `EntityTestFunc` / numeric type id → `[]` (opaque)
+ *
+ * @typeParam Q - Query expression to analyse.
  */
 export type ExtractRequired<Q> = Q extends typeof Component ? [Q] : Q extends readonly (typeof Component)[] ? Q : Q extends {
     HAS: infer H;
@@ -64,11 +74,9 @@ export type ExtractRequired<Q> = Q extends typeof Component ? [Q] : Q extends re
     HAS_ONLY: infer H;
 } ? ExtractRequired<H> : Q extends {
     AND: infer A extends readonly QueryDSL[];
-} ? ExtractAndChain<A> : [];
-type ExtractAndChain<A extends readonly QueryDSL[]> = A extends readonly [
+} ? _ExtractAndChain<A> : [];
+type _ExtractAndChain<A extends readonly QueryDSL[]> = A extends readonly [
     infer First,
     ...infer Rest extends readonly QueryDSL[]
-] ? [...ExtractRequired<First>, ...ExtractAndChain<Rest>] : [];
-/** Convert a {@link QueryDSL} expression into a runtime entity-test predicate. */
-export declare function buildEntityTest(world: World, q: QueryDSL): EntityTestFunc;
+] ? [...ExtractRequired<First>, ..._ExtractAndChain<Rest>] : [];
 export {};

package/dist/dsl.js

@@ -1,56 +1,82 @@
-import { Component, calculateComponentBitmask, } from "./component.js";
-export function HAS(world, ...components) {
-    const testBitmask = calculateComponentBitmask(components, world);
+import { Component, _calculateComponentBitmask, } from "./component.js";
+/**
+ * Build a predicate that returns `true` when an entity has every component
+ * type in `components` set on its archetype.
+ *
+ * @internal Factory used by {@link _buildEntityTest} and by `Query.update`'s
+ * watchlist auto-expansion.
+ *
+ * @param world - World used to resolve component classes to type ids.
+ * @param components - Component classes or numeric type ids to require.
+ */
+export function _HAS(world, ...components) {
+    const testBitmask = _calculateComponentBitmask(components, world);
     return (e) => e.componentBitmask.hasBitset(testBitmask);
 }
-function HAS_ONLY(world, ...components) {
-    const testBitmask = calculateComponentBitmask(components, world);
+/**
+ * Build a predicate that returns `true` only when an entity's archetype is
+ * exactly the set in `components` (no other components attached).
+ */
+function _HAS_ONLY(world, ...components) {
+    const testBitmask = _calculateComponentBitmask(components, world);
     return (e) => e.componentBitmask.equal(testBitmask);
 }
-function NOT(func) {
+/** Negate a predicate. */
+function _NOT(func) {
     return (e) => !func(e);
 }
-function AND(...funcs) {
+/** Conjunction of multiple predicates. */
+function _AND(...funcs) {
     return (e) => funcs.every((f) => f(e));
 }
-function OR(...funcs) {
+/** Disjunction of multiple predicates. */
+function _OR(...funcs) {
     return (e) => funcs.some((f) => f(e));
 }
-function PARENT(func) {
+/** Lift a predicate to apply to the entity's parent (false when no parent). */
+function _PARENT(func) {
     return (e) => (e.parent && func(e.parent)) || false;
 }
-/** Convert a {@link QueryDSL} expression into a runtime entity-test predicate. */
-export function buildEntityTest(world, q) {
+/**
+ * Compile a {@link QueryDSL} expression into a runtime entity-test predicate.
+ *
+ * @internal Used by `Query`, `System`, and `Filter` to translate user-supplied
+ * DSL expressions into the predicate stored on `Query._belongs`.
+ *
+ * @param world - World used to resolve component classes to type ids.
+ * @param q - Query expression.
+ */
+export function _buildEntityTest(world, q) {
     if (typeof q === "number" || (typeof q === "function" && q.prototype instanceof Component)) {
-        return HAS(world, q);
+        return _HAS(world, q);
     }
     else if (typeof q === "function") {
         return q;
     }
     if (q instanceof Array) {
-        return HAS(world, ...q);
+        return _HAS(world, ...q);
     }
     if ("HAS" in q) {
-        return buildEntityTest(world, q.HAS);
+        return _buildEntityTest(world, q.HAS);
     }
     if ("HAS_ONLY" in q) {
         const v = q.HAS_ONLY;
         if (v instanceof Array) {
-            return HAS_ONLY(world, ...v);
+            return _HAS_ONLY(world, ...v);
         }
-        return HAS_ONLY(world, v);
+        return _HAS_ONLY(world, v);
     }
     if ("AND" in q) {
-        return AND(...q.AND.map((sq) => buildEntityTest(world, sq)));
+        return _AND(...q.AND.map((sq) => _buildEntityTest(world, sq)));
     }
     if ("OR" in q) {
-        return OR(...q.OR.map((sq) => buildEntityTest(world, sq)));
+        return _OR(...q.OR.map((sq) => _buildEntityTest(world, sq)));
     }
     if ("NOT" in q) {
-        return NOT(buildEntityTest(world, q.NOT));
+        return _NOT(_buildEntityTest(world, q.NOT));
     }
     if ("PARENT" in q) {
-        return PARENT(buildEntityTest(world, q.PARENT));
+        return _PARENT(_buildEntityTest(world, q.PARENT));
     }
     throw "Unrecognized query term";
 }

package/dist/dsl.js.map

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