@awesome-ecs/abstract 0.33.0 → 0.34.0

package/dist/{index-BOS-47DQ.d.mts → index-DGyDijY7.d.mts}

@@ -1,8 +1,46 @@
-import { a as IEntity, c as IEntityProxy, i as EntityUid, o as IEntityModel, p as ComponentTypeUid, r as EntityTypeUid, s as EntityProxy, v as ConfigRecord } from "./index-Tznk33g6.mjs";
-import { r as Immutable } from "./types-UnqKSA14.mjs";
-import { b as IEntityConfigSnapshot, h as IEntityEvent, l as IEntitySnapshot, m as EntityEventUid, p as EntityEventSubscriptionOptions, s as IEntityUpdate, v as IEventData } from "./index--9JJtMKF.mjs";
-import { c as IMiddleware, l as IPipelineContext, o as IPipeline, u as PipelineDispatch } from "./index-DXbpfhHa.mjs";
+import { T as ConfigRecord, a as IEntityProxy, b as ComponentTypeUid, f as IEntity, h as IEntitySpec, i as EntityProxyManyLookup, n as EntityProxy, p as IEntityModel, r as EntityProxyLookup, u as EntityTypeUid } from "./index-Dbwzlrgp.mjs";
+import { r as Immutable } from "./types-BaCGIrym.mjs";
+import { b as IEntityConfigSnapshot, c as IEntityUpdate, g as IEntityEvent, h as EntityEventUid, m as EntityEventSubscriptionOptions, u as IEntitySnapshot, y as IEventData } from "./index-BanhgPCc.mjs";
+import { c as IMiddleware, l as IPipelineContext, o as IPipeline, u as PipelineDispatch } from "./index-B3DqdxE6.mjs";
 
+//#region src/utils/dispatch-sequential.d.ts
+/**
+ * Executes a function for each item in an iterable, sequentially.
+ *
+ * Uses a sync fast-path: iterates synchronously until the first Promise is
+ * encountered, then switches to async for the remainder. If no item produces
+ * a Promise, the entire call stays synchronous with zero async overhead.
+ *
+ * @param items - The iterable to iterate over.
+ * @param fn - The function to call for each item. May return void or a Promise.
+ * @returns void if all calls were synchronous, or a Promise if any were async.
+ */
+declare function dispatchSequential<T>(items: Iterable<T>, fn: (item: T) => void | Promise<void>): void | Promise<void>;
+//#endregion
+//#region src/utils/json-serializer.d.ts
+/**
+ * Custom JSON serialization and deserialization interface.
+ * Allows different serialization strategies for handling complex types.
+ * Used for entity snapshots, events, and any data needing JSON conversion.
+ */
+interface IJsonSerializer {
+  /**
+   * Converts an object to a serializable JSON representation.
+   * Handles types that don't serialize naturally (dates, maps, custom objects, etc.).
+   * @param value - The object to serialize.
+   * @returns A JSON-serializable representation.
+   */
+  serializeCustom(value: object): string;
+  /**
+   * Converts a JSON string back to its original object type.
+   * Reconstructs complex types from their serialized form.
+   * @template TObject - The target object type.
+   * @param text - The JSON string to deserialize.
+   * @returns The deserialized object of the specified type.
+   */
+  parseCustom<TObject>(text: string): TObject;
+}
+//#endregion
 //#region src/utils/logger.d.ts
 /**
  * Logger interface for debug and diagnostic output.
@@ -78,6 +116,103 @@ interface ILoggerOptions {
   enabled: Map<LogLevel, boolean>;
 }
 //#endregion
+//#region src/utils/performance.d.ts
+type TickMetricEntry = {
+  name: string;
+  category: string;
+  totalMs: number;
+  count: number;
+};
+type TickSnapshot = {
+  tickIndex: number;
+  tickDurationMs: number;
+  fps: number;
+  queueSize: number;
+  timestamp: number;
+  metrics: TickMetricEntry[];
+  render?: RenderSnapshot;
+};
+type RenderSnapshot = {
+  frameTimeMs: number;
+  renderTimeMs: number;
+  gpuFrameTimeMs: number;
+  drawCalls: number;
+  activeMeshesEvalMs: number;
+  cameraRenderMs: number;
+  totalVertices: number;
+  activeIndices: number;
+};
+type MiddlewareMetricsSummary = {
+  name: string;
+  category: PipelineCategoryName;
+  count: number;
+  totalMs: number;
+  avgMs: number;
+  minMs: number;
+  maxMs: number;
+  lastMs: number;
+};
+//#endregion
+//#region src/utils/performance-timer.d.ts
+/**
+ * Unique identifier for a timer instance.
+ */
+type PerformanceTimerUid = number;
+/**
+ * Options for identifying and categorizing performance metrics.
+ * Used by pipeline factories and performance decorators.
+ */
+type PerformanceMetricOptions = {
+  name?: string;
+  category?: string;
+};
+/**
+ * Record of a completed timer measurement.
+ * Captures timing information for performance analysis and profiling.
+ */
+interface PerformanceTimeEntry {
+  /**
+   * The name identifying this timer.
+   */
+  name: string;
+  /**
+   * The category of this metric (e.g. 'module', 'runtime', 'system').
+   */
+  category?: string;
+  /**
+   * Timestamp in milliseconds when the timer started.
+   */
+  startedAt: number;
+  /**
+   * Timestamp in milliseconds when the timer ended.
+   */
+  endedAt?: number;
+  /**
+   * Duration in milliseconds that elapsed.
+   */
+  msPassed?: number;
+}
+/**
+ * Interface for measuring operation duration.
+ * Provides start/stop functionality for performance profiling.
+ * Used throughout the system to collect timing metrics.
+ */
+interface IPerformanceTimer {
+  /**
+   * Starts a new timer.
+   * @param name - Label for this timer (used in results).
+   * @param category - Optional category for grouping metrics.
+   * @returns A unique identifier for this timer instance.
+   */
+  startTimer(name: string, category?: string): PerformanceTimerUid;
+  /**
+   * Stops a timer and returns the recorded metrics.
+   * @param timerUid - The timer identifier returned by startTimer.
+   * @returns Complete timing entry with start, end, and duration.
+   */
+  endTimer(timerUid: PerformanceTimerUid): PerformanceTimeEntry;
+}
+//#endregion
 //#region src/systems/pipeline/system-context-config.d.ts
 /**
  * Config-specific API for the current system execution.
@@ -286,30 +421,18 @@ interface ISystemContextProxies {
    * @param proxy - The entity reference to remove.
    */
   remove(proxy: IEntityProxy): void;
