@awesome-ecs/abstract 0.20.2 → 0.21.1

package/dist/index-CKh4A7mH.d.cts

@@ -0,0 +1,460 @@
+import { EntityProxy, EntityTypeUid, IEntity, IEntityModel, IEntityProxy } from "./identity-component-BDWEtAXA.cjs";
+import { Immutable } from "./types-DvzdpbLu.cjs";
+import { EntityEventUid, IEntityEvent, IEntityRepository, IEntitySnapshot, IEntityUpdate, IEventData } from "./index-DLm-DKAk.cjs";
+import { IMiddleware, IPipeline, IPipelineContext, PipelineResult } from "./index-D81Fo9XN.cjs";
+import { IJsonSerializer, ILogger } from "./index-ChV4Q5j6.cjs";
+
+//#region src/systems/module/system-type.d.ts
+/**
+ * Enum representing the built-in System pipeline types.
+ * These types can be extended to introduce more types, and the System Runtime Pipeline should
+ * add Middleware to handle the newly added types.
+ */
+declare enum SystemType {
+  /**
+   * The initialization phase of the Module pipeline.
+   * This phase is typically used for setting up initial state and resources.
+   */
+  initialize = "initialize",
+  /**
+   * The update phase of the Module pipeline.
+   * This phase is responsible for updating the game logic and state of entities.
+   */
+  update = "update",
+  /**
+   * The render phase of the Module pipeline.
+   * This phase is used for rendering the game to the screen.
+   */
+  render = "render",
+  /**
+   * The synchronization phase of the Module pipeline.
+   * This phase is used for synchronizing game state with external systems or other components.
+   */
+  sync = "sync",
+}
+//#endregion
+//#region src/systems/pipeline/system-context-events.d.ts
+/**
+ * The ISystemContextEvents is the access point for Event related APIs.
+ * The access is made in a SystemMiddleware through the provided ISystemPipelineContext.
+ */
+interface ISystemContextEvents {
+  /**
+   * Dispatches and schedules the Event to its Subscribers or provided Entity Targets.
+   * @param data - The EventData to dispatch.
+   * @param targets - (optional) The Entities to send this event to. Providing this parameter will not broadcast this event.
+   */
+  dispatchEvent<TEventData extends IEventData>(data: TEventData, ...targets: IEntityProxy[]): void;
+  /**
+   * Dispatches and schedules the Events to their Subscribers or provided Entity Targets.
+   * @param data - The EventData Array to dispatch.
+   * @param targets - (optional) The Entities to send this event to. Providing this parameter will not broadcast this event.
+   */
+  dispatchEvents<TEventData extends IEventData>(data: TEventData[], ...targets: IEntityProxy[]): void;
+  /**
+   * Retrieves the Event with the given UID if it has been previously set on the current Context.
+   * @param uid - The Event UID to retrieve.
+   * @returns The Event with the given UID if it exists, otherwise undefined.
+   */
+  getEvent<TEventData extends IEventData>(uid: EntityEventUid): IEntityEvent<TEventData> | undefined;
+  /**
+   * Retrieves all the Events currently set on the Context.
+   * @returns An array of all the Events currently set on the Context.
+   */
+  listEvents<TEventData extends IEventData>(): IEntityEvent<TEventData>[];
+  /**
+   * Returns whether the Event with the given UID has previously been set on the current Context.
+   * @param uid - The Event UID to check for existence. If not provided, checks for any events in the context.
+   * @returns True if the Event with the given UID exists, otherwise false.
+   */
+  hasEvent(uid?: EntityEventUid): boolean;
+  /**
+   * Subscribes to Events with the given UID. When the matching Event is dispatched,
+   * the Entity update loop will set this Event on the Pipeline Context.
+   * @param uid - The Event UID to subscribe to.
+   * @param filter - (optional) Provides a callback function that will be executed on all matching Events.
+   * Can be used to filter what Event to schedule through to the current Entity update.
+   */
+  subscribeTo<TEventData extends IEventData>(uid: EntityEventUid, filter?: (event: IEntityEvent<TEventData>) => boolean): void;
+  /**
+   * Stops subscribing to Events with the given UID. The Entity will not receive any future Events with this UID.
+   * @param uid - The Event UID to stop listening to.
+   */
+  unsubscribeFrom(uid: EntityEventUid): void;
+  /**
+   * Adds the given Events into the Context instance.
+   * @param events - The Event instances to be set on the Context.
+   */
+  setContextEvents(events: IEntityEvent<IEventData>[]): void;
+  /**
+   * Adds the given Event into the Context instance.
+   * @param event - The Event instance to be set on the Context.
+   */
+  setContextEvent(event: IEntityEvent<IEventData>): void;
+  /**
+   * Removes all the Events currently set on the Context instance.
+   */
+  clearContextEvents(): void;
+  /**
+   * Removes all the Event Subscriptions for the current Entity.
+   */
+  clearSubscriptions(): void;
+}
+//#endregion
+//#region src/systems/pipeline/system-context-proxies.d.ts
+/**
+ * Provides a context-bound interface for managing proxy relationships for the current entity.
+ */
+interface ISystemContextProxies {
+  /**
+   * Registers a proxy for the current entity, establishing a bi-directional link.
+   * @param proxy The proxy to register for the current entity.
+   * @param cleanup If true, removes all existing proxies of the same type before adding the new one.
+   */
+  register(proxy: IEntityProxy, cleanup?: boolean): void;
+  /**
+   * Registers multiple proxies for the current entity.
+   * @param proxies The proxies to register.
+   * @param cleanup If true, removes existing proxies of the same types as the new ones before adding.
+   */
+  registerMany(proxies: readonly IEntityProxy[], cleanup?: boolean): void;
+  /**
+   * Removes a proxy from the current entity, breaking the bi-directional link.
+   * @param proxy The proxy to remove from the current entity.
+   */
+  remove(proxy: IEntityProxy): void;
+  /**
+   * Removes all proxies for the current entity, optionally filtered by a target entity type.
+   * @param targetType The optional entity type to remove. If not provided, all proxies are removed.
+   */
+  removeAll(targetType?: EntityTypeUid): void;
+  /**
+   * Gets a single proxy for the current entity by its target type.
+   * If multiple proxies of the same type exist, the first one found is returned.
+   * @param targetType The entity type of the proxy to retrieve.
+   * @returns The entity proxy, or null if not found.
+   */
+  get(targetType: EntityTypeUid): IEntityProxy | null;
+  /**
+   * Gets all proxies for the current entity that match a given target type.
+   * @param targetType The entity type of the proxies to retrieve.
+   * @returns A readonly array of entity proxies.
+   */
+  getMany(targetType: EntityTypeUid): Readonly<IEntityProxy[]>;
+  /**
+   * Gets all proxies associated with the current entity.
+   * @returns A readonly map of entity type UIDs to an array of their proxies.
+   */
+  getAll(): ReadonlyMap<EntityTypeUid, Readonly<IEntityProxy[]>>;
+}
+//#endregion
+//#region src/systems/pipeline/system-context-repository.d.ts
+/**
+ * The `ISystemContextRepository` is the access point for the `IEntityRepository` related APIs.
+ *
+ * The access is made in an `ISystemMiddleware` through the provided `ISystemPipelineContext`.
+ */
+interface ISystemContextRepository {
+  /**
+   * Schedule adding a new entity to the repository.
+   *
+   * @param entityType - The type of the entity.
+   * @param model - The model of the entity.
+   * @param snapshot - Optional initial snapshot of the entity.
+   */
+  addEntity(entityType: EntityTypeUid, model: IEntityModel, snapshot?: IEntitySnapshot): void;
+  /**
+   * Retrieves an entity from the repository.
+   *
+   * @template TEntity - The type of the entity.
+   * @param proxy - The proxy of the entity.
+   * @returns An immutable representation of the entity.
+   */
+  getEntity<TEntity extends IEntity>(proxy: EntityProxy<TEntity>): Immutable<TEntity>;
+  /**
+   * Schedule updating an entity in the repository.
+   *
+   * @param target - Optional target entity proxy. If not provided, updates the current entity set on the system context.
+   */
+  updateEntity(target?: IEntityProxy): void;
+  /**
+   * Removes an entity from the repository.
+   *
+   * @param target - The entity proxy to be removed.
+   */
+  removeEntity(target: IEntityProxy): void;
+}
+//#endregion
+//#region src/systems/pipeline/system-context-scheduler.d.ts
+/**
+ * The `ISystemContextScheduler` interface represents the access point for Scheduler related APIs.
+ * The access is made in a `SystemMiddleware` through the provided `ISystemPipelineContext`.
+ */
+interface ISystemContextScheduler {
+  /**
+   * Schedules an update for the specified `target` entity proxy at a given `intervalMs`.
+   * If no `target` is provided, update will be scheduled for the current entity set on the system context.
+   * If no `intervalMs` is provided, the default update interval will be used.
+   *
+   * @param target - The entity proxy for which the update is scheduled.
+   * @param intervalMs - The interval in milliseconds at which the update should be triggered.
+   */
+  scheduleUpdate(target?: IEntityProxy, intervalMs?: number): void;
+  /**
+   * Removes the scheduled update for the specified `target` entity proxy.
+   * If no `target` is provided, schedule is removed for the current entity set on the system context.
+   *
+   * @param target - The entity proxy for which the scheduled update should be removed.
+   */
+  removeSchedule(target?: IEntityProxy): void;
+}
+//#endregion
+//#region src/systems/pipeline/system-context-snapshot.d.ts
+/**
+ * The ISystemContextSnapshot is the access point for Snapshot related APIs.
+ * The access is made in a SystemMiddleware through the provided ISystemPipelineContext.
+ */
+interface ISystemContextSnapshot {
+  /**
+   * A read-only reference to the JSON serializer used for snapshot serialization.
+   */
+  readonly serializer: Immutable<IJsonSerializer>;
+  /**
+   * Applies the provided entity snapshot to the current entity set on the system context.
+   *
+   * @param snapshot - The entity snapshot to apply.
+   */
+  applyToEntity(snapshot: IEntitySnapshot): void;
+  /**
+   * Creates a new entity snapshot from the provided entity.
+   *
+   * @param entity - The entity to create a snapshot from. If not provided, a snapshot for the current entity set on the system context will be created.
+   * @returns A new entity snapshot.
+   */
+  createFromEntity(entity?: IEntity): IEntitySnapshot;
+  /**
+   * Dispatches an update to the entity using the provided snapshot and entity proxy.
+   *
+   * @param snapshot - The entity snapshot to use for the update.
+   * @param proxy - The entity proxy to use for the update.
+   */
+  dispatchToUpdate(snapshot: IEntitySnapshot, proxy: IEntityProxy): void;
+}
+//#endregion
+//#region src/systems/pipeline/system-context.d.ts
+/**
+ * The ISystemContext is the Context passed to a SystemMiddleware as part of the Pipeline Dispatch.
+ * It's an abstraction layer so that the Middleware code won't have explicit dependencies on other parts of the ECS.
+ *
+ * Any State changes done by the SystemMiddleware are executed using the APIs provided by the ISystemContext.
+ *
+ * @template TEntity - The type of entity that the SystemMiddleware operates on.
+ * @extends IPipelineContext - The ISystemContext extends the IPipelineContext interface.
+ */
+interface ISystemContext<TEntity extends IEntity> extends IPipelineContext {
+  /**
+   * The time in milliseconds since the last entity update.
+   */
+  readonly deltaTimeMs: Immutable<number>;
+  /**
+   * The entity that the SystemMiddleware is operating on.
+   */
+  readonly entity: Immutable<TEntity>;
+  /**
+   * The update object containing information about the entity's changes.
+   */
+  readonly update: Immutable<IEntityUpdate>;
+  /**
+   * The events API for the SystemMiddleware to interact with the ECS events system.
+   */
+  readonly events: Immutable<ISystemContextEvents>;
+  /**
+   * The proxies API for the SystemMiddleware to interact with the ECS proxies system.
+   */
+  readonly proxies: Immutable<ISystemContextProxies>;
+  /**
+   * The repository API for the SystemMiddleware to interact with the ECS repository system.
+   */
+  readonly repository: Immutable<ISystemContextRepository>;
+  /**
+   * The scheduler API for the SystemMiddleware to interact with the ECS scheduler system.
+   */
+  readonly scheduler: Immutable<ISystemContextScheduler>;
+  /**
+   * The snapshot API for the SystemMiddleware to interact with the ECS snapshot system.
+   */
+  readonly snapshot: Immutable<ISystemContextSnapshot>;
+  /**
+   * The logger API for the SystemMiddleware to log messages.
+   */
+  readonly logger: Immutable<ILogger>;
+}
+//#endregion
+//#region src/systems/pipeline/system-context-entity.d.ts
+/**
+ * Interface representing a system context entity.
+ * This interface provides methods to manipulate and access entity and update data.
+ */
+interface ISystemContextEntity {
+  /**
+   * The immutable entity associated with the system context.
+   */
+  readonly entity: Immutable<IEntity>;
+  /**
+   * The immutable entity update associated with the system context.
+   */
+  readonly update: Immutable<IEntityUpdate>;
+  /**
+   * Sets the entity associated with the system context entity.
+   *
+   * @param entity - The new entity to be associated with the system context.
+   */
+  setEntity(entity: IEntity): void;
+  /**
+   * Sets the entity update associated with the system context.
+   *
+   * @param update - The new entity update to be associated with the system context.
+   */
+  setUpdate(update: IEntityUpdate): void;
+}
+//#endregion
+//#region src/systems/runtime/systems-runtime-context.d.ts
+/**
+ * The ISystemsRuntimeContext is the Context passed by a SystemsRuntimePipeline.
+ * It helps orchestrate the execution of SystemPipelines registered in the SystemsModule.
+ */
+interface ISystemsRuntimeContext<TEntity extends IEntity> extends IPipelineContext {
+  /**
+   * A Set of allowed steps for the SystemPipelines.
+   */
+  readonly allowedSteps: Set<SystemType>;
+  /**
+   * An entity provider for the SystemPipelines.
+   */
+  readonly entityProvider: ISystemContextEntity;
+  /**
+   * An entity repository for the SystemPipelines.
+   */
+  readonly entityRepository: IEntityRepository;
+  /**
+   * A Map of SystemPipelines registered in the SystemsModule.
+   */
+  readonly systemPipelines: Map<SystemType, IPipeline<ISystemContext<TEntity>>>;
+  /**
+   * The SystemContext for the SystemPipelines.
+   */
+  readonly systemContext: ISystemContext<TEntity>;
+}
+//#endregion
+//#region src/systems/runtime/systems-runtime-middleware.d.ts
+/**
+ * The `ISystemsRuntimeMiddleware` represents the building blocks of executing SystemsModule's registered Pipelines.
+ * It receives the current State in the Context, and can decide which SystemPipelines to execute.
+ *
+ * @typeParam TEntity - The type of entity that the middleware operates on.
+ * @extends {IMiddleware<ISystemsRuntimeContext<TEntity>>} - Extends the base `IMiddleware` interface, which is used for defining middleware functions.
+ */
+type ISystemsRuntimeMiddleware<TEntity extends IEntity> = IMiddleware<ISystemsRuntimeContext<TEntity>>;
+//#endregion
+//#region src/systems/pipeline/system-middleware.d.ts
+/**
+ * The `ISystemMiddleware` is a basic System implementation that can be registered as a Middleware in a SystemPipeline.
+ * It provides a `SystemPipelineContext` to its exposed methods.
+ *
+ * @template TEntity - The type of entity that this middleware operates on.
+ * @extends {IMiddleware<ISystemContext<TEntity>>} - Extends the base `IMiddleware` interface, which requires a `SystemPipelineContext` to be provided.
+ */
+type ISystemMiddleware<TEntity extends IEntity> = IMiddleware<ISystemContext<TEntity>>;
+//#endregion
+//#region src/systems/module/systems-module-definition.d.ts
+/**
+ * The SystemModuleDefinition is the main way of composing SystemsModules for an Entity.
+ * It can be used as building blocks for SystemsModules as a way to register common SystemMiddlewares and share across different Entities.
+ */
+interface ISystemsModuleDefinition<TEntity extends IEntity> {
+  readonly systems: Map<SystemType, IPipeline<ISystemContext<TEntity>>>;
+  /**
+   * Registers SystemMiddlewares to the specified SystemPipelineType.
+   *
+   * @param type - The SystemPipelineType to append the provided SystemMiddlewares to.
+   * @param systems - The SystemMiddlewares to be registered in the provided SystemPipelineType in the same order as the provided array.
+   * The SystemMiddlewares will be appended to existing Pipelines to allow easy extension of existing behaviors.
+   */
+  registerSystems?(type: SystemType, systems: Immutable<ISystemMiddleware<TEntity>[]>): void;
+  /**
+   * Registers the middleware of the provided SystemsModule in the current SystemsModule. Keeps the same system types.
+   * @param module - The SystemsModule to be registered.
+   */
+  registerModule?(module: Immutable<ISystemsModuleDefinition<TEntity>>): void;
+}
+//#endregion
+//#region src/systems/module/systems-module.d.ts
+/**
+ * The SystemModule is the main way of registering and triggering the SystemMiddlewares registered for an Entity.
+ * It can handle EntityUpdate objects and decides which SystemPipelines to trigger based on the information in the EntityUpdate.
+ */
+interface ISystemsModule<TEntity extends IEntity> extends ISystemsModuleDefinition<TEntity> {
+  /**
+   * Triggers all registered SystemPipelines to apply the changes from the provided EntityUpdate to an Entity instance.
+   *
+   * @param update - The EntityUpdate containing the desired changes to be applied on an Entity instance.
+   * @returns An optional PipelineResult indicating the success or failure of the triggered SystemPipelines.
+   */
+  triggerSystems(update: Immutable<IEntityUpdate>): void | PipelineResult;
+}
+//#endregion
+//#region src/systems/module/systems-module-repository.d.ts
+/**
+ * Interface for managing systems modules.
+ *
+ * @template TEntity - The type of entity that the systems module operates on.
+ */
+interface ISystemsModuleRepository {
+  /**
+   * The number of systems modules in the repository.
+   */
+  readonly size: number;
+  /**
+   * Retrieves a systems module for a specific entity type.
+   *
+   * @param type - The unique identifier of the entity type.
+   * @returns The systems module for the specified entity type.
+   */
+  get<TEntity extends IEntity>(type: EntityTypeUid): ISystemsModule<TEntity>;
+  /**
+   * Adds or updates a systems module for a specific entity type.
+   *
+   * @param type - The unique identifier of the entity type.
+   * @param module - The systems module to add or update.
+   */
+  set(type: EntityTypeUid, module: ISystemsModule<IEntity>): void;
+  /**
+   * Retrieves a read-only map of all systems modules in the repository.
+   *
+   * @returns A read-only map of entity type unique identifiers to systems modules.
+   */
+  list(): ReadonlyMap<EntityTypeUid, Immutable<ISystemsModule<IEntity>>>;
+}
+//#endregion
+//#region src/systems/runtime/systems-runtime.d.ts
+/**
+ * The System Runtime allows running a loop of Ticks.
+ *
+ * Each `runTick` method can process one or more Entity Updates.
+ *
+ * We can have multiple implementations of a `SystemsRuntime`, based on the use-case.
+ * A different implementation can be chosen at runtime, based for example on performance.
+ */
+interface ISystemsRuntime {
+  /**
+   * The method should trigger the SystemsModule logic for the provided `IEntityUpdate`.
+   * If no EntityUpdate is given, the `SystemRuntime` implementation can choose to dequeue one from the `IEntityUpdateQueue`.
+   *
+   * @param update - An optional `IEntityUpdate` to process. If not provided, the method will dequeue one from the `IEntityUpdateQueue`.
+   * @returns A `PipelineResult` representing the outcome of the SystemsModule logic execution.
+   */
+  runTick(update?: IEntityUpdate): PipelineResult;
+}
+//#endregion
+export { ISystemContext, ISystemContextEntity, ISystemContextEvents, ISystemContextProxies, ISystemContextRepository, ISystemContextScheduler, ISystemContextSnapshot, ISystemMiddleware, ISystemsModule, ISystemsModuleDefinition, ISystemsModuleRepository, ISystemsRuntime, ISystemsRuntimeContext, ISystemsRuntimeMiddleware, SystemType };
+//# sourceMappingURL=index-CKh4A7mH.d.cts.map

