@awesome-ecs/abstract 0.21.0 → 0.21.1

package/dist/index-Cm-YSPhK.d.ts

@@ -0,0 +1,254 @@
+import { Immutable } from "./types-yh4pOGEm.js";
+import { PerformanceTimeEntry } from "./index-oenqxDCa.js";
+
+//#region src/pipelines/pipeline-status.d.ts
+
+/**
+ * The PipelineStatus enum represents the different states a pipeline can be in.
+ *
+ * @remarks
+ * This enum is used to track the current status of the pipeline.
+ */
+declare enum PipelineStatus {
+  /**
+   * The pipeline is currently idle and not processing any tasks.
+   */
+  idle = "idle",
+  /**
+   * The pipeline is currently processing tasks.
+   */
+  ongoing = "ongoing",
+  /**
+   * The pipeline has completed all tasks successfully.
+   */
+  completed = "completed",
+  /**
+   * The pipeline has been halted due to an error or middleware intervention.
+   */
+  halted = "halted",
+}
+//#endregion
+//#region src/pipelines/pipeline-context.d.ts
+/**
+ * The Pipeline Context allows exposing state to the Pipeline's middlewares.
+ */
+interface IPipelineContext {
+  /**
+   * The runtime state of the pipeline.
+   */
+  readonly runtime?: PipelineRuntime;
+}
+/**
+ * The Pipeline Runtime exposes runtime status controls for Middlewares, as part of the PipelineContext.
+ * It allows controlling the pipeline's execution flow.
+ */
+type PipelineRuntime = {
+  /**
+   * A flag indicating whether the pipeline should stop executing.
+   * If true, the pipeline execution will be stopped.
+   */
+  shouldStop: boolean;
+  /**
+   * The current status of the pipeline.
+   * It can be undefined if the status is not set.
+   */
+  status?: PipelineStatus;
+  /**
+   * An optional error that occurred during the pipeline operation.
+   */
+  error?: any;
+};
+//#endregion
+//#region src/pipelines/pipeline-result.d.ts
+/**
+ * Represents the result of a pipeline operation.
+ * It can provide performance metrics collected from self or inner middleware & pipeline calls.
+ */
+type PipelineResult = {
+  /**
+   * Performance metrics collected from the current pipeline operation.
+   * This field is optional and can be `undefined` if no performance metrics were collected.
+   */
+  readonly performance?: PerformanceTimeEntry;
+  /**
+   * An array of results from inner middleware & pipeline calls.
+   * This field is optional and can be `undefined` if there were no inner calls.
+   */
+  readonly inner?: PipelineResult[];
+};
+//#endregion
+//#region src/pipelines/middleware.d.ts
+/**
+ * A middleware, the building block of a Pipeline. Middlewares will provide a unit-of-work implementation
+ * dealing with potential state changes over the input Context, or running cleanup logic over the input Context.
+ *
+ * @template TContext The type of the context that the middleware will operate on.
+ * @template TResult The type of the result that the middleware will return.
+ */
+interface IMiddleware<TContext extends IPipelineContext> {
+  /**
+   * An optional name for the middleware.
+   */
+  readonly name?: string;
+  /**
+   * This optional function gets called before executing the middleware. It acts as a boolean gateway whether enough conditions are
+   * being met so this middleware's action should run.
+   *
+   * @param context The Context to determine whether the run condition is satisfied.
+   * @returns A boolean indicating whether the middleware should run.
+   */
+  shouldRun?(context: TContext): boolean;
+  /**
+   * The function gets called as part of the pipeline, based on the registration order.
+   *
+   * @param context The Context can be read or updated. The Context holds all the state necessary for the execution of the middleware.
+   * @returns The result of the middleware's action.
+   */
+  action(context: TContext): void | PipelineResult;
+  /**
+   * This optional function gets called when the cleanup of the Pipeline is necessary, based on reverse order of Middleware registration.
+   *
+   * @param context Part of the Context should be cleaned, and any allocated resources in the Action, should be disposed.
+   * @returns The result of the middleware's cleanup.
+   */
+  cleanup?(context: TContext): void | PipelineResult;
+}
+//#endregion
+//#region src/pipelines/middleware-runner.d.ts
+/**
+ * The `IMiddlewareRunner` interface allows for custom logic when running an {@link IMiddleware} method.
+ * It's useful for implementing different `Decorators` to compose extensible runtime logic.
+ *
+ * @template TContext The type of the context that will be passed to the middleware methods.
+ */
+interface IMiddlewareRunner<TContext extends IPipelineContext> {
+  /**
+   * The `dispatch` method decides how to run the {@link IMiddleware.action} method on the provided {@link IMiddleware} instance.
+   *
+   * @param context The {@link IPipelineContext} passed to the Middleware's {@link IMiddleware.action} method.
+   * @param middleware The {@link IMiddleware} to call the {@link IMiddleware.action} method on.
+   * @returns A {@link MiddlewareResult} indicating the outcome of the middleware's action.
+   */
+  dispatch(context: TContext, middleware: IMiddleware<TContext>): void | PipelineResult;
+  /**
+   * The `cleanup` method decides how to run the {@link IMiddleware.cleanup} method on the provided {@link IMiddleware} instance.
+   *
+   * @param context The {@link IPipelineContext} passed to the Middleware's {@link IMiddleware.cleanup} method.
+   * @param middleware The {@link IMiddleware} to call the {@link IMiddleware.cleanup} method on.
+   * @returns A {@link MiddlewareResult} indicating the outcome of the middleware's cleanup.
+   */
+  cleanup(context: TContext, middleware: IMiddleware<TContext>): void | PipelineResult;
+}
+//#endregion
+//#region src/pipelines/pipeline.d.ts
+/**
+ * An interface representing a middleware container and dispatcher.
+ * It allows registering and executing middleware functions in a pipeline.
+ *
+ * @template TContext - The type of the context object that will be passed to each middleware function.
+ * @template TResult - The type of the result that each middleware function will return.
+ *                     Defaults to {@link MiddlewareResult}.
+ */
+interface IPipeline<TContext extends IPipelineContext> {
+  /**
+   * Represents the name of the pipeline.
+   * This property is optional and can be used for debugging purposes.
+   */
+  readonly name?: string;
+  /**
+   * Represents the number of middleware functions registered in the pipeline.
+   * This property is optional.
+   */
+  readonly length?: number;
+  /**
+   * Represents the middleware functions registered in the pipeline.
+   * This property is optional.
+   */
+  readonly middleware?: Immutable<IMiddleware<TContext>[]>;
+  /**
+   * Register middleware for this pipeline.
+   *
+   * @param middleware - The middleware function to be added to the pipeline.
+   * @returns This instance of the pipeline, allowing for method chaining.
+   */
+  use(middleware: Immutable<IMiddleware<TContext>>): this;
+  /**
+   * Execute the Dispatch phase on the chain of middleware, with the given Context.
+   * The Dispatch phase is responsible for invoking the middleware functions in the pipeline.
+   *
+   * @param context - The context object that will be passed to each middleware function.
+   * @returns A {@link PipelineResult} object representing the result of the pipeline execution.
+   */
+  dispatch(context: Partial<TContext>): PipelineResult;
+  /**
+   * Execute the Cleanup phase on the chain of middleware, with the given Context.
+   * The Cleanup phase is responsible for performing any necessary cleanup operations after the pipeline execution.
+   *
+   * @param context - The context object that will be passed to each middleware function.
+   * @returns A {@link PipelineResult} object representing the result of the cleanup execution.
+   */
+  cleanup(context: Partial<TContext>): PipelineResult;
+}
+//#endregion
+//#region src/pipelines/pipeline-nested.d.ts
+/**
+ * A context that is passed to a parent pipeline in a nested setup.
+ *
+ * @template N - The context type of the nested pipeline.
+ */
+interface IParentContext<N extends IPipelineContext> extends IPipelineContext {
+  readonly nestedPipeline: IPipeline<INestedContext<this>>;
+  readonly nestedContexts: Partial<N>[];
+}
+/**
+ * A context that is passed to a nested pipeline.
+ *
+ * @template P - The context type of the parent pipeline.
+ */
+interface INestedContext<P extends IParentContext<any>> extends IPipelineContext {
+  readonly current: P extends IParentContext<infer N> ? N : never;
+  readonly previous?: P extends IParentContext<infer N> ? N : never;
+  readonly parent: P;
+}
+/**
+ * A middleware that is ran as part of a nested pipeline.
+ *
+ * @template P - The context type of the parent pipeline.
+ */
+type INestedMiddleware<P extends IParentContext<any>> = IMiddleware<INestedContext<P>>;
+/**
+ * A middleware that is ran as part of a parent pipeline.
+ *
+ * @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
+/**
+ * The `Pipeline Runner` allows for custom logic when running an {@link IMiddleware} Array.
+ * It's useful for implementing different `Decorators` to compose extensible runtime logic.
+ */
+interface IPipelineRunner<TContext extends IPipelineContext> {
+  /**
+   * The {@link dispatch} method will decide how to run the {@link IMiddleware.action} method on the provided {@link IMiddleware} instances, starting with the provided {@link startIndex} (optional).
+   *
+   * @param context - The {@link IPipelineContext} passed to the Middleware's {@link IMiddleware.action} method.
+   * @param middleware - The {@link IMiddleware} Array to call the {@link IMiddleware.action} methods on.
+   * @param startIndex - (optional) the Start Index to run in the Middleware Array.
+   *
+   * @returns A {@link PipelineResult} indicating the success or failure of the operation.
+   */
+  dispatch(context: Partial<TContext>, middleware: IMiddleware<TContext>[], startIndex?: number): PipelineResult;
+  /**
+   * The {@link cleanup} method will decide how to run the {@link IMiddleware.cleanup} method on the provided {@link IMiddleware} instances.
+   *
+   * @param context - The {@link IPipelineContext} passed to the Middleware's {@link IMiddleware.cleanup} method.
+   * @param middleware - The {@link IMiddleware} Array to call the {@link IMiddleware.cleanup} methods on.
+   *
+   * @returns A {@link PipelineResult} indicating the success or failure of the operation.
+   */
+  cleanup(context: Partial<TContext>, middleware: IMiddleware<TContext>[]): PipelineResult;
+}
+//#endregion
+export { IMiddleware, IMiddlewareRunner, INestedContext, INestedMiddleware, IParentContext, IParentMiddleware, IPipeline, IPipelineContext, IPipelineRunner, PipelineResult, PipelineRuntime, PipelineStatus };
+//# sourceMappingURL=index-Cm-YSPhK.d.ts.map

