@awesome-ecs/abstract/dist/index-Cm-YSPhK.d.ts

A comprehensive Entity-Component-System (ECS) Architecture implementation. Abstract components.

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