@awesome-ecs/abstract 0.29.0 → 0.30.0

package/dist/index-Df4VhCPr.d.cts

@@ -1,544 +0,0 @@
-import { a as IEntity, c as IEntityProxy, l as IEntityProxyRepository, o as IEntityModel, r as EntityTypeUid, s as EntityProxy } from "./identity-component-CsU-wYTX.cjs";
-import { n as Immutable } from "./types-DqWnkvhp.cjs";
-import { c as IEntitySnapshot, d as EntityEventSubscriptionOptions, f as EntityEventUid, g as IEventData, o as IEntityUpdate, p as IEntityEvent } from "./index-DTHsTJ1j.cjs";
-import { a as ILogger, c as IJsonSerializer, r as PerformanceTimeEntry } from "./index-DCx0PjvH.cjs";
-import { c as IMiddleware, l as IPipelineContext, o as IPipeline } from "./index-BRkKPsOV.cjs";
-
-//#region src/systems/pipeline/system-context-events.d.ts
-/**
- * System context API for event-driven entity communication.
- * Allows middleware to dispatch events, manage subscriptions, and query event state.
- * Events enable decoupled communication between distant or unrelated entities.
- */
-interface ISystemContextEvents {
-  /**
-   * Publishes an event to one or more explicit targets.
-   * The event is sent only to the specified target(s) — it does NOT fall back to subscriptions.
-   * @param data - The event payload.
-   * @param target - The entity or entities to send the event to.
-   */
-  dispatchEvent<TEventData extends IEventData>(data: TEventData, target: IEntityProxy | IEntityProxy[]): void;
-  /**
-   * Publishes multiple events to one or more explicit targets.
-   * Each target receives all events in a single update.
-   * @param data - Array of event payloads to dispatch.
-   * @param target - The entity or entities to send the events to.
-   */
-  dispatchEvents<TEventData extends IEventData>(data: TEventData[], target: IEntityProxy | IEntityProxy[]): void;
-  /**
-   * Broadcasts an event to all subscribers registered for that event type.
-   * Uses the subscription registry to resolve targets.
-   * @param data - The event payload.
-   */
-  broadcastEvent<TEventData extends IEventData>(data: TEventData): void;
-  /**
-   * Broadcasts multiple events to all subscribers.
-   * Events are grouped per subscriber so each receives a single update.
-   * @param data - Array of event payloads to broadcast.
-   */
-  broadcastEvents<TEventData extends IEventData>(data: TEventData[]): void;
-  /**
-   * Retrieves an event from the current context by its identifier.
-   * Useful for checking if an event was received this frame.
-   * @param uid - The event type identifier.
-   * @returns The event if present, undefined otherwise.
-   */
-  getEvent<TEventData extends IEventData>(uid: EntityEventUid): IEntityEvent<TEventData> | undefined;
-  /**
-   * Retrieves all events currently set on this context.
-   * Events are cleared between frames.
-   * @returns Array of all active events for this context.
-   */
-  listEvents<TEventData extends IEventData>(): IEntityEvent<TEventData>[];
-  /**
-   * Checks if a specific event is present in the current context.
-   * If no uid is provided, checks if any events exist.
-   * @param uid - Optional event type to check for. If omitted, checks for any event.
-   * @returns True if matching event(s) found, false otherwise.
-   */
-  hasEvent(uid?: EntityEventUid): boolean;
-  /**
-   * Subscribes to events of a specific type.
-   * The entity will be notified of matching events through the update system.
-   * @param uid - The event type to listen for.
-   * @param options - Optional subscription options (filter, scopeId).
-   */
-  subscribeTo(uid: EntityEventUid, options?: EntityEventSubscriptionOptions): void;
-  /**
-   * Stops listening for events of a specific type.
-   * @param uid - The event type to stop listening for.
-   */
-  unsubscribeFrom(uid: EntityEventUid): void;
-  /**
-   * Adds events to the current context for processing by this and downstream middleware.
-   * @param events - Event array to add to context.
-   */
-  setContextEvents(events: IEntityEvent<IEventData>[]): void;
-  /**
-   * Adds a single event to the current context.
-   * @param event - Event to add to context.
-   */
-  setContextEvent(event: IEntityEvent<IEventData>): void;
-  /**
-   * Removes all events from the current context.
-   */
-  clearContextEvents(): void;
-  /**
-   * Clears all event subscriptions for the current entity.
-   */
-  clearSubscriptions(): void;
-}
-//#endregion
-//#region src/systems/pipeline/system-context-proxies.d.ts
-/**
- * System context API for managing entity relationships (proxies).
- * Provides context-bound operations for establishing and managing entity links.
- * All operations apply to the current entity in the context.
- */
-interface ISystemContextProxies {
-  /**
-   * Establishes a reference to another entity from the current entity.
-   * Creates a bidirectional link between the entities.
-   * @param proxy - The entity to establish a reference to.
-   * @param cleanup - If true, removes existing proxies of the same type before adding.
-   */
-  register(proxy: IEntityProxy, cleanup?: boolean): void;
-  /**
-   * Establishes multiple references from the current entity.
-   * Batch version of register for efficiency.
-   * @param proxies - The entities to establish references to.
-   * @param cleanup - If true, removes existing proxies of matching types before adding.
-   */
-  registerMany(proxies: readonly IEntityProxy[], cleanup?: boolean): void;
-  /**
-   * Removes a reference from the current entity to another entity.
-   * Breaks the bidirectional link.
-   * @param proxy - The entity reference to remove.
-   */
-  remove(proxy: IEntityProxy): void;
-  /**
-   * Removes all entity references from the current entity.
-   * Optionally filter by target entity type.
-   * @param targetType - If provided, only removes references to entities of this type.
-   */
-  removeAll(targetType?: EntityTypeUid): void;
-  /**
-   * Retrieves a single reference of a specific entity type from the current entity.
-   * @param targetType - The entity type to find.
-   * @returns The first matching proxy, or null if not found.
-   */
-  get(targetType: EntityTypeUid): IEntityProxy | null;
-  /**
-   * Retrieves all references to entities of a specific type from the current entity.
-   * @param targetType - The entity type to find.
-   * @returns Array of matching proxies.
-   */
-  getMany(targetType: EntityTypeUid): Readonly<IEntityProxy[]>;
-  /**
-   * Retrieves all entity references from the current entity.
-   * Organized by target entity type.
-   * @returns Map of entity type to their proxies.
-   */
-  getAll(): ReadonlyMap<EntityTypeUid, Readonly<IEntityProxy[]>>;
-}
-//#endregion
-//#region src/systems/pipeline/system-context-repository.d.ts
-/**
- * System context API for entity repository operations.
- * Provides controlled access to entity storage for creating, updating, and removing entities.
- * All changes go through the repository to maintain system consistency.
- */
-interface ISystemContextRepository {
-  /**
-   * Queues a new entity for creation.
-   * The entity is created with the provided model and optional initial snapshot.
-   * @param entityType - The type of entity to create.
-   * @param model - The entity initialization data.
-   * @param snapshot - Optional initial state for the entity.
-   */
-  addEntity(entityType: EntityTypeUid, model: IEntityModel, snapshot?: IEntitySnapshot): void;
-  /**
-   * Retrieves an entity from storage.
-   * @template TEntity - The expected entity type.
-   * @param proxy - Reference to the entity.
-   * @returns The immutable entity instance.
-   */
-  getEntity<TEntity extends IEntity>(proxy: EntityProxy<TEntity> | EntityTypeUid): Immutable<TEntity>;
-  /**
-   * Queues an entity for update.
-   * Triggers the update pipeline for the entity.
-   * @param target - Optional specific entity to update. Defaults to current entity in context.
-   */
-  updateEntity(target?: IEntityProxy): void;
-  /**
-   * Removes an entity from storage.
-   * Triggers entity cleanup and removal from all systems.
-   * @param target - The entity to remove.
-   */
-  removeEntity(target: IEntityProxy): void;
-}
-//#endregion
-//#region src/systems/pipeline/system-context-scheduler.d.ts
-/**
- * System context API for scheduling and managing entity updates.
- * Allows middleware to request that an entity (or another) be updated again on the next or subsequent frame.
- * Supports both immediate (next frame) and interval-based scheduling.
- */
-interface ISystemContextScheduler {
-  /**
-   * Schedules an entity for update.
-   * If no target is specified, schedules the current entity.
-   * If no interval is specified, schedules on a default interval.
-   * @param target - Optional entity to schedule. Defaults to current entity in context.
-   * @param intervalMs - Optional update interval in milliseconds. Undefined uses default interval.
-   */
-  scheduleUpdate(target?: IEntityProxy, intervalMs?: number): void;
-  /**
-   * Cancels scheduled updates for an entity.
-   * If no target is specified, removes schedule for the current entity.
-   * @param target - Optional entity to unschedule. Defaults to current entity in context.
-   */
-  removeSchedule(target?: IEntityProxy): void;
-  /**
-   * Checks whether an entity has a scheduled update.
-   * If no target is specified, checks the current entity.
-   * @param target - Optional entity to check. Defaults to current entity in context.
-   */
-  hasSchedule(target?: IEntityProxy): boolean;
-}
-//#endregion
-//#region src/systems/pipeline/system-context-snapshot.d.ts
-/**
- * System context API for entity serialization and state transfer.
- * Handles conversion between entities and their serializable snapshots.
- * Used for state persistence, synchronization, and applying external updates.
- */
-interface ISystemContextSnapshot {
-  /**
-   * The JSON serializer instance used by this context.
-   * Handles serialization of complex types within snapshots.
-   */
-  readonly serializer: Immutable<IJsonSerializer>;
-  /**
-   * Applies serialized state to the current entity.
-   * Updates the entity's components based on the snapshot.
-   * @param snapshot - The state to apply.
-   */
-  applyToEntity(snapshot: IEntitySnapshot): void;
-  /**
-   * Creates a serialized snapshot of an entity.
-   * Captures the current state for transmission or storage.
-   * @param entity - The entity to snapshot. If omitted, snapshots current entity in context.
-   * @returns The serialized entity state.
-   */
-  createFromEntity(entity?: IEntity): IEntitySnapshot;
-  /**
-   * Queues a snapshot-based update for an entity.
-   * Applies the snapshot through the entity update system.
-   * @param snapshot - The state to apply.
-   * @param proxy - The entity to update.
-   */
-  dispatchToUpdate(snapshot: IEntitySnapshot, proxy: IEntityProxy): void;
-}
-//#endregion
-//#region src/systems/pipeline/system-context.d.ts
-/**
- * The execution context passed to system middleware.
- * Provides comprehensive access to entity state, scheduling, events, and repository operations.
- * Serves as the primary interface between middleware and the ECS framework.
- *
- * @template TEntity - The specific entity type this context operates on.
- */
-interface ISystemContext<TEntity extends IEntity> extends IPipelineContext {
-  /**
-   * Time elapsed since the last system update for this entity, in milliseconds.
-   * Useful for time-based calculations and animations.
-   */
-  readonly deltaTimeMs: Immutable<number>;
-  /**
-   * The entity currently being processed by this middleware.
-   */
-  readonly entity: Immutable<TEntity>;
-  /**
-   * Information about the update triggering this system execution.
-   * Contains type (update/remove) and optional model/snapshot data.
-   */
-  readonly update: Immutable<IEntityUpdate>;
-  /**
-   * Event system API for publishing and subscribing to entity events.
-   */
-  readonly events: Immutable<ISystemContextEvents>;
-  /**
-   * Proxy management API for establishing and managing entity relationships.
-   */
-  readonly proxies: Immutable<ISystemContextProxies>;
-  /**
-   * Repository access API for querying and modifying entity storage.
-   */
-  readonly repository: Immutable<ISystemContextRepository>;
-  /**
-   * Scheduling API for requesting follow-up entity updates.
-   */
-  readonly scheduler: Immutable<ISystemContextScheduler>;
-  /**
-   * Snapshot management API for serialization and state transfer.
-   */
-  readonly snapshot: Immutable<ISystemContextSnapshot>;
-  /**
-   * Logging interface for debug and diagnostic output.
-   */
-  readonly logger: Immutable<ILogger>;
-}
-//#endregion
-//#region src/systems/system-type.d.ts
-/**
- * The four phases of entity system execution in each frame.
- * Each phase serves a specific purpose in the entity lifecycle and can be extended by custom system types.
- * The runtime handles each phase in order, allowing systems to perform stage-specific operations.
- */
-declare enum SystemType {
-  /**
-   * Initial setup and resource allocation for the entity.
-   * Runs once when the entity is first created or initialized.
-   */
-  initialize = 0,
-  /**
-   * Main logic and state updates for the entity.
-   * Runs on every update to change entity behavior and properties.
-   */
-  update = 1,
-  /**
-   * Output and visualization operations.
-   * Runs after updates to render or display the entity state.
-   */
-  render = 2,
-  /**
-   * Synchronization and persistence.
-   * Runs last to synchronize state with external systems or storage.
-   */
-  sync = 3
-}
-//#endregion
-//#region src/systems/module/systems-module.d.ts
-/**
- * Collection of pipelines for a specific entity type.
- * Defines the complete system processing flow for one entity category.
- *
- * @template TEntity - The entity type this module processes.
- */
-interface ISystemsModule<TEntity extends IEntity> {
-  /**
-   * The pipelines for this entity type.
-   * Each pipeline contains middleware that operates on the entity.
-   */
-  readonly pipelines: ReadonlyMap<SystemType, Immutable<IPipeline<ISystemContext<TEntity>>>>;
-  /**
-   * Optional factory function to initialize new entity instances.
-   * If provided, is called when a new entity of this type is created.
-   * @param model - The initialization model.
-   * @returns The initialized entity.
-   */
-  readonly initEntity?: (model: IEntityModel) => TEntity;
-  /**
-   * If true, this entity type creates a new scope boundary when initialized.
-   * A new scope ID is auto-generated. All child entities inherit this scope.
-   * Typically used for root entities like Engine.
-   */
-  readonly scopeRoot?: boolean;
-  /**
-   * If true, this entity type registers itself as a scoped proxy when initialized.
-   * It joins the inherited scope and becomes resolvable via `context.proxies.get()`
-   * by any entity in the same scope. Throws if no scope exists.
-   * Typically used for scope-wide entities like Scene, Input, AssetsManager.
-   */
-  readonly scopedProxy?: boolean;
-}
-//#endregion
-//#region src/systems/pipeline/system-middleware.d.ts
-/**
- * A middleware unit that operates within the system pipeline.
- * System middleware receive comprehensive context about the entity being processed
- * and can influence entity state and behavior through various APIs.
- *
- * @template TEntity - The entity type this middleware handles.
- */
-type ISystemMiddleware<TEntity extends IEntity> = IMiddleware<ISystemContext<TEntity>>;
-//#endregion
-//#region src/systems/module/systems-module-builder.d.ts
-/**
- * Builder pattern interface for constructing system modules.
- * Allows incremental registration of systems and modules for an entity type.
- * Supports adding individual systems or entire pre-configured modules.
- *
- * @template TEntity - The entity type for which systems are being added.
- */
-interface ISystemsModuleBuilder<TEntity extends IEntity> {
-  /**
-   * The Module Builder's name.
-   */
-  readonly name: string;
-  /**
-   * The pipelines being built.
-   * Accessible during and after construction.
-   */
-  readonly pipelines: ReadonlyMap<SystemType, IPipeline<ISystemContext<TEntity>>>;
-  /**
-   * Whether this entity type is a scope root.
-   */
-  readonly scopeRoot: boolean;
-  /**
-   * Whether this entity type is a scoped proxy.
-   */
-  readonly scopedProxy: boolean;
-  /**
-   * Registers middleware systems for a specific pipeline stage.
-   * The middleware are added to the pipeline in the order provided.
-   * @param type - The pipeline stage (initialize, update, render, sync).
-   * @param systems - Array of middleware to add.
-   * @returns This builder for method chaining.
-   */
-  addSystems(type: SystemType, systems: Immutable<ISystemMiddleware<TEntity>[]>): this;
-  /**
-   * Integrates an entire module's pipelines into this builder.
-   * Allows composition of multiple modules into one.
-   * @template TModuleEntity - The module's entity type (must extend current type).
-   * @param module - The module to integrate.
-   * @param systemType - Optional specific pipeline to integrate from module. If omitted, integrates all.
-   * @returns This builder for method chaining.
-   */
-  addModule<TModuleEntity extends TEntity>(module: ISystemsModule<TModuleEntity>, systemType?: SystemType): this;
-  /**
-   * Marks this entity type as a scope root.
-   * When initialized, a new scope is auto-generated and all child entities inherit it.
-   * @returns This builder for method chaining.
-   */
-  setScopeRoot(): this;
-  /**
-   * Marks this entity type as a scoped proxy.
-   * When initialized, the entity registers itself in the inherited scope,
-   * making it resolvable via `context.proxies.get()` by any entity in the same scope.
-   * @returns This builder for method chaining.
-   */
-  setScopedProxy(): this;
-}
-//#endregion
-//#region src/systems/module/systems-module-repository.d.ts
-/**
- * Central registry for all systems modules in the ECS.
- * Maintains a module for each entity type, providing access to all system pipelines.
- * This is the authoritative source for system module data.
- *
- * @template TEntity - The entity types managed by modules in this repository.
- */
-interface ISystemsModuleRepository {
-  /**
-   * The total number of modules in the repository.
-   */
-  readonly size: number;
-  /**
-   * Retrieves the module for a specific entity type.
-   * @template TEntity - The entity type to retrieve module for.
-   * @param type - The entity type identifier.
-   * @returns The systems module for that entity type.
-   */
-  get<TEntity extends IEntity>(type: EntityTypeUid): ISystemsModule<TEntity>;
-  /**
-   * Registers or updates a module for an entity type.
-   * @param type - The entity type identifier.
-   * @param module - The systems module to register.
-   */
-  set(type: EntityTypeUid, module: ISystemsModule<IEntity>): void;
-  /**
-   * Retrieves all registered modules.
-   * @returns A read-only map of entity type to module.
-   */
-  list(): ReadonlyMap<EntityTypeUid, Immutable<ISystemsModule<IEntity>>>;
-}
-//#endregion
-//#region src/systems/pipeline/system-context-entity.d.ts
-/**
- * Manages the current entity and update being processed in the system context.
- * Provides internal state management for the system execution pipeline.
- * Typically used by runtime infrastructure rather than system middleware directly.
- */
-interface ISystemContextEntity {
-  /**
-   * The entity currently being processed.
-   */
-  readonly entity: Immutable<IEntity>;
-  /**
-   * The update that triggered processing of this entity.
-   */
-  readonly update: Immutable<IEntityUpdate>;
-  /**
-   * Updates the entity being processed.
-   * @param entity - The new entity for this context.
-   */
-  setEntity(entity: IEntity): void;
-  /**
-   * Updates the entity update being processed.
-   * @param update - The new update for this context.
-   */
-  setUpdate(update: IEntityUpdate): void;
-  /**
-   * Clears the current entity and update from the context and the IEntityRepository.
-   * @param deep - If true, also removes the entity from the IEntityRepository; otherwise, just clears the context reference.
-   */
-  clear(deep?: boolean): void;
-}
-//#endregion
-//#region src/systems/runtime/systems-runtime.d.ts
-/**
- * Executes system middleware for entities.
- * Processes entity updates by dispatching them through appropriate system modules.
- * Different implementations may use different execution strategies or optimizations.
- */
-interface ISystemsRuntime {
-  /**
-   * Processes a single entity update through its system pipeline.
-   * If no update is provided, may dequeue one from an internal queue.
-   * @param update - Optional specific update to process. If omitted, dequeues the next update.
-   * @returns Array of pipeline results containing execution metrics and data.
-   */
-  runTick(update?: IEntityUpdate): PerformanceTimeEntry[] | void;
-}
-//#endregion
-//#region src/systems/runtime/systems-runtime-context.d.ts
-/**
- * Runtime context for system pipeline execution.
- * Coordinates the execution of system pipelines across all entities.
- * Maintains state about the current entity being processed and enabled pipeline stages.
- *
- * @template TEntity - The entity type being processed.
- */
-interface ISystemsRuntimeContext<TEntity extends IEntity> extends IPipelineContext {
-  /**
-   * Indicates if the system pipeline should perform initialization for the current entity.
-   */
-  readonly shouldInitialize?: boolean;
-  /**
-   * The systems module for the current entity type.
-   */
-  readonly systemsModule: ISystemsModule<TEntity>;
-  /**
-   * The system context for the current entity execution.
-   */
-  readonly systemContext: ISystemContext<TEntity>;
-  /**
-   * The proxy repository for managing entity proxy relationships and scopes.
-   */
-  readonly proxyRepository: IEntityProxyRepository;
-}
-//#endregion
-//#region src/systems/runtime/systems-runtime-middleware.d.ts
-/**
- * Middleware for orchestrating system execution across entities.
- * Operates at the runtime level to coordinate system module pipelines.
- * Can influence which pipelines execute and in what order.
- *
- * @template TEntity - The entity type being processed.
- */
-type ISystemsRuntimeMiddleware<TEntity extends IEntity> = IMiddleware<ISystemsRuntimeContext<TEntity>>;
-//#endregion
-export { ISystemsModuleRepository as a, ISystemsModule as c, ISystemContextSnapshot as d, ISystemContextScheduler as f, ISystemContextEvents as h, ISystemContextEntity as i, SystemType as l, ISystemContextProxies as m, ISystemsRuntimeContext as n, ISystemsModuleBuilder as o, ISystemContextRepository as p, ISystemsRuntime as r, ISystemMiddleware as s, ISystemsRuntimeMiddleware as t, ISystemContext as u };
-//# sourceMappingURL=index-Df4VhCPr.d.cts.map