package/dist/index-ChV4Q5j6.d.cts

@@ -0,0 +1,137 @@
+//#region src/utils/json-serializer.d.ts
+/**
+ * A custom `IJsonSerializer` interface allows for different ways of serializing and parsing objects.
+ */
+interface IJsonSerializer {
+  /**
+   * Serializes the given object into a JSON string.
+   *
+   * @param value The object to be serialized.
+   * @returns A JSON string representation of the object.
+   */
+  serializeCustom(value: object): string;
+  /**
+   * Parses a JSON string into the specified object type.
+   *
+   * @template TObject The type of the object to be parsed.
+   * @param text The JSON string to be parsed.
+   * @returns The parsed object of type `TObject`.
+   */
+  parseCustom<TObject>(text: string): TObject;
+}
+//#endregion
+//#region src/utils/logger.d.ts
+/**
+ * An ILogger instance allows printing messages to console or other targets.
+ */
+interface ILogger {
+  /**
+   * Logs a message with a specified level.
+   * @param level The level of the message.
+   * @param message The message to be logged.
+   * @param ...args Additional arguments to be included in the message.
+   */
+  log(level: LogLevel, message: any, ...args: any[]): void;
+  /**
+   * Logs a trace-level message.
+   * @param message The message to be logged.
+   * @param ...args Additional arguments to be included in the message.
+   */
+  trace(message: any, ...args: any[]): void;
+  /**
+   * Logs a debug-level message.
+   * @param message The message to be logged.
+   * @param ...args Additional arguments to be included in the message.
+   */
+  debug(message: any, ...args: any[]): void;
+  /**
+   * Logs a warning-level message.
+   * @param message The message to be logged.
+   * @param ...args Additional arguments to be included in the message.
+   */
+  warn(message: any, ...args: any[]): void;
+  /**
+   * Logs an error-level message.
+   * @param message The message to be logged.
+   * @param ...args Additional arguments to be included in the message.
+   */
+  error(message: any, ...args: any[]): void;
+}
+/**
+ * An enumeration of log levels.
+ */
+declare enum LogLevel {
+  /**
+   * Trace-level logging.
+   */
+  trace = 0,
+  /**
+   * Debug-level logging.
+   */
+  debug = 1,
+  /**
+   * Warning-level logging.
+   */
+  warn = 2,
+  /**
+   * Error-level logging.
+   */
+  error = 3,
+}
+/**
+ * Options for configuring an ILogger instance.
+ */
+interface ILoggerOptions {
+  /**
+   * A map of log levels to their corresponding enabled status.
+   */
+  enabled: Map<LogLevel, boolean>;
+}
+//#endregion
+//#region src/utils/performance-timer.d.ts
+/**
+ * A unique identifier for a timer.
+ */
+type PerformanceTimerUid = number;
+/**
+ * A record of a timer's execution.
+ *
+ * @remarks
+ * This interface represents the details of a timer's execution.
+ * It includes the timer's name, start timestamp, end timestamp, and the duration of the timer's execution in milliseconds.
+ *
+ * @property {string} name - The name of the timer.
+ * @property {number} startedAt - The timestamp when the timer started.
+ * @property {number} [endedAt] - The timestamp when the timer ended.
+ * @property {number} [msPassed] - The time in milliseconds that the timer was active.
+ */
+interface PerformanceTimeEntry {
+  name: string;
+  startedAt: number;
+  endedAt?: number;
+  msPassed?: number;
+}
+/**
+ * An interface for a performance timer.
+ * This interface provides methods to start and end timers,
+ * and retrieve information about their execution.
+ */
+interface IPerformanceTimer {
+  /**
+   * Starts a new timer with the given name.
+   * @param {string} name - The name of the timer.
+   * @returns {PerformanceTimerUid} - A unique identifier for the newly started timer.
+   */
+  startTimer(name: string): PerformanceTimerUid;
+  /**
+   * Ends the timer with the given timerUid and returns a record of its execution.
+   * @param {PerformanceTimerUid} timerUid - The unique identifier of the timer to end.
+   * @returns {PerformanceTimeEntry} - A record of the timer's execution.
+   * The returned object contains the timer's name, start timestamp, end timestamp,
+   * and the duration of the timer's execution in milliseconds.
+   */
+  endTimer(timerUid: PerformanceTimerUid): PerformanceTimeEntry;
+}
+//#endregion
+export { IJsonSerializer, ILogger, ILoggerOptions, IPerformanceTimer, LogLevel, PerformanceTimeEntry, PerformanceTimerUid };
+//# sourceMappingURL=index-ChV4Q5j6.d.cts.map