@awesome-ecs/abstract 0.31.0 → 0.32.0

package/dist/{index-BguFn1Xj.d.cts → index-BGLTfuj8.d.cts}

@@ -1,5 +1,19 @@
-import { S as IComponent, _ as IEntityProxy, f as EntityTypeUid, h as IEntityModel, m as IEntity, n as IdentityComponent, p as EntityUid } from "./identity-component-DLDaOTyK.cjs";
+import { _ as ConfigRecord, a as IEntity, c as IEntityProxy, f as ComponentTypeUid, i as EntityUid, n as IdentityComponent, o as IEntityModel, p as IComponent, r as EntityTypeUid } from "./index-C0jDrUBA.cjs";
+import { n as DeepPartial } from "./types-Bbmnq4ni.cjs";
 
+//#region src/entities/entity-config.d.ts
+/**
+ * Config-only entity state update.
+ *
+ * Unlike an entity snapshot, this payload is only for component-backed config
+ * values. Runtime patches the matching component's `config` object after the
+ * regular snapshot payload, then runs the config system phase before the normal
+ * update/render/sync phases.
+ */
+interface IEntityConfigSnapshot<TConfig extends ConfigRecord = ConfigRecord> {
+  readonly components: Record<ComponentTypeUid, DeepPartial<TConfig>>;
+}
+//#endregion
 //#region src/entities/entity-context-cache.d.ts
 /**
  * A generic per-entity key-value store for runtime contexts.
@@ -280,6 +294,12 @@ interface IEntityUpdate {
    * Optional serialized state to apply to the entity.
    */
   readonly snapshot?: IEntitySnapshot;
+  /**
+   * Optional config-only component state to apply to the entity.
+   * When present on an update, the runtime applies it after `snapshot` and
+   * includes the config system phase in the same tick.
+   */
+  readonly config?: IEntityConfigSnapshot;
 }
 /**
  * Queue interface for managing pending entity updates.
@@ -430,7 +450,7 @@ interface IEntityScheduler {
    */
   readonly isPaused: boolean;
   /**
-   * Registers an entity for updates.
+   * Registers or replaces an entity schedule.
    * @param entityProxy - The entity to schedule.
    * @param intervalMs - Update frequency in milliseconds. If omitted, the entity is scheduled per-frame.
    */
@@ -470,5 +490,5 @@ interface IEntityScheduler {
   resume(): void;
 }
 //#endregion
-export { IEntityContextCache as _, EntityUpdateType as a, IEntitySnapshot as c, EntityEventSubscriptionOptions as d, EntityEventUid as f, IEventData as g, IEntityEventsManager as h, IEntityRepository as i, IEntitySnapshotProvider as l, IEntityEventsDispatcher as m, IEntityScheduler as n, IEntityUpdate as o, IEntityEvent as p, SchedulerPauseType as r, IEntityUpdateQueue as s, EntitySchedule as t, EntityEventSubscriptionFilter as u };
-//# sourceMappingURL=index-BguFn1Xj.d.cts.map
+export { IEntityContextCache as _, EntityUpdateType as a, IEntitySnapshot as c, EntityEventSubscriptionOptions as d, EntityEventUid as f, IEventData as g, IEntityEventsManager as h, IEntityRepository as i, IEntitySnapshotProvider as l, IEntityEventsDispatcher as m, IEntityScheduler as n, IEntityUpdate as o, IEntityEvent as p, SchedulerPauseType as r, IEntityUpdateQueue as s, EntitySchedule as t, EntityEventSubscriptionFilter as u, IEntityConfigSnapshot as v };
+//# sourceMappingURL=index-BGLTfuj8.d.cts.map

package/dist/{identity-component-CuWHf7jX.d.mts → index-C0jDrUBA.d.cts}

