@awesome-ecs/abstract 0.22.0 → 0.23.0

package/dist/factories/index.d.mts

@@ -0,0 +1,69 @@
+import { a as IEntity } from "../identity-component-BCmEilvk.mjs";
+import { l as IPipelineContext, o as IPipeline } from "../index-DcirKLCP.mjs";
+import { n as ISystemsRuntimeContext, o as ISystemsModuleBuilder, u as ISystemContext } from "../index-CW6-OhB4.mjs";
+
+//#region src/factories/context-factory.d.ts
+interface IContextFactory {
+  /**
+   * 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.
+   */
+  createSystemContext<TEntity extends IEntity>(): ISystemContext<TEntity>;
+}
+//#endregion
+//#region src/factories/pipeline-factory.d.ts
+/**
+ * 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 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 runtime context for system execution.
+   * @template TEntity - The entity type for the runtime context.
+   * @returns A new systems runtime context instance.
+   */
+  createRuntimeContext<TEntity extends IEntity>(): ISystemsRuntimeContext<TEntity>;
+  /**
+   * 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
+//#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.mts.map

package/dist/factories/index.mjs

@@ -0,0 +1 @@
+export {  };

package/dist/identity-component-5neFUd2Q.d.cts

@@ -0,0 +1,241 @@
+import { n as Immutable } from "./types-DLOd2zXO.cjs";
+
+//#region src/components/component.d.ts
+type ComponentTypeUid = string | number;
+/**
+ * The foundational data storage interface for all entity state.
+ * Components are pure data holders without behavior.
+ * They are the primary mechanism for organizing and accessing entity state.
+ * Systems read and modify components to drive entity behavior.
+ */
+interface IComponent {
+  /**
+   * The unique type identifier for this component.
+   * Enables type-safe component retrieval and categorization.
+   */
+  readonly componentType: ComponentTypeUid;
+  /**
+   * Indicates whether this component's state should be included in entity snapshots.
+   * Set to false for local-only state (UI, caches, transient data).
+   * Set to true for state that needs replication or persistence.
+   */
+  readonly isSerializable: boolean;
+  /**
+   * Optional version number for this component.
+   * Useful for managing backwards-compatibility when component schemas evolve.
+   * Allows deserialization to handle multiple component versions.
+   */
+  readonly version?: number;
+  /**
+   * Optional custom serialization function.
+   * Converts the component to a transmittable or storable format.
+   * If not provided, standard JSON stringification is used.
+   * @returns Serialized representation of the component.
+   */
+  toJSON?(): string | object;
+  /**
+   * Optional custom deserialization function.
+   * Updates the component's state from a previously serialized form.
+   * If not provided, fields are overwritten directly from the target state.
+   * @param targetState The serialized state to restore.
+   */
+  load?(targetState: this): void;
+}
+//#endregion
+//#region src/entities/entity-proxies.d.ts
+/**
+ * Represents a reference (pointer) to another entity.
+ * Proxies are the primary mechanism for establishing and maintaining relationships between entities,
+ * enabling decoupled entity-to-entity communication without direct dependencies.
+ */
+interface IEntityProxy {
+  /**
+   * The type identifier of the entity being referenced.
+   * Allows filtering and categorizing proxy relationships by entity type.
+   */
+  readonly entityType: EntityTypeUid;
+  /**
+   * The unique identifier of the referenced entity instance.
+   */
+  readonly entityUid: EntityUid;
+}
+/**
+ * A typed variant of `IEntityProxy` that carries compile-time type information.
+ * This allows IDEs to provide better type inference and type-checking when working with entity relationships.
+ *
+ * @template TEntity - The specific entity type that this proxy references.
+ */
+interface EntityProxy<TEntity extends IEntity> extends IEntityProxy {}
+/**
+ * A helper type to create a typed entity proxy.
+ */
+type TypedEntityProxy<T extends EntityTypeUid> = {
+  entityType: T;
+  entityUid: EntityUid;
+};
+/**
+ * A mapped type that transforms an array of EntityType into an array of TypedEntityProxy.
+ */
+type RequiredProxies<TProxyTypes extends readonly EntityTypeUid[]> = [...{ [I in keyof TProxyTypes]: TypedEntityProxy<TProxyTypes[I]> }, ...IEntityProxy[]];
+/**
+ * Central registry for managing entity-to-entity relationships through proxies.
+ * Maintains bidirectional proxy links, ensuring consistency across all entity references.
+ * This is the authoritative source for proxy data and manages the complete relationship lifecycle.
+ */
+interface IEntityProxyRepository {
+  /**
+   * Establishes a bidirectional proxy relationship between two entities.
+   * @param source - The entity establishing the reference.
+   * @param target - The entity being referenced.
+   * @param cleanup - If true, removes existing proxies of the same type before registering new relationship.
+   */
+  register(source: IEntityProxy, target: IEntityProxy, cleanup?: boolean): void;
+  /**
+   * Establishes multiple bidirectional proxy relationships for a source entity.
+   * Efficiently batch-registers relationships to multiple target entities.
+   * @param source - The entity establishing the references.
+   * @param targets - The entities being referenced.
+   * @param cleanup - If true, removes existing proxies of matching types before registering new relationships.
+   */
+  registerMany(source: IEntityProxy, targets: readonly IEntityProxy[], cleanup?: boolean): void;
+  /**
+   * Removes a bidirectional proxy relationship between two entities.
+   * @param source - The entity from which the reference is removed.
+   * @param target - The entity whose reference is being removed.
+   */
+  remove(source: IEntityProxy, target: IEntityProxy): void;
+  /**
+   * Removes all proxies from an entity, optionally filtered by target entity type.
+   * Also cleans up corresponding back-references from target entities.
+   * @param source - The entity from which proxies are removed.
+   * @param targetType - Optional entity type filter. If provided, only proxies to entities of this type are removed.
+   */
+  removeAllFor(source: IEntityProxy, targetType?: EntityTypeUid): void;
+  /**
+   * Retrieves a single proxy of a specific type for a source entity.
+   * If multiple proxies of the same type exist, it returns the first one found.
+   * @param source - The proxy of the source entity.
+   * @param targetType - The entity type of the target proxy to retrieve.
+   * @returns The entity proxy, or null if not found.
+   */
+  get(source: IEntityProxy, targetType: EntityTypeUid): IEntityProxy | null;
+  /**
+   * Retrieves all proxies of a specific type for a source entity.
+   * @param source - The proxy of the source entity.
+   * @param targetType - The entity type of the target proxies to retrieve.
+   * @returns A readonly array of entity proxies.
+   */
+  getMany(source: IEntityProxy, targetType: EntityTypeUid): Readonly<IEntityProxy[]>;
+  /**
+   * Retrieves all proxies for a source entity.
+   * @param source - The proxy of the source entity.
+   * @returns A readonly map of entity type UIDs to an array of their proxies.
+   */
+  getAll(source: IEntityProxy): ReadonlyMap<EntityTypeUid, Readonly<IEntityProxy[]>>;
+}
+//#endregion
+//#region src/entities/entity.d.ts
+/**
+ * Represents the unique identifier for an entity type.
+ * Can be either a string or a number.
+ */
+type EntityTypeUid = string | number;
+/**
+ * Represents the unique identifier for an entity.
+ * Can be either a string or a number.
+ */
+type EntityUid = string | number;
+/**
+ * Represents the core identification and initialization data for an entity.
+ * Every entity must have a model containing the minimal information needed for instantiation.
+ * Models are immutable and define the entity's initial structure.
+ */
+interface IEntityModel {
+  /**
+   * The unique identifier for this entity instance.
+   */
+  readonly uid: EntityUid;
+  /**
+   * Optional array of proxies (references) to other entities.
+   * Used to establish relationships at entity creation time.
+   */
+  readonly proxies?: readonly IEntityProxy[];
+}
+/**
+ * Entity model with enforced required proxy relationships.
+ * Used when an entity requires specific relationships to be present from creation.
+ *
+ * @template TProxyTypes - A readonly array of entity type IDs that must be provided as proxies.
+ */
+interface IEntityModelWithRequiredProxies<TProxyTypes extends readonly EntityTypeUid[]> extends IEntityModel {
+  /**
+   * Required proxies for this entity.
+   * The array structure matches the TProxyTypes template to ensure type-safe proxy definitions.
+   */
+  readonly proxies: RequiredProxies<TProxyTypes>;
+}
+/**
+ * The core entity interface representing a composition of components and relationships.
+ * Entities are immutable containers that store data (components) and maintain relationships (proxies) to other entities.
+ * State modifications occur exclusively through system operations, maintaining data integrity and enabling safe concurrent access.
+ *
+ * Implementations should provide strongly-typed accessors for components and proxies specific to their entity type,
+ * enhancing IDE support and type safety without adding behavior beyond data access.
+ */
+interface IEntity {
+  /**
+   * The set of components attached to this entity.
+   * Components are the primary data storage mechanism, mapped by their unique type identifiers.
+   */
+  readonly components: ReadonlyMap<ComponentTypeUid, IComponent>;
+  /**
+   * The identity component containing core entity metadata and initialization information.
+   * Every entity has exactly one identity component that persists for the entity's lifetime.
+   */
+  readonly identity: Readonly<IdentityComponent<IEntityModel>>;
+  /**
+   * A reference to this entity's own proxy.
+   */
+  readonly myProxy: Readonly<EntityProxy<this>>;
+}
+//#endregion
+//#region src/components/identity-component.d.ts
+/**
+ * The `BasicComponentType` enum defines the types of basic components available.
+ */
+declare enum BasicComponentType {
+  identity = "identity"
+}
+/**
+ * The mandatory metadata component for every entity.
+ * Contains core information that defines what an entity is and when it was last updated.
+ * This component is immutable after creation and uniquely identifies each entity.
+ *
+ * @template TModel - The entity model type containing initialization data.
+ */
+interface IdentityComponent<TModel extends IEntityModel> extends IComponent {
+  /**
+   * The entity type classification.
+   * Categorizes entities into logical types, allowing systems to selectively operate on specific entity categories.
+   */
+  readonly entityType: EntityTypeUid;
+  /**
+   * The initialization model for this entity.
+   * Provides the minimal data structure used when the entity was first created.
+   * Serves as a reference point for the entity's initial configuration.
+   *
+   * @type {Immutable<TModel>}
+   */
+  readonly model: Immutable<TModel>;
+  /**
+   * The timestamp of the entity's last system update.
+   * Useful for calculating elapsed time (delta time) between consecutive updates.
+   * Helps systems make time-aware decisions.
+   *
+   * @type {Date | undefined}
+   */
+  readonly lastUpdated?: Date;
+}
+//#endregion
+export { IEntity as a, EntityProxy as c, RequiredProxies as d, TypedEntityProxy as f, EntityUid as i, IEntityProxy as l, IComponent as m, IdentityComponent as n, IEntityModel as o, ComponentTypeUid as p, EntityTypeUid as r, IEntityModelWithRequiredProxies as s, BasicComponentType as t, IEntityProxyRepository as u };
+//# sourceMappingURL=identity-component-5neFUd2Q.d.cts.map

