FwoomRouter

💨...fwoom...💨

That’s the sound of a request flying through your routing table at full speed.

---

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

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:

{ 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)

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.

router.compile();

router.match("GET", "/user/123")?.handler();

---

Adapters

Pure Node.js Integration

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

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

return "OK";

JSON

return { message: "done" };

Custom status and headers

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 © 2025