@@ -1,3 +1,73 @@
+import { r as Immutable } from "./types-Bbmnq4ni.cjs";
+
+//#region src/components/config.d.ts
+/**
+ * Extension point for application-specific config controls.
+ *
+ * Consumers can augment this interface to add extra controls while still
+ * preserving value-aware option typing.
+ *
+ * @example
+ * ```ts
+ * declare module '@awesome-ecs/abstract/components' {
+ *   interface ConfigCustomControlOptions<TValue> {
+ *     slider: NonNullable<TValue> extends number
+ *       ? { readonly min?: number; readonly max?: number; readonly step?: number }
+ *       : never;
+ *   }
+ * }
+ * ```
+ */
+interface ConfigCustomControlOptions<TValue> {}
+/**
+ * A generic configuration object for a component, where keys are config paths and values are the corresponding config values.
+ */
+type ConfigRecord = Record<string, unknown>;
+/**
+ * Defines a single configuration option for a specific key in a component's config record.
+ * If the config value is itself a nested config record, it can include an `inner` array of further config options.
+ */
+type ConfigOption<TConfig extends object> = keyof TConfig & string extends infer K ? K extends keyof TConfig & string ? ConfigOptionForKey<TConfig, K> : never : never;
+type ConfigOptionForKey<TConfig extends object, K extends keyof TConfig & string> = ConfigOptionForValue<NonNullable<TConfig[K]>, K>;
+type ConfigOptionForValue<TValue, K extends string> = ConfigNestedOptionForValue<TValue, K> | ConfigLeafOptionForValue<TValue, K> | ConfigCustomControlOption<TValue, K>;
+type ConfigNestedOptionForValue<TValue, K extends string> = TValue extends readonly unknown[] ? never : TValue extends ((...args: never[]) => unknown) ? never : TValue extends object ? ConfigNestedOption<TValue, K> : never;
+type ConfigLeafOptionForValue<TValue, K extends string> = [TValue] extends [number] ? ConfigNumberOption<K> | ConfigChoiceOption<K, Extract<TValue, ConfigChoiceValue>> : [TValue] extends [boolean] ? ConfigBooleanOption<K> | ConfigChoiceOption<K, Extract<TValue, ConfigChoiceValue>> : [TValue] extends [string] ? ConfigStringOption<K> | ConfigColorOption<K> | ConfigChoiceOption<K, Extract<TValue, ConfigChoiceValue>> : never;
+type ConfigCustomControlOption<TValue, K extends string> = { [TControl in keyof ConfigCustomControlOptions<TValue> & string]: ConfigOptionBase<K> & {
+  readonly control: TControl;
+} & ConfigCustomControlOptions<TValue>[TControl] }[keyof ConfigCustomControlOptions<TValue> & string];
+type ConfigNumberOption<K extends string> = ConfigOptionBase<K> & {
+  readonly control: 'number';
+  readonly min?: number;
+  readonly max?: number;
+  readonly step?: number;
+};
+type ConfigBooleanOption<K extends string> = ConfigOptionBase<K> & {
+  readonly control: 'boolean';
+};
+type ConfigStringOption<K extends string> = ConfigOptionBase<K> & {
+  readonly control: 'string';
+};
+type ConfigColorOption<K extends string> = ConfigOptionBase<K> & {
+  readonly control: 'color';
+};
+type ConfigNestedOption<TValue extends object, K extends string> = ConfigOptionBase<K> & {
+  readonly inner?: ConfigOption<TValue>[];
+};
+type ConfigChoiceOption<K extends string, TValue extends ConfigChoiceValue = ConfigChoiceValue> = ConfigOptionBase<K> & {
+  readonly control: 'select' | 'radio';
+  readonly options: ReadonlyArray<ConfigChoice<TValue>>;
+};
+type ConfigOptionBase<K extends string> = {
+  readonly key: K;
+  readonly label: string;
+  readonly group?: string;
+};
+type ConfigChoice<TValue extends ConfigChoiceValue = ConfigChoiceValue> = {
+  readonly label: string;
+  readonly value: TValue;
+};
+type ConfigChoiceValue = string | number | boolean;
+//#endregion
 //#region src/components/component.d.ts
 type ComponentTypeUid = string | number;
 /**
@@ -39,6 +109,15 @@ interface IComponent {
    */
   load?(targetState: this): void;
 }
