Universal Middleware Router

2.2.0 verified Thu Apr 23 auth: no javascript

middle-router is a universal routing library designed for both client-side and server-side JavaScript applications, allowing URL changes to be processed through a series of asynchronous middleware functions. As of version 2.2.0, it provides a consistent API for managing routing logic across different environments. It distinguishes itself by integrating Koa-style `await next()` patterns for middleware execution, enabling control to flow downstream and then back upstream. This allows for complex lifecycle management around route changes, such as measuring execution time, handling exit conditions, or even prompting before navigation. The library leverages `path-to-regexp` for flexible path matching, similar to Express 4.x, and utilizes `middle-run` for robust middleware orchestration. While the provided examples often showcase integration with frameworks like Express and React, `middle-router` itself is entirely framework-agnostic, offering core routing functionality without imposing external dependencies. It focuses on providing a flexible and powerful middleware-based approach to handling application state changes tied to URLs. Its release cadence is stable, with new features and bug fixes rolled out incrementally.

Common errors

error TypeError: Router is not a function ↓

cause Attempting to import `Router` as a named export (e.g., `import { Router } from 'middle-router'`) when it is the default export, resulting in `Router` being `undefined`.

fix

Change your import statement to import Router from 'middle-router' to correctly access the default exported constructor.

error Middleware did not call resolve() or throw an error, leading to a hang or timeout. ↓

cause An asynchronous middleware function completed execution without explicitly calling `resolve()` to yield a result, calling `next()` to pass control, or throwing an error.

fix

Ensure all execution paths within your middleware functions either call resolve(viewData), call await next() (if passing control to subsequent middleware), or explicitly throw an error to prevent the routing process from hanging indefinitely.

error Invariant Violation: You should not use <Router> outside a <BrowserRouter> ↓

cause This error message is specific to React Router and indicates a common misunderstanding: `middle-router` is a standalone, framework-agnostic routing library, not a wrapper or replacement for React Router components. The error occurs when a React Router component is used without its necessary context provider.

fix

Remember that middle-router provides core routing logic. If integrating with React, it supplies the 'view' (e.g., a React element) that you then render with ReactDOM, but it does not replace or depend on react-router-dom.

Warnings

gotcha Misunderstanding 'await exiting' lifecycle ↓

fix Ensure `await exiting` is placed *after* `resolve()` in your middleware. Placing it before `resolve()` will prevent the route from resolving until the next URL change occurs, leading to unexpected behavior and potential hangs.

breaking Potential changes to middleware signature between major versions ↓

fix When upgrading major versions, always review the official API documentation for your specific major version. The expected arguments for middleware functions (`{ context, next, params, resolve, etc. }`) may have undergone significant changes or reordering.

gotcha Client-side routing requires explicit initialization and event handling ↓

fix For browser-based client-side routing, ensure you explicitly call `router.on('route', handler)` to process the resolved view data and `router.start()` to initiate routing and listen for browser history (e.g., `popstate`) and hash changes.

Install

npm install middle-router

yarn add middle-router

pnpm add middle-router

Imports

Router Constructor (ESM)
wrong
```
import { Router } from 'middle-router'
```
correct
```
import Router from 'middle-router'
```
The `Router` constructor/factory function is exported as the default export. Destructuring it from the package will result in `undefined`.
Router Constructor (CommonJS)
wrong
```
const { Router } = require('middle-router')
```
correct
```
const Router = require('middle-router')
```
In CommonJS environments, the `Router` constructor is the direct `module.exports`. Attempting to destructure it as a named export will not work as expected.
Router Instance Creation
wrong
```
import Router from 'middle-router'; const myRouter = new Router();
```
correct
```
import Router from 'middle-router'; const myRouter = Router();
```
The `Router` from `middle-router` is a factory function; it should be called directly (e.g., `Router()`) to create a router instance, not instantiated with the `new` keyword.

Quickstart

This quickstart demonstrates how to create a `middle-router` instance, define asynchronous middleware functions for different paths, and use `router.route()` to process URLs, simulating both specific and default route handling in a Node.js environment.

import Router from 'middle-router';

const appRouter = Router()
  .use(async ({ context, next }) => {
    const start = Date.now();
    console.log(`[Middleware 1] Entering: ${context.url}`);
    await next(); // Pass control to the next middleware
    const duration = Date.now() - start;
    context.totalTime = duration;
    console.log(`[Middleware 1] Exiting: ${context.url} (took ${duration}ms)`);
  })
  .use('/users/:id', async ({ params, resolve, context }) => {
    console.log(`[Middleware 2] Matched /users/${params.id}`);
    // Simulate async data fetching
    await new Promise(res => setTimeout(res, 50));
    const userData = { id: params.id, name: `User ${params.id}`, fetchedAt: Date.now() };
    resolve(`<h1>User Profile</h1><p>ID: ${userData.id}</p><p>Name: ${userData.name}</p><p>Fetched at: ${userData.fetchedAt}</p>`);
    console.log(`[Middleware 2] Resolved for /users/${params.id}`);
  })
  .use(async ({ resolve, context }) => {
    console.log(`[Middleware 3] Default catch-all for: ${context.url}`);
    resolve(`<h1>Welcome</h1><p>No specific route matched for ${context.url}.</p>`);
  });

async function runExample() {
  console.log('--- Routing /users/123 ---');
  const userView = await appRouter.route('/users/123', { initialData: '...' });
  console.log('Resolved View:', userView);
  console.log('\n--- Routing /about ---');
  const aboutView = await appRouter.route('/about');
  console.log('Resolved View:', aboutView);
  console.log('\n--- Routing / ---');
  const homeView = await appRouter.route('/');
  console.log('Resolved View:', homeView);
}

runExample();