From 67ebb4307a2a1c588b78f8f0c498d1a4276ad09b Mon Sep 17 00:00:00 2001 From: "Max P." Date: Tue, 27 May 2025 14:49:15 +0200 Subject: [PATCH] feat(interfaces): add runRoute method to IInternalRoute - Introduces a statically compiled `runRoute` method to encapsulate the middleware chain and final handler execution for routes. - Ensures consistent pipeline execution with safeguards like single `next()` invocation and a guaranteed `Response` return type. --- src/Interfaces/IInternalRoute.ts | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/src/Interfaces/IInternalRoute.ts b/src/Interfaces/IInternalRoute.ts index 7fc7d66..fd3e33f 100644 --- a/src/Interfaces/IInternalRoute.ts +++ b/src/Interfaces/IInternalRoute.ts @@ -36,4 +36,29 @@ export interface IInternalRoute { * The final handler that generates the HTTP response after all middleware has run. */ handler: Handler; + + /** + * The fully compiled execution pipeline for this route. + * + * This function is generated at route registration time and encapsulates the + * entire middleware chain as well as the final handler. It is called by the + * HttpKernel during request dispatch when a route has been matched. + * + * Internally, `runRoute` ensures that each middleware is invoked in the correct order + * and receives a `next()` callback to pass control downstream. The final handler is + * invoked once all middleware has completed or short-circuited the pipeline. + * + * It is guaranteed that: + * - The function is statically compiled and does not perform dynamic dispatching. + * - Each middleware can only call `next()` once; repeated invocations will throw. + * - The return value is either a `Response` or a Promise resolving to one. + * + * @param ctx - The context object carrying route, request, response and other scoped data. + * @returns A `Response` object or a Promise resolving to a `Response`. + * + * @throws {Error} If a middleware calls `next()` more than once. + */ + runRoute: ( + ctx: TContext, + ) => Promise | Response; }