import { ExtensionKey, type HttpRequest, type HttpResponse, type HttpResponseLike } from "../http/index.js";
import type { HttpLayer } from "../layer/index.js";
import type { HttpService } from "../service/index.js";
import { type ErrorHandler } from "../util/index.js";
import { type Handler } from "./handler.js";
import type { MethodRouter } from "./method-router.js";
/**
 * Extension key which holds the original URI.
 *
 * This is required as the URI within a `HttpRequest` can be mutated during
 * the request lifecycle.
 */
export declare const ORIGINAL_URI: ExtensionKey<URL>;
/**
 * The Router class is responsible for handling and routing HTTP requests based
 * on specified paths and methods.
 *
 * It allows nesting of sub-routers, adding layers, defining fallback handlers,
 * and processing requests.
 *
 * ## Error Handling
 *
 * Every route and service in Taxum is allowed to be fallible, as throwing
 * errors in an essential part of the application workflow. Taxum ensures that
 * errors never short-circuit the request-response cycle by wrapping each route
 * and every layered route in a `MapErrorToResponse` service.
 *
 * This means that you can safely throw errors from your routes and services,
 * and Taxum will ensure that they are handled properly. By default, Taxum will
 * convert any error into a `500 Internal Server Error` response, unless they
 * implement the `ToHttpResponse` interface, in which case they will be
 * converted to the appropriate response.
 *
 * If an error results in a `5xx` response, Taxum will log the error. Unless
 * changes, this will use the `console`. You can change the error logger by
 * calling {@link setLoggerProxy}.
 *
 * You can also change the error handler to customize the way errors are
 * converted to responses. See {@link Router.errorHandler} for more details.
 */
export declare class Router implements HttpService {
    private pathRouter;
    private catchAllFallback;
    private errorHandler_;
    /**
     * Defines a route for a specified path and associates it with a method
     * router.
     *
     * @param path - the URL path to define the route for.
     * @param methodRouter - the router that handles the methods for the given
     *        path.
     */
    route(path: string, methodRouter: MethodRouter): this;
    /**
     * Nests a given router under a specific path.
     *
     * @param path - the base path where the nested router will be applied.
     * @param router - the router instance to be nested under the specified
     *        path.
     */
    nest(path: string, router: Router): this;
    nestService(path: string, service: HttpService<HttpResponseLike>): this;
    /**
     * Sets a fallback handler for the service.
     *
     * The specified handler will be used as a fallback to handle any requests
     * that do not match existing routes.
     *
     * @param handler - the function to be used as a fallback handler.
     */
    fallback(handler: Handler): this;
    /**
     * Resets the fallback handler to the default.
     */
    resetFallback(): this;
    /**
     * Adds a fallback handler for the case where a route exists, but the method
     * of the request is not supported.
     *
     * Sets a fallback on all previously registered `MethodRouter`s to be called
     * when no matching method handler is set.
     *
     * ```ts
     * const router = new Router()
     *     .route("/", m.get(helloWorld))
     *     .fallback(handle404)
     *     .methodNotAllowedFallback(handle405);
     * ```
     *
     * The fallback only applies if there is a `MethodRouter` registered for a
     * given path, but the method used in the request is not specified. In the
     * example, a `GET` on `/` causes the `helloWorld` handler to react, while
     * issuing a `POST` triggers `handle405`. Calling an entirely different
     * route, like `/hello` causes `handle404` to run.
     */
    methodNotAllowedFallback(handler: Handler): this;
    /**
     * Sets the error handler to convert errors into responses.
     *
     * @see {@link ErrorHandler}
     */
    errorHandler(errorHandler: ErrorHandler): this;
    /**
     * Applies the specified layer to all previously registered routes.
     *
     * @param layer - the layer to be applied to the endpoints.
     */
    layer(layer: HttpLayer<HttpResponseLike>): this;
    /**
     * Applies the specified layer to all previously registered routes.
     */
    routeLayer(layer: HttpLayer<HttpResponseLike>): this;
    /**
     * Makes an asynchronous HTTP call using the provided request object.
     *
     * Routes the request to the appropriate handler and returns the response.
     * If no response is returned from the primary handler, it executes the
     * fallback handler.
     *
     * This function is normally considered internal, but it can be used in
     * unit- and integration testing to avoid spinning up a server.
     *
     * @param req - the HTTP request object containing all necessary details for
     *        the call.
     */
    invoke(req: HttpRequest): Promise<HttpResponse>;
}