Universal request router built on web standards with generator-based middleware.
npm install @b9g/routerUniversal request router built on web standards with generator-based middleware.
- Web Standards: Built on URLPattern-like syntax, Request, and Response APIs
- Generator Middleware: Uses yield for flow control (no Express-style next())
- Universal: Same code runs in browsers, Node.js, Bun, and edge platforms
- Simple Context: Route parameters and middleware-extensible context
- Router Composition: Mount subrouters with path prefixes
``bash`
npm install @b9g/router
`javascript
import {Router} from '@b9g/router';
const router = new Router();
// Simple route
router.route('/hello').get(() => new Response('Hello World!'));
// Route with parameters
router.route('/posts/:id').get((request, context) => {
const {id} = context.params;
return Response.json({id, title: Post ${id}});
});
// Handle request
const response = await router.handle(request);
`
The router supports function and generator-based middleware with yield for clean flow control:`javascript
// Function middleware
router.use(async (request, context) => {
if (!request.headers.get('Authorization')) {
return new Response('Unauthorized', { status: 401 });
}
// Return null/undefined to continue to next middleware
return null;
});
// Generator middleware
router.use(async function* (request, context) {
console.log(${request.method} ${request.url});${response.status}
const response = yield request;
console.log();`
return response;
});
#### Constructor
`javascript`
new Router()
#### Methods
##### route(pattern)
Create a route builder for the given pattern.
`javascript`
router.route('/api/posts/:id')
.get(handler)
.post(handler)
.delete(handler);
##### use(middleware)
Add global middleware.
`javascript`
router.use(loggingMiddleware);
##### handle(request): Promise
Handle an incoming request and return a response.
`javascript`
const response = await router.handle(request);
##### mount(path, subrouter)
Mount a subrouter at a specific path prefix.
`javascript
const apiRouter = new Router();
apiRouter.route('/users').get(handler);
const mainRouter = new Router();
mainRouter.mount('/api/v1', apiRouter);
// Routes become: /api/v1/users
`
##### match(url): RouteMatch | null
Match a URL against registered routes without executing handlers.
`javascript`
const match = router.match(new URL('https://example.com/api/users'));
if (match) {
console.log(match.params, match.methods);
}
#### Properties
##### routes: RouteEntry[]
Read-only array of registered routes for introspection.
`javascript`
router.routes.forEach(route => {
console.log(route.pattern, route.method);
});
##### middlewares: MiddlewareEntry[]
Read-only array of registered middleware for introspection.
`javascript`
router.middlewares.forEach(mw => {
console.log(mw.pathPrefix);
});
Handler and middleware functions receive a context object:
`javascript`
{
params: Record
// Middleware can add arbitrary properties
}
Middleware can extend context with custom properties:
`javascript`
router.use(async function* (request, context) {
context.user = await authenticate(request);
return yield request;
});
`javascript
const router = new Router();
router.route('/api/health').get(() =>
Response.json({status: 'ok'})
);
router.route('/api/posts')
.get(async () => {
const posts = await db.posts.findAll();
return Response.json(posts);
})
.post(async (request) => {
const data = await request.json();
const post = await db.posts.create(data);
return Response.json(post, {status: 201});
});
`
`javascript
const router = new Router();
// Add user to context
router.use(async function* (request, context) {
const token = request.headers.get('Authorization')?.replace('Bearer ', '');
if (token) {
context.user = await verifyToken(token);
}
return yield request;
});
// Protected route
router.route('/api/profile').get(async (request, context) => {
if (!context.user) {
return new Response('Unauthorized', { status: 401 });
}
return Response.json(context.user);
});
`
`javascript
// API subrouter
const apiRouter = new Router();
apiRouter.route('/users').get(getUsersHandler);
apiRouter.route('/posts').get(getPostsHandler);
// Main router
const mainRouter = new Router();
mainRouter.mount('/api/v1', apiRouter);
// Routes become: /api/v1/users, /api/v1/posts
`
- Router - Main router classRouteBuilder
- - Fluent API for defining routes (returned by router.route())
`typescript
// Handler and middleware types
type Handler = (request: Request, context: RouteContext) => Response | Promise
type FunctionMiddleware = (request: Request, context: RouteContext) => Response | null | undefined | Promise
type GeneratorMiddleware = (request: Request, context: RouteContext) => Generator
type Middleware = GeneratorMiddleware | FunctionMiddleware
// Context and route types
interface RouteContext {
params: Record
}
interface RouteOptions {
name?: string
}
interface RouteMatch {
params: Record
methods: string[]
}
interface RouteEntry {
pattern: MatchPattern
method: string
handler: Handler
name?: string
middleware: Middleware[]
}
interface MiddlewareEntry {
middleware: Middleware
pathPrefix?: string
}
// HTTP methods
type HTTPMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS"
// Utility types
type TrailingSlashMode = "strip" | "add"
`
Standard middleware is available from @b9g/router/middleware:
`typescript
import {cors, logger, trailingSlash} from '@b9g/router/middleware';
// Request logging
router.use(logger());
// CORS middleware
router.use(cors({
origin: "https://example.com",
credentials: true
}));
// Trailing slash normalization
router.use(trailingSlash("strip")); // /path/ → /path
`
#### logger(options?: LoggerOptions)
Logs incoming requests and outgoing responses with timing information via LogTape.
`
→ GET /
← 200 GET / (3ms)
`typescript`
interface LoggerOptions {
category?: string[]; // Default: ["app", "router"]
}
#### cors(options?: CORSOptions)
Handles Cross-Origin Resource Sharing headers and preflight requests.
`typescript`
interface CORSOptions {
origin?: string | string[] | ((origin: string) => boolean); // Default: "*"
methods?: string[]; // Default: ["GET", "HEAD", "PUT", "POST", "DELETE", "PATCH"]
allowedHeaders?: string[]; // Default: ["Content-Type", "Authorization"]
exposedHeaders?: string[];
credentials?: boolean; // Default: false
maxAge?: number; // Default: 86400 (24 hours)
}
#### trailingSlash(mode: TrailingSlashMode)
Normalizes URL trailing slashes via 301 redirect.
`typescript``
type TrailingSlashMode = "strip" | "add";
MIT