@awesome-ecs/abstract 0.22.0 → 0.24.0

package/README.md

@@ -1,228 +1,126 @@
-# Awesome ECS (Entity-Component-System)
-
-## What is it?
-
-The Entity-Component-System is a well-known Architecture type used for responsive, complex applications, not only restricted to the Web.
-It's mostly associated with Game Engines, because of it's way of segregating Behavior from State, and allowing fine-control of the Runtime.
-
-## Real-World Usage Patterns
-
-Based on the analysis of real-world usage in project-anchor, here are the key patterns that have proven effective:
-
-### Component Patterns
-
-- **Component Type Enumeration**: Components are identified using a `ComponentType` enum, making component retrieval and identification type-safe and consistent
-- **Specialized Component Focus**: Components focus on specific concerns (e.g., `CoordinatesComponent`, `RenderingComponent`, `AssetsComponent`)
-- **Component Serialization**: Components can be marked with `isSerializable` to control which components get synchronized with external systems
-- **Component Factories**: Using factory patterns to create and configure components with standard defaults
-
-### Entity Patterns
-
-- **Type-Safe Entity Access**: Entities expose strongly-typed getters for their components
-- **Entity Proxies**: Entities use proxy objects to reference other entities, maintaining relationships while avoiding direct dependencies
-- **Entity Type Enumeration**: Entities are categorized using an `EntityType` enum
-- **Entity Hierarchy**: Entities often form hierarchical relationships (e.g., scene → grid → tile)
-
-### System Organization
-
-- **System Pipelines**: Systems are organized into distinct pipelines (initialize, update, render) that execute in sequence
-- **System Modules**: Systems are grouped in modules that target specific entity types
-- **Middleware Approach**: Systems implement the middleware pattern for clean, composable behavior
-
-## Building blocks
-
-### Entities
-
-Entities are really just collections of Components. 
-
-In this Awesome ECS Architecture implementation, an Entity is built of:
-
-- one or more Components
-- proxies to other Entities
-
-Entity changes can triggered from outside systems (e.g. UI events, data from backend, a Redux Store change), or on ran a Schedule (e.g. Engine Loop).
-
-### Components
-
-Components are data-holders. They are instantiated for each Entity, and hold the state for the Entity.
-An Entity can have many different types of Components, based on what the Entity State is.
-
-Components should not contain any behavior, only keep data (e.g. Plain-Objects).
-
-### Systems
-
-Systems are behaviors of the ECS Architecture. They receive an Entity as input, and run Behaviors, altering the data contained in the Entity's Components.
-Systems are usually Entity-specific, but they can be shared (e.g. Two Entities having the same Component Type, can in fact, share a System's Behavior).
-
-## Awesome ECS Architecture
-
-### Pipeline
-
-The Pipelines are at the heart of the Easy ECS Architecture implementation, and it's a way of declaring which Systems are run as part of the Runtime Loop.
-
-### Middleware
-
-The Middleware is the Unit-of-Work implementation of a System, and allows for a System to achieve Single-Responsibility (part of SOLID principles.).
-
-A Middleware has 3 methods:
- - `shouldRun: boolean` -> specifies whether the current System should run it's `action` method, to introduce State changes on the Entity's Components
- - `action: void` -> the System implementation that allows for altering Entity Component state, can use Entity Proxies, or Schedule updates for itself or other Entities
- - `cleanup: void` -> the System implementation method that gets called when the Entity Model Change Type is Removed. It handles the disposal of any internal objects the System might have instantiated
-
-Each Middleware method will receive a `context: SystemPipelineContext<TEntity>`, which contains the current Entity state, as well as the Entity Model Change, and any Entity changes Scheduled for Dispatch at the end of the current Tick
-
-## Entity Changes
-
-Each Entity has a mandatory Identity Component. This Identity Component will hold the current Entity Model, and it's Entity Unique Identifier.
-Model changes will prompt an Entity to introduce itself on a Entity Change Queue, to be processed on the next Tick by the Runtime. 
-
-### The Runtime
-
-The Awesome ECS Architecture implementation Runtime is structured in Loops of Ticks.
-
-Each Tick has an allocated time for running, and will process Entity Changes during that Tick.
-If there is more time left in the current Loop, and the Entity Change Queue is not empty, the next Entity Change in the Entity Change Queue, will be processed.
-
-### The Ticks
-
-Each Tick will receive as an input an Entity Model Change, which will contain: the Current Model, the Previous Model (if available), and the Change Type (Added, Updated or Removed).
-
-Based on the Change Type and Model, the Entity Identifier is being searched.
-Based on the found Entity Identifier and Change Type, The Runtime instantiates the System Pipeline associated with that change.
-
-## Runtime Stages
-
-The Runtime has a few Stages, that will run in this order:
-
-- Initializer Systems
-- Updater Systems
-- Renderer Systems
-- (Dispatcher) Systems
-
-Each Stage is a System Pipeline, which will run it's associated System Middlewares, in the order they were registered in.
-
-### Generator Systems
-
-The Generator Systems will be ran once per Entity, when the Model Change Type is Added.
-All the Middlewares registered for this stage will contribute to enrich the Entity Components with bootstrap data.
-
-### Updater Systems
-
-The Updater Systems will be ran on each Model Change, and it's the main way of altering the Entity's Components state.
-
-### Render Systems
-
-The Render Systems will make sure to update the underlying Render system with the Entity's `RenderingComponent` state. It's useful as an abstraction layer to lower-lever Rendering (e.g. a Game Engine, WebGL, Canvas)
-
-The Render Systems can be skipped from the Runtime, if needed. That can be useful to simulate the same Runtime in a non-rendered system, like the Backend.
-
-### (Dispatch) Systems
-
-The Dispatch Systems are built-in Systems in the Awesome ECS, and will take care of Dispatching Actions, Scheduling Entity updates, or synchronizing the Entity Repository with the latest Entity State in the current Context.
-
-The Dispatch Systems, as well as any other Runtime Stage, can be extended as needed by registering more System Middlewares in the Stage Pipeline.
-
-## Integration Examples
-
-### Component Definition Example
-
-```typescript
-import { IComponent } from "@awesome-ecs/abstract";
-import { ComponentType } from "../abstract/components/component-type";
-
-export class CoordinatesComponent implements IComponent {
-  readonly componentType = ComponentType.coordinates;
-  readonly isSerializable = false;
-
-  // Component state
-  private coordinates: GridCoordinates;
-
-  // Component methods
-  setTileRadius(value: SpaceMeasurement) {
-    this.coordinates = new GridCoordinates(value);
-  }
-  
-  getCenterPointFor(position: GridPosition): GridPoint {
-    return this.coordinates.getCenterPointFor(position);
-  }
-}
-```
-
-### Entity Definition Example
-
-```typescript
-import { EntityBase } from "@awesome-ecs/core";
-import { EntityProxy, EntityUid, IEntityModel, IEntityProxy } from "@awesome-ecs/abstract";
-import { ComponentType } from "../abstract/components/component-type";
-import { EntityType } from "../abstract/entities/entity-type";
-
-export class GridEntity extends EntityBase<GridModel> {
-  // Entity proxies for relationships
-  get sceneProxy(): EntityProxy<SceneEntity> {
-    return this.getProxy(EntityType.scene);
-  }
-
-  get buildingProxies(): IterableIterator<EntityProxy<BuildingEntity>> {
-    return this.getProxies(EntityType.building);
-  }
-
-  // Component accessors
-  get coordinates(): CoordinatesComponent {
-    return this.getComponent(ComponentType.coordinates);
-  }
-
-  get rendering(): RenderingComponent<GridRenderingContext> {
-    return this.getComponent(ComponentType.rendering);
-  }
-}
-```
-
-### System Module Example
-
-```typescript
-import { SystemPipelineType } from "@awesome-ecs/abstract";
-import { LocalSystemsModuleBase } from "../abstract/systems/system-module-base";
-
-export class GridSystemsModule extends LocalSystemsModuleBase<GridEntity> {
-  constructor(
-    // Systems injected via dependency injection
-    gridContainerInitializerSystem: GridContainerInitializerSystem,
-    gridCoordinatesInitializerSystem: GridCoordinatesInitializerSystem,
-    gridPerimeterRenderingSystem: GridPerimeterRenderingSystem
-  ) {
-    super();
-
-    // Register systems for different pipeline stages
-    this.registerSystems(SystemPipelineType.initialize, [
-      gridContainerInitializerSystem,
-      gridCoordinatesInitializerSystem
-    ]);
-
-    this.registerSystems(SystemPipelineType.render, [
-      gridPerimeterRenderingSystem
-    ]);
-  }
-
-  // Entity factory method
-  protected initEntity(model: GridModel): GridEntity {
-    // Create and return entity instance
-    const entity = new GridEntity(
-      ComponentFactory.identity(EntityType.grid, model),
-      [
-        ComponentFactory.coordinates(),
-        ComponentFactory.rendering()
-      ],
-      [
-        // Entity relationships via proxies
-        model.parent,
-        {
-          entityType: EntityType.scene,
-          entityUid: IdGenerator.sceneUid(),
-        }
-      ]
-    );
-
-    return entity;
-  }
-}
-```
+# Awesome ECS - Abstract Package
+
+## Overview
+
+The Abstract package defines all core interfaces and abstractions for the Entity-Component-System (ECS) framework. It provides the foundational contracts that all other packages implement, including:
+
+- **Components**: Data-storage contracts
+- **Entities**: Container contracts for components and relationships
+- **Pipelines**: Middleware-based execution chains
+- **Systems**: Modular logic execution patterns
+- **Utilities**: Serialization, events, and scheduling
+
+This package has **zero external dependencies** and serves as the contract layer for the entire ECS framework.
+
+## Core Concepts
+
+### Components (`src/components/`)
+
+Components are **data-only containers**. They should never contain business logic.
+
+```typescript
+import { IComponent } from "@awesome-ecs/abstract";
+
+export class HealthComponent implements IComponent {
+  readonly componentType = ComponentType.health;
+  readonly isSerializable = true;  // Include in snapshots
+  
+  current: number = 100;
+  max: number = 100;
+}
+```
+
+**Key interfaces:**
+- `IComponent`: Base component interface with `componentType` and `isSerializable`
+- `IdentityComponent`: Mandatory component tracking entity UID and model
+
+### Entities (`src/entities/`)
+
+Entities are immutable **containers of components** and **proxies to other entities**. They never directly reference other entities—they use proxies for loose coupling.
+
+```typescript
+export class GridEntity extends EntityBase<GridModel> {
+  // Strongly-typed component getters
+  get coordinates(): CoordinatesComponent {
+    return this.getComponent(ComponentType.coordinates);
+  }
+
+  // Entity proxies for relationships (not direct references)
+  get sceneProxy(): EntityProxy<SceneEntity> {
+    return this.getProxy(EntityType.scene);
+  }
+}
+```
+
+**Key files:**
+- `entity.ts`: Base `IEntity` interface and `EntityTypeUid` types
+- `entity-proxies.ts`: `EntityProxy` for loose-coupling relationships
+- `entity-snapshot.ts`: `IEntitySnapshot` for serialization
+- `entity-queue.ts`: `IEntityUpdate` and `IEntityUpdateQueue` for batching changes
+- `entity-repository.ts`: `IEntityRepository` for entity lookups
+- `entity-scheduler.ts`: `IEntityScheduler` for deferred updates
+- `entity-events.ts`: `IEntityEvents` for reactive patterns
+
+### Pipelines (`src/pipelines/`)
+
+Pipelines execute **middleware chains** with two phases:
+
+1. **dispatch(context)**: Main execution phase
+2. **cleanup(context)**: Resource cleanup phase
+
+```typescript
+export interface IPipeline<TContext extends IPipelineContext> {
+  use(middleware: IMiddleware<TContext>): this;
+  dispatch(context: Partial<TContext>): PipelineResult;
+  cleanup(context: Partial<TContext>): PipelineResult;
+}
+```
+
+**Key files:**
+- `pipeline.ts`: Core `IPipeline` interface
+- `middleware.ts`: `IMiddleware` contract (action + optional cleanup)
+- `middleware-runner.ts`: Middleware execution engine
+- `pipeline-context.ts`: Context passed to middleware
+- `pipeline-runner.ts`: Pipeline execution orchestration
+- `pipeline-result.ts`: Result type for success/failure
+
+### Systems (`src/systems/`)
+
+Systems are **modular logic units** that operate on entities. They implement the middleware pattern.
+
+**Pipeline-based systems:**
+- `system-middleware.ts`: `ISystemMiddleware<TEntity>` - middleware for a specific entity type
+- `system-context.ts`: Context passed to system middleware (entity, events, repository, etc.)
+
+**Module-based organization:**
+- `systems-module.ts`: `ISystemsModule<TEntity>` - groups related systems targeting an entity type
+- `systems-module-definition.ts`: Module definition and pipeline registration
+- `systems-module-repository.ts`: Module lifecycle and registration
+
+**Runtime execution:**
+- `systems-runtime.ts`: `ISystemsRuntime` - core tick-based execution loop
+- `systems-runtime-context.ts`: Context for runtime execution
+- `systems-runtime-middleware.ts`: Middleware for runtime operations
+
+### Utilities (`src/utils/`)
+
+- `types.ts`: Common types (`Immutable`, `BooleanProps`, `Readonly`)
+- `json-serializer.ts`: JSON serialization contracts
+- `logger.ts`: Logging interface
+- `performance-timer.ts`: Performance measurement
+
+## Key Design Principles
+
+1. **Components are data-only** - no behavior, just properties
+2. **Entities are immutable** - modifications through systems only
+3. **Relationships use proxies** - loose coupling between entities
+4. **Systems are middleware** - pluggable into pipelines
+5. **Pipelines are composable** - middleware chains with dispatch + cleanup
+
+## What's NOT in Abstract
+
+- Concrete entity implementations (→ @awesome-ecs/core)
+- System module base classes (→ @awesome-ecs/core)
+- Component factories (→ @awesome-ecs/core)
+- Multi-threading (→ @awesome-ecs/workers)
+- AI patterns (→ @awesome-ecs/ai)

package/dist/components/index.cjs

@@ -3,9 +3,9 @@
 /**
 * The `BasicComponentType` enum defines the types of basic components available.
 */
-let BasicComponentType = /* @__PURE__ */ function(BasicComponentType$1) {
-	BasicComponentType$1["identity"] = "identity";
-	return BasicComponentType$1;
+let BasicComponentType = /* @__PURE__ */ function(BasicComponentType) {
+	BasicComponentType["identity"] = "identity";
+	return BasicComponentType;
 }({});
 
 //#endregion

package/dist/components/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":[],"sources":["../../src/components/identity-component.ts"],"sourcesContent":["import { EntityTypeUid, IEntityModel } from '../entities/entity';\nimport { Immutable } from '../utils/types';\nimport { IComponent } from './component';\n\n/**\n * The `BasicComponentType` enum defines the types of basic components available.\n */\nexport enum BasicComponentType {\n  identity = 'identity'\n}\n\n/**\n * IdentityComponent interface represents the basic information regarding what makes the current Entity unique.\n * It extends the IComponent interface.\n *\n * @template TModel - The type of the model that extends IEntityModel.\n */\nexport interface IdentityComponent<TModel extends IEntityModel> extends IComponent {\n  /**\n   * The Entity Type that defines what Category type the Entity is part of.\n   * There can be multiple Entities sharing the same EntityType.\n   */\n  readonly entityType: EntityTypeUid;\n\n  /**\n   * The Model is the basic information needed to create an `IEntity` when it's first initialized.\n   * It provides a first snapshot of information needed for the successful creation of an Entity instance.\n   *\n   * @type {Immutable<TModel>}\n   */\n  readonly model: Immutable<TModel>;\n\n  /**\n   * Keeps track when the Entity's systems have ran last.\n   * Useful to calculate the `DeltaTime` between runs.\n   *\n   * @type {Date | undefined}\n   */\n  readonly lastUpdated?: Date;\n}\n"],"mappings":";;;;;AAOA,IAAY,oEAAL;AACL;;AACD"}
+{"version":3,"file":"index.cjs","names":[],"sources":["../../src/components/identity-component.ts"],"sourcesContent":["import { EntityTypeUid, IEntityModel } from '../entities/entity';\r\nimport { Immutable } from '../utils/types';\r\nimport { IComponent } from './component';\r\n\r\n/**\r\n * The `BasicComponentType` enum defines the types of basic components available.\r\n */\r\nexport enum BasicComponentType {\r\n  identity = 'identity'\r\n}\r\n\r\n/**\r\n * The mandatory metadata component for every entity.\r\n * Contains core information that defines what an entity is and when it was last updated.\r\n * This component is immutable after creation and uniquely identifies each entity.\r\n *\r\n * @template TModel - The entity model type containing initialization data.\r\n */\r\nexport interface IdentityComponent<TModel extends IEntityModel> extends IComponent {\r\n  /**\r\n   * The entity type classification.\r\n   * Categorizes entities into logical types, allowing systems to selectively operate on specific entity categories.\r\n   */\r\n  readonly entityType: EntityTypeUid;\r\n\r\n  /**\r\n   * The initialization model for this entity.\r\n   * Provides the minimal data structure used when the entity was first created.\r\n   * Serves as a reference point for the entity's initial configuration.\r\n   *\r\n   * @type {Immutable<TModel>}\r\n   */\r\n  readonly model: Immutable<TModel>;\r\n\r\n  /**\r\n   * The timestamp of the entity's last system update.\r\n   * Useful for calculating elapsed time (delta time) between consecutive updates.\r\n   * Helps systems make time-aware decisions.\r\n   *\r\n   * @type {Date | undefined}\r\n   */\r\n  readonly lastUpdated?: Date;\r\n}\r\n"],"mappings":";;;;;AAOA,IAAY,kEAAL;AACL"}

package/dist/components/index.d.cts

@@ -1,3 +1,2 @@
-import { BasicComponentType, ComponentTypeUid, IComponent, IdentityComponent } from "../identity-component-BDWEtAXA.cjs";
-import "../types-DvzdpbLu.cjs";
+import { f as ComponentTypeUid, n as IdentityComponent, p as IComponent, t as BasicComponentType } from "../identity-component-uU0yDR-y.cjs";
 export { BasicComponentType, ComponentTypeUid, IComponent, IdentityComponent };

package/dist/components/index.d.mts

@@ -0,0 +1,2 @@
+import { f as ComponentTypeUid, n as IdentityComponent, p as IComponent, t as BasicComponentType } from "../identity-component-CgzvgBVh.mjs";
+export { BasicComponentType, ComponentTypeUid, IComponent, IdentityComponent };

package/dist/components/{index.js → index.mjs}

@@ -2,11 +2,11 @@
 /**
 * The `BasicComponentType` enum defines the types of basic components available.
 */
-let BasicComponentType = /* @__PURE__ */ function(BasicComponentType$1) {
-	BasicComponentType$1["identity"] = "identity";
-	return BasicComponentType$1;
+let BasicComponentType = /* @__PURE__ */ function(BasicComponentType) {
+	BasicComponentType["identity"] = "identity";
+	return BasicComponentType;
 }({});
 
 //#endregion
 export { BasicComponentType };
-//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.mjs.map

package/dist/components/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/components/identity-component.ts"],"sourcesContent":["import { EntityTypeUid, IEntityModel } from '../entities/entity';\r\nimport { Immutable } from '../utils/types';\r\nimport { IComponent } from './component';\r\n\r\n/**\r\n * The `BasicComponentType` enum defines the types of basic components available.\r\n */\r\nexport enum BasicComponentType {\r\n  identity = 'identity'\r\n}\r\n\r\n/**\r\n * The mandatory metadata component for every entity.\r\n * Contains core information that defines what an entity is and when it was last updated.\r\n * This component is immutable after creation and uniquely identifies each entity.\r\n *\r\n * @template TModel - The entity model type containing initialization data.\r\n */\r\nexport interface IdentityComponent<TModel extends IEntityModel> extends IComponent {\r\n  /**\r\n   * The entity type classification.\r\n   * Categorizes entities into logical types, allowing systems to selectively operate on specific entity categories.\r\n   */\r\n  readonly entityType: EntityTypeUid;\r\n\r\n  /**\r\n   * The initialization model for this entity.\r\n   * Provides the minimal data structure used when the entity was first created.\r\n   * Serves as a reference point for the entity's initial configuration.\r\n   *\r\n   * @type {Immutable<TModel>}\r\n   */\r\n  readonly model: Immutable<TModel>;\r\n\r\n  /**\r\n   * The timestamp of the entity's last system update.\r\n   * Useful for calculating elapsed time (delta time) between consecutive updates.\r\n   * Helps systems make time-aware decisions.\r\n   *\r\n   * @type {Date | undefined}\r\n   */\r\n  readonly lastUpdated?: Date;\r\n}\r\n"],"mappings":";;;;AAOA,IAAY,kEAAL;AACL"}

package/dist/entities/index.cjs

@@ -1,12 +1,19 @@
 
 //#region src/entities/entity-queue.ts
 /**
-* The `EntityUpdateType` enum specifies whether the current Entity should be `updated` or `removed`.
+* Specifies the action to be performed on an entity.
+* Updates are categorized to enable different processing paths in the runtime.
 */
-let EntityUpdateType = /* @__PURE__ */ function(EntityUpdateType$1) {
-	EntityUpdateType$1["update"] = "update";
-	EntityUpdateType$1["remove"] = "remove";
-	return EntityUpdateType$1;
+let EntityUpdateType = /* @__PURE__ */ function(EntityUpdateType) {
+	/**
+	* Indicates the entity should be updated with new data.
+	*/
+	EntityUpdateType["update"] = "update";
+	/**
+	* Indicates the entity should be removed from the system.
+	*/
+	EntityUpdateType["remove"] = "remove";
+	return EntityUpdateType;
 }({});
 
 //#endregion

package/dist/entities/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":[],"sources":["../../src/entities/entity-queue.ts"],"sourcesContent":["import { IEntityModel } from './entity';\nimport { IEntityProxy } from './entity-proxies';\nimport { IEntitySnapshot } from './entity-snapshot';\n\n/**\n * The `EntityUpdateType` enum specifies whether the current Entity should be `updated` or `removed`.\n */\nexport enum EntityUpdateType {\n  update = 'update',\n  remove = 'remove'\n}\n\n/**\n * The `IEntityUpdate` interface represents an Entity update that should be applied over an existing Entity.\n */\nexport interface IEntityUpdate {\n  /**\n   * The type of the update, which can be either `update` or `remove`.\n   */\n  type: EntityUpdateType;\n\n  /**\n   * The proxy of the Entity that needs to be updated.\n   */\n  entity: IEntityProxy;\n\n  /**\n   * Optional. The model of the Entity that needs to be updated.\n   */\n  model?: IEntityModel;\n\n  /**\n   * Optional. The snapshot of the Entity that needs to be updated.\n   */\n  snapshot?: IEntitySnapshot;\n}\n\n/**\n * The `IEntityUpdateQueue` interface is the main mechanism to queue and retrieve `EntityUpdate` instances.\n *\n * The interface can be implemented using a simple queue mechanism, or perhaps, a Priority Queue.\n */\nexport interface IEntityUpdateQueue {\n  /**\n   * The number of `EntityUpdate` instances currently in the queue.\n   */\n  readonly size: number;\n\n  /**\n   * Adds an `EntityUpdate` instance to the end of the queue.\n   * @param change - The `EntityUpdate` instance to be added.\n   */\n  enqueue(change: IEntityUpdate): void;\n\n  /**\n   * Removes and returns the `EntityUpdate` instance at the front of the queue.\n   * @returns The `EntityUpdate` instance at the front of the queue.\n   */\n  dequeue(): IEntityUpdate;\n\n  /**\n   * Returns the `EntityUpdate` instance at the front of the queue without removing it.\n   * @returns The `EntityUpdate` instance at the front of the queue.\n   */\n  peek(): IEntityUpdate;\n\n  /**\n   * Removes all `EntityUpdate` instances from the queue.\n   */\n  clear(): void;\n}\n"],"mappings":";;;;;AAOA,IAAY,gEAAL;AACL;AACA;;AACD"}
+{"version":3,"file":"index.cjs","names":[],"sources":["../../src/entities/entity-queue.ts"],"sourcesContent":["import { IEntityModel } from './entity';\r\nimport { IEntityProxy } from './entity-proxies';\r\nimport { IEntitySnapshot } from './entity-snapshot';\r\n\r\n/**\r\n * Specifies the action to be performed on an entity.\r\n * Updates are categorized to enable different processing paths in the runtime.\r\n */\r\nexport enum EntityUpdateType {\r\n  /**\r\n   * Indicates the entity should be updated with new data.\r\n   */\r\n  update = 'update',\r\n  /**\r\n   * Indicates the entity should be removed from the system.\r\n   */\r\n  remove = 'remove'\r\n}\r\n\r\n/**\r\n * Represents a queued entity state change or removal.\r\n * Updates flow through the system to be processed by entity update handlers.\r\n */\r\nexport interface IEntityUpdate {\r\n  /**\r\n   * The type of operation: update or remove.\r\n   */\r\n  readonly type: EntityUpdateType;\r\n\r\n  /**\r\n   * The entity being affected by this update.\r\n   */\r\n  readonly entity: IEntityProxy;\r\n\r\n  /**\r\n   * Optional model data for initialization or reconfiguration.\r\n   */\r\n  readonly model?: IEntityModel;\r\n\r\n  /**\r\n   * Optional serialized state to apply to the entity.\r\n   */\r\n  readonly snapshot?: IEntitySnapshot;\r\n}\r\n\r\n/**\r\n * Queue interface for managing pending entity updates.\r\n * Different implementations may use different prioritization strategies (e.g., priority queues, FIFO, ordered by entity type).\r\n * Updates are consumed by the runtime and dispatched to appropriate entity systems.\r\n */\r\nexport interface IEntityUpdateQueue {\r\n  /**\r\n   * The current number of updates in the queue.\r\n   */\r\n  readonly size: number;\r\n\r\n  /**\r\n   * Adds an update to the queue for processing.\r\n   * @param change - The update to queue.\r\n   */\r\n  enqueue(change: IEntityUpdate): void;\r\n\r\n  /**\r\n   * Removes and returns the next update from the queue.\r\n   * The specific update returned depends on the queue's prioritization strategy.\r\n   * @returns The next queued update.\r\n   */\r\n  dequeue(): IEntityUpdate;\r\n\r\n  /**\r\n   * Views the next update without removing it.\r\n   * Useful for inspection before dequeuing.\r\n   * @returns The next update in the queue.\r\n   */\r\n  peek(): IEntityUpdate;\r\n\r\n  /**\r\n   * Removes all updates from the queue.\r\n   */\r\n  clear(): void;\r\n}\r\n"],"mappings":";;;;;;AAQA,IAAY,8DAAL;;;;AAIL;;;;AAIA"}

package/dist/entities/index.d.cts

@@ -1,4 +1,3 @@
-import { EntityProxy, EntityTypeUid, EntityUid, IEntity, IEntityModel, IEntityModelWithFeatures, IEntityModelWithRequiredProxies, IEntityProxy, IEntityProxyRepository, RequiredProxies, TypedEntityProxy } from "../identity-component-BDWEtAXA.cjs";
-import "../types-DvzdpbLu.cjs";
-import { EntityEventSubscriptionFilter, EntityEventUid, EntityUpdateType, IEntityEvent, IEntityEventsDispatcher, IEntityEventsManager, IEntityRepository, IEntityScheduler, IEntitySnapshot, IEntitySnapshotProvider, IEntityUpdate, IEntityUpdateQueue, IEventData } from "../index-DLm-DKAk.cjs";
-export { EntityEventSubscriptionFilter, EntityEventUid, EntityProxy, EntityTypeUid, EntityUid, EntityUpdateType, IEntity, IEntityEvent, IEntityEventsDispatcher, IEntityEventsManager, IEntityModel, IEntityModelWithFeatures, IEntityModelWithRequiredProxies, IEntityProxy, IEntityProxyRepository, IEntityRepository, IEntityScheduler, IEntitySnapshot, IEntitySnapshotProvider, IEntityUpdate, IEntityUpdateQueue, IEventData, RequiredProxies, TypedEntityProxy };
+import { a as IEntity, c as IEntityProxy, d as TypedEntityProxy, i as EntityUid, l as IEntityProxyRepository, o as IEntityModel, r as EntityTypeUid, s as EntityProxy, u as RequiredProxies } from "../identity-component-uU0yDR-y.cjs";
+import { a as IEntityUpdateQueue, c as EntityEventSubscriptionFilter, d as IEntityEvent, f as IEntityEventsDispatcher, i as IEntityUpdate, l as EntityEventSubscriptionOptions, m as IEventData, n as IEntityRepository, o as IEntitySnapshot, p as IEntityEventsManager, r as EntityUpdateType, s as IEntitySnapshotProvider, t as IEntityScheduler, u as EntityEventUid } from "../index-qSeVF9hf.cjs";
+export { EntityEventSubscriptionFilter, EntityEventSubscriptionOptions, EntityEventUid, EntityProxy, EntityTypeUid, EntityUid, EntityUpdateType, IEntity, IEntityEvent, IEntityEventsDispatcher, IEntityEventsManager, IEntityModel, IEntityProxy, IEntityProxyRepository, IEntityRepository, IEntityScheduler, IEntitySnapshot, IEntitySnapshotProvider, IEntityUpdate, IEntityUpdateQueue, IEventData, RequiredProxies, TypedEntityProxy };

package/dist/entities/index.d.mts

@@ -0,0 +1,3 @@
+import { a as IEntity, c as IEntityProxy, d as TypedEntityProxy, i as EntityUid, l as IEntityProxyRepository, o as IEntityModel, r as EntityTypeUid, s as EntityProxy, u as RequiredProxies } from "../identity-component-CgzvgBVh.mjs";
+import { a as IEntityUpdateQueue, c as EntityEventSubscriptionFilter, d as IEntityEvent, f as IEntityEventsDispatcher, i as IEntityUpdate, l as EntityEventSubscriptionOptions, m as IEventData, n as IEntityRepository, o as IEntitySnapshot, p as IEntityEventsManager, r as EntityUpdateType, s as IEntitySnapshotProvider, t as IEntityScheduler, u as EntityEventUid } from "../index-CfEs8NEA.mjs";
+export { EntityEventSubscriptionFilter, EntityEventSubscriptionOptions, EntityEventUid, EntityProxy, EntityTypeUid, EntityUid, EntityUpdateType, IEntity, IEntityEvent, IEntityEventsDispatcher, IEntityEventsManager, IEntityModel, IEntityProxy, IEntityProxyRepository, IEntityRepository, IEntityScheduler, IEntitySnapshot, IEntitySnapshotProvider, IEntityUpdate, IEntityUpdateQueue, IEventData, RequiredProxies, TypedEntityProxy };

package/dist/entities/index.mjs

@@ -0,0 +1,20 @@
+//#region src/entities/entity-queue.ts
+/**
+* Specifies the action to be performed on an entity.
+* Updates are categorized to enable different processing paths in the runtime.
+*/
+let EntityUpdateType = /* @__PURE__ */ function(EntityUpdateType) {
+	/**
+	* Indicates the entity should be updated with new data.
+	*/
+	EntityUpdateType["update"] = "update";
+	/**
+	* Indicates the entity should be removed from the system.
+	*/
+	EntityUpdateType["remove"] = "remove";
+	return EntityUpdateType;
+}({});
+
+//#endregion
+export { EntityUpdateType };
+//# sourceMappingURL=index.mjs.map

package/dist/entities/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/entities/entity-queue.ts"],"sourcesContent":["import { IEntityModel } from './entity';\r\nimport { IEntityProxy } from './entity-proxies';\r\nimport { IEntitySnapshot } from './entity-snapshot';\r\n\r\n/**\r\n * Specifies the action to be performed on an entity.\r\n * Updates are categorized to enable different processing paths in the runtime.\r\n */\r\nexport enum EntityUpdateType {\r\n  /**\r\n   * Indicates the entity should be updated with new data.\r\n   */\r\n  update = 'update',\r\n  /**\r\n   * Indicates the entity should be removed from the system.\r\n   */\r\n  remove = 'remove'\r\n}\r\n\r\n/**\r\n * Represents a queued entity state change or removal.\r\n * Updates flow through the system to be processed by entity update handlers.\r\n */\r\nexport interface IEntityUpdate {\r\n  /**\r\n   * The type of operation: update or remove.\r\n   */\r\n  readonly type: EntityUpdateType;\r\n\r\n  /**\r\n   * The entity being affected by this update.\r\n   */\r\n  readonly entity: IEntityProxy;\r\n\r\n  /**\r\n   * Optional model data for initialization or reconfiguration.\r\n   */\r\n  readonly model?: IEntityModel;\r\n\r\n  /**\r\n   * Optional serialized state to apply to the entity.\r\n   */\r\n  readonly snapshot?: IEntitySnapshot;\r\n}\r\n\r\n/**\r\n * Queue interface for managing pending entity updates.\r\n * Different implementations may use different prioritization strategies (e.g., priority queues, FIFO, ordered by entity type).\r\n * Updates are consumed by the runtime and dispatched to appropriate entity systems.\r\n */\r\nexport interface IEntityUpdateQueue {\r\n  /**\r\n   * The current number of updates in the queue.\r\n   */\r\n  readonly size: number;\r\n\r\n  /**\r\n   * Adds an update to the queue for processing.\r\n   * @param change - The update to queue.\r\n   */\r\n  enqueue(change: IEntityUpdate): void;\r\n\r\n  /**\r\n   * Removes and returns the next update from the queue.\r\n   * The specific update returned depends on the queue's prioritization strategy.\r\n   * @returns The next queued update.\r\n   */\r\n  dequeue(): IEntityUpdate;\r\n\r\n  /**\r\n   * Views the next update without removing it.\r\n   * Useful for inspection before dequeuing.\r\n   * @returns The next update in the queue.\r\n   */\r\n  peek(): IEntityUpdate;\r\n\r\n  /**\r\n   * Removes all updates from the queue.\r\n   */\r\n  clear(): void;\r\n}\r\n"],"mappings":";;;;;AAQA,IAAY,8DAAL;;;;AAIL;;;;AAIA"}

package/dist/factories/index.d.cts

@@ -1,57 +1,69 @@
-import { IEntity } from "../identity-component-BDWEtAXA.cjs";
-import "../types-DvzdpbLu.cjs";
-import "../index-DLm-DKAk.cjs";
-import { IPipeline, IPipelineContext } from "../index-D81Fo9XN.cjs";
-import "../index-ChV4Q5j6.cjs";
-import { ISystemContext, ISystemsRuntimeContext } from "../index-CjNeb3ML.cjs";
+import { a as IEntity } from "../identity-component-uU0yDR-y.cjs";
+import { l as IPipelineContext, o as IPipeline } from "../index-DZvjMjYZ.cjs";
+import { n as ISystemsRuntimeContext, o as ISystemsModuleBuilder, u as ISystemContext } from "../index-J5AU4JAU.cjs";
 
 //#region src/factories/context-factory.d.ts
-/**
- * The IContextFactory interface is used to create abstraction layers for quickly creating Pipeline Contexts.
- * It helps to avoid manually resolving all dependencies when creating these contexts.
- */
 interface IContextFactory {
   /**
-   * Creates a new instance of ISystemsRuntimeContext.
-   *
-   * @template TEntity - The type of entity to be used in the runtime context. It must extend IEntity.
-   * @returns A new instance of ISystemsRuntimeContext with the specified entity type.
+   * Creates a new system context for the given entity type.
+   * @template TEntity - The entity type for which the system context is being created.
+   * @returns A new context instance.
    */
-  createRuntimeContext<TEntity extends IEntity>(): ISystemsRuntimeContext<TEntity>;
+  createSystemContext<TEntity extends IEntity>(): ISystemContext<TEntity>;
 }
 //#endregion
 //#region src/factories/pipeline-factory.d.ts
 /**
- * The PipelineFactory interface provides methods to create different types of pipelines.
- * It helps to quickly create IPipeline objects without manually resolving their dependencies.
+ * Creates pipeline instances for various contexts.
+ * Abstracts pipeline creation to support different implementations.
+ * Used by the system to instantiate pipelines without coupling to specific implementations.
  */
 interface IPipelineFactory {
   /**
-   * Creates a new pipeline with the specified context and result type.
-   *
-   * @template TContext - The type of the pipeline context. It must extend IPipelineContext.
-   * @param name - Optional name for the pipeline. If not provided, a default name will be assigned.
-   * @returns A new instance of IPipeline with the specified context and result type.
+   * Creates a new pipeline for the specified context type.
+   * @template TContext - The context type for the pipeline. Must extend IPipelineContext.
+   * @param name - Optional name for the pipeline (useful for debugging).
+   * @returns A new pipeline instance ready for middleware registration.
    */
   createPipeline<TContext extends IPipelineContext>(name?: string): IPipeline<TContext>;
+}
+//#endregion
+//#region src/factories/runtime-factory.d.ts
+/**
+ * Creates runtime contexts and pipelines for system execution.
+ * Provides factory methods for constructing runtime infrastructure.
+ * Allows different runtime strategies through multiple implementations.
+ */
+interface IRuntimeFactory {
   /**
-   * Creates a new pipeline specifically for systems with the specified entity type and result type.
-   *
-   * @template TEntity - The type of the entity. It must extend IEntity.
-   * @param name - Optional name for the pipeline. If not provided, a default name will be assigned.
-   * @returns A new instance of IPipeline with the specified system context and result type.
+   * Creates a new runtime context for system execution.
+   * @template TEntity - The entity type for the runtime context.
+   * @returns A new systems runtime context instance.
    */
-  createSystemsPipeline<TEntity extends IEntity>(name?: string): IPipeline<ISystemContext<TEntity>>;
+  createRuntimeContext<TEntity extends IEntity>(): ISystemsRuntimeContext<TEntity>;
   /**
-   * Creates a new pipeline specifically for systems runtime with the specified entity type and result type.
-   *
-   * @template TEntity - The type of the entity. It must extend IEntity.
-   * @template TResult - The type of the result returned by the pipeline. Default is MiddlewareResult.
-   * @param name - Optional name for the pipeline. If not provided, a default name will be assigned.
-   * @returns A new instance of IPipeline with the specified systems runtime context and result type.
+   * Creates a pipeline for systems runtime orchestration.
+   * @template TEntity - The entity type for this runtime pipeline.
+   * @param name - Optional name for debugging.
+   * @returns A new runtime pipeline for system execution.
    */
   createRuntimePipeline<TEntity extends IEntity>(name?: string): IPipeline<ISystemsRuntimeContext<TEntity>>;
 }
 //#endregion
-export { IContextFactory, IPipelineFactory };
+//#region src/factories/systems-factory.d.ts
+/**
+ * Creates systems module builders for constructing entity system pipelines.
+ * Provides factory access to module builder instances.
+ * Enables composition of systems for different entity types.
+ */
+interface ISystemsFactory {
+  /**
+   * Creates a new builder for constructing a systems module.
+   * @template TEntity - The entity type for which systems are being built.
+   * @returns A new systems module builder instance.
+   */
+  createSystemsModuleBuilder<TEntity extends IEntity>(): ISystemsModuleBuilder<TEntity>;
+}
+//#endregion
+export { IContextFactory, IPipelineFactory, IRuntimeFactory, ISystemsFactory };
 //# sourceMappingURL=index.d.cts.map