-  /**
-   * Removes all entity references from the current entity.
-   * Optionally filter by target entity type.
-   * @param targetType - If provided, only removes references to entities of this type.
-   */
-  removeAll(targetType?: EntityTypeUid): void;
   /**
    * Retrieves a single reference of a specific entity type from the current entity.
    * @param targetType - The entity type to find.
    * @returns The first matching proxy, or null if not found.
    */
-  get(targetType: EntityTypeUid): IEntityProxy | null;
+  getProxy<TEntity extends IEntity = IEntity>(targetType: EntityProxyLookup<TEntity>): EntityProxy<TEntity> | null;
   /**
    * Retrieves all references to entities of a specific type from the current entity.
    * @param targetType - The entity type to find.
    * @returns Array of matching proxies.
    */
-  getMany(targetType: EntityTypeUid): Readonly<IEntityProxy[]>;
-  /**
-   * Retrieves all entity references from the current entity.
-   * Organized by target entity type.
-   * @returns Map of entity type to their proxies.
-   */
-  getAll(): ReadonlyMap<EntityTypeUid, Readonly<IEntityProxy[]>>;
+  getProxies<TEntity extends IEntity = IEntity>(targetType: EntityProxyManyLookup<TEntity>): Readonly<EntityProxy<TEntity>[]>;
 }
 //#endregion
 //#region src/systems/pipeline/system-context-repository.d.ts
