@contextjs/routing/api/index.d.ts

Declarative, fast, and extensible route matching for ContextJS applications.

/**
 * @license
 * Copyright ContextJS All Rights Reserved.
 *
 * Use of this source code is governed by an MIT-style license that can be
 * found at https://github.com/contextjs/context/blob/main/LICENSE
 */

import { Dictionary } from "@contextjs/collections";
import "@contextjs/system";

declare module "@contextjs/system" {
    /**
     * Adds routing configuration to the Application interface.
     */
    export interface Application {
        /**
         * The list of routes defined in the application.
         */
        routes: RouteDefinition[];

        /**
         * Configures routing for the application.
         * @returns The current Application instance.
         */
        useRouting(): Application;
    }
}

/**
 * Decorates a method as a route handler.
 * @param template The URL template for the route.
 * @param name The name of the route (optional).
 */
export declare function Route(template: string, name?: string): MethodDecorator;

/**
 * Represents a route with a URL template and optional name.
 */
export declare class RouteInfo {
    /** The route's URL template (e.g., "home/{id}"). */
    public readonly template: string;

    /** The route's name, or null if unnamed. */
    public readonly name: string | null;

    /** The decoded version of the route's template.*/
    public readonly decodedTemplate: string;

    /**
     * Creates a new route.
     * @param template The route's URL template.
     * @param name The route's name.
     */
    public constructor(template: string, name?: string | null);
}

/**
 * Represents a route definition, including the import path, class reference, method name, and route information.
 */
export class RouteDefinition<T extends RouteInfo = RouteInfo> {
    /**
     * The class name of the route handler, or null if not applicable.
     * This is typically used for class-based controllers.
     */
    public readonly className: string | null;

    /**
     * The method name of the route handler, or null if not applicable.
     * This is typically used for class-based controllers.
     */
    public readonly methodName: string | null;

    /**
     * The route information, which includes the URL template and name.
     */
    public readonly route: T;

    /**
     * Creates a new route definition.
     * @param className The class name of the route handler, or null if not applicable.
     * @param methodName The method name of the route handler, or null if not applicable.
     * @param route The route information.
     */
    public constructor(className: string | null, methodName: string | null, route: T);
}

/**
 * Represents a parsed route, including the route definition and any parameters extracted from the path.
 */
export declare class ParsedRoute {
    /**
     * The route definition that was matched.
     */
    public readonly definition: RouteDefinition;

    /**
     * The parameters extracted from the route path.
     * This is a dictionary where keys are parameter names and values are their corresponding values.
     */
    public readonly parameters: Dictionary<string, any>;

    /**
     * Creates a new parsed route.
     * @param definition The route definition that was matched.
     * @param parameters The parameters extracted from the route path.
     */
    public constructor(definition: RouteDefinition, parameters: Dictionary<string, any>);
}

/**
 * Provides matching logic to resolve a route from a path.
 */
export declare class RouteService {
    /**
     * Finds the best matching route for a given path.
     * @param value The request path (e.g., "home/123").
     * @param routes The available route definitions to match against.
     * @returns The matching ParsedRoute, or null if no match is found.
     */
    public static match(value: string, routes: RouteDefinition[]): ParsedRoute | null;

    /**
     * Splits a raw request path into normalized segments.
     * @param value The raw request path.
     */
    public static getSegments(value: string): string[];
}