@nextrush/router 3.0.7 → 4.0.0-beta.1

package/dist/index.d.ts

@@ -1,238 +1,279 @@
-import { RouterOptions, RouteHandler, HttpMethod, Middleware, RouteMatch, Context } from '@nextrush/types';
+import { RouteHandler, Middleware, MetadataContribution, RouteMetaMarker, RouterOptions, RouteEntry, HttpMethod, RouteDefinition, RouteMatch, Context } from '@nextrush/types';
 export { HttpMethod, Middleware, Route, RouteHandler, RouteMatch, Router as RouterInterface, RouterOptions } from '@nextrush/types';
 
 /**
- * @nextrush/router - Router Implementation
+ * @nextrush/router - Redirect Handler Compilation
  *
- * 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.
+ * Single, shared redirect implementation used by both `Router.redirect()` and
+ * route groups (audit RT-4). Previously the group variant used a naive
+ * `replaceAll(':key', value)` that could mis-substitute overlapping param names
+ * and re-scanned the string per request; this precompiles the target template
+ * once and only substitutes route-style `:param` slots (a `:` at position 0 or
+ * preceded by `/`), so `https://` and other literal colons are never touched.
  *
  * @packageDocumentation
  */
 
+/** HTTP redirect status codes supported by `redirect()`. */
+type RedirectStatus = 301 | 302 | 303 | 307 | 308;
+
+/**
+ * @nextrush/router - Route Groups
+ *
+ * A route group applies a shared path prefix and middleware to a set of routes
+ * registered inside a callback. Extracted from `router.ts` (audit RT-3) and
+ * given a real public type (audit RT-6): `router.group()` callbacks receive a
+ * {@link RouteGroup}, not a mis-cast `Router`.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The object passed to a `router.group(prefix, callback)` callback.
+ *
+ * @remarks
+ * Exposes only the route-registration surface that is valid inside a group —
+ * intentionally NOT the full {@link Router} (no `mount`/`use`/`reset`), which is
+ * why the previous `as unknown as Router` cast was a lie (audit RT-6).
+ */
+interface RouteGroup {
+    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;
+    redirect(from: string, to: string, status?: RedirectStatus): this;
+    group(prefix: string, middlewareOrCallback: Middleware[] | ((router: RouteGroup) => void), callback?: (router: RouteGroup) => void): this;
+}
+
 /**
- * Router class — high-performance segment trie router
+ * @nextrush/router - Route Metadata Contributions
+ *
+ * Inline route metadata (`endpoint()`) and the registration-time merge of
+ * contributions from `validate()`, `endpoint()`, etc. Extracted from `router.ts`
+ * (audit RT-3). None of this is on the request hot path — it is read only at
+ * registration and by `getRoutes()` at doc-generation time.
  *
- * 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.
+ * @packageDocumentation
+ */
+
+/**
+ * Declare route metadata inline in a route's argument list. Returns a pure data
+ * marker (not a middleware) — the router reads its metadata at registration and
+ * never executes it per request.
  *
  * @example
  * ```typescript
- * const router = createRouter();
+ * router.post('/users',
+ *   validate(User),
+ *   endpoint({ summary: 'Create a user', responses: { 201: UserResponse } }),
+ *   handler,
+ * );
+ * ```
+ */
+declare function endpoint(metadata: MetadataContribution): RouteMetaMarker;
+
+/**
+ * @nextrush/router - Router Implementation
  *
- * router.get('/users', listUsers);
- * router.get('/users/:id', getUser);
- * router.post('/users', createUser);
+ * The public `Router` shell: a thin, chainable facade delegating registration,
+ * matching, dispatch, composition, and grouping to focused sibling modules
+ * (design.md D1/D2). Segment trie keyed by whole path segments, not a radix tree.
  *
- * app.use(router.routes());
- * ```
+ * @packageDocumentation
+ */
+
+/**
+ * High-performance segment-trie router: O(d) lookup by path segment, with a
+ * static-route hash map for an O(1) fast path.
+ * @see {@link https://github.com/0xTanzim/nextRush/blob/main/packages/router/README.md | @nextrush/router README}
  */
 declare class Router {
     private readonly root;
     private readonly opts;
     private readonly routerMiddleware;
+    /** Static-route fast path: method-nested map for O(1) lookup with no per-request key string (HP-9). */
+    private readonly staticRoutes;
     /**
-     * Static route hash map for O(1) lookup.
-     * Key: "METHOD path" (e.g. "GET /users"), Value: HandlerEntry
+     * Introspection registry, kept SEPARATE from the hot-path trie/staticRoutes
+     * so request dispatch never reads metadata — only getRoutes() touches it.
      */
-    private readonly staticRoutes;
+    private readonly routeDefinitions;
     /** Whether any routes have params or wildcards (disables static-only fast path) */
     private hasParamRoutes;
-    constructor(options?: RouterOptions);
+    /** Whether router-level middleware has already been sealed into executors (audit RT-7) */
+    private _sealed;
     /**
-     * Normalize path based on router options
+     * Single-entry memo for {@link matchesMountPrefix}'s canonicalization of the
+     * mount prefix, which is fixed at registration time. Declared as two fields
+     * rather than an object so a miss stores without allocating.
      */
-    private normalizePath;
+    private _prefixMemoRaw;
+    private _prefixMemoCanonical;
+    /** Memoized state the extracted registration/matching functions read (see {@link createRouterState}). */
+    private readonly state;
+    constructor(options?: RouterOptions);
     /**
-     * Add a route to the radix tree
+     * Validate + normalize a raw path, then delegate trie insertion to the
+     * extracted `addRoute` (design.md D2); flips `hasParamRoutes` from its return.
      */
     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;
+    get(path: string, ...entries: RouteEntry[]): this;
+    post(path: string, ...entries: RouteEntry[]): this;
+    put(path: string, ...entries: RouteEntry[]): this;
+    delete(path: string, ...entries: RouteEntry[]): this;
+    patch(path: string, ...entries: RouteEntry[]): this;
+    head(path: string, ...entries: RouteEntry[]): this;
+    options(path: string, ...entries: RouteEntry[]): 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');
-     * ```
+     * Register a route for every HTTP method under one consolidated `isAnyMethod`
+     * introspection row (T016) — matching is unchanged (see {@link pushAnyMethodDefinition}).
      */
-    redirect(from: string, to: string, status?: 301 | 302 | 303 | 307 | 308): this;
-    use(pathOrMiddleware: string | Middleware | Router, routerOrUndefined?: Router): this;
+    all(path: string, ...entries: RouteEntry[]): this;
+    route(method: HttpMethod, path: string, ...entries: RouteEntry[]): 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());
-     * ```
+     * Every registered route as a read-only list, for renderers (`@nextrush/openapi`,
+     * SDK/RPC generators). Doc-generation-time only — never on the request path.
      */
-    mount(path: string, router: Router): this;
+    getRoutes(): readonly RouteDefinition[];
     /**
-     * Mount a sub-router (internal)
-     *
-     * Carries the sub-router's own `routerMiddleware` forward so that
-     * `subrouter.use(mw)` middleware applies to every copied route.
+     * Register a redirect from one path to another (301 by default). 307/308
+     * additionally register POST/PUT/PATCH/DELETE to preserve the method.
+     * @see {@link https://github.com/0xTanzim/nextRush/blob/main/packages/router/README.md#redirects | README: Redirects}
      */
-    private mountRouter;
-    /**
-     * Recursively copy routes from another router
-     */
-    private copyRoutes;
+    redirect(from: string, to: string, status?: RedirectStatus): this;
+    use(pathOrMiddleware: string | Middleware | Router, routerOrUndefined?: Router): this;
     /**
-     * Match a route and return handler + params
+     * Mount a sub-router at a path prefix (Hono-style) — the explicit, more
+     * semantic equivalent of `router.use(path, subRouter)`.
+     * @see {@link https://github.com/0xTanzim/nextRush/blob/main/packages/router/README.md#sub-router-mounting | README: Sub-Router Mounting}
      */
+    mount(path: string, router: Router): this;
+    /** Mount a sub-router, carrying its own `routerMiddleware` onto every copied route. */
+    private mountRouter;
+    /** Match a request to a route — delegates to {@link resolveMatch} (design.md D1). */
     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
+     * Test whether `path` falls under `prefix` using this router's OWN
+     * canonicalization (case folding per `caseSensitive`, structural
+     * normalization) — the mount-boundary counterpart to {@link match}, so a
+     * router mounted via `Application.route()` is tested with the identical
+     * rule it dispatches with (RFC-029, task 3.8). Implements the optional
+     * `Routable.matchesMountPrefix` contract from `@nextrush/core`.
      *
-     * @example
-     * ```typescript
-     * app.use(router.routes());
-     * ```
+     * @param path - The full request path being tested for this mount.
+     * @param prefix - The normalized mount prefix (leading `/`, no trailing `/`).
+     * @returns The path's remainder past the prefix (e.g. `/users` for a
+     *   `/ADMIN/Users` request mounted at `/admin`), or `undefined` when `path`
+     *   is not under `prefix` per this router's canonicalization.
      */