@@ -333,7 +456,28 @@ interface ISystemContextRepository {
    * @param proxy - Reference to the entity.
    * @returns The immutable entity instance.
    */
-  getEntity<TEntity extends IEntity>(proxy: EntityProxy<TEntity> | EntityTypeUid): Immutable<TEntity>;
+  getEntity<TEntity extends IEntity>(proxy: EntityProxy<TEntity> | null | undefined): TEntity | undefined;
+  /**
+   * Retrieves an entity from storage based on its type.
+   * @template TEntity - The expected entity type.
+   * @param targetType - Reference to the entity type.
+   * @returns The immutable entity instance.
+   */
+  getEntity<TEntity extends IEntity>(targetType: EntityProxyLookup<TEntity> | null | undefined): TEntity | undefined;
+  /**
+   * Retrieves an entity from storage based on its type or proxy.
+   * @template TEntity - The expected entity type.
+   * @param proxyOrTargetType - Reference to the entity proxy or type.
+   * @returns The immutable entity instance.
+   */
+  getEntity<TEntity extends IEntity>(proxy: EntityProxy<TEntity> | EntityProxyLookup<TEntity> | null | undefined): TEntity | undefined;
+  /**
+   * Retrieves all entities from the current entity's proxy relationships.
+   * @template TEntity - The expected entity type.
+   * @param targetType - Reference to the entity type.
+   * @returns The immutable entity instances.
+   */
+  getEntities<TEntity extends IEntity>(targetType: EntityProxyManyLookup<TEntity> | null | undefined): Readonly<TEntity[]>;
   /**
    * Enqueues an entity for update.
    * Triggers the update pipeline for the entity.
@@ -377,30 +521,6 @@ interface ISystemContextScheduler {
   hasSchedule(target?: IEntityProxy): boolean;
 }
 //#endregion
-//#region src/utils/json-serializer.d.ts
-/**
- * Custom JSON serialization and deserialization interface.
- * Allows different serialization strategies for handling complex types.
- * Used for entity snapshots, events, and any data needing JSON conversion.
- */
-interface IJsonSerializer {
-  /**
-   * Converts an object to a serializable JSON representation.
-   * Handles types that don't serialize naturally (dates, maps, custom objects, etc.).
-   * @param value - The object to serialize.
-   * @returns A JSON-serializable representation.
-   */
-  serializeCustom(value: object): string;
-  /**
-   * Converts a JSON string back to its original object type.
-   * Reconstructs complex types from their serialized form.
-   * @template TObject - The target object type.
-   * @param text - The JSON string to deserialize.
-   * @returns The deserialized object of the specified type.
-   */
-  parseCustom<TObject>(text: string): TObject;
-}
-//#endregion
 //#region src/systems/pipeline/system-context-snapshot.d.ts
 /**
  * System context API for entity serialization and state transfer.
@@ -452,7 +572,7 @@ interface ISystemContext<TEntity extends IEntity> extends IPipelineContext {
   /**
    * The entity currently being processed by this middleware.
    */
-  readonly entity: TEntity;
+  readonly entity: Immutable<TEntity>;
   /**
    * Config metadata and config-update API for the current update.
    */
@@ -513,9 +633,7 @@ interface IMutableSystemContext<TEntity extends IEntity> extends ISystemContext<
 //#endregion
 //#region src/factories/context-factory.d.ts
 interface IContextFactory {
-  getOrCreateContext<TEntity extends IEntity>(entity: TEntity, registry?: MiddlewareRegistryReadonly): IMutableSystemContext<TEntity>;
-  getContext<TEntity extends IEntity>(entityUid: EntityUid): IMutableSystemContext<TEntity> | undefined;
-  disposeEntity(entityUid: EntityUid): void;
+  createContext<TEntity extends IEntity>(entity: Immutable<TEntity>, registry?: MiddlewareRegistryReadonly): IMutableSystemContext<TEntity>;
 }
 //#endregion
 //#region src/factories/pipeline-factory.d.ts
@@ -559,117 +677,6 @@ interface IPipelineFactory {
   createPipeline<TContext extends IPipelineContext>(options?: PipelineOptions): IPipeline<TContext>;
 }
 //#endregion
-//#region src/utils/dispatch-sequential.d.ts
-/**
- * Executes a function for each item in an iterable, sequentially.
- *
- * Uses a sync fast-path: iterates synchronously until the first Promise is
- * encountered, then switches to async for the remainder. If no item produces
- * a Promise, the entire call stays synchronous with zero async overhead.
- *
- * @param items - The iterable to iterate over.
- * @param fn - The function to call for each item. May return void or a Promise.
- * @returns void if all calls were synchronous, or a Promise if any were async.
- */
-declare function dispatchSequential<T>(items: Iterable<T>, fn: (item: T) => void | Promise<void>): void | Promise<void>;
-//#endregion
-//#region src/utils/performance.d.ts
-type TickMetricEntry = {
-  name: string;
-  category: string;
-  totalMs: number;
-  count: number;
-};
-type TickSnapshot = {
-  tickIndex: number;
-  tickDurationMs: number;
-  fps: number;
-  queueSize: number;
-  timestamp: number;
-  metrics: TickMetricEntry[];
-  render?: RenderSnapshot;
-};
-type RenderSnapshot = {
-  frameTimeMs: number;
-  renderTimeMs: number;
-  gpuFrameTimeMs: number;
-  drawCalls: number;
-  activeMeshesEvalMs: number;
-  cameraRenderMs: number;
-  totalVertices: number;
-  activeIndices: number;
-};
-type MiddlewareMetricsSummary = {
-  name: string;
-  category: PipelineCategoryName;
-  count: number;
-  totalMs: number;
-  avgMs: number;
-  minMs: number;
-  maxMs: number;
-  lastMs: number;
-};
-//#endregion
-//#region src/utils/performance-timer.d.ts
-/**
- * Unique identifier for a timer instance.
- */
-type PerformanceTimerUid = number;
-/**
- * Options for identifying and categorizing performance metrics.
- * Used by pipeline factories and performance decorators.
- */
-type PerformanceMetricOptions = {
-  name?: string;
-  category?: string;
-};
-/**
- * Record of a completed timer measurement.
- * Captures timing information for performance analysis and profiling.
- */
-interface PerformanceTimeEntry {
-  /**
-   * The name identifying this timer.
-   */
-  name: string;
-  /**
-   * The category of this metric (e.g. 'module', 'runtime', 'system').
-   */
-  category?: string;
-  /**
-   * Timestamp in milliseconds when the timer started.
-   */
-  startedAt: number;
-  /**
-   * Timestamp in milliseconds when the timer ended.
-   */
-  endedAt?: number;
-  /**
-   * Duration in milliseconds that elapsed.
-   */
-  msPassed?: number;
-}
-/**
- * Interface for measuring operation duration.
- * Provides start/stop functionality for performance profiling.
- * Used throughout the system to collect timing metrics.
- */
-interface IPerformanceTimer {
-  /**
-   * Starts a new timer.
-   * @param name - Label for this timer (used in results).
-   * @param category - Optional category for grouping metrics.
-   * @returns A unique identifier for this timer instance.
-   */
-  startTimer(name: string, category?: string): PerformanceTimerUid;
-  /**
-   * Stops a timer and returns the recorded metrics.
-   * @param timerUid - The timer identifier returned by startTimer.
-   * @returns Complete timing entry with start, end, and duration.
-   */
-  endTimer(timerUid: PerformanceTimerUid): PerformanceTimeEntry;
-}
-//#endregion
 //#region src/systems/system-type.d.ts
 /**
  * The five phases of entity system execution in each frame.
@@ -721,13 +728,6 @@ interface ISystemsModule<TEntity extends IEntity> {
    * The builder instance used to construct this module.
    */
   readonly builder: ISystemsModuleBuilderReadonly<TEntity>;
-  /**
-   * Optional factory function to initialize new entity instances.
-   * If provided, is called when a new entity of this type is created.
-   * @param model - The initialization model.
-   * @returns The initialized entity.
-   */
-  readonly initEntity?: (model: IEntityModel) => TEntity;
 }
 //#endregion
 //#region src/systems/module/systems-module-builder.d.ts