+/**
+ * Component variant that exposes live, mutable configuration values.
+ *
+ * `config` is the runtime value object systems read from and config
+ * updates patch into.
+ */
+interface IComponentWithConfig<TConfig extends ConfigRecord> extends IComponent {
+  readonly config: TConfig;
+}
 //#endregion
 //#region src/entities/entity-proxies.d.ts
 /**
@@ -210,74 +289,6 @@ interface IEntity {
   readonly myProxy: Readonly<EntityProxy<this>>;
 }
 //#endregion
-//#region src/utils/types.d.ts
-/**
- * Maps all properties of a type to boolean flags.
- * Useful for feature flags, capability indicators, or boolean option sets.
- *
- * @template T - The type whose properties are mapped to booleans.
- * @example type Features = BooleanProps<{health: any; armor: any}>; // => {health: boolean, armor: boolean}
- */
-type BooleanProps<T> = { [Property in keyof T]: boolean };
-/**
- * Removes readonly modifiers from all properties, making them mutable.
- * One level of immutability removal (see MutableDeep for recursive removal).
- *
- * @template T - The type to make mutable.
- * @example type Mut = Mutable<{readonly x: number}>; // => {x: number}
- */
-type Mutable<T> = { -readonly [K in keyof T]: T[K] };
-/**
- * Recursively removes readonly modifiers from all properties at all nesting levels.
- * Makes entire object graph mutable.
- *
- * @template T - The type to make mutable recursively.
- */
-type MutableDeep<T> = { -readonly [K in keyof T]: Mutable<T[K]> };
-type ImmutablePrimitive = undefined | null | boolean | string | number | Function;
-/**
- * Makes a type fully immutable at the top level only.
- * Primitives and functions remain unchanged.
- * Collections (Array, Map, Set) become readonly.
- * Objects have their properties made readonly.
- *
- * @template T - The type to make immutable.
- * @example type Imm = Immutable<{x: number}>; // => {readonly x: number}
- */
-type Immutable<T> = T extends ImmutablePrimitive ? T : T extends Array<infer U> ? ImmutableArray<U> : T extends Map<infer K, infer V> ? ImmutableMap<K, V> : T extends Set<infer M> ? ImmutableSet<M> : ImmutableObject<T>;
-/**
- * Readonly array variant for use in Immutable type transformation.
- *
- * @template T - Element type of the array.
- */
-type ImmutableArray<T> = ReadonlyArray<Immutable<T>>;
-/**
- * Readonly map variant for use in Immutable type transformation.
- *
- * @template K - Key type of the map.
- * @template V - Value type of the map.
- */
-type ImmutableMap<K, V> = ReadonlyMap<Immutable<K>, Immutable<V>>;
-/**
- * Readonly set variant for use in Immutable type transformation.
- *
- * @template T - Element type of the set.
- */
-type ImmutableSet<T> = ReadonlySet<Immutable<T>>;
-/**
- * Makes all object properties readonly (one level only).
- *
- * @template T - The type to make immutable.
- */
-type ImmutableObject<T> = { readonly [K in keyof T]: T[K] };
-/**
- * Recursively makes all properties readonly at all nesting levels.
- * Provides complete immutability guarantee for the entire object graph.
- *
- * @template T - The type to make deeply immutable.
- */
-type ImmutableObjectDeep<T> = { readonly [K in keyof T]: Immutable<T[K]> };
-//#endregion
 //#region src/components/identity-component.d.ts
 /**
  * The `BasicComponentType` enum defines the types of basic components available.
@@ -316,5 +327,5 @@ interface IdentityComponent<TModel extends IEntityModel> extends IComponent {
   readonly lastUpdated?: Date;
 }
 //#endregion
-export { IComponent as S, IEntityProxy as _, ImmutableArray as a, TypedEntityProxy as b, ImmutableObjectDeep as c, MutableDeep as d, EntityTypeUid as f, EntityProxy as g, IEntityModel as h, Immutable as i, ImmutableSet as l, IEntity as m, IdentityComponent as n, ImmutableMap as o, EntityUid as p, BooleanProps as r, ImmutableObject as s, BasicComponentType as t, Mutable as u, IEntityProxyRepository as v, ComponentTypeUid as x, RequiredProxies as y };
-//# sourceMappingURL=identity-component-CuWHf7jX.d.mts.map
+export { ConfigRecord as _, IEntity as a, IEntityProxy as c, TypedEntityProxy as d, ComponentTypeUid as f, ConfigOption as g, ConfigCustomControlOptions as h, EntityUid as i, IEntityProxyRepository as l, IComponentWithConfig as m, IdentityComponent as n, IEntityModel as o, IComponent as p, EntityTypeUid as r, EntityProxy as s, BasicComponentType as t, RequiredProxies as u };
+//# sourceMappingURL=index-C0jDrUBA.d.cts.map

package/dist/{index-kNcUiDBd.d.mts → index-C1hRAjM-.d.mts}

@@ -1,5 +1,19 @@
-import { S as IComponent, _ as IEntityProxy, f as EntityTypeUid, h as IEntityModel, m as IEntity, n as IdentityComponent, p as EntityUid } from "./identity-component-CuWHf7jX.mjs";
+import { _ as ConfigRecord, a as IEntity, c as IEntityProxy, f as ComponentTypeUid, i as EntityUid, n as IdentityComponent, o as IEntityModel, p as IComponent, r as EntityTypeUid } from "./index-b5BtWAvO.mjs";
+import { n as DeepPartial } from "./types-C1ojaDL4.mjs";
 
+//#region src/entities/entity-config.d.ts
+/**
+ * Config-only entity state update.
+ *
+ * Unlike an entity snapshot, this payload is only for component-backed config
+ * values. Runtime patches the matching component's `config` object after the
+ * regular snapshot payload, then runs the config system phase before the normal
+ * update/render/sync phases.
+ */
+interface IEntityConfigSnapshot<TConfig extends ConfigRecord = ConfigRecord> {
+  readonly components: Record<ComponentTypeUid, DeepPartial<TConfig>>;
+}
+//#endregion
 //#region src/entities/entity-context-cache.d.ts
 /**
  * A generic per-entity key-value store for runtime contexts.
@@ -280,6 +294,12 @@ interface IEntityUpdate {
    * Optional serialized state to apply to the entity.
    */
   readonly snapshot?: IEntitySnapshot;