-    routes(): Middleware;
+    matchesMountPrefix(path: string, prefix: string): string | undefined;
     /**
-     * Re-compile all route executors to include router-level middleware.
-     * Called once when routes() is invoked, not per-request.
+     * Return the router's dispatch middleware — mount this on the application.
+     * @see {@link https://github.com/0xTanzim/nextRush/blob/main/packages/router/README.md#routerroutes | README: router.routes()}
      */
-    private sealRouterMiddleware;
+    routes(): Middleware;
     /**
-     * Generate allowed methods middleware
-     * Responds to OPTIONS and sets Allow header
+     * Generate allowed-methods middleware. Responds to OPTIONS with an `Allow`
+     * header and returns 405 for a known path hit with an unregistered method.
      */
     allowedMethods(): Middleware;
     /**
-     * Find all HTTP methods registered for a given path via single tree walk
-     * @internal
+     * Create a route group with a shared prefix and middleware. The callback
+     * receives a {@link RouteGroup} to register routes against.
+     * @see {@link https://github.com/0xTanzim/nextRush/blob/main/packages/router/README.md#route-groups | README: Route Groups}
      */
-    private findAllowedMethods;
+    group(prefix: string, middlewareOrCallback: Middleware[] | ((router: RouteGroup) => void), callback?: (router: RouteGroup) => void): this;
     /**
-     * Walk the tree to find the node matching a path (ignoring HTTP method)
-     * @internal
+     * Remove all routes and middleware, resetting the router to its initial
+     * state — for test isolation or hot-reload re-registration.
      */