@@ -753,9 +753,10 @@ interface ISystemsModuleBuilderReadonly<TEntity extends IEntity> {
    */
   readonly scopeRoot: boolean;
   /**
-   * Whether this entity type is a scoped proxy. When initialized, the entity registers itself in the inherited scope, making it resolvable via `context.proxies.get()` by any entity in the same scope.
+   * Whether this entity type is a scoped proxy. When initialized, the entity registers itself in the inherited scope, making it resolvable via `context.proxies.getProxy()` by any entity in the same scope.
    */
   readonly scopedProxy: boolean;
+  readonly entitySpec?: IEntitySpec<TEntity>;
 }
 /**
  * Builder pattern interface for constructing system modules.
@@ -781,13 +782,23 @@ interface ISystemsModuleBuilder<TEntity extends IEntity> extends ISystemsModuleB
   addEventSystems(uid: EntityEventUid, systems: Immutable<ISystemEventMiddleware<TEntity>[]>): this;
   /**
    * Integrates an entire module's pipelines into this builder.
-   * Allows composition of multiple modules into one.
-   * @template TModuleEntity - The module's entity type (must extend current type).
+   *
+   * Composition is gated by structural assignability: the host's `TEntity` must extend
+   * the inner module's `TInner`. In other words, the host entity contract must contain
+   * every field the inner module reads from `context.entity`.
+   *
+   * @template TInner - The inner module's entity type; must be assignable from `TEntity`.
    * @param module - The module to integrate.
    * @param systemType - Optional specific pipeline to integrate from module. If omitted, integrates all.
    * @returns This builder for method chaining.
    */
