@prexjs/router

Fast, robust, and promise-aware routing middleware engine for Prex and Express applications.

@prexjs/router provides the modular routing and middleware dispatcher engine for Prex. It supports nested router hierarchies, async/await promise resolution, parameterized route patterns (/users/:id), custom param preprocessing, case-sensitive matching, and automatic HTTP OPTIONS response handling.

Features

• Promise & Async/Await Aware: Unhandled rejections inside route handlers automatically propagate to next(err).
• Parameter Extraction & Validation: Route parameters with regex matching (@prexjs/path-to-regexp) and custom param callbacks (router.param()).
• Flexible Mounting & Nesting: Mount sub-routers on distinct path prefixes with optional param merging (mergeParams).
• Complete HTTP Method Coverage: Supports all standard HTTP verbs (get, post, put, delete, patch, head, options, all).
• Automatic OPTIONS Dispatch: Automatically computes and replies with allowed methods for matched endpoints.

Installation

Install using your preferred package manager:

# npm
npm install @prexjs/router

# pnpm
pnpm add @prexjs/router

# Yarn
yarn add @prexjs/router

# Bun
bun add @prexjs/router

Quick start

import http from 'node:http';
import Router from '@prexjs/router';

const router = new Router();

// Middleware
router.use((req, res, next) => {
  console.log(`${req.method} ${req.url}`);
  next();
});

// Route with parameter
router.get('/users/:id', async (req, res) => {
  const userId = req.params.id;
  res.setHeader('Content-Type', 'application/json');
  res.end(JSON.stringify({ userId }));
});

// Nested sub-router
const apiRouter = new Router({ mergeParams: true });
apiRouter.get('/health', (req, res) => {
  res.end('OK');
});
router.use('/api', apiRouter);

// Dispatch incoming HTTP requests
const server = http.createServer((req, res) => {
  router.handle(req, res, (err) => {
    if (err) {
      res.statusCode = 500;
      res.end('Internal Server Error');
      return;
    }
    res.statusCode = 404;
    res.end('Not Found');
  });
});

server.listen(3000);

API

new Router(options?) / Router(options?)

Creates a new router instance.

• caseSensitive: Enable case sensitivity (default: false).
• mergeParams: Preserve req.params from parent routers (default: false).
• strict: Enable strict routing where /foo and /foo/ are distinct (default: false).

Route Methods

• router.use([path], ...handlers): Mount middleware or sub-routers.
• router.all(path, ...handlers): Match all HTTP methods.
• router.get(path, ...handlers), router.post(path, ...handlers), etc.
• router.route(path): Return an IRoute instance to chain multiple HTTP verbs on a single route path.
• router.param(name, callback): Add parameter validation/preprocessing callback (req, res, next, value, name) => void.
• router.handle(req, res, next): Dispatch an incoming HTTP request through the router stack.

Compatibility

• Node.js >= 18.0.0
• Supports both ESM and CommonJS
• TypeScript 5.0+

Related Packages

• @prexjs/path-to-regexp: Route path pattern parser.
• @prexjs/application: Application layer.
• @prexjs/prex: The core Prex web framework.

License

MIT