package/dist/index-D81Fo9XN.d.cts

@@ -0,0 +1,254 @@
+import { Immutable } from "./types-DvzdpbLu.cjs";
+import { PerformanceTimeEntry } from "./index-ChV4Q5j6.cjs";
+
+//#region src/pipelines/pipeline-status.d.ts
+
+/**
+ * The PipelineStatus enum represents the different states a pipeline can be in.
+ *
+ * @remarks
+ * This enum is used to track the current status of the pipeline.
+ */
+declare enum PipelineStatus {
+  /**
+   * The pipeline is currently idle and not processing any tasks.
+   */
+  idle = "idle",
+  /**
+   * The pipeline is currently processing tasks.
+   */
+  ongoing = "ongoing",
+  /**
+   * The pipeline has completed all tasks successfully.
+   */
+  completed = "completed",
+  /**
+   * The pipeline has been halted due to an error or middleware intervention.
+   */
+  halted = "halted",
+}
+//#endregion
+//#region src/pipelines/pipeline-context.d.ts
+/**
+ * The Pipeline Context allows exposing state to the Pipeline's middlewares.
+ */
+interface IPipelineContext {
+  /**
+   * The runtime state of the pipeline.
+   */
+  readonly runtime?: PipelineRuntime;
+}
+/**
+ * The Pipeline Runtime exposes runtime status controls for Middlewares, as part of the PipelineContext.
+ * It allows controlling the pipeline's execution flow.
+ */
+type PipelineRuntime = {
+  /**
+   * A flag indicating whether the pipeline should stop executing.
+   * If true, the pipeline execution will be stopped.
+   */
+  shouldStop: boolean;
+  /**
+   * The current status of the pipeline.
+   * It can be undefined if the status is not set.
+   */
+  status?: PipelineStatus;
+  /**
+   * An optional error that occurred during the pipeline operation.
+   */
+  error?: any;
+};
+//#endregion
+//#region src/pipelines/pipeline-result.d.ts
+/**
+ * Represents the result of a pipeline operation.
+ * It can provide performance metrics collected from self or inner middleware & pipeline calls.
+ */
+type PipelineResult = {
+  /**
+   * Performance metrics collected from the current pipeline operation.
+   * This field is optional and can be `undefined` if no performance metrics were collected.
+   */
+  readonly performance?: PerformanceTimeEntry;
+  /**
+   * An array of results from inner middleware & pipeline calls.
+   * This field is optional and can be `undefined` if there were no inner calls.
+   */
+  readonly inner?: PipelineResult[];
+};
+//#endregion
+//#region src/pipelines/middleware.d.ts
+/**
+ * A middleware, the building block of a Pipeline. Middlewares will provide a unit-of-work implementation
+ * dealing with potential state changes over the input Context, or running cleanup logic over the input Context.
+ *
+ * @template TContext The type of the context that the middleware will operate on.
+ * @template TResult The type of the result that the middleware will return.
+ */
+interface IMiddleware<TContext extends IPipelineContext> {
+  /**
+   * An optional name for the middleware.
+   */
+  readonly name?: string;
+  /**
+   * This optional function gets called before executing the middleware. It acts as a boolean gateway whether enough conditions are
+   * being met so this middleware's action should run.
+   *
+   * @param context The Context to determine whether the run condition is satisfied.
+   * @returns A boolean indicating whether the middleware should run.
+   */
+  shouldRun?(context: TContext): boolean;
+  /**
+   * The function gets called as part of the pipeline, based on the registration order.
+   *
+   * @param context The Context can be read or updated. The Context holds all the state necessary for the execution of the middleware.
+   * @returns The result of the middleware's action.
+   */
+  action(context: TContext): void | PipelineResult;
+  /**
+   * This optional function gets called when the cleanup of the Pipeline is necessary, based on reverse order of Middleware registration.
+   *
+   * @param context Part of the Context should be cleaned, and any allocated resources in the Action, should be disposed.
+   * @returns The result of the middleware's cleanup.
+   */
+  cleanup?(context: TContext): void | PipelineResult;
+}
+//#endregion
+//#region src/pipelines/middleware-runner.d.ts
+/**
+ * The `IMiddlewareRunner` interface allows for custom logic when running an {@link IMiddleware} method.
+ * It's useful for implementing different `Decorators` to compose extensible runtime logic.
+ *
+ * @template TContext The type of the context that will be passed to the middleware methods.
+ */
+interface IMiddlewareRunner<TContext extends IPipelineContext> {
+  /**
+   * The `dispatch` method decides how to run the {@link IMiddleware.action} method on the provided {@link IMiddleware} instance.
+   *
+   * @param context The {@link IPipelineContext} passed to the Middleware's {@link IMiddleware.action} method.
+   * @param middleware The {@link IMiddleware} to call the {@link IMiddleware.action} method on.
+   * @returns A {@link MiddlewareResult} indicating the outcome of the middleware's action.
+   */
+  dispatch(context: TContext, middleware: IMiddleware<TContext>): void | PipelineResult;
+  /**
+   * The `cleanup` method decides how to run the {@link IMiddleware.cleanup} method on the provided {@link IMiddleware} instance.
+   *
+   * @param context The {@link IPipelineContext} passed to the Middleware's {@link IMiddleware.cleanup} method.
+   * @param middleware The {@link IMiddleware} to call the {@link IMiddleware.cleanup} method on.
+   * @returns A {@link MiddlewareResult} indicating the outcome of the middleware's cleanup.
+   */
+  cleanup(context: TContext, middleware: IMiddleware<TContext>): void | PipelineResult;
+}
+//#endregion
+//#region src/pipelines/pipeline.d.ts
+/**
+ * An interface representing a middleware container and dispatcher.
+ * It allows registering and executing middleware functions in a pipeline.
+ *
+ * @template TContext - The type of the context object that will be passed to each middleware function.
+ * @template TResult - The type of the result that each middleware function will return.
+ *                     Defaults to {@link MiddlewareResult}.
+ */
+interface IPipeline<TContext extends IPipelineContext> {
+  /**
+   * Represents the name of the pipeline.
+   * This property is optional and can be used for debugging purposes.
+   */
+  readonly name?: string;
+  /**
+   * Represents the number of middleware functions registered in the pipeline.
+   * This property is optional.
+   */
+  readonly length?: number;
+  /**
+   * Represents the middleware functions registered in the pipeline.
+   * This property is optional.
+   */
+  readonly middleware?: Immutable<IMiddleware<TContext>[]>;
+  /**
+   * Register middleware for this pipeline.
+   *
+   * @param middleware - The middleware function to be added to the pipeline.
+   * @returns This instance of the pipeline, allowing for method chaining.
+   */
+  use(middleware: Immutable<IMiddleware<TContext>>): this;
+  /**
+   * Execute the Dispatch phase on the chain of middleware, with the given Context.
+   * The Dispatch phase is responsible for invoking the middleware functions in the pipeline.
+   *
+   * @param context - The context object that will be passed to each middleware function.
+   * @returns A {@link PipelineResult} object representing the result of the pipeline execution.
+   */
+  dispatch(context: Partial<TContext>): PipelineResult;
+  /**
+   * Execute the Cleanup phase on the chain of middleware, with the given Context.
+   * The Cleanup phase is responsible for performing any necessary cleanup operations after the pipeline execution.
+   *
+   * @param context - The context object that will be passed to each middleware function.
+   * @returns A {@link PipelineResult} object representing the result of the cleanup execution.
+   */
+  cleanup(context: Partial<TContext>): PipelineResult;
+}
+//#endregion
+//#region src/pipelines/pipeline-nested.d.ts
+/**
+ * A context that is passed to a parent pipeline in a nested setup.
+ *
+ * @template N - The context type of the nested pipeline.
+ */
+interface IParentContext<N extends IPipelineContext> extends IPipelineContext {
+  readonly nestedPipeline: IPipeline<INestedContext<this>>;
+  readonly nestedContexts: Partial<N>[];
+}
+/**
+ * A context that is passed to a nested pipeline.
+ *
+ * @template P - The context type of the parent pipeline.
+ */
+interface INestedContext<P extends IParentContext<any>> extends IPipelineContext {
+  readonly current: P extends IParentContext<infer N> ? N : never;
+  readonly previous?: P extends IParentContext<infer N> ? N : never;
+  readonly parent: P;
+}
+/**
+ * A middleware that is ran as part of a nested pipeline.
+ *
+ * @template P - The context type of the parent pipeline.
+ */
+type INestedMiddleware<P extends IParentContext<any>> = IMiddleware<INestedContext<P>>;
+/**
+ * A middleware that is ran as part of a parent pipeline.
+ *
+ * @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
+/**
+ * The `Pipeline Runner` allows for custom logic when running an {@link IMiddleware} Array.
+ * It's useful for implementing different `Decorators` to compose extensible runtime logic.
+ */
+interface IPipelineRunner<TContext extends IPipelineContext> {
+  /**
+   * The {@link dispatch} method will decide how to run the {@link IMiddleware.action} method on the provided {@link IMiddleware} instances, starting with the provided {@link startIndex} (optional).
+   *
+   * @param context - The {@link IPipelineContext} passed to the Middleware's {@link IMiddleware.action} method.
+   * @param middleware - The {@link IMiddleware} Array to call the {@link IMiddleware.action} methods on.
+   * @param startIndex - (optional) the Start Index to run in the Middleware Array.
+   *
+   * @returns A {@link PipelineResult} indicating the success or failure of the operation.
+   */
+  dispatch(context: Partial<TContext>, middleware: IMiddleware<TContext>[], startIndex?: number): PipelineResult;
+  /**
+   * The {@link cleanup} method will decide how to run the {@link IMiddleware.cleanup} method on the provided {@link IMiddleware} instances.
+   *
+   * @param context - The {@link IPipelineContext} passed to the Middleware's {@link IMiddleware.cleanup} method.
+   * @param middleware - The {@link IMiddleware} Array to call the {@link IMiddleware.cleanup} methods on.
+   *
+   * @returns A {@link PipelineResult} indicating the success or failure of the operation.
+   */
+  cleanup(context: Partial<TContext>, middleware: IMiddleware<TContext>[]): PipelineResult;
+}
+//#endregion
+export { IMiddleware, IMiddlewareRunner, INestedContext, INestedMiddleware, IParentContext, IParentMiddleware, IPipeline, IPipelineContext, IPipelineRunner, PipelineResult, PipelineRuntime, PipelineStatus };
+//# sourceMappingURL=index-D81Fo9XN.d.cts.map