🌳 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,
  routesOverlap,
  findOverlappingRoutes,
  routeToRegExp,
  regExpToRoute,
  NullProtoObj,
} from "rou3";

CDN (Deno and Browsers)

import {
  createRouter,
  addRoute,
  findRoute,
  removeRoute,
  findAllRoutes,
  routesOverlap,
  findOverlappingRoutes,
  routeToRegExp,
  regExpToRoute,
  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.

• 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:

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"

Pattern overlap

findRoute/findAllRoutes match a concrete path against registered patterns. Sometimes you instead need to reason about patterns against patterns — e.g. to resolve an "effective" merged config over a whole scope, you need to know when two patterns can match a common concrete path.

Two utilities cover this:

import { createRouter, addRoute, routesOverlap, findOverlappingRoutes } from "rou3";

// Do two patterns share at least one concrete path? (pure, router-free)
routesOverlap("/**", "/protected/feed/**"); // true
routesOverlap("/a/**", "/b/**"); // false

// Every registered route whose match-set intersects a *pattern* (a scope),
// ordered least -> most specific like findAllRoutes.
const router = createRouter();
addRoute(router, "GET", "/**", { isr: true });
addRoute(router, "GET", "/protected/**", { basicAuth: true });
addRoute(router, "GET", "/protected/feed/**", { isr: 60 });

findOverlappingRoutes(router, "GET", "/protected/feed/**");
// [ { data: { isr: true } },        // /**
//   { data: { basicAuth: true } },  // /protected/**
//   { data: { isr: 60 } } ]         // /protected/feed/**

• routesOverlap(patternA, patternB) — returns true if the two patterns' match-sets intersect (there exists a concrete path matched by both). This is overlap, not subset containment.
• findOverlappingRoutes(router, method, pattern) — like findAllRoutes, but the query is a pattern instead of a concrete path. Returns every registered route whose match-set intersects the pattern, ordered least → most specific, with the same method handling as findAllRoutes (falls back to the method-agnostic bucket). Matches carry only data — a scope has no single concrete path, so no params are resolved. A single route registered with optional/group syntax expands into several tree entries sharing one data reference and is reported once; distinct routes are always reported separately, even when they share an equal primitive data value (or none).

Overlap semantics are computed with rou3's own segment/radix rules, so they stay consistent with findRoute/findAllRoutes:

• Patterns are expanded through the same pipeline as addRoute, so groups ({s}?), optional/repeat modifiers (:x?/:x+/:x*), and escaping (\:, \*) are all respected. A pattern with optional syntax expands to several shapes; two patterns overlap when any pair of shapes overlaps.
• Segment counts: bare ** matches zero or more segments (so /a/** overlaps /a), **:name matches one or more, a trailing bare * matches zero or one, and mid-pattern * / :name match exactly one.
• Regex constraints (:id(\d+), unnamed groups, *.png) are matched precisely against static literals (/user/:id(\d+) does not overlap /user/abc), but two dynamic segments where at least one is constrained are over-approximated to "overlaps" — routesOverlap("/user/:id(\d+)", "/user/:name([a-z]+)") returns true even though the sets are disjoint. Exact regex intersection is undecidable, and over-approximating toward "overlaps" is the safe conservative default.

Regular expressions

routeToRegExp(route) converts a route pattern into an anchored RegExp with named capture groups, useful outside the router (validation, codegen, matching in other tools):

import { routeToRegExp } from "rou3";

routeToRegExp("/users/:id(\\d+)");
// /^\/users\/(?<id>\d+)\/?$/  ->  "/users/123".match(re).groups // { id: "123" }

The output is PCRE-compatible: it uses (?<name>...) named groups and avoids JS-only constructs, so the generated .source also compiles in PCRE2 engines (grep -P, rg -P, pcre2grep, PHP preg_*) and Perl — not just JavaScript. In particular, trailing optional groups are compiled inline as (?:...)? instead of an alternation, so a param is never emitted twice as a duplicate named group (which PCRE2 rejects unless PCRE2_DUPNAMES is set):

routeToRegExp("/blog/:id(\\d+){-:title}?");
// /^\/blog\/(?<id>\d+)(?:-(?<title>[^/]+))?\/?$/

[!NOTE] Multi-group or mid-route optionals that cannot be inlined fall back to an alternation and may contain duplicate named groups. That output is valid in JavaScript (per the TC39 duplicate-named-groups proposal) and Perl, but requires PCRE2_DUPNAMES on strict PCRE2 engines.

regExpToRoute(regexp) is the inverse: it parses an anchored, PCRE-compatible RegExp (or its source string) back into a route pattern. Pass either a RegExp or a source string:

import { regExpToRoute } from "rou3";

regExpToRoute(/^\/users\/(?<id>\d+)\/?$/); // "/users/:id(\\d+)"
regExpToRoute(/^\/path\/(?<param>[^/]+)\/?$/); // "/path/:param"
regExpToRoute(/^\/base\/?(?<path>.+)\/?$/); // "/base/**:path"
regExpToRoute("^\\/files\\/(?<_0>[^/]*)\\.png\\/?$"); // "/files/*.png"

It targets the dialect routeToRegExp() emits — named groups (?<name>...), [^/]+/[^/]* segment matchers, .*/.+ catch-alls, and (?:/...)? optional groups. Bare (unnamed) capturing groups such as (\d+) are accepted too, and arbitrary regex inside an inline constraint (...) is preserved verbatim. Every reversible output round-trips exactly: routeToRegExp(regExpToRoute(regexp)).source === regexp.source.

Anything outside that dialect throws a clear error rather than returning a corrupt pattern: structural look-arounds ((?=…), (?<=…)) and backreferences, bare regex operators outside a constraint (|, ., +, […], …), match-affecting flags (i/m/s), the non-reversible alternation fallback described above, and inline constraints that can't be expressed as a route (e.g. one containing /).

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