From 927a9081d4f363202520d017eb424c7c097ced94 Mon Sep 17 00:00:00 2001
From: "Max P." <mail@0xMax42.io>
Date: Sat, 10 May 2025 16:50:41 +0200
Subject: [PATCH] feat(interfaces): add pipeline executor interface

- Introduce `IPipelineExecutor` to define pipeline execution
- Add `PipelineExecutorFactory` for instantiating pipeline executors
- Export new types in the interfaces module for external use
---
 src/Interfaces/IPipelineExecutor.ts | 50 +++++++++++++++++++++++++++++
 src/Interfaces/mod.ts               |  4 +++
 2 files changed, 54 insertions(+)
 create mode 100644 src/Interfaces/IPipelineExecutor.ts

diff --git a/src/Interfaces/IPipelineExecutor.ts b/src/Interfaces/IPipelineExecutor.ts
new file mode 100644
index 0000000..a25ce09
--- /dev/null
+++ b/src/Interfaces/IPipelineExecutor.ts
@@ -0,0 +1,50 @@
+import { Handler, Middleware } from '../Types/mod.ts';
+import { IContext } from './IContext.ts';
+import { IPipelineExecutorConfig } from './IPipelineExecutorConfig.ts';
+
+/**
+ * Constructor type for a class implementing the IPipelineExecutor interface.
+ *
+ * This can be used for dependency injection, factory-based initialization,
+ * or dynamic instantiation of pipeline executors.
+ *
+ * @template TContext - The extended context type passed through the pipeline.
+ */
+export interface PipelineExecutorFactory<TContext extends IContext = IContext> {
+    /**
+     * Creates a new instance of a pipeline executor.
+     *
+     * @param config - Configuration used to control error handling,
+     *                 response decoration and lifecycle hooks.
+     */
+    new (
+        config: IPipelineExecutorConfig<TContext>,
+    ): IPipelineExecutor<TContext>;
+}
+
+/**
+ * Defines the contract for executing a middleware and handler pipeline.
+ *
+ * The pipeline is responsible for:
+ * - Executing middleware in order with `next()` chaining
+ * - Invoking the final handler
+ * - Applying optional lifecycle hooks
+ * - Producing and decorating a Response
+ *
+ * @template TContext - The context type flowing through the pipeline.
+ */
+export interface IPipelineExecutor<TContext extends IContext = IContext> {
+    /**
+     * Executes the middleware pipeline and returns the final Response.
+     *
+     * @param ctx - The context object representing the current HTTP request state.
+     * @param middleware - An ordered array of middleware functions to be executed.
+     * @param handler - The final route handler to be called after all middleware.
+     * @returns A Promise resolving to the final HTTP Response.
+     */
+    run(
+        ctx: TContext,
+        middleware: Middleware<TContext>[],
+        handler: Handler<TContext>,
+    ): Promise<Response>;
+}
diff --git a/src/Interfaces/mod.ts b/src/Interfaces/mod.ts
index 67856a0..ab31600 100644
--- a/src/Interfaces/mod.ts
+++ b/src/Interfaces/mod.ts
@@ -5,6 +5,10 @@ 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 {
+    IPipelineExecutor,
+    PipelineExecutorFactory,
+} from './IPipelineExecutor.ts';
 export type { IPipelineExecutorConfig } from './IPipelineExecutorConfig.ts';
 export type { IPipelineHooks } from './IPipelineHooks.ts';
 export type { IRouteBuilder, IRouteBuilderFactory } from './IRouteBuilder.ts';