+  /**
+   * Optional config-only component state to apply to the entity.
+   * When present on an update, the runtime applies it after `snapshot` and
+   * includes the config system phase in the same tick.
+   */
+  readonly config?: IEntityConfigSnapshot;
 }
 /**
  * Queue interface for managing pending entity updates.
@@ -430,7 +450,7 @@ interface IEntityScheduler {
    */
   readonly isPaused: boolean;
   /**
-   * Registers an entity for updates.
+   * Registers or replaces an entity schedule.
    * @param entityProxy - The entity to schedule.
    * @param intervalMs - Update frequency in milliseconds. If omitted, the entity is scheduled per-frame.
    */
@@ -470,5 +490,5 @@ interface IEntityScheduler {
   resume(): void;
 }
 //#endregion
-export { IEntityContextCache as _, EntityUpdateType as a, IEntitySnapshot as c, EntityEventSubscriptionOptions as d, EntityEventUid as f, IEventData as g, IEntityEventsManager as h, IEntityRepository as i, IEntitySnapshotProvider as l, IEntityEventsDispatcher as m, IEntityScheduler as n, IEntityUpdate as o, IEntityEvent as p, SchedulerPauseType as r, IEntityUpdateQueue as s, EntitySchedule as t, EntityEventSubscriptionFilter as u };
-//# sourceMappingURL=index-kNcUiDBd.d.mts.map
+export { IEntityContextCache as _, EntityUpdateType as a, IEntitySnapshot as c, EntityEventSubscriptionOptions as d, EntityEventUid as f, IEventData as g, IEntityEventsManager as h, IEntityRepository as i, IEntitySnapshotProvider as l, IEntityEventsDispatcher as m, IEntityScheduler as n, IEntityUpdate as o, IEntityEvent as p, SchedulerPauseType as r, IEntityUpdateQueue as s, EntitySchedule as t, EntityEventSubscriptionFilter as u, IEntityConfigSnapshot as v };
+//# sourceMappingURL=index-C1hRAjM-.d.mts.map

package/dist/index-CeqaKmWR.d.mts