-    private findNode;
+    reset(): void;
+    /** Register a route on behalf of a {@link RouteGroup} (group context). @internal */
+    _addGroupRoute(method: HttpMethod, path: string, handlers: RouteHandler[], groupMiddleware: Middleware[], recordIntrospection?: boolean): void;
     /**
-     * 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-facing entry point to {@link pushAnyMethodDefinition} — a group's `.all()`
+     * records its consolidated row here since group routes live on the parent. @internal
      */
-    group(prefix: string, middlewareOrCallback: Middleware[] | ((router: Router) => void), callback?: (router: Router) => void): this;
+    _pushAnyMethodRouteDefinition(path: string): void;
+}
+/**
+ * Create a new {@link Router} instance.
+ * @see {@link https://github.com/0xTanzim/nextRush/blob/main/packages/router/README.md#quick-start | README: Quick Start}
+ */
+declare function createRouter(options?: RouterOptions): Router;
+
+/**
+ * @nextrush/router - Canonical Request Path
+ *
+ * The single normalization owner (RFC-029): every consumer that needs to know
+ * "what path does the router treat this request as" — the router's own match,
+ * a mounted-router prefix test, a CSRF exclude-path match, an adapter's
+ * published `ctx.path` — calls {@link canonicalizePath} instead of hand-rolling
+ * its own fold/collapse/strip, so there is exactly one definition of "the same
+ * path" across the framework (SEC-02, SEC-09, SEC-15).
+ *
+ * @see docs/RFC/request-data/029-canonical-request-path.md
+ * @packageDocumentation
+ */
+/** Result of {@link canonicalizePath}. */
+interface CanonicalPathResult {
     /**
-     * Remove all registered routes and middleware, resetting the router to its initial state.
-     * Useful for plugin `destroy()` to cleanly un-register routes.
+     * `true` when the path contains a `.`/`..` path segment. A dot segment is
+     * rejected outright (400), never resolved — resolving it locally would
+     * diverge from how a front-end proxy already resolved (or didn't resolve)
+     * the same segment before forwarding, reopening the desync this RFC closes.
      */
-    reset(): void;
+    readonly rejected: boolean;
     /**
-     * Internal method to add route with group context
-     * @internal
+     * The canonical path: query-stripped, dot-segment-free, case-folded (unless
+     * `caseSensitive`), slash-collapsed, trailing-slash-stripped per `strict`.
+     * Meaningless when {@link rejected} is `true`.
      */
-    _addGroupRoute(method: HttpMethod, path: string, handlers: RouteHandler[], groupMiddleware: Middleware[]): void;
+    readonly path: string;
 }
 /**
- * Create a new Router instance
+ * True when `path` (already query-stripped) contains a `.` or `..` segment —
+ * a component that is exactly `.` or `..` between slash boundaries (or at the
+ * start/end of the string). A single linear scan, no backtracking regex
+ * (task 3.5): each character is visited at most once, so a pathological input
+ * cannot degrade to worse than O(n).
  *
- * @param options - Router options
- * @returns New Router instance
+ * A dot as filename content (`archive.tar.gz`, `..hidden.txt`) is NOT a dot
+ * segment — only a component whose entire text between slashes is `.` or `..`
+ * counts.
+ */
+declare function hasDotSegment(path: string): boolean;
+/**
+ * Canonicalize a raw request target into the one path value every consumer
+ * (router match, mount-prefix test, CSRF exclude match, published `ctx.path`)
+ * treats as "this request's path" (RFC-029).
  *
- * @example
- * ```typescript
- * const router = createRouter();
- * const apiRouter = createRouter({ prefix: '/api/v1' });
- * ```
+ * Order: strip the query string, reject a dot segment before any further
+ * normalization (a dot segment is a request-shape violation, not something to
+ * fold case on first), then fold case (unless `caseSensitive`) and collapse
+ * structure exactly as {@link import('./matching').normalizePathForMatch} does
+ * — this function IS that normalization, extended with dot-segment rejection
+ * and made a public, adapter-facing entry point.
+ *
+ * The most recent result is memoized; see the note above the memo fields for
+ * why that is sound. Treat the returned object as immutable.
+ *
+ * @param rawTarget - The raw request target, may include a query string.
+ * @param caseSensitive - Router case-sensitivity option.
+ * @param strict - Router strict-trailing-slash option.
  */
