Max P.
beadcefc6a
- 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.
65 lines
2.6 KiB
TypeScript
65 lines
2.6 KiB
TypeScript
import type { Handler, HttpMethod, Middleware } from '../Types/mod.ts';
|
|
import type { IContext, IRouteMatcher } from './mod.ts';
|
|
|
|
/**
|
|
* Represents an internally registered route within the HttpKernel.
|
|
*
|
|
* Contains all data required to match an incoming request and dispatch it
|
|
* through the associated middleware chain and final handler.
|
|
*/
|
|
export interface IInternalRoute<TContext extends IContext = IContext> {
|
|
/**
|
|
* The HTTP method (e.g. 'GET', 'POST') that this route responds to.
|
|
* The method should always be in uppercase.
|
|
*/
|
|
method: HttpMethod;
|
|
|
|
/**
|
|
* A matcher function used to determine whether this route matches a given request.
|
|
*
|
|
* If the matcher returns `null`, the route does not apply to the request.
|
|
* If it returns a params object, the route is considered matched and the extracted
|
|
* parameters are passed into the request context.
|
|
*
|
|
* @param url - The parsed URL object from the incoming request.
|
|
* @param req - The original Request object.
|
|
* @returns An object with extracted path parameters, or `null` if not matched.
|
|
*/
|
|
matcher: IRouteMatcher;
|
|
|
|
/**
|
|
* An ordered list of middleware functions to be executed before the handler.
|
|
*/
|
|
middlewares: Middleware<TContext>[];
|
|
|
|
/**
|
|
* The final handler that generates the HTTP response after all middleware has run.
|
|
*/
|
|
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;
|
|
}
|