🌳 rou3

Lightweight and fast router for JavaScript.

Usage

Install:

# ✨ Auto-detect
npx nypm install rou3

Import:

ESM (Node.js, Bun, Deno)

import {
  createRouter,
  addRoute,
  findRoute,
  removeRoute,
  findAllRoutes,
  routeToRegExp,
  NullProtoObj,
} from "rou3";

CDN (Deno and Browsers)

import {
  createRouter,
  addRoute,
  findRoute,
  removeRoute,
  findAllRoutes,
  routeToRegExp,
  NullProtoObj,
} from "https://esm.sh/rou3";

Create a router instance and insert routes:

import { createRouter, addRoute } from "rou3";

const router = createRouter(/* options */);

addRoute(router, "GET", "/path", { payload: "this path" });
addRoute(router, "POST", "/path/:name", { payload: "named route" });
addRoute(router, "GET", "/path/foo/**", { payload: "wildcard route" });
addRoute(router, "GET", "/path/foo/**:name", {
  payload: "named wildcard route",
});

Match route to access matched data:

// Returns { payload: 'this path' }
findRoute(router, "GET", "/path");

// Returns { payload: 'named route', params: { name: 'fooval' } }
findRoute(router, "POST", "/path/fooval");

// Returns { payload: 'wildcard route' }
findRoute(router, "GET", "/path/foo/bar/baz");

// Returns undefined (no route matched for/)
findRoute(router, "GET", "/");

Important

Paths should always begin with /.

Important

Method should always be UPPERCASE.

Tip

If you need to register a pattern containing literal : or *, you can escape them with \\. For example, /static\\:path/\\*\\* matches only the static /static:path/** route.

Route Patterns

rou3 supports URLPattern-compatible syntax.

Pattern	Example Match	Params
/path/to/resource	/path/to/resource	{}
/users/:name	/users/foo	{ name: "foo" }
/path/**	/path/foo/bar	{}
/path/**:rest	/path/foo/bar	{ rest: "foo/bar" }
/files/*.png	/files/icon.png	{ "0": "icon" }
/files/file-*-*.png	/files/file-a-b.png	{ "0": "a", "1": "b" }
/users/:id(\\d+)	/users/123	{ id: "123" }
/files/:ext(png|jpg)	/files/png	{ ext: "png" }
/path/(\\d+)	/path/123	{ "0": "123" }
/users/:id?	/users or /users/123	{} or { id: "123" }
/files/:path+	/files/a/b/c	{ path: "a/b/c" }
/files/:path*	/files or /files/a/b	{} or { path: "a/b" }
/book{s}?	/book or /books	{}
/blog/:id(\\d+){-:title}?	/blog/123 or /blog/123-my-post	{ id: "123" } or { id: "123", title: "my-post" }

• Named params (:name) match a single segment.
• Single-segment wildcards (*) capture unnamed params (0, 1, ...) and can be used as full or mid-segment tokens (for example /* or /*.png).
• Wildcards (**) match zero or more segments. Use **:name to capture.
• Regex constraints (:name(regex)) restrict matching. Constrained and unconstrained params can coexist on the same node (constrained checked first).
• Unnamed groups ((regex)) capture into auto-indexed keys 0, 1, etc.
• Modifiers: :name? (optional), :name+ (one or more), :name* (zero or more). Can combine with regex: :id(\d+)?.
• Non-capturing groups ({...}): supported with inline (/foo{bar}) and optional (/foo{bar}?) forms.
• Current limitation: repeating non-capturing groups ({...}+, {...}*) are supported only within a single segment (no / inside the group body).
• Backslash escaping (\): escape special characters like :, *, (, ), {, } with a backslash (e.g., /static\:path matches literal /static:path).

Differences from URLPattern

rou3 aims for URLPattern-compatible syntax but has intentional differences due to its radix-tree design:

Feature	URLPattern	rou3
* (single star)	Greedy catch-all (.*) across /	Single-segment unnamed param ([^/]*)
** (double star)	Literal **	Catch-all wildcard (zero or more segments)
(.*) in segment	Greedy match across /	Segment-scoped (does not cross /)
{...}+ / {...}* groups	Cross-segment group repetition	Only supported within a single segment (no / in group body)
Path normalization (./..)	Resolves ./.. in input paths	Not done by default (opt-in with { normalize: true })
Case sensitivity	Can be case-insensitive	Always case-sensitive
Non-/-prefixed paths	Supported	Paths must start with /
Unicode param names	Supports Unicode identifiers	Params use \w (ASCII word chars only)
Percent-encoding	Normalizes %xx sequences	Does not decode percent-encoded input

Path normalization

By default, findRoute and findAllRoutes do not resolve ./.. segments in input paths. If your input paths may contain relative segments, enable normalization:

findRoute(router, "GET", "/foo/bar/../baz", { normalize: true });
// Matches "/foo/baz"

findAllRoutes(router, "GET", "/foo/./bar", { normalize: true });
// Matches "/foo/bar"

The compiled router also supports this via the normalize option:

const match = compileRouter(router, { normalize: true });
match("GET", "/foo/bar/../baz"); // Matches "/foo/baz"

Compiler

compileRouter(router, opts?)

Compiles the router instance into a faster route-matching function.

IMPORTANT: compileRouter requires eval support with new Function() in the runtime for JIT compilation.

Example:

import { createRouter, addRoute } from "rou3";
import { compileRouter } from "rou3/compiler";
const router = createRouter();
// [add some routes]
const findRoute = compileRouter(router);
const matchAll = compileRouter(router, { matchAll: true });
findRoute("GET", "/path/foo/bar");

compileRouterToString(router, functionName?, opts?)

Compile the router instance into a compact runnable code.

IMPORTANT: Route data must be serializable to JSON (i.e., no functions or classes) or implement the toJSON() method to render custom code or you can pass custom serialize function in options.

Example:

import { createRouter, addRoute } from "rou3";
import { compileRouterToString } from "rou3/compiler";
const router = createRouter();
// [add some routes with serializable data]
const compilerCode = compileRouterToString(router, "findRoute");
// "const findRoute=(m, p) => {}"

License

Published under the MIT license. Made by @pi0 and community 💛

---

🤖 auto updated with automd