-declare function createRouter(options?: RouterOptions): Router;
+declare function canonicalizePath(rawTarget: string, caseSensitive: boolean, strict: boolean): CanonicalPathResult;
 
 /**
  * @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.
+ * Segments are split by `/` and matched one trie level per segment for O(k)
+ * lookups where k is path length.
  *
  * @packageDocumentation
  * @internal
@@ -250,23 +291,23 @@ declare const enum NodeType {
     WILDCARD = 2
 }
 /**
- * Radix tree node
+ * Segment trie node
  */
-interface RadixNode {
+interface TrieNode {
     /** Path segment for this node */
     segment: string;
     /** Node type */
     type: NodeType;
-    /** Children nodes keyed by first character */
-    children: Map<string, RadixNode>;
+    /** Static child nodes keyed by whole path segment (e.g. `users`), not the first character */
+    children: Map<string, TrieNode>;
     /** 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;
+    wildcardChild?: TrieNode;
     /** Parameter child if any */
-    paramChild?: RadixNode;
+    paramChild?: TrieNode;
 }
 /**
  * Handler entry with middleware and pre-compiled executor
@@ -276,11 +317,19 @@ interface HandlerEntry {
     middleware: Middleware[];
     /** Pre-compiled executor for fast dispatch (no closure per request) */
     executor?: (ctx: Context) => Promise<void>;
+    /**
+     * `true` only for a `HEAD` entry derived from a `GET` registration
+     * (RFC 9110 §9.3.2). A derived entry is replaced by an explicit `HEAD`
+     * registration instead of reporting a route conflict, is absent from
+     * `getRoutes()`, and is skipped when copying routes into a parent router —
+     * which re-derives it from the `GET` it copies.
+     */
+    autoHead: boolean;
 }
 /**
- * Create a new radix node
+ * Create a new segment trie node
  */
-declare function createNode(segment: string, type?: NodeType): RadixNode;
+declare function createNode(segment: string, type?: NodeType): TrieNode;
 /**
  * Parse path segments
  * Splits path into segments and identifies param/wildcard types
@@ -298,4 +347,4 @@ interface ParsedSegment {
     paramName?: string;
 }
 
-export { type HandlerEntry, NodeType, type ParsedSegment, type RadixNode, Router, createNode, createRouter, parseSegments };
+export { type CanonicalPathResult, type HandlerEntry, NodeType, type ParsedSegment, type RouteGroup, Router, type TrieNode, canonicalizePath, createNode, createRouter, endpoint, hasDotSegment, parseSegments };