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.
This commit is contained in:
2025-05-27 14:49:15 +02:00
parent 3da34e2684
commit 67ebb4307a

View File

@@ -36,4 +36,29 @@ export interface IInternalRoute<TContext extends IContext = IContext> {
* The final handler that generates the HTTP response after all middleware has run. * The final handler that generates the HTTP response after all middleware has run.
*/ */
handler: Handler<TContext>; handler: Handler<TContext>;
/**
* 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> | Response;
} }