@awesome-ecs/abstract 0.32.1 → 0.34.0

package/dist/{index-BOsrKTWm.d.cts → index-CSaKdQe-.d.cts}

@@ -1,6 +1,15 @@
-import { _ as ConfigRecord, a as IEntity, c as IEntityProxy, f as ComponentTypeUid, i as EntityUid, n as IdentityComponent, o as IEntityModel, p as IComponent, r as EntityTypeUid } from "./index-C5nragoq.cjs";
-import { n as DeepPartial } from "./types-Bbmnq4ni.cjs";
+import { T as ConfigRecord, a as IEntityProxy, b as ComponentTypeUid, f as IEntity, p as IEntityModel, u as EntityTypeUid, x as IComponent, y as IdentityComponent } from "./index-DMZSrHoB.cjs";
+import { n as DeepPartial } from "./types-BaCGIrym.cjs";
 
+//#region src/entities/context-repository.d.ts
+declare const SYSTEM_CONTEXT_KEY: unique symbol;
+interface IContextRepository {
+  get<TContext>(proxy: IEntityProxy, key: string | symbol): TContext | undefined;
+  set<TContext>(proxy: IEntityProxy, key: string | symbol, context: TContext): TContext;
+  delete(proxy: IEntityProxy, key: string | symbol): boolean;
+  deleteAll(proxy: IEntityProxy): boolean;
+}
+//#endregion
 //#region src/entities/entity-config.d.ts
 /**
  * Config-only entity state update.
@@ -14,59 +23,6 @@ interface IEntityConfigSnapshot<TConfig extends ConfigRecord = ConfigRecord> {
   readonly components: Record<ComponentTypeUid, DeepPartial<TConfig>>;
 }
 //#endregion
-//#region src/entities/entity-context-cache.d.ts
-/**
- * A generic per-entity key-value store for runtime contexts.
- *
- * Each package registers its own per-entity data using its own key constants.
- * Disposal removes all entries for an entity in a single call, covering all packages.
- *
- * @example
- * // Core stores SystemContext:
- * cache.set(entityUid, SYSTEM_KEY, systemContext);
- *
- * // AI stores per-module StateContexts:
- * cache.set(entityUid, `state:${moduleName}`, stateContext);
- *
- * // On removal, one call cleans up everything:
- * cache.disposeEntity(entityUid);
- */
-interface IEntityContextCache {
-  /**
-   * Retrieves a cached value by entity UID and key.
-   * @template T - The expected value type.
-   * @param entityUid - The entity's unique identifier.
-   * @param key - The key to look up.
-   * @returns The cached value, or undefined if not found.
-   */
-  get<T>(entityUid: EntityUid, key: string | symbol): T | undefined;
-  /**
-   * Stores a value for an entity under the given key.
-   * @param entityUid - The entity's unique identifier.
-   * @param key - The key to store under.
-   * @param value - The value to cache.
-   */
-  set(entityUid: EntityUid, key: string | symbol, value: unknown): void;
-  /**
-   * Checks whether a cached entry exists.
-   * @param entityUid - The entity's unique identifier.
-   * @param key - Optional key to check. If omitted, checks if any entry exists for the entity.
-   */
-  has(entityUid: EntityUid, key?: string | symbol): boolean;
-  /**
-   * Returns an iterator over all key-value pairs cached for the given entity.
-   * @param entityUid - The entity's unique identifier.
-   * @returns An iterable iterator of [key, value] pairs, or undefined if the entity has no entries.
-   */
-  getEntries(entityUid: EntityUid): IterableIterator<[string | symbol, unknown]> | undefined;
-  /**
-   * Removes all cached entries for the given entity.
-   * Should be called when an entity is removed from the system.
-   * @param entityUid - The entity's unique identifier.
-   */
-  disposeEntity(entityUid: EntityUid): void;
-}
-//#endregion
 //#region src/entities/entity-events.d.ts
 /**
  * Represents a unique identifier for an entity event.
@@ -211,6 +167,59 @@ interface IEntityEventsDispatcher {
   broadcastEvents(events: IEntityEvent<IEventData>[]): void;
 }
 //#endregion
+//#region src/entities/entity-repository.d.ts
+/**
+ * Central storage for all active entities in the system.
+ * The repository provides CRUD operations and is the source of truth for entity existence and state.
+ * All entity access and modifications go through this repository.
+ */
+interface IEntityRepository {
+  /**
+   * The total number of entities currently stored.
+   */
+  readonly size: number;
+  /**
+   * Checks if an entity exists in storage.
+   * @param proxy - Reference to the entity to check.
+   * @returns True if the entity exists, false otherwise.
+   */
+  has(proxy: IEntityProxy): boolean;
+  /**
+   * Retrieves an entity from storage by proxy.
+   * @template TEntity - The expected entity type.
+   * @param proxy - Reference to the entity to retrieve.
+   * @returns The requested entity.
+   */
+  getEntity<TEntity extends IEntity>(proxy: IEntityProxy): TEntity | undefined;
+  /**
+   * Retrieves all entities of a specific type.
+   * @template TEntity - The entity type to retrieve.
+   * @param entityType - The type identifier to filter by.
+   * @returns Array of all entities matching the type.
+   */
+  getEntities<TEntity extends IEntity>(entityType: EntityTypeUid): TEntity[];
+  /**
+   * Iterates over all entities regardless of type.
+   * @returns An iterator over all stored entities.
+   */
+  listAll(): IterableIterator<IEntity>;
+  /**
+   * Stores or updates an entity.
+   * @param entity - The entity to store.
+   */
+  set<TEntity extends IEntity>(entity: TEntity): TEntity;
+  /**
+   * Removes an entity from storage.
+   * @param proxy - Reference to the entity to remove.
+   */
+  delete(proxy: IEntityProxy): void;
+  /**
+   * Removes all entities of a specific type from storage.
+   * @param entityType - The type identifier for entities to remove.
+   */
+  clear(entityType: EntityTypeUid): void;
+}
+//#endregion
 //#region src/entities/entity-snapshot.d.ts
 /**
  * A serializable representation of entity state.
@@ -258,237 +267,69 @@ interface IEntitySnapshotProvider {
   createSnapshot(entity: IEntity): IEntitySnapshot;
 }
 //#endregion
-//#region src/entities/entity-queue.d.ts
-/**
- * Specifies the action to be performed on an entity.
- * Updates are categorized to enable different processing paths in the runtime.
- */
+//#region src/entities/entity-scheduler.d.ts
 declare enum EntityUpdateType {
-  /**
-   * Indicates the entity should be updated with new data.
-   */
   update = "update",
-  /**
-   * Indicates the entity should be removed from the system.
-   */
   remove = "remove"
 }
