npm package: @fwoom/router
Description: High-performance HTTP router based on a segmented radix trie
Author: SUJWN
Latest version: 0.3.0

# FwoomRouter

<div align="center">
<b><i>💨...fwoom...💨</i></b>

<br>

<i>That’s the sound of a request flying through your routing table at full speed.</i>

[![npm version](https://img.shields.io/npm/v/@fwoom/router)](https://www.npmjs.com/package/@fwoom/router)
![license](https://img.shields.io/npm/l/@fwoom/router)


</div>

---

High-performance, framework-agnostic HTTP router for Node.js, built on a segmented radix tree with an optional compiled mode for maximum speed.

**FwoomRouter** focuses on **correctness, performance, and predictability**. It is designed as a low-level routing engine, not a full web framework.

## What is FwoomRouter?

**FwoomRouter** is:

* A **fast HTTP router** (method + path → handler)
* Based on a **segmented radix trie**
* Designed for **zero-allocation runtime matching**
* Capable of a **compiled mode** for maximum throughput
* **Framework-agnostic** (works with Express, Node.js HTTP, or custom servers)

It only answers one question efficiently:

> "Given a method and a path, which handler should run, and with what params?"

---

## Features

* **Segmented radix trie** routing
* Static, param, and wildcard routes
* Full precedence correctness: **static > param > wildcard**
* Wildcard remainder support (`/files/*rest`)
* **Zero-allocation** hot-path matcher
* Optional compiled mode (flattened trie + jump tables)
* Adapters
  * Pure Node.js adapter (`fwoomNode`)
  * Express adapter (`fwoomExpress`)
  * **...and more to come!**
* Custom handler responses: `{ statusCode, headers, body }`
* Clean, minimal public API

---

## Installation

```
npm install @fwoom/router
```

---

## Public API

```js
import { createRouter, fwoomExpress, fwoomNode } from "@fwoom/router";
```

### createRouter()

Creates a new router instance.

### router.add(method, path, handler)

Registers a route.

* `method`: HTTP method (string)
* `path`: route path (`/user/:id`, `/files/*rest`, etc.)
* `handler`: function invoked on match

### router.match(method, path)

Matches a request and returns:

```js
{ handler, params } | null
```

### router.compile()

Compiles the internal trie into a high-performance flattened structure.

---

## Match Order

FwoomRouter uses deterministic precedence:

1. **Static routes** (`/users/me`)
2. **Param routes** (`/users/:id`)
3. **Wildcard routes** (`/users/*rest`)

Param routes correctly fall back to wildcard routes when deeper paths exist.

---

## Basic Usage

### Runtime routing (no compile)

```js
import { createRouter } from "@fwoom/router";

const router = createRouter();

router.add("GET", "/hello", () => "Hello World");
router.add("GET", "/user/:id", ({ id }) => `User ${id}`);

console.log(router.match("GET", "/hello")?.handler());
// → "Hello World"
```

---

## Compiled Mode

Compiled mode rearranges the trie into a high-performance flattened structure.

```js
router.compile();

router.match("GET", "/user/123")?.handler();
```

---

## Adapters

### Pure Node.js Integration

```js
import { createServer } from "http";
import { createRouter, fwoomNode } from "@fwoom/router";

const router = createRouter();

router.add("GET", "/hello", () => "Hi from Node");
router.add("POST", "/data", ({ body }) => ({ statusCode: 201, body }));

router.compile();

const server = createServer(
  fwoomNode(router, { json: true })
);

server.listen(3000);
```

---

### Express Integration

```js
import express from "express";
import { createRouter, fwoomExpress } from "@fwoom/router";

const app = express();
app.use(express.json());

const router = createRouter();

router.add("POST", "/user", ({ body }) => ({
  statusCode: 201,
  body: { message: "Created", body }
}));

router.compile();

app.use(fwoomExpress(router));

app.listen(3000);
```

---


## Handler Return Values

Handlers may return:

### String

```js
return "OK";
```

### JSON

```js
return { message: "done" };
```

### Custom status and headers

```js
return {
  statusCode: 201,
  headers: { "x-created": "true" },
  body: { id: 1 }
};
```

---

## Testing Philosophy

FwoomRouter uses **equivalence tests**:

* Runtime matcher is tested **before** `compile()`
* Compiled matcher is tested **after** `compile()`

If compiled mode behaves correctly, runtime behavior is implicitly verified.

---

## Caveats (v0.3.0)

* No route grouping yet
* No constraints or regex params
* One wildcard per route
* No built-in middleware system

These are planned for future releases.

---

## Roadmap

Planned milestones:

* Route grouping (`router.group()`)
* Router introspection (`listRoutes()`, `printTree()`)
* Route validation & better errors
* Benchmark suite
* Memory optimizations
* More adapters

---

## License

[MIT](LICENSE) © 2025