@@ -0,0 +1,218 @@
+import { r as Immutable } from "./types-C1ojaDL4.mjs";
+
+//#region src/pipelines/pipeline-context.d.ts
+/**
+ * Base interface for all pipeline context objects.
+ * Provides hooks for runtime state and control flow during pipeline execution.
+ */
+interface IPipelineContext {
+  /**
+   * The runtime state and control interface for the pipeline.
+   * Allows middleware to query and influence pipeline behavior.
+   */
+  readonly runtime?: PipelineRuntime;
+}
+/**
+ * Runtime state and control interface for pipeline execution.
+ * Allows middleware to query status and influence pipeline flow.
+ */
+type PipelineRuntime = {
+  /**
+   * Flag to request pipeline halt.
+   * Set to true to stop executing remaining middleware (cleanup still runs).
+   */
+  shouldStop?: boolean;
+  /**
+   * Optional error state if an exception occurred during execution.
+   */
+  error?: any;
+};
+//#endregion
+//#region src/pipelines/middleware.d.ts
+/**
+ * The basic unit of work in a pipeline.
+ * Middleware are chained together to form processing pipelines.
+ * Each middleware can inspect/modify context during dispatch and perform cleanup on their changes.
+ *
+ * @template TContext The context type passed through the middleware chain.
+ */
+interface IMiddleware<TContext extends IPipelineContext> {
+  /**
+   * Optional name for debugging and logging purposes.
+   */
+  readonly name?: string;
+  /**
+   * Optional guard condition before running the action.
+   * Allows middleware to skip execution based on context state.
+   * @param context The current pipeline context.
+   * @returns True to execute action, false to skip.
+   */
+  shouldRun?(context: TContext): boolean;
+  /**
+   * The main unit of work executed as part of the pipeline.
+   * Middlewares execute in registration order during dispatch phase.
+   * Can read and modify the context to influence downstream middleware and results.
+   * @param context The pipeline context containing all relevant state.
+   */
+  action(context: TContext): void | Promise<void>;
+  /**
+   * Optional cleanup function executed during pipeline teardown.
+   * Middlewares execute in reverse registration order during cleanup phase.
+   * Used to release resources, clear temporary state, and perform final operations.
+   * @param context The pipeline context (may be in modified state from action phases).
+   */
+  cleanup?(context: TContext): void | Promise<void>;
+}
+//#endregion
+//#region src/pipelines/middleware-runner.d.ts
+/**
+ * Customizes how middleware is executed within a pipeline.
+ * Allows decorators to wrap, intercept, or modify middleware execution behavior.
+ * Useful for implementing middleware decorators (logging, timing, error handling, etc.).
+ *
+ * @template TContext The type of context passed to middleware.
+ */
+interface IMiddlewareRunner<TContext extends IPipelineContext> {
+  /**
+   * Decides how to execute a middleware's action.
+   * Can add pre/post processing, error handling, or performance tracking around the middleware.
+   * @param context The current pipeline context.
+   * @param middleware The middleware whose action should be executed.
+   */
+  dispatch(context: TContext, middleware: IMiddleware<TContext>): void | Promise<void>;
+  /**
+   * Decides how to execute a middleware's cleanup.
+   * Can add pre/post processing or error handling around cleanup operations.
+   * @param context The current pipeline context.
+   * @param middleware The middleware whose cleanup should be executed.
+   */
+  cleanup(context: TContext, middleware: IMiddleware<TContext>): void | Promise<void>;
+}
+//#endregion
+//#region src/pipelines/pipeline.d.ts
+/**
+ * A composable middleware chain for ordered execution of operations.
+ * Pipelines provide a framework for registering and executing middleware with dispatch and cleanup phases.
+ * Used throughout the ECS system for entity initialization, updates, rendering, and synchronization.
+ *
+ * @template TContext - The context type passed to all registered middleware.
+ */
+interface IPipeline<TContext extends IPipelineContext> {
+  /**
+   * The pipeline's name, useful for debugging and logging.
+   */
+  readonly name?: string;
+  /**
+   * The number of middleware currently registered in this pipeline.
+   */
+  readonly length?: number;
+  /**
+   * Direct access to the ordered list of registered middleware.
+   * Allows inspection of the execution chain.
+   */
+  readonly middleware?: Immutable<IMiddleware<TContext>[]>;
+  /**
+   * Registers middleware to be executed as part of this pipeline.
+   * Middleware is added to the end of the chain and executed in registration order during dispatch.
+   * @param middleware - The middleware to register.
+   * @returns This instance for method chaining.
+   */
+  use(middleware: Immutable<IMiddleware<TContext>>): this;
+  /**
+   * Executes the dispatch phase with all registered middleware in order.
+   * Each middleware's action is called, allowing modifications to context state.
+   * Execution continues until all middleware complete or a middleware requests early termination.
+   * @param context - The context object passed to all middleware.
+   */
+  dispatch(context: Partial<TContext>): void | Promise<void>;
+  /**
+   * Executes the cleanup phase with all registered middleware in reverse order.
+   * Allows middleware to perform resource cleanup and final operations.
+   * Typically called after dispatch to ensure proper teardown.
+   *
+   * @param context - The context object that will be passed to each middleware function.
+   */
+  cleanup(context: Partial<TContext>): void | Promise<void>;
+}
+//#endregion
+//#region src/pipelines/pipeline-nested.d.ts
+/**
+ * Context for a parent pipeline containing nested pipelines.
+ * Allows coordination between outer and inner pipeline execution.
+ *
+ * @template N - The context type for the nested pipelines.
+ */
+interface IParentContext<N extends IPipelineContext> extends IPipelineContext {
+  /**
+   * The nested pipeline to execute for each context in nestedContexts.
+   */
+  readonly nestedPipeline: IPipeline<INestedContext<this>>;
+  /**
+   * Contexts to pass to the nested pipeline.
+   * The parent pipeline iterates these and executes the nested pipeline for each.
+   */
+  readonly nestedContexts: Partial<N>[];
+}
+/**
+ * Context for a nested pipeline.
+ * Provides access to both current and previous nested context data plus the parent context.
+ *
+ * @template P - The context type of the parent pipeline.
+ */
+interface INestedContext<P extends IParentContext<any>> extends IPipelineContext {
+  /**
+   * The current context item being processed in the nested pipeline.
+   */
+  readonly current: P extends IParentContext<infer N> ? N : never;
+  /**
+   * The previous context item (if this is not the first iteration).
+   */
+  readonly previous?: P extends IParentContext<infer N> ? N : never;
+  /**
+   * Reference back to the parent pipeline context.
+   */
+  readonly parent: P;
+}
+/**
+ * Middleware executing within a nested pipeline.
+ *
+ * @template P - The context type of the parent pipeline.
+ */
+type INestedMiddleware<P extends IParentContext<any>> = IMiddleware<INestedContext<P>>;
+/**
+ * Middleware executing within a parent pipeline (containing nested pipelines).
+ *
+ * @template P - The context type of the parent pipeline.
+ */
+type IParentMiddleware<P extends IParentContext<any>> = IMiddleware<P>;
+//#endregion
+//#region src/pipelines/pipeline-runner.d.ts
+/**
+ * Executes an array of middleware in a controlled sequence.
+ * Supports custom execution strategies through implementation flexibility.
+ * Used by pipelines to manage complex middleware chains with features like early termination and nested pipelines.
+ *
+ * @template TContext - The context type passed to all middleware.
+ */
+interface IPipelineRunner<TContext extends IPipelineContext> {
+  /**
+   * Executes the action phase of all middleware in sequence.
+   * Middleware at startIndex and onward are executed in order.
+   * Execution may terminate early if middleware requests it via context.runtime.shouldStop.
+   * @param context - The context passed to each middleware action.
+   * @param middleware - The ordered middleware array to execute.
+   * @param startIndex - Optional starting position in the middleware array (default: 0).
+   */
+  dispatch(context: Partial<TContext>, middleware: IMiddleware<TContext>[], startIndex?: number): void | Promise<void>;
+  /**
+   * Executes the cleanup phase of all middleware in reverse order.
+   * All middleware cleanup functions are called (if defined), regardless of errors.
+   * Allows proper resource release and final state management.
+   * @param context - The context passed to each middleware cleanup.
+   * @param middleware - The ordered middleware array for cleanup (reversed during execution).
+   */
+  cleanup(context: Partial<TContext>, middleware: IMiddleware<TContext>[]): void | Promise<void>;
+}
+//#endregion
+export { IParentMiddleware as a, IMiddleware as c, IParentContext as i, IPipelineContext as l, INestedContext as n, IPipeline as o, INestedMiddleware as r, IMiddlewareRunner as s, IPipelineRunner as t, PipelineRuntime as u };
+//# sourceMappingURL=index-CeqaKmWR.d.mts.map