extreme-router

KO | EN

gitlite — search

#javascript #llm #go #golang #android #machine-learning #rust #macos #java #windows #cli #kubernetes #vue #ios

(★ 9)

A high-performance, tree-based router for JavaScript and TypeScript, featuring a powerful plugin system for extreme extensibility

extreme-router Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<div align="center">
  <img src="./assets/logo.svg" alt="Extreme Router Logo" width="120" height="120">
  <h1>Extreme Router</h1>
  <p><strong>High-Performance, Plugin-Driven JavaScript Router</strong></p>
  
  <img src="https://img.shields.io/npm/v/extreme-router.svg" />
  &nbsp;
  <img src="https://img.shields.io/badge/License-MIT-orange.svg?color=orange" alt="License: MIT" />
</div>

<br />

**A high-performance, tree-based router for JavaScript and TypeScript, featuring a powerful plugin system for extreme extensibility.**

Extreme Router is designed for speed and flexibility. It uses an optimized radix tree (trie) structure for fast dynamic route matching and a dedicated cache for O(1) static route lookups, while its plugin architecture allows you to easily extend its capabilities to handle virtually any URL pattern.

## Table of Contents

- [Features](#features)
- [Installation](#installation)
- [Basic Usage](#basic-usage)
- [Advanced Usage](#advanced-usage)
- [Built-in Plugins](#built-in-plugins)
  - [Example using regex param plugin](#example-using-regex-param-plugin)
- [Custom Plugins](#custom-plugins)
  - [createPlugin Helper](#createplugin-helper)
- [API](#api)
  - [Error Types](./docs/error-types.md)
- [Benchmarks](#benchmarks)
- [Testing](#testing)
- [Acknowledgments](#acknowledgments)
- [Contributing](#contributing)
- [License](#license)

## Features

- **Fast:** Optimized radix tree implementation for O(k) lookup (k = path length)\*, with a dedicated cache for static routes (O(1)).
- **Universal Compatibility:** Runs seamlessly on every JavaScript environment.
- **Static & Dynamic Routing:** Supports fixed paths, parameterized segments, and wildcards.
- **Path Normalization:** Automatically normalizes paths by removing trailing slashes and collapsing multiple consecutive slashes (e.g., `/a//b///c/` becomes `/a/b/c`).
- **No URI Decoding by Default:** The router operates on raw path segments. URI decoding (e.g., `%20` to space) should be handled by the user before matching if needed.
- **Extensible Plugin System:** Easily add custom logic for complex routing patterns.
- **Smart Optional Parameter Handling:** Efficiently generates all unique path combinations (2^n) for routes with optional parameters using bitwise operations, ensuring comprehensive matching.
- **Built-in Plugins:** Comes with essential plugins for common use cases:
  - Parameters (`:id`)
  - Wildcards (`*`, `:name*`)
  - Regex Parameters (`:id<\\d+>`)
  - Optional Parameters (`:id?`)
  - File Extension Parameters (`:file.ext`)
  - Group Parameters (`/:paramName(val1|val2)`)
  - Prefix Group Parameters (`img(png|jpg|gif)`)
  - Optional Prefix Group Parameters (`img(png|jpg|gif)?`)
- **`createPlugin` Helper:** Quickly create custom plugins with minimal boilerplate using a simple declarative config.
- **TypeScript Native:** Written entirely in TypeScript with excellent type support.
- **Zero Dependencies:** Lightweight and dependency-free core.
- **Compact Size:** The core library is lightweight: **~13.17 KB minified** / **~3.85 KB gzipped** (ESM) and **~13.73 KB minified** / **~4.10 KB gzipped** (CJS).
- **Well-Tested:** Comprehensive test suite ensuring reliability with **100% code coverage**.
- **Benchmarked:** Performance is continuously monitored.

\* _For dynamic routes, the base radix tree lookup is O(k) (where k is the number of segments in the path). When matching a segment against dynamic patterns, the router iterates through the dynamic child nodes registered at that specific point in the tree. If `D_max` is the maximum number of distinct dynamic patterns (each associated with a related plugin) branching from any single node in the trie, the worst-case complexity for matching can approach O(k \* D_max). However, because dynamic children are evaluated in order of plugin priority, average-case performance is typically much closer to O(k) in case of higher priorities. The router's design aims for efficient handling even in scenarios with multiple competing plugin types for a segment._

## Installation

```bash
bun install extreme-router
# or
npm install extreme-router
# or
yarn add extreme-router
# or
pnpm add extreme-router
```

## Basic Usage

```typescript
import Extreme, { param, wildcard } from 'extreme-router';

// 1. Initialize the router
const router = new Extreme<{ handler: string }>(); // Specify the type for your route store
// Alternatively, specify a custom store factory function:
// const router = new Extreme<{ handler: string }>({ storeFactory: () => ({ handler: 'SharedHandler' }) });

// 2. Register plugins (chaining supported)
router.use(param).use(wildcard);

// Alternatively, you can register plugins when creating the router:
// const router = new Extreme<{ handler: string }>({
//  plugins: [param, wildcard],
// });

// 3. Register routes
// The register method returns the store object associated with the route.
// The store object is created by the storeFactory function (if provided) or defaults to an empty object.
// You can use the store object to attach any data to the route, such as handler functions, HTTP methods, middlewares, or other metadata.

router.register('/').handler = 'HomePage';
router.register('/users').handler = 'UserListPage';
router.register('/users/:userId').handler = 'UserProfilePage';
router.register('/files/*').handler = 'FileCatchAll';

// 4. Match paths
const match1 = router.match('/');
// match1 = { handler: 'HomePage' }

const match2 = router.match('/users/123');
// match2 = { handler: 'UserProfilePage', params: { userId: '123' } }

const match3 = router.match('/files/a/b/c.txt');
// match3 = { handler: 'FileCatchAll', params: { '*': 'a/b/c.txt' } }

const match4 = router.match('/nonexistent');
// match4 = null

router.unregister('/users/:userId'); // Unregister a specific route

const match5 = router.match('/users/123');
// match5 = null // Unregistered route, no match

console.log(router.inspect());
/*
[
  {
    path: "/",
    type: "static",
    store: {
      handler: "HomePage",
    },
  }, {
    path: "/users",
    type: "static",
    store: {
      handler: "UserListPage",
    },
  }, {
    path: "/files/*",
    type: "dynamic",
    store: [Object: null prototype] {
      handler: "FileCatchAll",
    },
  }
]
*/
```

## Advanced Usage

Here are examples `docs/examples` of how to integrate Extreme Router into simple HTTP servers using different JavaScript runtimes.

- [Bun HTTP Server](./docs/examples/server.bun.md)
- [Node.js HTTP Server](./docs/examples/server.node.md)
- [Deno HTTP Server](./docs/examples/server.deno.md)
- [Browser Example (using JSDelivr)](./docs/examples/browser.md)

## Built-in Plugins

Extreme Router comes with several pre-built plugins. You need to register them using `router.use()` before registering routes that depend on them. When matching a URL segment against potential dynamic routes, the router checks the registered plugins based on their **`priority`** value. **Lower priority numbers are checked first**.

| Priority | Plugin                | Syntax Example        | Description                                                             | Example Usage (after registering plugin)                                                                                                                |
| :------- | :-------------------- | :-------------------- | :---------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 100      | `prefixGroup`         | `/img(png\|jpg\|gif)` | Matches a static prefix followed by one of a predefined set.            | `router.register('/img(png\|jpg)');` <br> `match('/imgpng'); // Match` <br> `match('/img'); // No Match`                                                |
| 200      | `optionalPrefixGroup` | `/img(png\|jpg)?`     | Matches a static prefix optionally followed by one of a predefined set. | `router.register('/img(png\|jpg)?');` <br> `match('/imgpng'); // Match` <br> `match('/img'); // Match`                                                  |
| 300      | `groupParam`          | `/:png(jpg\|gif)`     | Matches one of a predefined set of static values as a parameter.        | `router.register('/:fmt(png\|jpg)');` <br> `match('/png'); // { params: { fmt: 'png' } }` <br> `match('/gif'); // No Match`                             |
| 400      | `regexParam`          | `/:id<\\d+>`          | Matches a named parameter against a custom regex.                       | `router.register('/user/:id<\\d+>');` <br> `match('/user/123'); // { params: { id: '123' } }` <br> `match('/user/abc'); // No Match`                    |
| 500      | `extensionParam`      | `/:file.ext`          | Matches segments with a specific file extension.                        | `router.register('/:file.:ext');` <br> `match('/report.pdf'); // { params: { file: 'report', ext: 'pdf' } }`                                            |
| 600      | `optionalParam`       | `/:id?`               | Matches an optional named parameter. See note below on priority.        | `router.register('/product/:id?');` <br> `match('/product/123'); // { params: { id: '123' } }` <br> `match('/product'); // Match (no params)`           |
| 700      | `param`               | `/:id`                | Matches a standard named parameter.                                     | `router.register('/post/:slug');` <br> `match('/post/hello'); // { params: { slug: 'hello' } }`                                                         |
| 800      | `wildcard`            | `/*`, `/:name*`       | Matches the rest of the path. Must be the last segment.                 | `router.register('/files/*');` <br> `match('/files/a/b'); // { params: { '*': 'a/b' } }` <br> `router.register('/docs/:p*'); // { params: { p: ... } }` |

<span id="note-on-optional-parameters-and-priority"></span>
[See Note on Optional Parameters and Priority](./docs/optional-parameters-priority.md)

### Example using regex param plugin

```typescript
import Extreme, { regexParam } from 'extreme-router';

// Initialize the router
const router = new Extreme<{ handler: string }>();

// Register plugins
router.use(regexParam);

// Register route
router.register('/users/:userId<\\d+>').handler = 'UserProfilePage';

// Match paths
const match1 = router.match('/users/123');
// match1 = { handler: 'UserProfilePage', params: { userId: '123' } }

const match2 = router.match('/users/abc');
// match2 = null // No match, regex didn't match
```

## Custom Plugins

Extreme Router's power lies in its extensibility. You can easily create your own plugins to handle unique URL patterns or add custom matching logic. The process involves defining a plugin function that returns a configuration object, which in turn includes a handler function responsible for recognizing syntax and providing the runtime matching logic.

**Core Types:** (from [src/types.ts](src/types.ts))

1.  **`Plugin`**: `() => PluginConfig`
    - The function you register with `router.use()`. It's a factory function that, when called, returns a `PluginConfig` object. This allows plugins to be configured or initialized if needed, though simple plugins might just return a static configuration object.

2.  **`PluginConfig`**: `{ id: string, priority: number, syntax: string, handler: PluginHandler }`
    - Defines the plugin's identity, precedence, the **representative syntax pattern** it handles, and the handler function.
    - **`id: string`**: A unique identifier for the plugin (e.g., `"param"`, `"myCustomPlugin"`). This is used internally and for error reporting.
    - **`priority: number`**: A number determining the order in which plugins are evaluated during route registration and matching. Lower numbers have higher priority. Built-in plugins have priorities like `param` (700) and `wildcard` (800). Choose a priority that makes sense relative to other plugins.
    - **`syntax: string`**: A representative string example of the syntax this plugin handles (e.g., `":paramName"`, `":id<regex>"`, `"*"`). This string is passed to the `plugin.handler` during `router.use()` to validate that the handler can correctly process this type of syntax.
    - **`handler: PluginHandler`**: The function responsible for processing path segments during route registration.

3.  **`PluginHandler`**: `(segment: string) => PluginMeta | undefined | null`
    - Called during `router.register()`. It receives a path segment string (e.g., `":userId"`, `":id<uuid>"`, `"*"`).
    - Its job is to determine if this `segment` matches the pattern the plugin is designed for.
    - If it matches, it should return a `PluginMeta` object containing the necessary information for matching and parameter extraction.
    - If it doesn't match the plugin's expected syntax, it should return `null` or `undefined` to allow other plugins to attempt to handle the segment.

4.  **`PluginMeta`**: `{ paramName: string, match: (args) => boolean, override?: boolean, wildcard?: boolean, additionalMeta?: object }`
    - Returned by the `PluginHandler` if a segment's syntax is recognized. This object is stored in the routing tree node.
    - **`paramName: string`**: The name to be used for the parameter if the segment is dynamic (e.g., for `":userId"`, `paramName` would be `"userId"`). For non-capturing plugins (like a static prefix group), this might be an empty string.
    - **`match: ({ urlSegment: string, urlSegments: string[], index: number, params: Record<string, unknown> }) => boolean`**: This is the crucial function called during `router.match()`.
      - It receives the current URL segment (`urlSegment`), all URL segments (`urlSegments`), the current segment's `index`, and the `params` object (to populate if a match occurs).
      - It must return `true` if the `urlSegment` matches the plugin's logic, and `false` otherwise.
      - If it returns `true`, it should also populate the `params` object with any captured values.
    - **`override?: boolean`** (optional): If `true`, this plugin can override an existing dynamic segment registered by a plugin with the _same ID_ at the same node. This is useful for plugins like `optionalParam` that might need to "claim" a segment that could also be interpreted by the base `param` plugin if the optional marker wasn't present. Defaults to `false`.
    - **`wildcard?: boolean`** (optional): If `true`, indicates this plugin handles a wildcard match (like `*` or `:name*`). Wildcard routes have special handling (e.g., they must be at the end of a path, and matching can consume multiple remaining segments). Defaults to `false`.
    - **`additionalMeta?: object`** (optional for logging purpose): An object to store any other metadata about the plugin's behavior. For example, the `regexParam` plugin stores the compiled `RegExp` object here.
      - `group?: Record<string | number, unknown>`: Used by group-based plugins.
      - `regex?: RegExp`: Used by regex-based plugins.
      - `extension?: string`: Used by extension-based plugins.

**Example: Custom UUID Plugin**

```typescript
import Extreme, { param } from 'extreme-router';
import type { Plugin, PluginHandler, PluginMeta } from 'extreme-router'; // Import types

// Define the UUID regex
const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

// 1. Define the Plugin Function
const uuidPlugin: Plugin = () => {
  // 2. Define the Plugin Handler
  const handler: PluginHandler = (segment) => {
    // Check if the registration segment matches our syntax :name<uuid>
    const syntaxMatch = /^:(?<paramName>[a-zA-Z0-9_-]+)<uuid>$/i.exec(segment);

if (!syntaxMatch?.groups?.paramName) {
      return null; // Doesn't match our syntax, let other plugins handle it
    }

const paramName = syntaxMatch.groups.paramName;

// 3. Return the PluginMeta object
    const meta: PluginMeta = {
      paramName: paramName,
      // 4. Define the runtime 'match' function
      match: ({ urlSegment, params }) => {
        // Check if the actual URL segment matches the UUID regex
        if (UUID_REGEX.test(urlSegment)) {
          params[paramName] = urlSegment; // Capture the value
          return true; // It's a match!
        }
        return false; // Not a match
      },
    };
    return meta;
  };

// 5. Return the PluginConfig
  return {
    id: 'uuid', // Unique ID for this plugin
    priority: 550, // Example: Higher precedence than 'param' (700)
    syntax: ':name<uuid>', // Representative syntax pattern for validation
    handler: handler,
  };
};

// --- Usage ---
const router = new Extreme<{ handler: string }>();

// Register plugins - priority determines order handlers are checked during registration
router
  .use(uuidPlugin) // Priority 550
  .use(param); // Priority 700

// Register routes: The highest-priority plugin whose handler recognizes
// the segment's syntax during registration determines which PluginMeta
// is associated with the resulting node in the routing tree.
router.register('/orders/:orderId<uuid>').handler = 'GetOrder'; // Handled by uuidPlugin
router.register('/users/:userId').handler = 'GetUser'; // Handled by param plugin

// Match paths
const match1 = router.match('/orders/123e4567-e89b-12d3-a456-426614174000');
// match1 = { handler: 'GetOrder', params: { orderId: '...' } }
// Uses the match function from the uuidPlugin's PluginMeta.

const match2 = router.match('/orders/invalid-uuid-format');
// match2 = null
// The uuidPlugin's match function returned false. No other dynamic nodes
// were registered at this specific point for '/orders/...'

const match3 = router.match('/users/regular-id');
// match3 = { handler: 'GetUser', params: { userId: 'regular-id' } }
// Uses the match function from the param plugin's PluginMeta.

console.log(match1);
console.log(match2);
console.log(match3);
```

### createPlugin Helper

For the most common plugin pattern - matching a segment against a regex and capturing a named parameter - the `createPlugin` helper eliminates all the boilerplate. Instead of manually writing `PluginHandler`, `PluginMeta`, and the factory wrapper, you provide a minimal declarative config.

**Example: UUID plugin using `createPlugin`**

```typescript
import Extreme, { createPlugin, param } from 'extreme-router';

const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

const uuidPlugin = createPlugin({
  id: 'uuid',
  priority: 550,
  syntax: ':name<uuid>',
  detect: /^:(?<paramName>[a-zA-Z0-9_-]+)<uuid>$/,
  test: (urlSegment) => UUID_REGEX.test(urlSegment),
});

const router = new Extreme<{ handler: string }>();
router.use(uuidPlugin).use(param);

router.register('/orders/:orderId<uuid>').handler = 'GetOrder';
router.register('/users/:userId').handler = 'GetUser';

router.match('/orders/123e4567-e89b-12d3-a456-426614174000');
// { handler: 'GetOrder', params: { orderId: '123e4567-...' } }

router.match('/orders/not-a-uuid'); // null
router.match('/users/regular-id'); // { handler: 'GetUser', params: { userId: 'regular-id' } }
```

> For advanced plugin patterns that require full control over `PluginMeta` (e.g. wildcard consumption, non-capturing segments, custom `additionalMeta`), use the full manual approach described above.

## API

- **`new Extreme<T>(options?: Options<T>)`**: Creates a new router instance.
  - `options.storeFactory`: A function that returns a new store object for each registered route. Defaults to `() => Object.create(null)`.
  - `options.plugins`: An array of plugin functions (`Plugin[]`) to register automatically when the router is created. Defaults to `[]`. Plugins will be applied (and sorted by priority) before any manual `router.use()` calls.
  - `options.allowRegisterUpdateExisting`: If set to `true`, calling `router.register()` for a path that is already registered will not throw an error; instead, it will return the existing store object for that path, allowing you to update or modify its data. If `false` (default), attempting to register an already registered path will throw an error. This option only affects exact path matches and does not merge or update routes with different parameterizations or plugin handling.
  - `options.skipPluginValidation`: If set to `true`, plugin validation is skipped during plugin registration (both in the constructor and when using `router.use()`), improving router initialization time. Defaults to `false`. **⚠️ WARNING:** Enabling this option is safe **only** when using official plugins or well validated custom plugins. When enabled, the router will not verify plugin structure, handler functions, or match function returns, which could lead to runtime errors if plugins are malformed. Use this option only when you are certain your plugins are properly implemented validated and tested.
- **`router.use(plugin: Plugin): this`**: Registers a plugin function and returns the router instance, allowing method chaining.
  - Example:
    ```typescript
    router.use(param).use(wildcard).use(regexParam);
    ```
- **`router.register(path: string): T`**: Registers a route path and returns the associated store object (created by `storeFactory`). Throws errors for invalid paths or conflicts.
- **`router.unregister(path: string): boolean`**: Unregisters a route path. Returns `true` if the path was successfully unregistered, `false` otherwise.
  - Handles static paths, dynamic paths, and paths with optional parameters.
    - For paths with optional parameters, all generated combinations are unregistered **only if you unregister the full registered URL with the optionals**. If you unregister just one of its generated combinations, only that specific combination is removed.
- **`router.match(path: string): Match<T> | null`**: Matches a given path against the registered routes.
  - Returns a `Match<T>` object if a matching route is found. `Match<T>` is the route's store `T` augmented with a `params: Record<string, string>` property.
    - For dynamic path matches, the returned object includes a `params` property containing the extracted parameter values.
    - For static path matches, the returned object is simply the route's store. While the `Match<T>` type includes a `params` property, it will not be present as an own property on the returned store object.
  - Returns `null` if no match is found.
- **`router.inspect(): ListedRoute<T>[]`**: Retrieves a list of all registered routes. This is useful for debugging or administrative purposes.
  - Returns an array of `ListedRoute<T>` objects. Each object has the following properties:
    - `path: string`: The registered path string.
    - `type: 'static' | 'dynamic'`: The type of the route.
    - `store: T`: The original store object associated with the route.
- **`createPlugin(options: CreatePluginOptions): Plugin`**: A helper utility that creates a fully valid `Plugin` from a minimal declarative config, eliminating boilerplate for common plugin patterns. See the [createPlugin Helper](#createplugin-helper) section for details and a full option reference.
- **Error Handling**: The router uses a set of predefined [Error Types](./docs/error-types.md) for consistent error reporting.

## Benchmarks

The following benchmarks measure the raw speed of the `router.match()` operation (ops/sec) for different route types and route counts.

Benchmarks were conducted on: Intel(R) Core(TM) i7-9750H CPU @ 2.60GHz, 16GB RAM.

### Benchmark Results

**Matching Benchmarks (ops/sec)**
Higher is better.

<table style="width:100%; border: none; border-spacing: 0;">
  <tr style="border: none;">
    <td style="width:50%; vertical-align:top; padding-right:10px; padding-bottom:15px; border: none;">
      <strong>25 Routes</strong>
      <table>
        <thead>
          <tr>
            <th>Runtime</th>
            <th>Type</th>
            <th>Ops/sec</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td>Bun</td>
            <td>Static</td>
            <td>40,664,369.57</td>
          </tr>
          <tr>
            <td>Node</td>
            <td>Static</td>
            <td>32,699,587.31</td>
          </tr>
          <tr>
            <td>Bun</td>
            <td>Mixed</td>
            <td>11,275,739.98</td>
          </tr>
          <tr>
            <td>Node</td>
            <td>Mixed</td>
            <td>7,984,073.83</td>
          </tr>
          <tr>
            <td>Bun</td>
            <td>Dynamic</td>
            <td>5,315,190.38</td>
          </tr>
          <tr>
            <td>Node</td>
            <td>Dynamic</td>
            <td>3,700,454.56</td>
          </tr>
        </tbody>
      </table>
    </td>
    <td style="width:50%; vertical-align:top; padding-left:10px; padding-bottom:15px; border: none;">
      <strong>100 Routes</strong>
      <table>
        <thead>
          <tr>
            <th>Runtime</th>
            <th>Type</th>
            <th>Ops/sec</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td>Bun</td>
            <td>Static</td>
            <td>43,161,335.67</td>
          </tr>
          <tr>
            <td>Node</td>
            <td>Static</td>
            <td>30,731,126.72</td>
          </tr>
          <tr>
            <td>Bun</td>
            <td>Mixed</td>
            <td>10,314,999.21</td>
          </tr>
          <tr>
            <td>Node</td>
            <td>Mixed</td>
            <td>7,047,826.06</td>
          </tr>
          <tr>
            <td>Bun</td>
            <td>Dynamic</td>
            <td>2,570,193.17</td>
          </tr>
          <tr>
            <td>Node</td>
            <td>Dynamic</td>
            <td>1,791,611.34</td>
          </tr>
        </tbody>
      </table>
    </td>
  </tr>
  <tr style="border: none;">
    <td style="width:50%; vertical-align:top; padding-right:10px; border: none;">
      <strong>500 Routes</strong>
      <table>
        <thead>
          <tr>
            <th>Runtime</th>
            <th>Type</th>
            <th>Ops/sec</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td>Bun</td>
            <td>Static</td>
            <td>30,417,507.26</td>
          </tr>
          <tr>
            <td>Node</td>
            <td>Static</td>
            <td>28,521,879.69</td>
          </tr>
          <tr>
            <td>Bun</td>
            <td>Mixed</td>
            <td>5,597,866.27</td>
          </tr>
          <tr>
            <td>Node</td>
            <td>Mixed</td>
            <td>4,139,942.82</td>
          </tr>
          <tr>
            <td>Bun</td>
            <td>Dynamic</td>
            <td>1,822,528.37</td>
          </tr>
          <tr>
            <td>Node</td>
            <td>Dynamic</td>
            <td>1,226,324.41</td>
          </tr>
        </tbody>
      </table>
    </td>
    <td style="width:50%; vertical-align:top; padding-left:10px; border: none;">
      <strong>1000 Routes</strong>
      <table>
        <thead>
          <tr>
            <th>Runtime</th>
            <th>Type</th>
            <th>Ops/sec</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td>Bun</td>
            <td>Static</td>
            <td>25,570,061.69</td>
          </tr>
          <tr>
            <td>Node</td>
            <td>Static</td>
            <td>27,940,237.55</td>
          </tr>
          <tr>
            <td>Bun</td>
            <td>Mixed</td>
            <td>4,723,668.94</td>
          </tr>
          <tr>
            <td>Node</td>
            <td>Mixed</td>
            <td>3,477,167.42</td>
          </tr>
          <tr>
            <td>Bun</td>
            <td>Dynamic</td>
            <td>1,859,733.12</td>
          </tr>
          <tr>
            <td>Node</td>
            <td>Dynamic</td>
            <td>1,166,799.26</td>
          </tr>
        </tbody>
      </table>
    </td>
  </tr>
</table>

#### Stress Test Benchmarks

Total matches performed in 20 seconds with 50 concurrent workers. Higher is better.

| Runtime | Routes | Total Matches |
| :------ | :----- | :------------ |
| Bun     | 25     | 151,799,882   |
| Node    | 25     | 92,383,913    |
| Bun     | 100    | 129,399,072   |
| Node    | 100    | 78,502,959    |
| Bun     | 500    | 75,988,452    |
| Node    | 500    | 50,230,329    |
| Bun     | 1000   | 66,190,291    |
| Node    | 1000   | 46,227,299    |

#### Memory Usage Benchmarks

Test duration: 30 seconds. Lower heap usage and increase is generally better.

| Runtime | Routes | Start Heap | Stable End Heap | Peak Heap | Increase (Stable End - Start) |
| :------ | :----- | :--------- | :-------------- | :-------- | :---------------------------- |
| Bun     | 25     | 228.86 KB  | 1.97 MB         | 2.04 MB   | 1.75 MB (782.49%)             |
| Node    | 25     | 5.33 MB    | 6.53 MB         | 8.56 MB   | 1.19 MB (22.39%)              |
| Bun     | 100    | 228.86 KB  | 2.06 MB         | 2.15 MB   | 1.83 MB (820.44%)             |
| Node    | 100    | 5.47 MB    | 6.7 MB          | 8.63 MB   | 1.23 MB (22.58%)              |
| Bun     | 500    | 228.86 KB  | 2.18 MB         | 2.27 MB   | 1.96 MB (876.51%)             |
| Node    | 500    | 5.67 MB    | 7.83 MB         | 12.04 MB  | 2.15 MB (37.99%)              |
| Bun     | 1000   | 228.86 KB  | 2.37 MB         | 2.45 MB   | 2.15 MB (961.21%)             |
| Node    | 1000   | 5.96 MB    | 9.02 MB         | 12.12 MB  | 3.06 MB (51.26%)              |

### Understanding Bun vs. Node.js Memory Behavior

The memory benchmark results highlight differing memory usage patterns between Bun and Node.js. These differences primarily stem from their underlying JavaScript engines and memory management strategies:

1.  **JavaScript Engines:**
    - **Bun:** Utilizes JavaScriptCore (JSC), known for quick startup and potentially lower initial memory consumption.
    - **Node.js:** Employs V8, which is highly optimized for long-running server applications.

2.  **Initial Heap Size and Growth:**
    - **Bun (JSC):** The benchmarks show Bun starting with a very small heap (e.g., `228.86 KB`). This results in a large _percentage_ increase as the application allocates memory, even if the final _absolute_ heap size remains relatively small (around 2 MB).
    - **Node.js (V8):** Node.js starts with a considerably larger initial heap (e.g., `5.33 MB - 5.67 MB`). Consequently, its _percentage_ increase is smaller for comparable absolute memory growth.

3.  **Interpreting the "Increase":**
    - The significant _percentage_ increase in Bun's memory usage is largely due to its low starting base. The "Stable End Heap" and absolute MB increase offer a clearer view of the memory actively used during the test.
    - Both runtimes demonstrate memory stability under the test conditions, suggesting `extreme-router` itself is not exhibiting a runaway memory leak. The observed variations are more indicative of the engines' default heap management behaviors.

In essence, Bun/JSC's strategy leads to a low initial memory footprint, causing high percentage growth to a still modest absolute size. Node/V8 begins with a larger heap, resulting in smaller percentage growth for similar absolute increases. Both appear to manage memory effectively for the router in these tests.

You can run benchmarks to see Extreme Router's performance:

```bash
# Matching benchmark (25 routes by default)
# General mixed benchmark
bun run benchmark # static and dynamic routes
# Specify type: static, dynamic
bun run benchmark:static
bun run benchmark:dynamic
# Specify number of routes
bun run benchmark --routes=100
bun run benchmark:static --routes=100
bun run benchmark:dynamic --routes=100

# Memory usage benchmark
bun run benchmark:memory
bun run benchmark:memory --routes=200

# Stress test (concurrent matching)
bun run benchmark:stress
bun run benchmark:stress --routes=500
bun run benchmark:stress --routes=1000
```

## Testing

Run the comprehensive test suite:

```bash
bun test
# or for coverage report
bun run test:coverage
```

The coverage report can be found in the `coverage/` directory ([coverage/index.html](coverage/index.html)).

**100% code coverage** is ensured.

## Acknowledgments

Extreme Router draws inspiration from the high-level routing concepts and per-route register/store design of [Medley Router](https://github.com/medleyjs/router). Sincere thanks to the Medley Router authors for their foundational ideas.

## Contributing

Contributions are welcome!  
Please read our [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines on development, testing, benchmarking, and submitting pull requests.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

extreme-router

extreme-router Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

extreme-router

extreme-router Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README