-  addModule<TModuleEntity extends TEntity>(module: ISystemsModule<TModuleEntity>, systemType?: SystemType): this;
+  addModule<TInner extends IEntity>(module: TEntity extends TInner ? ISystemsModule<TInner> : never, systemType?: SystemType): this;
+  /**
+   * Declares this module's entity creation spec. `type` carries the entity type UID;
+   * `init` constructs and returns the entity at first creation. The dispatcher validates
+   * at runtime that the returned entity's `identity.entityType` matches `type`.
+   */
+  setEntity(spec: IEntitySpec<TEntity>): this;
   /**
    * Marks this entity type as a scope root.
    * When initialized, a new scope is auto-generated and all child entities inherit it.
@@ -797,7 +808,7 @@ interface ISystemsModuleBuilder<TEntity extends IEntity> extends ISystemsModuleB
   /**
    * Marks this entity type as a scoped proxy.
    * When initialized, the entity registers itself in the inherited scope,
-   * making it resolvable via `context.proxies.get()` by any entity in the same scope.
+   * making it resolvable via `context.proxies.getProxy()` by any entity in the same scope.
    * @returns This builder for method chaining.
    */
   setScopedProxy(): this;
@@ -819,5 +830,5 @@ interface ISystemsFactory {
   createSystemsModuleBuilder<TEntity extends IEntity>(name: string): ISystemsModuleBuilder<TEntity>;
 }
 //#endregion
-export { ISystemContextControlState as A, ISystemContextConfigReadonly as B, IJsonSerializer as C, IMutableSystemContextEvents as D, ISystemContextProxies as E, MiddlewareRegistry as F, ILoggerOptions as H, MiddlewareRegistryReadonly as I, SystemMiddlewareName as L, SystemContextControlTarget as M, ISystemEventMiddleware as N, ISystemContextEvents as O, ISystemMiddleware as P, SystemModuleName as R, ISystemContextSnapshot as S, ISystemContextRepository as T, LogLevel as U, ILogger as V, PipelineCategoryName as _, SystemType as a, IMutableSystemContext as b, PerformanceTimeEntry as c, RenderSnapshot as d, TickMetricEntry as f, PipelineCategory as g, IPipelineFactory as h, ISystemsModule as i, SystemContextControlState as j, ISystemContextControl as k, PerformanceTimerUid as l, dispatchSequential as m, ISystemsModuleBuilder as n, IPerformanceTimer as o, TickSnapshot as p, ISystemsModuleBuilderReadonly as r, PerformanceMetricOptions as s, ISystemsFactory as t, MiddlewareMetricsSummary as u, PipelineOptions as v, ISystemContextScheduler as w, ISystemContext as x, IContextFactory as y, ISystemContextConfig as z };
-//# sourceMappingURL=index-BOS-47DQ.d.mts.map
+export { ISystemContextConfigReadonly as A, ILoggerOptions as B, ISystemEventMiddleware as C, SystemMiddlewareName as D, MiddlewareRegistryReadonly as E, MiddlewareMetricsSummary as F, IJsonSerializer as H, RenderSnapshot as I, TickMetricEntry as L, PerformanceMetricOptions as M, PerformanceTimeEntry as N, SystemModuleName as O, PerformanceTimerUid as P, TickSnapshot as R, SystemContextControlTarget as S, MiddlewareRegistry as T, dispatchSequential as U, LogLevel as V, IMutableSystemContextEvents as _, SystemType as a, ISystemContextControlState as b, PipelineCategoryName as c, IMutableSystemContext as d, ISystemContext as f, ISystemContextProxies as g, ISystemContextRepository as h, ISystemsModule as i, IPerformanceTimer as j, ISystemContextConfig as k, PipelineOptions as l, ISystemContextScheduler as m, ISystemsModuleBuilder as n, IPipelineFactory as o, ISystemContextSnapshot as p, ISystemsModuleBuilderReadonly as r, PipelineCategory as s, ISystemsFactory as t, IContextFactory as u, ISystemContextEvents as v, ISystemMiddleware as w, SystemContextControlState as x, ISystemContextControl as y, ILogger as z };
+//# sourceMappingURL=index-DGyDijY7.d.mts.map