@neabyte/fast-router/dist/index.d.mts

A fast, versatile router with radix tree structure for JavaScript

/**
 * Router context containing the tree structure and static route cache.
 * @template T - Type of data associated with routes
 */
interface RouterContext<T = unknown> {
    /** Root node of the router tree */
    root: RouterNode<T>;
    /** Static route cache for fast lookups */
    static: Record<string, RouterNode<T> | undefined>;
}
/**
 * Result of a successful route match.
 * @template T - Type of data associated with the matched route
 */
interface RouterMatchedRoute<T = unknown> {
    /** Data associated with the matched route */
    data: T;
    /** Extracted route parameters */
    params: Record<string, string> | undefined;
}
/**
 * Method-specific data stored in router nodes.
 * @template T - Type of data associated with routes
 */
interface RouterMethodData<T = unknown> {
    /** Data associated with the route */
    data: T;
    /** Parameter mapping for route segments */
    paramsMap: RouterParamsMap | undefined;
    /** Regular expressions for parameter validation */
    paramsRegexp: RegExp[];
}
/**
 * Node in the router tree structure.
 * @template T - Type of data associated with routes
 */
interface RouterNode<T = unknown> {
    /** Node key/segment value */
    key: string;
    /** Static child nodes */
    static?: Record<string, RouterNode<T>>;
    /** Parameter child node */
    param?: RouterNode<T>;
    /** Wildcard child node */
    wildcard?: RouterNode<T>;
    /** Whether this node has regex parameter validation */
    hasRegexParam?: boolean;
    /** HTTP method handlers */
    methods?: Record<string, RouterMethodData<T>[] | undefined>;
}
/**
 * Parameter mapping array for route segments.
 * Each tuple contains [index, name/regex, optional]
 */
type RouterParamsMap = Array<[Index: number, name: string | RegExp, optional: boolean]>;

/**
 * Router implementation with static route optimization.
 * @description Fast router with radix tree structure for optimized route matching.
 * @template T - Type of data associated with routes
 */
declare class FastRouter<T = unknown> {
    /** Internal router context containing tree structure and static routes */
    private context;
    /**
     * Initialize FastRouter with empty context.
     */
    constructor();
    /**
     * Add a route to the router with optional data and HTTP method.
     * @param method - HTTP method (use '' for any method)
     * @param path - Route path pattern (supports :param, *, ** wildcards)
     * @param data - Optional data to associate with the route
     */
    add(method: string, path: string, data?: T): void;
    /**
     * Find matching route for given path and HTTP method.
     * @param method - HTTP method to match (use '' for any method)
     * @param path - Path to search for
     * @param opts - Search options
     * @param opts.params - Whether to extract parameters (default: true)
     * @returns Matched route data with parameters or undefined if not found
     */
    find(method: string, path: string, opts?: {
        params?: boolean;
    }): RouterMatchedRoute<T> | RouterMethodData<T> | undefined;
    /**
     * Remove a route from the router.
     * @param method - HTTP method to remove (use '' for any method)
     * @param path - Route path pattern to remove
     * @returns true if route was removed, false if route not found
     */
    remove(method: string, path: string): boolean;
    /**
     * Find the node for a given path in the tree.
     * @param segments - Path segments
     * @returns The router node or undefined if not found
     */
    private findNode;
}

export { FastRouter };
export type { RouterContext, RouterMatchedRoute, RouterMethodData, RouterNode, RouterParamsMap };