From 3f114bb68d94c48a53514752d57cb4f01adeaae3 Mon Sep 17 00:00:00 2001 From: "Max P." Date: Sat, 10 May 2025 16:21:16 +0200 Subject: [PATCH] feat(pipeline): add configuration and hooks for pipeline execution - Introduce `IPipelineExecutorConfig` to enable customizable pipeline behavior - Add `IPipelineHooks` interface for tracing and monitoring lifecycle events - Define callback types for pipeline start, step execution, and completion - Export new types and interfaces for broader integration within the system --- src/Interfaces/IPipelineExecutorConfig.ts | 33 +++++++++++++++ src/Interfaces/IPipelineHooks.ts | 36 +++++++++++++++++ src/Interfaces/mod.ts | 2 + src/Types/PipelineHooks.ts | 49 +++++++++++++++++++++++ src/Types/mod.ts | 6 +++ 5 files changed, 126 insertions(+) create mode 100644 src/Interfaces/IPipelineExecutorConfig.ts create mode 100644 src/Interfaces/IPipelineHooks.ts create mode 100644 src/Types/PipelineHooks.ts diff --git a/src/Interfaces/IPipelineExecutorConfig.ts b/src/Interfaces/IPipelineExecutorConfig.ts new file mode 100644 index 0000000..616d716 --- /dev/null +++ b/src/Interfaces/IPipelineExecutorConfig.ts @@ -0,0 +1,33 @@ +import { ResponseDecorator } from '../Types/ResponseDecorator.ts'; +import { IContext } from './IContext.ts'; +import { IHttpErrorHandlers } from './IHttpErrorHandlers.ts'; +import { IPipelineHooks } from './IPipelineHooks.ts'; + +/** + * Configuration object for the PipelineExecutor, defining how to handle + * errors, responses, and tracing hooks. + * + * This allows the execution logic to remain decoupled from kernel-level behavior + * while still supporting custom behavior injection. + * + * @template TContext - The context type propagated during pipeline execution. + */ +export interface IPipelineExecutorConfig { + /** + * Optional function used to transform or decorate the final Response object + * before it is returned to the client. + */ + decorateResponse?: ResponseDecorator; + + /** + * Optional map of error handlers, keyed by HTTP status codes (e.g., 404, 500). + * These handlers are invoked if an error occurs during middleware or handler execution. + */ + errorHandlers?: IHttpErrorHandlers; + + /** + * Optional hooks that allow tracing and lifecycle monitoring during pipeline execution. + * Each hook is called at a specific phase of the middleware/handler lifecycle. + */ + pipelineHooks?: IPipelineHooks; +} diff --git a/src/Interfaces/IPipelineHooks.ts b/src/Interfaces/IPipelineHooks.ts new file mode 100644 index 0000000..32a979a --- /dev/null +++ b/src/Interfaces/IPipelineHooks.ts @@ -0,0 +1,36 @@ +import { + OnPipelineEnd, + OnPipelineStart, + OnStepEnd, + OnStepStart, +} from '../Types/mod.ts'; +import { IContext } from './IContext.ts'; + +/** + * A set of optional hook functions that can be triggered during pipeline execution. + * These hooks allow tracing, performance measurement, and logging to be integrated + * without altering middleware or handler logic. + * + * @template TContext - The custom context type used within the application. + */ +export interface IPipelineHooks { + /** + * Triggered once before any middleware or handler is executed. + */ + onPipelineStart?: OnPipelineStart; + + /** + * Triggered immediately before each middleware or handler runs. + */ + onStepStart?: OnStepStart; + + /** + * Triggered immediately after each middleware or handler has finished executing. + */ + onStepEnd?: OnStepEnd; + + /** + * Triggered after the entire pipeline completes execution. + */ + onPipelineEnd?: OnPipelineEnd; +} diff --git a/src/Interfaces/mod.ts b/src/Interfaces/mod.ts index 7c235d9..67856a0 100644 --- a/src/Interfaces/mod.ts +++ b/src/Interfaces/mod.ts @@ -5,6 +5,8 @@ export type { IHttpErrorHandlers } from './IHttpErrorHandlers.ts'; export type { IHttpKernel } from './IHttpKernel.ts'; export type { IHttpKernelConfig } from './IHttpKernelConfig.ts'; export type { IInternalRoute } from './IInternalRoute.ts'; +export type { IPipelineExecutorConfig } from './IPipelineExecutorConfig.ts'; +export type { IPipelineHooks } from './IPipelineHooks.ts'; export type { IRouteBuilder, IRouteBuilderFactory } from './IRouteBuilder.ts'; export { isDynamicRouteDefinition, diff --git a/src/Types/PipelineHooks.ts b/src/Types/PipelineHooks.ts new file mode 100644 index 0000000..f1b0ce1 --- /dev/null +++ b/src/Types/PipelineHooks.ts @@ -0,0 +1,49 @@ +import { IContext } from '../Interfaces/mod.ts'; + +/** + * A callback invoked when the middleware pipeline starts. + * + * @template TContext - The context type passed throughout the pipeline. + * @param ctx - The context object for the current request. + */ +export type OnPipelineStart = ( + ctx: TContext, +) => void; + +/** + * A callback invoked immediately before a middleware or handler is executed. + * + * @template TContext - The context type passed throughout the pipeline. + * @param name - Optional name of the current middleware or handler, if defined. + * @param ctx - The context object for the current request. + */ +export type OnStepStart = ( + name: string | undefined, + ctx: TContext, +) => void; + +/** + * A callback invoked immediately after a middleware or handler has completed. + * + * @template TContext - The context type passed throughout the pipeline. + * @param name - Optional name of the current middleware or handler, if defined. + * @param ctx - The context object for the current request. + * @param duration - Execution time in milliseconds. + */ +export type OnStepEnd = ( + name: string | undefined, + ctx: TContext, + duration: number, +) => void; + +/** + * A callback invoked after the entire pipeline has completed execution. + * + * @template TContext - The context type passed throughout the pipeline. + * @param ctx - The context object for the current request. + * @param totalDuration - Total execution time of the pipeline in milliseconds. + */ +export type OnPipelineEnd = ( + ctx: TContext, + totalDuration: number, +) => void; diff --git a/src/Types/mod.ts b/src/Types/mod.ts index c159495..98da911 100644 --- a/src/Types/mod.ts +++ b/src/Types/mod.ts @@ -39,6 +39,12 @@ export type { HttpStatusCode } from './HttpStatusCode.ts'; export { isMiddleware } from './Middleware.ts'; export type { Middleware } from './Middleware.ts'; export type { Params } from './Params.ts'; +export type { + OnPipelineEnd, + OnPipelineStart, + OnStepEnd, + OnStepStart, +} from './PipelineHooks.ts'; export type { Query } from './Query.ts'; export type { RegisterRoute } from './RegisterRoute.ts'; export type { ResponseDecorator } from './ResponseDecorator.ts';