API REFERENCE

Router

import { Router } from '@rasenganjs/futon';
import type { HTTPMethod, RouterGroupOptions } from '@rasenganjs/futon';

Registers typed route handlers by method + pattern and produces a Middleware that dispatches incoming requests via radix-tree matching — O(k) regardless of route count. Futon owns one internal Router instance; app.get()/app.post()/etc. delegate to it directly.

Constructor

new Router();

HTTP Method Shortcuts

get(pattern: string, handler: (ctx: Context) => Promise<Response>): this
post(pattern: string, handler: (ctx: Context) => Promise<Response>): this
put(pattern: string, handler: (ctx: Context) => Promise<Response>): this
patch(pattern: string, handler: (ctx: Context) => Promise<Response>): this
delete(pattern: string, handler: (ctx: Context) => Promise<Response>): this
head(pattern: string, handler: (ctx: Context) => Promise<Response>): this
options(pattern: string, handler: (ctx: Context) => Promise<Response>): this

Middleware

use(...middlewares: Middleware[]): this

Registers route-level middleware — only applies to routes registered after this call on the same Router instance.

Groups

group(prefix: string, callback: (router: Router) => void): this
group(prefix: string, options: RouterGroupOptions, callback: (router: Router) => void): this
RouterGroupOptions
interface RouterGroupOptions {
  prefix?: string;
  middlewares?: Middleware[];
}

See Route Groups.

Dispatch

middleware(): Middleware

Produces a Middleware that dispatches to matching routes. Snapshots the currently-registered route trees — routes added after calling .middleware() are not picked up by that snapshot.

Introspection

readonly version: number   // bumped on every route/middleware registration
routesCount(): number      // total registered routes across every method

HTTPMethod

type HTTPMethod =
  'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';

Automatic 405 Responses

If a pathname matches a registered route under a different method, the router's dispatch middleware responds 405 Method Not Allowed with an Allow header listing the methods that do match, instead of falling through to your 404 handler.

Low-Level Primitives

import {
  RasenganTreeRouter,
  matchPath,
  parseQueryString,
} from '@rasenganjs/futon';
import type { TreeMatchResult } from '@rasenganjs/futon';

These are the building blocks Router is implemented on top of. Most apps never touch them directly — they're exported for advanced cases like building a custom router or matching paths outside of a Futon instance.

RasenganTreeRouter

class RasenganTreeRouter<T = unknown> {
  add(pattern: string, handler: T): void;
  match(pathname: string): TreeMatchResult<T>;
}

A radix (compressed trie) tree for HTTP path matching — one tree node per /-separated segment, giving O(k) lookup (k = number of path segments) regardless of how many routes are registered. This is what Router uses internally instead of a linear route scan. Handles static segments, :param, :param?, :param*, and bare * catch-alls, with static matches taking priority over dynamic ones at each level.

Standalone usage
const tree = new RasenganTreeRouter();
tree.add('/users/:id', handler);
tree.add('/static/*', staticHandler);
 
tree.match('/users/42');
// → { handler, params: { id: '42' } }
 
tree.match('/unknown');
// → { handler: undefined, params: {} }

TreeMatchResult

interface TreeMatchResult<T = unknown> {
  handler?: T;
  params: Record<string, string>;
}

The return type of RasenganTreeRouter.match().

matchPath()

function matchPath(
  pattern: string,
  pathname: string
): Record<string, string> | null;

Matches a single route pattern against a pathname directly (no tree, no registration) — returns the captured params, or null if the pattern doesn't match.

Examples
matchPath('/users/:id', '/users/42'); // → { id: '42' }
matchPath('/users/:id?', '/users'); // → {}
matchPath('/files/:path*', '/files/a/b'); // → { path: 'a/b' }
matchPath('/static/*', '/static/foo.js'); // → { _: 'foo.js' }
matchPath('/users/:id', '/posts'); // → null

See Route Patterns for the full pattern syntax reference.

parseQueryString()

function parseQueryString(url: string): Record<string, string>;

Parses the query string portion of a URL into a plain key-value object, handling URL-encoded keys and values. This is what powers ctx.query internally.

Futon
Context