package/dist/identity-component-BCmEilvk.d.mts

@@ -0,0 +1,241 @@
+import { n as Immutable } from "./types-CnDtpKsY.mjs";
+
+//#region src/components/component.d.ts
+type ComponentTypeUid = string | number;
+/**
+ * The foundational data storage interface for all entity state.
+ * Components are pure data holders without behavior.
+ * They are the primary mechanism for organizing and accessing entity state.
+ * Systems read and modify components to drive entity behavior.
+ */
+interface IComponent {
+  /**
+   * The unique type identifier for this component.
+   * Enables type-safe component retrieval and categorization.
+   */
+  readonly componentType: ComponentTypeUid;
+  /**
+   * Indicates whether this component's state should be included in entity snapshots.
+   * Set to false for local-only state (UI, caches, transient data).
+   * Set to true for state that needs replication or persistence.
+   */
+  readonly isSerializable: boolean;
+  /**
+   * Optional version number for this component.
+   * Useful for managing backwards-compatibility when component schemas evolve.
+   * Allows deserialization to handle multiple component versions.
+   */
+  readonly version?: number;
+  /**
+   * Optional custom serialization function.
+   * Converts the component to a transmittable or storable format.
+   * If not provided, standard JSON stringification is used.
+   * @returns Serialized representation of the component.
+   */
+  toJSON?(): string | object;
+  /**
+   * Optional custom deserialization function.
+   * Updates the component's state from a previously serialized form.
+   * If not provided, fields are overwritten directly from the target state.
+   * @param targetState The serialized state to restore.
+   */
+  load?(targetState: this): void;
+}
+//#endregion
+//#region src/entities/entity-proxies.d.ts
+/**
+ * Represents a reference (pointer) to another entity.
+ * Proxies are the primary mechanism for establishing and maintaining relationships between entities,
+ * enabling decoupled entity-to-entity communication without direct dependencies.
+ */
+interface IEntityProxy {
+  /**
+   * The type identifier of the entity being referenced.
+   * Allows filtering and categorizing proxy relationships by entity type.
+   */
+  readonly entityType: EntityTypeUid;
+  /**
+   * The unique identifier of the referenced entity instance.
+   */
+  readonly entityUid: EntityUid;
+}
+/**
+ * A typed variant of `IEntityProxy` that carries compile-time type information.
+ * This allows IDEs to provide better type inference and type-checking when working with entity relationships.
+ *
+ * @template TEntity - The specific entity type that this proxy references.
+ */
+interface EntityProxy<TEntity extends IEntity> extends IEntityProxy {}
+/**
+ * A helper type to create a typed entity proxy.
+ */
+type TypedEntityProxy<T extends EntityTypeUid> = {
+  entityType: T;
+  entityUid: EntityUid;
+};
+/**
+ * A mapped type that transforms an array of EntityType into an array of TypedEntityProxy.
+ */
+type RequiredProxies<TProxyTypes extends readonly EntityTypeUid[]> = [...{ [I in keyof TProxyTypes]: TypedEntityProxy<TProxyTypes[I]> }, ...IEntityProxy[]];
+/**
+ * Central registry for managing entity-to-entity relationships through proxies.
+ * Maintains bidirectional proxy links, ensuring consistency across all entity references.
+ * This is the authoritative source for proxy data and manages the complete relationship lifecycle.
+ */
+interface IEntityProxyRepository {
+  /**
+   * Establishes a bidirectional proxy relationship between two entities.
+   * @param source - The entity establishing the reference.
+   * @param target - The entity being referenced.
+   * @param cleanup - If true, removes existing proxies of the same type before registering new relationship.
+   */
+  register(source: IEntityProxy, target: IEntityProxy, cleanup?: boolean): void;
+  /**
+   * Establishes multiple bidirectional proxy relationships for a source entity.
+   * Efficiently batch-registers relationships to multiple target entities.
+   * @param source - The entity establishing the references.
+   * @param targets - The entities being referenced.
+   * @param cleanup - If true, removes existing proxies of matching types before registering new relationships.
+   */
+  registerMany(source: IEntityProxy, targets: readonly IEntityProxy[], cleanup?: boolean): void;
+  /**
+   * Removes a bidirectional proxy relationship between two entities.
+   * @param source - The entity from which the reference is removed.
+   * @param target - The entity whose reference is being removed.
+   */
+  remove(source: IEntityProxy, target: IEntityProxy): void;
+  /**
+   * Removes all proxies from an entity, optionally filtered by target entity type.
+   * Also cleans up corresponding back-references from target entities.
+   * @param source - The entity from which proxies are removed.
+   * @param targetType - Optional entity type filter. If provided, only proxies to entities of this type are removed.
+   */
+  removeAllFor(source: IEntityProxy, targetType?: EntityTypeUid): void;
+  /**
+   * Retrieves a single proxy of a specific type for a source entity.
+   * If multiple proxies of the same type exist, it returns the first one found.
+   * @param source - The proxy of the source entity.
+   * @param targetType - The entity type of the target proxy to retrieve.
+   * @returns The entity proxy, or null if not found.
+   */
+  get(source: IEntityProxy, targetType: EntityTypeUid): IEntityProxy | null;
+  /**
+   * Retrieves all proxies of a specific type for a source entity.
+   * @param source - The proxy of the source entity.
+   * @param targetType - The entity type of the target proxies to retrieve.
+   * @returns A readonly array of entity proxies.
+   */
+  getMany(source: IEntityProxy, targetType: EntityTypeUid): Readonly<IEntityProxy[]>;
+  /**
+   * Retrieves all proxies for a source entity.
+   * @param source - The proxy of the source entity.
+   * @returns A readonly map of entity type UIDs to an array of their proxies.
+   */
+  getAll(source: IEntityProxy): ReadonlyMap<EntityTypeUid, Readonly<IEntityProxy[]>>;
+}
+//#endregion
+//#region src/entities/entity.d.ts
+/**
+ * Represents the unique identifier for an entity type.
+ * Can be either a string or a number.
+ */
+type EntityTypeUid = string | number;
+/**
+ * Represents the unique identifier for an entity.
+ * Can be either a string or a number.
+ */
+type EntityUid = string | number;
+/**
+ * Represents the core identification and initialization data for an entity.
+ * Every entity must have a model containing the minimal information needed for instantiation.
+ * Models are immutable and define the entity's initial structure.
+ */
+interface IEntityModel {
+  /**
+   * The unique identifier for this entity instance.
+   */
+  readonly uid: EntityUid;
+  /**
+   * Optional array of proxies (references) to other entities.
+   * Used to establish relationships at entity creation time.
+   */
+  readonly proxies?: readonly IEntityProxy[];
+}
+/**
+ * Entity model with enforced required proxy relationships.
+ * Used when an entity requires specific relationships to be present from creation.
+ *
+ * @template TProxyTypes - A readonly array of entity type IDs that must be provided as proxies.
+ */
+interface IEntityModelWithRequiredProxies<TProxyTypes extends readonly EntityTypeUid[]> extends IEntityModel {
+  /**
+   * Required proxies for this entity.
+   * The array structure matches the TProxyTypes template to ensure type-safe proxy definitions.
+   */
+  readonly proxies: RequiredProxies<TProxyTypes>;
+}
+/**
+ * The core entity interface representing a composition of components and relationships.
+ * Entities are immutable containers that store data (components) and maintain relationships (proxies) to other entities.
+ * State modifications occur exclusively through system operations, maintaining data integrity and enabling safe concurrent access.
+ *
+ * Implementations should provide strongly-typed accessors for components and proxies specific to their entity type,
+ * enhancing IDE support and type safety without adding behavior beyond data access.
+ */
+interface IEntity {
+  /**
+   * The set of components attached to this entity.
+   * Components are the primary data storage mechanism, mapped by their unique type identifiers.
+   */
+  readonly components: ReadonlyMap<ComponentTypeUid, IComponent>;
+  /**
+   * The identity component containing core entity metadata and initialization information.
+   * Every entity has exactly one identity component that persists for the entity's lifetime.
+   */
+  readonly identity: Readonly<IdentityComponent<IEntityModel>>;
+  /**
+   * A reference to this entity's own proxy.
+   */
+  readonly myProxy: Readonly<EntityProxy<this>>;
+}
+//#endregion
+//#region src/components/identity-component.d.ts
+/**
+ * The `BasicComponentType` enum defines the types of basic components available.
+ */
+declare enum BasicComponentType {
+  identity = "identity"
+}
+/**
+ * The mandatory metadata component for every entity.
+ * Contains core information that defines what an entity is and when it was last updated.
+ * This component is immutable after creation and uniquely identifies each entity.
+ *
+ * @template TModel - The entity model type containing initialization data.
+ */
+interface IdentityComponent<TModel extends IEntityModel> extends IComponent {
+  /**
+   * The entity type classification.
+   * Categorizes entities into logical types, allowing systems to selectively operate on specific entity categories.
+   */
+  readonly entityType: EntityTypeUid;
+  /**
+   * The initialization model for this entity.
+   * Provides the minimal data structure used when the entity was first created.
+   * Serves as a reference point for the entity's initial configuration.
+   *
+   * @type {Immutable<TModel>}
+   */
+  readonly model: Immutable<TModel>;
+  /**
+   * The timestamp of the entity's last system update.
+   * Useful for calculating elapsed time (delta time) between consecutive updates.
+   * Helps systems make time-aware decisions.
+   *
+   * @type {Date | undefined}
+   */
+  readonly lastUpdated?: Date;
+}
+//#endregion
+export { IEntity as a, EntityProxy as c, RequiredProxies as d, TypedEntityProxy as f, EntityUid as i, IEntityProxy as l, IComponent as m, IdentityComponent as n, IEntityModel as o, ComponentTypeUid as p, EntityTypeUid as r, IEntityModelWithRequiredProxies as s, BasicComponentType as t, IEntityProxyRepository as u };
+//# sourceMappingURL=identity-component-BCmEilvk.d.mts.map