-/**
- * Represents a queued entity state change or removal.
- * Updates flow through the system to be processed by entity update handlers.
- */
 interface IEntityUpdate {
-  /**
-   * The type of operation: update or remove.
-   */
   readonly type: EntityUpdateType;
-  /**
-   * The entity being affected by this update.
-   */
   readonly entity: IEntityProxy;
-  /**
-   * Optional model data for initialization or reconfiguration.
-   */
   readonly model?: IEntityModel;
-  /**
-   * Optional serialized state to apply to the entity.
-   */
   readonly snapshot?: IEntitySnapshot;
-  /**
-   * Optional config-only component state to apply to the entity.
-   * When present on an update, the runtime applies it after `snapshot` and
-   * includes the config system phase in the same tick.
-   */
   readonly config?: IEntityConfigSnapshot;
 }
-/**
- * Queue interface for managing pending entity updates.
- * Different implementations may use different prioritization strategies (e.g., priority queues, FIFO, ordered by entity type).
- * Updates are consumed by the runtime and dispatched to appropriate entity systems.
- */
-interface IEntityUpdateQueue {
-  /**
-   * The current number of updates in the queue.
-   */
-  readonly size: number;
-  /**
-   * Adds an update to the queue for processing.
-   * @param change - The update to queue.
-   */
-  enqueue(change: IEntityUpdate): void;
-  /**
-   * Removes and returns the next update from the queue.
-   * The specific update returned depends on the queue's prioritization strategy.
-   * @returns The next queued update.
-   */
-  dequeue(): IEntityUpdate;
-  /**
-   * Views the next update without removing it.
-   * Useful for inspection before dequeuing.
-   * @returns The next update in the queue.
-   */
-  peek(): IEntityUpdate;
-  /**
-   * Returns a read-only snapshot of all queued updates without removing them.
-   * Useful for inspection/debugging UIs.
-   * @returns An array of all currently queued updates.
-   */
-  items(): ReadonlyArray<IEntityUpdate>;
-  /**
-   * Removes all updates from the queue.
-   */
-  clear(): void;
-}
-//#endregion
-//#region src/entities/entity-repository.d.ts
-/**
- * Central storage for all active entities in the system.
- * The repository provides CRUD operations and is the source of truth for entity existence and state.
- * All entity access and modifications go through this repository.
- */
-interface IEntityRepository {
-  /**
-   * The total number of entities currently stored.
-   */
-  readonly size: number;
-  /**
-   * Checks if an entity exists in storage.
-   * @param proxy - Reference to the entity to check.
-   * @returns True if the entity exists, false otherwise.
-   */
-  has(proxy: IEntityProxy): boolean;
-  /**
-   * Retrieves an entity from storage by proxy.
-   * @template TEntity - The expected entity type.
-   * @param proxy - Reference to the entity to retrieve.
-   * @returns The requested entity.
-   */
-  get<TEntity extends IEntity>(proxy: IEntityProxy): TEntity;
-  /**
-   * Retrieves all entities of a specific type.
-   * @template TEntity - The entity type to retrieve.
-   * @param entityType - The type identifier to filter by.
-   * @returns Array of all entities matching the type.
-   */
-  getAll<TEntity extends IEntity>(entityType: EntityTypeUid): TEntity[];
-  /**
-   * Iterates over all entities regardless of type.
-   * @returns An iterator over all stored entities.
-   */
-  listAll(): IterableIterator<IEntity>;
-  /**
-   * Stores or updates an entity.
-   * @param entity - The entity to store.
-   */
-  set(entity: IEntity): void;
-  /**
-   * Removes an entity from storage.
-   * @param proxy - Reference to the entity to remove.
-   */
-  delete(proxy: IEntityProxy): void;
-  /**
-   * Removes all entities of a specific type from storage.
-   * @param entityType - The type identifier for entities to remove.
-   */
-  clear(entityType: EntityTypeUid): void;
+interface IEntityDispatchGroup {
+  readonly entityType: EntityTypeUid;
+  readonly updates: ReadonlyArray<IEntityUpdate>;
+  readonly dirtyUpdates: number;
+  readonly scheduledUpdates: number;
+  readonly removeUpdates: number;
+  readonly pipelineMask?: number;
 }
-//#endregion
-//#region src/entities/entity-scheduler.d.ts
-/**
- * Describes a scheduled entity update, including the target entity and optional interval.
- */
+type EntityRuntimePendingGroupOptions = {
+  readonly includeFrameSubscriptions?: boolean;
+};
 type EntitySchedule = {
   readonly proxy: IEntityProxy;
   readonly intervalMs?: number;
 };
-/**
- * Controls which scheduling modes are paused.
- */
+type EntityPriorityModel = {
+  readonly defaultPriority?: number;
+  readonly entityTypes?: ReadonlyMap<EntityTypeUid, number>;
+};
 declare enum SchedulerPauseType {
-  /** Pause both interval timers and frame subscriptions. */
   full = "full",
-  /** Pause only frame subscriptions. Interval timers continue firing. */
   perFrame = "perFrame",
-  /** Pause only interval timers. Frame subscriptions continue. */
   intervals = "intervals"
 }
-/**
- * Manages time-based scheduling of entity updates.
- *
- * Entities can be scheduled with an interval (timer-driven) or without one (per-frame).
- * The runtime pulls pending entities each tick via the {@link pending} iterator,
- * which yields both per-frame subscriptions and interval entities whose timer has fired.
- */
-interface IEntityScheduler {
-  /**
-   * Returns all currently scheduled entities with their configuration.
-   * Useful for inspection and debugging.
-   */
-  readonly schedules: ReadonlyArray<EntitySchedule>;
-  /**
-   * Yields entities pending processing this tick: per-frame subscriptions
-   * followed by interval entities whose timer has fired since the last drain.
-   * Iterating drains the due interval buckets; a second iteration without
-   * timer advancement yields only per-frame subscriptions.
-   */
-  readonly pending: IterableIterator<IEntityProxy>;
-  /**
-   * The set of entities scheduled for per-frame updates (no interval).
-   */
-  readonly frameSubscriptions: ReadonlySet<IEntityProxy>;
-  /**
-   * Entity types currently excluded from {@link pending} iteration.
-   */
-  readonly skippedEntityTypes: ReadonlySet<EntityTypeUid>;
-  /**
-   * The number of entities currently awaiting processing:
-   * per-frame subscriptions (if not paused) plus interval entities whose timer has fired.
-   */
-  readonly pendingCount: number;
-  /**
-   * Whether the scheduler is currently paused in any mode.
-   */
-  readonly isPaused: boolean;
-  /**
-   * Registers or replaces an entity schedule.
-   * @param entityProxy - The entity to schedule.
-   * @param intervalMs - Update frequency in milliseconds. If omitted, the entity is scheduled per-frame.
-   */
-  schedule(entityProxy: IEntityProxy, intervalMs?: number): void;
-  /**
-   * Unregisters an entity from the scheduler.
-   * @param entityProxy - The entity to unschedule.
-   */
-  remove(entityProxy: IEntityProxy): void;
-  /**
-   * Checks if an entity is currently scheduled for updates.
-   * @param entityProxy - The entity to check.
-   * @returns True if the entity is scheduled, false otherwise.
-   */
-  has(entityProxy: IEntityProxy): boolean;
-  /**
-   * Removes all schedules and clears all timers.
-   */
-  clear(): void;
-  /**
-   * Excludes an entity type from {@link pending} iteration.
-   * Entities remain registered; only yielding is suppressed.
-   */
+interface IEntityRuntimeScheduler {
+  enqueue(update: IEntityUpdate): void;
+  enqueueEvent(entity: IEntityProxy, event: IEntityEvent<IEventData>): void;
+  enqueueEvents(entity: IEntityProxy, events: ReadonlyArray<IEntityEvent<IEventData>>): void;
+  clearDirtyUpdates(): void;
+  schedule(proxy: IEntityProxy, intervalMs?: number): void;
+  removeSchedule(proxy: IEntityProxy): void;
+  hasSchedule(proxy: IEntityProxy): boolean;
+  clearSchedules(): void;
+  takePendingGroups(maxItems?: number, options?: EntityRuntimePendingGroupOptions): ReadonlyArray<IEntityDispatchGroup>;
   skipEntityType(entityType: EntityTypeUid): void;
-  /**
-   * Re-includes a previously skipped entity type in {@link pending} iteration.
-   */
   unskipEntityType(entityType: EntityTypeUid): void;
-  /**
-   * Pauses the scheduler.
-   * @param type - Which scheduling modes to pause. Defaults to {@link SchedulerPauseType.full}.
-   */
   pause(type?: SchedulerPauseType): void;
-  /**
-   * Resumes the scheduler from any paused state.
-   */
   resume(): void;
 }
+interface IEntityRuntimeSchedulerInspector extends IEntityRuntimeScheduler {
+  readonly dirtyCount: number;
+  readonly frameSubscriptions: ReadonlySet<IEntityProxy>;
+  readonly isPaused: boolean;
+  readonly pauseType: SchedulerPauseType | null;
+  readonly pendingGroupCount: number;
+  readonly pendingCount: number;
+  readonly rawDirtyCount: number;
+  readonly schedules: ReadonlyArray<EntitySchedule>;
+  readonly skippedEntityTypes: ReadonlySet<EntityTypeUid>;
+  inspectDirtyUpdates(): ReadonlyArray<IEntityUpdate>;
+}
 //#endregion
-export { IEntityContextCache as _, EntityUpdateType as a, IEntitySnapshot as c, EntityEventSubscriptionOptions as d, EntityEventUid as f, IEventData as g, IEntityEventsManager as h, IEntityRepository as i, IEntitySnapshotProvider as l, IEntityEventsDispatcher as m, IEntityScheduler as n, IEntityUpdate as o, IEntityEvent as p, SchedulerPauseType as r, IEntityUpdateQueue as s, EntitySchedule as t, EntityEventSubscriptionFilter as u, IEntityConfigSnapshot as v };
-//# sourceMappingURL=index-BOsrKTWm.d.cts.map
+export { SYSTEM_CONTEXT_KEY as S, IEntityEventsDispatcher as _, IEntityDispatchGroup as a, IEntityConfigSnapshot as b, IEntityUpdate as c, IEntitySnapshotProvider as d, IEntityRepository as f, IEntityEvent as g, EntityEventUid as h, EntityUpdateType as i, SchedulerPauseType as l, EntityEventSubscriptionOptions as m, EntityRuntimePendingGroupOptions as n, IEntityRuntimeScheduler as o, EntityEventSubscriptionFilter as p, EntitySchedule as r, IEntityRuntimeSchedulerInspector as s, EntityPriorityModel as t, IEntitySnapshot as u, IEntityEventsManager as v, IContextRepository as x, IEventData as y };
+//# sourceMappingURL=index-CSaKdQe-.d.cts.map