@awesome-ecs/abstract 0.20.1 → 0.21.0

package/README.md

@@ -5,6 +5,30 @@
 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
@@ -97,3 +121,108 @@ The Render Systems can be skipped from the Runtime, if needed. That can be usefu
 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;
+  }
+}
+```

package/dist/components/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/components/index.ts","../../src/components/identity-component.ts"],"sourcesContent":["export * from './component';\nexport * from './identity-component';\n","import { IComponent } from './component';\nimport { EntityTypeUid, IEntityModel } from '../entities/entity';\nimport { Immutable } from '../utils/types';\n\nexport enum BasicComponentType {\n  identity = 'identity',\n}\n\n/**\n * The `IdentityComponent` contains basic information regarding what makes the current Entity unique.\n */\nexport interface IdentityComponent<TModel extends IEntityModel> extends IComponent {\n  /**\n   * The Entity Type that defines what Category type the Entity is part of. 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  readonly model: Immutable<TModel>;\n\n  /**\n   * Keeps track when the Entity's systems have ran last. Useful to calculate the `DeltaTime` between runs.\n   */\n  readonly lastUpdated?: Date;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACIO,IAAK,qBAAL,kBAAKA,wBAAL;AACL,EAAAA,oBAAA,cAAW;AADD,SAAAA;AAAA,GAAA;","names":["BasicComponentType"]}
+{"version":3,"sources":["../../src/components/index.ts","../../src/components/identity-component.ts"],"sourcesContent":["export * from './component';\nexport * from './identity-component';\n","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":";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACOO,IAAK,qBAAL,kBAAKA,wBAAL;AACL,EAAAA,oBAAA,cAAW;AADD,SAAAA;AAAA,GAAA;","names":["BasicComponentType"]}

package/dist/components/index.d.cts

@@ -1,2 +1,2 @@
-export { B as BasicComponentType, C as ComponentTypeUid, g as IComponent, f as IdentityComponent } from '../index-DK2CXVZ8.cjs';
-import '../types-BNwBqRWY.cjs';
+export { B as BasicComponentType, C as ComponentTypeUid, g as IComponent, f as IdentityComponent } from '../index-CnlpX7ys.cjs';
+import '../types-cZ-1lGPD.cjs';

package/dist/components/index.d.ts

@@ -1,2 +1,2 @@
-export { B as BasicComponentType, C as ComponentTypeUid, g as IComponent, f as IdentityComponent } from '../index-BPDsRt_F.js';
-import '../types-BNwBqRWY.js';
+export { B as BasicComponentType, C as ComponentTypeUid, g as IComponent, f as IdentityComponent } from '../index-B1KXekZD.js';
+import '../types-cZ-1lGPD.js';

package/dist/components/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/components/identity-component.ts"],"sourcesContent":["import { IComponent } from './component';\nimport { EntityTypeUid, IEntityModel } from '../entities/entity';\nimport { Immutable } from '../utils/types';\n\nexport enum BasicComponentType {\n  identity = 'identity',\n}\n\n/**\n * The `IdentityComponent` contains basic information regarding what makes the current Entity unique.\n */\nexport interface IdentityComponent<TModel extends IEntityModel> extends IComponent {\n  /**\n   * The Entity Type that defines what Category type the Entity is part of. 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  readonly model: Immutable<TModel>;\n\n  /**\n   * Keeps track when the Entity's systems have ran last. Useful to calculate the `DeltaTime` between runs.\n   */\n  readonly lastUpdated?: Date;\n}\n"],"mappings":";AAIO,IAAK,qBAAL,kBAAKA,wBAAL;AACL,EAAAA,oBAAA,cAAW;AADD,SAAAA;AAAA,GAAA;","names":["BasicComponentType"]}
+{"version":3,"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":";AAOO,IAAK,qBAAL,kBAAKA,wBAAL;AACL,EAAAA,oBAAA,cAAW;AADD,SAAAA;AAAA,GAAA;","names":["BasicComponentType"]}

package/dist/entities/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/entities/index.ts","../../src/entities/entity-queue.ts"],"sourcesContent":["export * from './entity';\nexport * from './entity-events';\nexport * from './entity-proxies';\nexport * from './entity-queue';\nexport * from './entity-repository';\nexport * from './entity-scheduler';\nexport * from './entity-snapshot';\n","import { IEntityModel } from './entity';\nimport { IEntityProxy } from './entity-proxies';\nimport { IEntitySnapshot } from './entity-snapshot';\n\n/**\n * The `EntityUpdateType` specifies whether the current should `update` or `remove` the Entity.\n */\nexport enum EntityUpdateType {\n  update = 'update',\n  remove = 'remove',\n}\n\n/**\n * The `IEntityUpdate` represents an Entity update that should be applied over an (existing) Entity.\n */\nexport interface IEntityUpdate {\n  type: EntityUpdateType;\n  entity: IEntityProxy;\n  model?: IEntityModel;\n  snapshot?: IEntitySnapshot;\n}\n\n/**\n * The `IEntityUpdateQueue` 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  readonly size: number;\n\n  enqueue(change: IEntityUpdate): void;\n  dequeue(): IEntityUpdate;\n\n  peek(): IEntityUpdate;\n  clear(): void;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACOO,IAAK,mBAAL,kBAAKA,sBAAL;AACL,EAAAA,kBAAA,YAAS;AACT,EAAAA,kBAAA,YAAS;AAFC,SAAAA;AAAA,GAAA;","names":["EntityUpdateType"]}
+{"version":3,"sources":["../../src/entities/index.ts","../../src/entities/entity-queue.ts"],"sourcesContent":["export * from './entity';\nexport * from './entity-events';\nexport * from './entity-proxies';\nexport * from './entity-queue';\nexport * from './entity-repository';\nexport * from './entity-scheduler';\nexport * from './entity-snapshot';\n","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":";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACOO,IAAK,mBAAL,kBAAKA,sBAAL;AACL,EAAAA,kBAAA,YAAS;AACT,EAAAA,kBAAA,YAAS;AAFC,SAAAA;AAAA,GAAA;","names":["EntityUpdateType"]}

package/dist/entities/index.d.cts

@@ -1,7 +1,7 @@
-import { I as IEntityProxy } from '../index-DK2CXVZ8.cjs';
-export { d as EntityProxy, E as EntityTypeUid, a as EntityUid, c as IEntity, b as IEntityModel, e as IEntityProxiesManager } from '../index-DK2CXVZ8.cjs';
-export { a as EntityEventSubscriptionFilter, E as EntityEventUid, e as EntityUpdateType, b as IEntityEvent, d as IEntityEventsDispatcher, c as IEntityEventsManager, h as IEntityRepository, i as IEntitySnapshot, j as IEntitySnapshotProvider, f as IEntityUpdate, g as IEntityUpdateQueue, I as IEventData } from '../entity-repository-DmfcUSrX.cjs';
-import '../types-BNwBqRWY.cjs';
+import { I as IEntityProxy } from '../index-CnlpX7ys.cjs';
+export { d as EntityProxy, E as EntityTypeUid, a as EntityUid, c as IEntity, b as IEntityModel, e as IEntityProxiesManager } from '../index-CnlpX7ys.cjs';
+export { a as EntityEventSubscriptionFilter, E as EntityEventUid, e as EntityUpdateType, b as IEntityEvent, d as IEntityEventsDispatcher, c as IEntityEventsManager, h as IEntityRepository, i as IEntitySnapshot, j as IEntitySnapshotProvider, f as IEntityUpdate, g as IEntityUpdateQueue, I as IEventData } from '../entity-repository-DJ1xbvaN.cjs';
+import '../types-cZ-1lGPD.cjs';
 
 /**
  * The `IEntityScheduler` is the main way of queuing `IEntityUpdate` instances on an Interval (based on time or a custom implementation).
@@ -9,8 +9,25 @@ import '../types-BNwBqRWY.cjs';
  * It usually reads the Entities from the `IEntityRepository`, and uses the `IEntityUpdateQueue` to enqueue Entity updates.
  */
 interface IEntityScheduler {
+    /**
+     * Schedules an entity for updates at a specified interval.
+     *
+     * @param entityProxy - The entity to schedule for updates.
+     * @param intervalMs - The interval at which to schedule updates, in milliseconds. If not provided, the default interval will be used.
+     */
     schedule(entityProxy: IEntityProxy, intervalMs?: number): void;
+    /**
+     * Removes an entity from the scheduler.
+     *
+     * @param entityProxy - The entity to remove from the scheduler.
+     */
     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;
 }
 

package/dist/entities/index.d.ts

@@ -1,7 +1,7 @@
-import { I as IEntityProxy } from '../index-BPDsRt_F.js';
-export { d as EntityProxy, E as EntityTypeUid, a as EntityUid, c as IEntity, b as IEntityModel, e as IEntityProxiesManager } from '../index-BPDsRt_F.js';
-export { a as EntityEventSubscriptionFilter, E as EntityEventUid, e as EntityUpdateType, b as IEntityEvent, d as IEntityEventsDispatcher, c as IEntityEventsManager, h as IEntityRepository, i as IEntitySnapshot, j as IEntitySnapshotProvider, f as IEntityUpdate, g as IEntityUpdateQueue, I as IEventData } from '../entity-repository-BASmOrq7.js';
-import '../types-BNwBqRWY.js';
+import { I as IEntityProxy } from '../index-B1KXekZD.js';
+export { d as EntityProxy, E as EntityTypeUid, a as EntityUid, c as IEntity, b as IEntityModel, e as IEntityProxiesManager } from '../index-B1KXekZD.js';
+export { a as EntityEventSubscriptionFilter, E as EntityEventUid, e as EntityUpdateType, b as IEntityEvent, d as IEntityEventsDispatcher, c as IEntityEventsManager, h as IEntityRepository, i as IEntitySnapshot, j as IEntitySnapshotProvider, f as IEntityUpdate, g as IEntityUpdateQueue, I as IEventData } from '../entity-repository-BlSpo-x2.js';
+import '../types-cZ-1lGPD.js';
 
 /**
  * The `IEntityScheduler` is the main way of queuing `IEntityUpdate` instances on an Interval (based on time or a custom implementation).
@@ -9,8 +9,25 @@ import '../types-BNwBqRWY.js';
  * It usually reads the Entities from the `IEntityRepository`, and uses the `IEntityUpdateQueue` to enqueue Entity updates.
  */
 interface IEntityScheduler {
+    /**
+     * Schedules an entity for updates at a specified interval.
+     *
+     * @param entityProxy - The entity to schedule for updates.
+     * @param intervalMs - The interval at which to schedule updates, in milliseconds. If not provided, the default interval will be used.
+     */
     schedule(entityProxy: IEntityProxy, intervalMs?: number): void;
+    /**
+     * Removes an entity from the scheduler.
+     *
+     * @param entityProxy - The entity to remove from the scheduler.
+     */
     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;
 }
 

package/dist/entities/index.js.map

@@ -1 +1 @@
-{"version":3,"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` specifies whether the current should `update` or `remove` the Entity.\n */\nexport enum EntityUpdateType {\n  update = 'update',\n  remove = 'remove',\n}\n\n/**\n * The `IEntityUpdate` represents an Entity update that should be applied over an (existing) Entity.\n */\nexport interface IEntityUpdate {\n  type: EntityUpdateType;\n  entity: IEntityProxy;\n  model?: IEntityModel;\n  snapshot?: IEntitySnapshot;\n}\n\n/**\n * The `IEntityUpdateQueue` 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  readonly size: number;\n\n  enqueue(change: IEntityUpdate): void;\n  dequeue(): IEntityUpdate;\n\n  peek(): IEntityUpdate;\n  clear(): void;\n}\n"],"mappings":";AAOO,IAAK,mBAAL,kBAAKA,sBAAL;AACL,EAAAA,kBAAA,YAAS;AACT,EAAAA,kBAAA,YAAS;AAFC,SAAAA;AAAA,GAAA;","names":["EntityUpdateType"]}
+{"version":3,"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":";AAOO,IAAK,mBAAL,kBAAKA,sBAAL;AACL,EAAAA,kBAAA,YAAS;AACT,EAAAA,kBAAA,YAAS;AAFC,SAAAA;AAAA,GAAA;","names":["EntityUpdateType"]}

package/dist/entity-repository-BlSpo-x2.d.ts

@@ -0,0 +1,253 @@
+import { I as IEntityProxy, f as IdentityComponent, b as IEntityModel, g as IComponent, c as IEntity, E as EntityTypeUid } from './index-B1KXekZD.js';
+
+/**
+ * Represents a unique identifier for an entity event.
+ * Can be either a string or a number.
+ */
+type EntityEventUid = string | number;
+/**
+ * A filter function for entity event subscriptions.
+ * Returns true if the event should be processed, false otherwise.
+ */
+type EntityEventSubscriptionFilter = (event: IEntityEvent<IEventData>) => boolean;
+/**
+ * The `IEventData` interface represents the data associated with an entity event.
+ * It contains at least the `Event Unique Identifier`.
+ */
+interface IEventData {
+    uid: EntityEventUid;
+}
+/**
+ * The `IEntityEvent` interface represents a basic building block for a Publish/Subscribe pattern.
+ * It is used to synchronize state between multiple entities.
+ *
+ * The events are scheduled as part of the `EntityUpdate` model.
+ * Systems subscribe and receive updates with the events included in their `SystemContext`.
+ */
+interface IEntityEvent<TEventData extends IEventData> {
+    origin: IEntityProxy;
+    target?: IEntityProxy;
+    data: TEventData;
+}
+/**
+ * The `IEntityEventsManager` interface represents a Publish/Subscribe broker for `IEntityEvent` instances.
+ * It keeps track of entity subscriptions (as part of the Observer design pattern).
+ */
+interface IEntityEventsManager {
+    /**
+     * Subscribes an entity to a specific event.
+     * @param uid - The unique identifier of the event.
+     * @param entity - The entity subscribing to the event.
+     * @param filter - An optional filter function to determine if the event should be processed.
+     */
+    subscribe(uid: EntityEventUid, entity: IEntityProxy, filter?: EntityEventSubscriptionFilter): void;
+    /**
+     * Unsubscribes an entity from a specific event.
+     * @param uid - The unique identifier of the event.
+     * @param entity - The entity unsubscribing from the event.
+     */
+    unsubscribe(uid: EntityEventUid, entity: IEntityProxy): void;
+    /**
+     * Retrieves the entities subscribed to a specific event.
+     * @param event - The event to retrieve subscriptions for.
+     * @returns An array of entities subscribed to the event.
+     */
+    getSubscriptions(event: IEntityEvent<IEventData>): IEntityProxy[];
+    /**
+     * Retrieves the unique identifiers of events subscribed to by a specific entity.
+     * @param entity - The entity to retrieve subscriptions for.
+     * @returns An array of unique identifiers of events subscribed to by the entity.
+     */
+    getSubscriptionsForEntity(entity: IEntityProxy): EntityEventUid[];
+    /**
+     * Removes all subscriptions for all entities.
+     */
+    clearSubscriptions(): void;
+    /**
+     * Removes all subscriptions for a specific event.
+     * @param uid - The unique identifier of the event to remove subscriptions from.
+     */
+    clearSubscriptionsForEvent(uid: EntityEventUid): void;
+    /**
+     * Removes all subscriptions for a specific entity.
+     * @param entity - The entity to remove subscriptions from.
+     */
+    clearSubscriptionsForEntity(entity: IEntityProxy): void;
+}
+/**
+ * The `IEntityEventsDispatcher` interface represents the main access point for dispatching events to entities.
+ * It can leverage the `IEntityEventsManager` to find subscribers and the `IEntityUpdateQueue` to register events
+ * into each observer entity's next update.
+ */
+interface IEntityEventsDispatcher {
+    /**
+     * Dispatches a single event to entities.
+     * @param event - The event to dispatch.
+     * @param targets - The entities to dispatch the event to.
+     */
+    dispatchEvent(event: IEntityEvent<IEventData>, ...targets: IEntityProxy[]): void;
+    /**
+     * Dispatches multiple events to entities.
+     * @param events - The events to dispatch.
+     * @param targets - The entities to dispatch the events to.
+     */
+    dispatchEvents(events: IEntityEvent<IEventData>[], ...targets: IEntityProxy[]): void;
+}
+
+/**
+ * The `IEntitySnapshot` interface represents a serializable state of an Entity.
+ * It can contain the full or partial state of the Entity, including its identity, components, proxies, and events.
+ * This interface is used to capture Entity state changes (deltas) or update existing Entity with changes from a remote source.
+ */
+interface IEntitySnapshot {
+    /**
+     * The identity of the Entity.
+     */
+    readonly identity?: Readonly<IdentityComponent<IEntityModel>>;
+    /**
+     * An array of components associated with the Entity.
+     */
+    readonly components?: IComponent[];
+    /**
+     * An array of proxies associated with the Entity.
+     */
+    readonly proxies?: IEntityProxy[];
+    /**
+     * An array of events associated with the Entity.
+     */
+    readonly events?: IEntityEvent<IEventData>[];
+}
+/**
+ * The `IEntitySnapshotProvider` interface is the main provider for creating and updating Entity snapshots.
+ * It provides methods to apply a snapshot to an Entity and to create a snapshot from an Entity.
+ */
+interface IEntitySnapshotProvider {
+    /**
+     * Applies a snapshot to an Entity.
+     * This method updates the Entity's state based on the provided snapshot.
+     *
+     * @param entity - The Entity to apply the snapshot to.
+     * @param snapshot - The snapshot to apply to the Entity.
+     */
+    applySnapshot(entity: IEntity, snapshot: IEntitySnapshot): void;
+    /**
+     * Creates a snapshot from an Entity.
+     * This method captures the current state of the Entity and returns it as a snapshot.
+     *
+     * @param entity - The Entity to create a snapshot from.
+     * @returns The created snapshot.
+     */
+    createSnapshot(entity: IEntity): IEntitySnapshot;
+}
+
+/**
+ * The `EntityUpdateType` enum specifies whether the current Entity should be `updated` or `removed`.
+ */
+declare enum EntityUpdateType {
+    update = "update",
+    remove = "remove"
+}
+/**
+ * The `IEntityUpdate` interface represents an Entity update that should be applied over an existing Entity.
+ */
+interface IEntityUpdate {
+    /**
+     * The type of the update, which can be either `update` or `remove`.
+     */
+    type: EntityUpdateType;
+    /**
+     * The proxy of the Entity that needs to be updated.
+     */
+    entity: IEntityProxy;
+    /**
+     * Optional. The model of the Entity that needs to be updated.
+     */
+    model?: IEntityModel;
+    /**
+     * Optional. The snapshot of the Entity that needs to be updated.
+     */
+    snapshot?: IEntitySnapshot;
+}
+/**
+ * The `IEntityUpdateQueue` interface is the main mechanism to queue and retrieve `EntityUpdate` instances.
+ *
+ * The interface can be implemented using a simple queue mechanism, or perhaps, a Priority Queue.
+ */
+interface IEntityUpdateQueue {
+    /**
+     * The number of `EntityUpdate` instances currently in the queue.
+     */
+    readonly size: number;
+    /**
+     * Adds an `EntityUpdate` instance to the end of the queue.
+     * @param change - The `EntityUpdate` instance to be added.
+     */
+    enqueue(change: IEntityUpdate): void;
+    /**
+     * Removes and returns the `EntityUpdate` instance at the front of the queue.
+     * @returns The `EntityUpdate` instance at the front of the queue.
+     */
+    dequeue(): IEntityUpdate;
+    /**
+     * Returns the `EntityUpdate` instance at the front of the queue without removing it.
+     * @returns The `EntityUpdate` instance at the front of the queue.
+     */
+    peek(): IEntityUpdate;
+    /**
+     * Removes all `EntityUpdate` instances from the queue.
+     */
+    clear(): void;
+}
+
+/**
+ * The `IEntityRepository` is the central storage for keeping track of existing Entities.
+ * It provides basic CRUD functionality.
+ */
+interface IEntityRepository {
+    /**
+     * Returns the number of entities in the repository.
+     */
+    readonly size: number;
+    /**
+     * Checks if the repository contains an entity represented by the given proxy.
+     * @param proxy - The proxy of the entity to check.
+     * @returns True if the repository contains the entity, false otherwise.
+     */
+    has(proxy: IEntityProxy): boolean;
+    /**
+     * Retrieves an entity from the repository by its proxy.
+     * @template TEntity - The type of the entity to retrieve.
+     * @param proxy - The proxy of the entity to retrieve.
+     * @returns The retrieved entity.
+     */
+    get<TEntity extends IEntity>(proxy: IEntityProxy): TEntity;
+    /**
+     * Retrieves all entities of a specific type from the repository.
+     * @template TEntity - The type of the entities to retrieve.
+     * @param entityType - The type UID of the entities to retrieve.
+     * @returns An array of the retrieved entities.
+     */
+    getAll<TEntity extends IEntity>(entityType: EntityTypeUid): TEntity[];
+    /**
+     * Iterator over all entities in the repository.
+     * @returns An iterator of all entities in the repository.
+     */
+    listAll(): IterableIterator<IEntity>;
+    /**
+     * Adds or updates an entity in the repository.
+     * @param entity - The entity to add or update.
+     */
+    set(entity: IEntity): void;
+    /**
+     * Deletes an entity from the repository by its proxy.
+     * @param proxy - The proxy of the entity to delete.
+     */
+    delete(proxy: IEntityProxy): void;
+    /**
+     * Clears all entities of a specific type from the repository.
+     * @param entityType - The type UID of the entities to clear.
+     */
+    clear(entityType: EntityTypeUid): void;
+}
+
+export { type EntityEventUid as E, type IEventData as I, type EntityEventSubscriptionFilter as a, type IEntityEvent as b, type IEntityEventsManager as c, type IEntityEventsDispatcher as d, EntityUpdateType as e, type IEntityUpdate as f, type IEntityUpdateQueue as g, type IEntityRepository as h, type IEntitySnapshot as i, type IEntitySnapshotProvider as j };