@nextrush/router 3.0.0

package/dist/index.d.ts

@@ -0,0 +1,301 @@
+import { RouterOptions, RouteHandler, HttpMethod, Middleware, RouteMatch, Context } from '@nextrush/types';
+export { HttpMethod, Middleware, Route, RouteHandler, RouteMatch, Router as RouterInterface, RouterOptions } from '@nextrush/types';
+
+/**
+ * @nextrush/router - Router Implementation
+ *
+ * High-performance router using a segment trie for route matching.
+ * Routes are keyed by full path segments (e.g. "users", ":id"), not by
+ * individual characters — this is a segment-based trie, not a compressed
+ * radix tree. Supports parameters, wildcards, and method-based routing.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Router class — high-performance segment trie router
+ *
+ * Routes are indexed by path segment, giving O(d) lookup where d is the
+ * number of segments. Static routes are additionally stored in a hash map
+ * for O(1) fast-path lookup.
+ *
+ * @example
+ * ```typescript
+ * const router = createRouter();
+ *
+ * router.get('/users', listUsers);
+ * router.get('/users/:id', getUser);
+ * router.post('/users', createUser);
+ *
+ * app.use(router.routes());
+ * ```
+ */
+declare class Router {
+    private readonly root;
+    private readonly opts;
+    private readonly routerMiddleware;
+    /**
+     * Static route hash map for O(1) lookup.
+     * Key: "METHOD path" (e.g. "GET /users"), Value: HandlerEntry
+     */
+    private readonly staticRoutes;
+    /** Whether any routes have params or wildcards (disables static-only fast path) */
+    private hasParamRoutes;
+    constructor(options?: RouterOptions);
+    /**
+     * Normalize path based on router options
+     */
+    private normalizePath;
+    /**
+     * Add a route to the radix tree
+     */
+    private addRoute;
+    get(path: string, ...handlers: RouteHandler[]): this;
+    post(path: string, ...handlers: RouteHandler[]): this;
+    put(path: string, ...handlers: RouteHandler[]): this;
+    delete(path: string, ...handlers: RouteHandler[]): this;
+    patch(path: string, ...handlers: RouteHandler[]): this;
+    head(path: string, ...handlers: RouteHandler[]): this;
+    options(path: string, ...handlers: RouteHandler[]): this;
+    all(path: string, ...handlers: RouteHandler[]): this;
+    route(method: HttpMethod, path: string, ...handlers: RouteHandler[]): this;
+    /**
+     * Register a redirect route from one path to another
+     *
+     * @param from - Source path to redirect from
+     * @param to - Target path or URL to redirect to
+     * @param status - HTTP status code (default: 301 permanent redirect)
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * // Permanent redirect (301)
+     * router.redirect('/old-page', '/new-page');
+     *
+     * // Temporary redirect (302)
+     * router.redirect('/temp', '/destination', 302);
+     *
+     * // Redirect to external URL
+     * router.redirect('/docs', 'https://docs.example.com');
+     *
+     * // With parameters - redirects /users/:id to /profiles/:id
+     * router.redirect('/users/:id', '/profiles/:id');
+     * ```
+     */
+    redirect(from: string, to: string, status?: 301 | 302 | 303 | 307 | 308): this;
+    use(pathOrMiddleware: string | Middleware | Router, routerOrUndefined?: Router): this;
+    /**
+     * Mount a sub-router at a path prefix (Hono-style)
+     *
+     * This is the explicit API for mounting sub-routers.
+     * Equivalent to `router.use(path, subRouter)` but more semantic.
+     *
+     * @param path - Path prefix for the sub-router
+     * @param router - Router instance to mount
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * // Create modular routers
+     * const users = createRouter();
+     * users.get('/', listUsers);
+     * users.get('/:id', getUser);
+     *
+     * const posts = createRouter();
+     * posts.get('/', listPosts);
+     *
+     * // Mount sub-routers
+     * const api = createRouter();
+     * api.mount('/users', users);
+     * api.mount('/posts', posts);
+     *
+     * // Or use on main router
+     * const router = createRouter();
+     * router.mount('/api', api);
+     *
+     * app.use(router.routes());
+     * ```
+     */
+    mount(path: string, router: Router): this;
+    /**
+     * Mount a sub-router (internal)
+     *
+     * Carries the sub-router's own `routerMiddleware` forward so that
+     * `subrouter.use(mw)` middleware applies to every copied route.
+     */
+    private mountRouter;
+    /**
+     * Recursively copy routes from another router
+     */
+    private copyRoutes;
+    /**
+     * Match a route and return handler + params
+     */
+    match(method: HttpMethod, path: string): RouteMatch | null;
+    /**
+     * Extract the next segment from path at given position without allocating arrays.
+     * Returns [segment, nextIndex] where nextIndex is position after the trailing '/'.
+     */
+    private extractSegment;
+    /**
+     * Index-based recursive node matching (avoids array allocation)
+     */
+    private matchNodeIndexed;
+    /**
+     * Get routes middleware function
+     * Mount this on the application
+     *
+     * @example
+     * ```typescript
+     * app.use(router.routes());
+     * ```
+     */
+    routes(): Middleware;
+    /**
+     * Re-compile all route executors to include router-level middleware.
+     * Called once when routes() is invoked, not per-request.
+     */
+    private sealRouterMiddleware;
+    /**
+     * Generate allowed methods middleware
+     * Responds to OPTIONS and sets Allow header
+     */
+    allowedMethods(): Middleware;
+    /**
+     * Find all HTTP methods registered for a given path via single tree walk
+     * @internal
+     */
+    private findAllowedMethods;
+    /**
+     * Walk the tree to find the node matching a path (ignoring HTTP method)
+     * @internal
+     */
+    private findNode;
+    /**
+     * Create a route group with shared prefix and middleware
+     *
+     * @param prefix - Path prefix for all routes in the group
+     * @param middlewareOrCallback - Middleware array or callback function
+     * @param callback - Callback function if middleware is provided
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * // Simple group with prefix
+     * router.group('/api', (r) => {
+     *   r.get('/users', listUsers);
+     *   r.get('/posts', listPosts);
+     * });
+     *
+     * // Group with middleware
+     * router.group('/admin', [authMiddleware], (r) => {
+     *   r.get('/dashboard', dashboard);
+     *   r.post('/settings', updateSettings);
+     * });
+     *
+     * // Nested groups
+     * router.group('/api/v1', (r) => {
+     *   r.group('/users', [rateLimit], (ur) => {
+     *     ur.get('/', listUsers);
+     *     ur.get('/:id', getUser);
+     *   });
+     * });
+     * ```
+     */
+    group(prefix: string, middlewareOrCallback: Middleware[] | ((router: Router) => void), callback?: (router: Router) => void): this;
+    /**
+     * Remove all registered routes and middleware, resetting the router to its initial state.
+     * Useful for plugin `destroy()` to cleanly un-register routes.
+     */
+    reset(): void;
+    /**
+     * Internal method to add route with group context
+     * @internal
+     */
+    _addGroupRoute(method: HttpMethod, path: string, handlers: RouteHandler[], groupMiddleware: Middleware[]): void;
+}
+/**
+ * Create a new Router instance
+ *
+ * @param options - Router options
+ * @returns New Router instance
+ *
+ * @example
+ * ```typescript
+ * const router = createRouter();
+ * const apiRouter = createRouter({ prefix: '/api/v1' });
+ * ```
+ */
+declare function createRouter(options?: RouterOptions): Router;
+
+/**
+ * @nextrush/router - Segment Trie Node
+ *
+ * Internal segment trie implementation for high-performance route matching.
+ * Uses a compressed trie structure for O(k) lookups where k is path length.
+ *
+ * @packageDocumentation
+ * @internal
+ */
+
+/**
+ * Node type enumeration
+ */
+declare const enum NodeType {
+    /** Static path segment: /users */
+    STATIC = 0,
+    /** Named parameter: /:id */
+    PARAM = 1,
+    /** Wildcard: /* */
+    WILDCARD = 2
+}
+/**
+ * Radix tree node
+ */
+interface RadixNode {
+    /** Path segment for this node */
+    segment: string;
+    /** Node type */
+    type: NodeType;
+    /** Children nodes keyed by first character */
+    children: Map<string, RadixNode>;
+    /** Parameter name if this is a param node */
+    paramName?: string;
+    /** Handlers keyed by HTTP method */
+    handlers: Map<HttpMethod, HandlerEntry>;
+    /** Wildcard child if any */
+    wildcardChild?: RadixNode;
+    /** Parameter child if any */
+    paramChild?: RadixNode;
+}
+/**
+ * Handler entry with middleware and pre-compiled executor
+ */
+interface HandlerEntry {
+    handler: RouteHandler;
+    middleware: Middleware[];
+    /** Pre-compiled executor for fast dispatch (no closure per request) */
+    executor?: (ctx: Context) => Promise<void>;
+}
+/**
+ * Create a new radix node
+ */
+declare function createNode(segment: string, type?: NodeType): RadixNode;
+/**
+ * Parse path segments
+ * Splits path into segments and identifies param/wildcard types
+ *
+ * @param path - Route path to parse
+ * @param caseSensitive - If false, lowercase static segments for case-insensitive matching
+ */
+declare function parseSegments(path: string, caseSensitive?: boolean): ParsedSegment[];
+/**
+ * Parsed segment structure
+ */
+interface ParsedSegment {
+    segment: string;
+    type: NodeType;
+    paramName?: string;
+}
+
+export { type HandlerEntry, NodeType, type ParsedSegment, type RadixNode, Router, createNode, createRouter, parseSegments };