import { IHandler } from './IHandler.ts';
import { IMiddleware } from './IMiddleware.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 {
    /**
     * The HTTP method (e.g. 'GET', 'POST') that this route responds to.
     * The method should always be in uppercase.
     */
    method: string;

    /**
     * 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: (
        url: URL,
        req: Request,
    ) => null | { params: Record<string, string> };

    /**
     * An ordered list of middleware functions to be executed before the handler.
     */
    middlewares: IMiddleware[];

    /**
     * The final handler that generates the HTTP response after all middleware has run.
     */
    handler: IHandler;
}