🌳 rou3

# ✨ Auto-detect
npx nypm install rou3

import { createRouter, addRoute, findRoute, findAllRoutes, removeRoute } from "rou3";
const router = createRouter();
addRoute(router, "GET", "/about", { page: "about" });
addRoute(router, "GET", "/users/:id", { page: "user" });
addRoute(router, "GET", "/docs/**", { page: "docs" });

findRoute(router, "GET", "/about");
// { data: { page: "about" } }
findRoute(router, "GET", "/users/42");
// { data: { page: "user" }, params: { id: "42" } }
findRoute(router, "GET", "/docs/guide/intro");
// { data: { page: "docs" }, params: { "0": "guide/intro", _: "guide/intro" } }
findRoute(router, "GET", "/missing");
// undefined

addRoute(router, "GET", "/docs/:section/intro", { page: "intro" });
findAllRoutes(router, "GET", "/docs/guide/intro");
// [
//   { data: { page: "docs" }, params: { "0": "guide/intro", _: "guide/intro" } },
//   { data: { page: "intro" }, params: { section: "guide" } },
// ]

removeRoute(router, "GET", "/users/:id");

rou3 supports URLPattern-like syntax. A segment is the part of a path between two /.

| Pattern | Example match | Params | | --------------------------- | ---------------------------------------- | ---------------------------------------------------- | | /path/to/resource | /path/to/resource | {} | | /users/:name | /users/foo | { name: "foo" } | | /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" } | | /files/* | /files/ or /files/a/b | { "0": "" } or { "0": "a/b" } | | /files/*.png | /files/icon.png or /files/a/icon.png | { "0": "icon" } or { "0": "a/icon" } | | /path/** | /path/foo/bar | { "0": "foo/bar", _: "foo/bar" } (_ is deprecated) | | /path/**:rest | /path/foo/bar | { rest: "foo/bar" } | | /**/_payload.json | /_payload.json or /a/b/_payload.json | {} or { "0": "a/b", _: "a/b" } | | /**.md | /docs/intro.md | { "0": "docs/intro" } | | /book{s}? | /book or /books | {} | | /blog/:id(\\d+){-:title}? | /blog/123 or /blog/123-my-post | { id: "123" } or { id: "123", title: "my-post" } | | /files/:name.:ext | /files/a.tar.gz | { name: "a", ext: "tar.gz" } | | /v:version? | /v or /v2 | {} or { version: "2" } |

[!NOTE]

In JavaScript strings a regex backslash is written twice: "/users/:id(\\d+)" is the pattern /users/:id(\d+).

Params

• Named params :name match one segment: /users/:name. They can also sit inside a segment: /blog/:year-:month. When several params share a segment, each one takes as little as it can, as in URLPattern: /:a-:b on /x-y-z gives { a: "x", b: "y-z" }, and /:name.:ext on /a.tar.gz gives { name: "a", ext: "tar.gz" }. A takes as much as it can, / included: /-:a on /x-y-z gives { "0": "x-y", a: "z" }, and on /x/y-z gives { "0": "x/y", a: "z" }.
• Regex constraints :name(regex) only match when the regex does: /users/:id(\\d+). The regex applies to one segment and can't contain /.
• Unnamed groups (regex) capture into numbered keys "0", "1", …: /path/(\\d+). Inside a regex, group with (?:…): a capturing group there throws (/:x((a)), /:x((?a))).
• Modifiers go at the end of a whole-segment param:

• ? inside a segment makes only the param optional: /pre-:x? matches /pre- and /pre-a, but not /. Use a group for an optional segment: /{pre-:x}?. After a or a regex constraint, the capture takes what it can first, as in URLPattern: /-:x? on /-- gives { "0": "-" }, and /:a(\\d+):b? on /12 gives { a: "12" }. An absent param has no key. A group holding only the param is the same (/-{:x}? is /-:x?).

Wildcards

• matches the rest of the path, as URLPattern's ((.) after its /): / included, captured into a numbered key. /files/ on /files/a/b gives { "0": "a/b" }. A whole-segment that ends the route, or ends one of its expansions (before optional segments or groups), is optional, as in rou3 0.11 (URLPattern's isn't): /files/ also matches /files (no key, like *) and /files/ ({ "0": "" }), so use("/api/")-style scopes cover /api too; so do /a//:x? and /a/{.png}? on /a, and /a{/b/}? on /a/b. Elsewhere it takes one segment or more: /files//raw doesn't match /files/raw. Inside a segment it takes the rest of the segment and what follows: /files/*.png on /files/a/icon.png gives { "0": "a/icon" }. For one segment, use a :name.

• matches zero or more segments and captures them into a numbered key, like : /docs/ on /docs/a/b gives { "0": "a/b", _: "a/b" }. Over zero segments both keys are left out (/docs/ on /docs and /docs/ gives {}), and an empty segment is "" (/docs// gives { "0": "", _: "" }). At the end of a route it matches the same paths as , which gives "" on /docs/ (and wins over where both are registered); before more of the route it can also take zero segments (/docs/*/x matches /docs/x, /docs//x doesn't).
• Unnamed captures (, and unnamed groups) are numbered in pattern order over the whole pattern, as in URLPattern, also those in an optional group that is left out: /(\\d+)/x/ on /1/x/b/c gives { "0": "1", "1": "b/c", _: "b/c" }, and /a{/(\\d+)}?/ on /a/x/y gives { "1": "x/y" }.

• :name matches one or more segments and captures them into name: /docs/:path. It is the same as :name+: like :name, it needs a value, and so does each segment it takes: /docs// and /docs/a//b don't match (see empty segments).
• Segments after a catch-all are matched from the end of the path, and the catch-all takes whatever is in between. //_payload.json matches _payload.json in any directory, /blog/:path/og.png matches og.png anywhere under /blog, and /*/edit matches /a/edit and /a/b/edit ({ "0": "a/b" }).
• followed by text reads like there, as in URLPattern: /.md is /.md, any path ending in .md (one capture). Anywhere else in a segment, throws (/ab, /a/x*): write or \\\\ for a literal.

Groups

{...} groups part of a pattern without capturing it. Add ? to make it optional:

• /book{s}? matches /book and /books.
• /users{/:id}?/posts matches /users/posts and /users/42/posts.

A pattern can start with a group. A group that starts with / is part of the path, as in URLPattern: {/:lang}?/docs matches /docs and /en/docs, and {/:lang}? matches / and /en. Write /{/:lang}?/docs for a route that starts with an empty segment (//docs, //en/docs). A pattern that doesn't start with / gets one (users/:id is /users/:id), and so does each form of a leading group without one: {v2}?/api matches /v2/api and /api. Text right after a leading {/…}? throws ({/a}?b, {/:id}?.png, {/a}?{.json}?): without the group the route would not start with /. Follow it with /, another {/…} group, or nothing.

Escaping

Escape :, *, ?, +, (, ), { and } with a backslash to match them literally (a literal ?, { or } is then percent-encoded, like other literal text). Outside a regex constraint, any escaped character is a literal (\\. is ., \\\\ is \), as in URLPattern. A \ can't escape / or end a segment.

addRoute(router, "GET", "/static\\:path/\\\\", {}); // matches only "/static:path/**"
addRoute(router, "GET", "/files/\\(2024\\)", {}); // matches only "/files/(2024)"

Percent-encoding

The literal text of a pattern is percent-encoded once, when the route is added, the same way URLPattern and new URL() encode a pathname. Lookup paths are not decoded or encoded, so pass the encoded pathname (new URL(req.url).pathname):

addRoute(router, "GET", "/café/:id", {});
findRoute(router, "GET", "/caf%C3%A9/1"); // { data: {}, params: { id: "1" } }
findRoute(router, "GET", "/café/1"); // undefined

• Encoded: control characters (tab and newline too, which URLPattern drops), space, ", #, <, >, ?, ^, ` `, {, }, and every non-ASCII character (as UTF-8, upper-case hex: é is %C3%A9). This covers escaped characters too: \\? matches %3F, \\{ matches %7B.
• Not encoded: %, so an existing %xx stays as written (/caf%c3%a9 matches only /caf%c3%a9, not /caf%C3%A9), and other ASCII characters (/a|b[c] stays as is).
• Regex constraints are regex and are not encoded: write :x(%C3%A9), not :x(é).
• A lone surrogate is encoded as U+FFFD (%EF%BF%BD), as in URLPattern.
• ^ follows the URL spec, as Node.js and Bun do. Deno (2.9) leaves it unencoded in new URL().pathname (/a^b), so on Deno encode it before a lookup (pathname.replaceAll("^", "%5E")) for routes with a literal ^.

addRoute throws a rou3: error that quotes the pattern when the syntax has no meaning, instead of silently matching something unexpected. For example: an unclosed ( or {, a nested group, an empty group (), a modifier in the wrong place (?, +, :x.png?), a ? after plain text (/foo?: lookup paths have no query string, escape a literal one as \\?), a in the middle of a segment (/a*b), an invalid or repeated param name (/:0, /:café, /:id$, /a/:x/:x), a second catch-all, a \/, a capturing group inside a regex constraint (/:x((a)), use (?:…)), or an anchor (^, $), look-around or numbered backreference (\1) in a regex constraint, or a character from U+FFFD to U+FFFF (used internally), or text right after a leading {/…}? group ({/a}?b). The router tests a constraint against its segment alone, while routeToRegExp puts it inline, where it would see the rest of the path, so the two would match different paths.

| Feature | URLPattern | rou3 | | ----------------------------- | ---------------------------------- | ----------------------------------------------- | | Trailing (a whole-segment that ends the route or one of its expansions) | Required (/foo/ doesn't match /foo, nor /a//:x? /a) | Optional (/foo/ matches /foo, no key; /a//:x? matches /a), so use("/api/*")-style scopes cover /api too | | Trailing slash on a | Part of the capture (/foo/ on /foo/a/ is { 0: "a/" }) | One trailing slash is ignored ({ 0: "a" }; /foo// is { 0: "" }, URLPattern: "/") | | Several catch-alls (, ) | Any number (//x/) | One per route (throws): write /:a/x/ | | (double star) | with a modifier: a numbered capture across /, unset over zero segments (/foo/ on /foo is {}) | Same key and value (also as the deprecated _) over whole segments. One trailing slash is ignored, so /foo/** on /foo/ is {} too (URLPattern: { 0: "" }) | | (.*) in a segment | Greedy match across / | Stays within the segment | | {...}+ / {...}* groups | Group repetition | Not supported (throws) | | Path normalization (./..) | Resolved in input paths | Opt-in with { normalize: true } | | Case sensitivity | Can be case-insensitive | Always case-sensitive | | Non-/-prefixed paths | Supported | Paths must start with / | | Patterns without a leading / (users/:id, {v2}?/api) | Never match an absolute path | Get a / (/users/:id); a leading group, in each form without one ({v2}?/api matches /v2/api and /api) | | Optional group with text after a greedy capture in its segment (/{.webp}?) | The capture takes what it can (/a.webp: { 0: "a.webp" }) | The route with the group wins (/a.webp: { 0: "a" }); a group holding only a param is that param, as in URLPattern (/-{:x}? is /-:x?, and /a/{:x}?, which is /a/:x?: its segment is required, no match on /a, and /a/b gives { 0: "b" }, not { 0: "", x: "b" }), except before more of its segment, where it stays a group (/-{:x}?(y) on /a--y: { 0: "a", x: "-", 1: "y" }, URLPattern { 0: "a-", 1: "y" }) | | Optional group before more of its segment (/:foo{x}?(.*)) | The param takes as little as it can (/abx: { foo: "a", 0: "bx" }) | The route with the group wins (/abx: { foo: "ab", 0: "" }) | | Optional group that can match empty text (/{:foo}{(\\d*)}?) | Unset where it matches nothing (/a: { foo: "a" }) | The router gives "" (/a: { foo: "a", 0: "" }); routeToRegExp leaves it unset | | Several optional groups in a segment (/{:foo}?{(\\d+)}?) | One regex (/1: { foo: "1" }) | They expand to separate routes, and a regex param outranks a plain :foo whatever the order (/1 matches /(\\d+) and /:foo: { 0: "1" }); routeToRegExp gives URLPattern's { foo: "1" } | | Optional segment after a catch-all (, , :name+, :name: //:x?, /a/{/b}?, /:a+/:b?) | The catch-all takes what it can (//:x? on /x/y: { 0: "x/y" }, /a/{/b}? on /a/x/b: { 0: "x/b" }) | Segments after a catch-all match from the end, and the route with the optional segment wins ({ 0: "x", x: "y" }, { 0: "x" }) | | Optional segment before a trailing (/a/:x?/, {/:a}?/) | The takes the segment (/a/b: { 0: "b" }, as rou3 0.11 did) | The route with the optional segment wins and the * is optional (/a/b: { x: "b" }; routeToRegExp too) | | Optional segment before a static one (/:x?/a/) | The pattern is matched left to right (/a/a/b: { x: "a", 0: "b" }, as routeToRegExp gives) | A static segment wins over a param, so the route without the optional one does (/a/a/b: { 0: "a/b" }; * too) | | Empty capture before a trailing slash (/a/(\\d), /a/:x?, /a/(\\d) on /a/) | Matches with "" | One trailing slash is ignored, so no segment is left to capture: only a whole-segment (/a/, /a/{.png}?) takes nothing there. /a// matches (/a/(\\d*): { 0: "", 1: "" }) | | Param names | Unicode identifiers | [A-Za-z_]\w*; a non-ASCII char or $ right after one throws | | Percent-encoding | Encodes the pattern's literal text and the input | Encodes the pattern's literal text; the input must already be encoded (new URL().pathname) and is never decoded |

The paths you look up must start with / and the methods must be UPPERCASE ("GET", not "get"). rou3 does not normalize lookup input, so do it before calling findRoute. Paths must be percent-encoded, as new URL().pathname gives them: a route's literal text is encoded (see percent-encoding).

Register a route with the method "" to match every method. It's useful for things like middleware or auth checks:

addRoute(router, "", "/users/*", { auth: true }); // any method
addRoute(router, "GET", "/users/:id(\\d+)", { handler: "user" });
findAllRoutes(router, "GET", "/users/42").map((m) => m.data);
// [{ auth: true }, { handler: "user" }]
findRoute(router, "GET", "/users/42")?.data; // { handler: "user" }
findRoute(router, "GET", "/users/me")?.data; // { auth: true }
findRoute(router, "POST", "/users/42")?.data; // { auth: true }

A lookup sees the routes for its method and the method-agnostic ones together, and the most specific one wins. When two routes are equally specific, the one registered for the method wins over the method-agnostic one (and comes after it in findAllRoutes). A lookup with the method "" only sees method-agnostic routes.

• At most one trailing slash is ignored: /users/foo/ matches /users/:name, /users/foo// does not. A ending a route reads it: /users/ gives { "0": "" } on /users/ (as in URLPattern) and no key on /users.
• In patterns, trailing slashes are ignored: /users/, /users// and /users are the same route.
• Empty segments in the middle are real: /a//b does not match /a/b.
• A :name, :name+, :name or :name needs a value, as in URLPattern: it never captures "" (a :name can match no segment instead), and none of the segments a :name+, :name or :name takes can be empty. A , * or a regex constraint that can match empty (:id(\\d)) takes an empty segment:

addRoute(router, "GET", "/admin/:id", {});
addRoute(router, "GET", "/files/:path+", {});
addRoute(router, "GET", "/docs/:path*", {});
addRoute(router, "GET", "/raw/*", {});
findRoute(router, "GET", "/admin/"); // undefined (the trailing slash is ignored)
findRoute(router, "GET", "/admin//"); // undefined (an empty segment)
findRoute(router, "GET", "/files//"); // undefined
findRoute(router, "GET", "/files///"); // undefined (two empty segments)
findRoute(router, "GET", "/files/a//b"); // undefined (an empty segment inside the value)
findRoute(router, "GET", "/files/a/b/"); // params: { path: "a/b" } (the trailing slash is ignored)
findRoute(router, "GET", "/docs"); // matches, no path
findRoute(router, "GET", "/docs//"); // undefined
findRoute(router, "GET", "/raw"); // params: {} (a trailing * is optional)
findRoute(router, "GET", "/raw/"); // params: { "0": "" }
findRoute(router, "GET", "/raw//"); // params: { "0": "" } (the trailing slash is ignored)

. and .. segments are not resolved by default. If your input paths may contain them, enable normalize:

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

As in new URL(), a last . or .. leaves a trailing slash: /foo/bar/.. is /foo/, which /foo/* matches ({ "0": "" }). Since 0.12 this also keeps an empty segment before it: /a//. is /a// and no longer matches /a, and //. and //x/.. are //, which no longer match /.

The compiler accepts the same option: compileRouter(router, { normalize: true }).

If you only need the route data, pass { params: false } to skip building the params object:

findRoute(router, "GET", "/docs/guide", { params: false });
// { data: { page: "docs" } }

findAllRoutes returns matches from the least to the most specific, and findRoute returns the most specific one. This order is part of the public API: you can rely on it, for example to merge all matched route rules so that the most specific one wins.

const router = createRouter();
addRoute(router, "GET", "/**", { name: "catch-all" });
addRoute(router, "GET", "/api/**", { name: "api" });
addRoute(router, "GET", "/api/:v/users/:id", { name: "user" });
findAllRoutes(router, "GET", "/api/v1/users/42").map((m) => m.data.name);
// ["catch-all", "api", "user"]

The compiled matchAll function returns exactly the same results in the same order.

const router = createRouter();
  addRoute(router, "GET", "/admin", { name: "admin" });
  addRoute(router, "GET", "/admin/:page?", { name: "admin-page" }); // superset of "/admin"
findAllRoutes(router, "GET", "/admin").map((m) => m.data.name);
  // ["admin", "admin-page"] (the broader pattern is last)

const router = createRouter();
  addRoute(router, "GET", "/p/:id/**", { name: "id-rest" }); // superset of "/p/:path+"
  addRoute(router, "GET", "/p/:path+", { name: "path" });
findAllRoutes(router, "GET", "/p/a/b").map((m) => m.data.name);
  // ["path", "id-rest"] (the broader pattern is last)

const router = createRouter();
  addRoute(router, "GET", "/blog/**", { name: "blog" });
  addRoute(router, "GET", "/blog/:slug", { name: "post" });
  addRoute(router, "GET", "/**/_payload.json", { name: "payload" });
  addRoute(router, "GET", "/blog/:slug/_payload.json", { name: "post-payload" });
findAllRoutes(router, "GET", "/blog/_payload.json").map((m) => m.data.name);
  // ["blog", "post", "payload"]
  findAllRoutes(router, "GET", "/blog/hello/_payload.json").map((m) => m.data.name);
  // ["blog", "payload", "post-payload"]
  findRoute(router, "GET", "/blog/hello")?.data.name; // "post"

removeRoute(router, method, pattern) removes everything that the matching addRoute call added, including all variants of an optional pattern and duplicate registrations. Other routes are left alone, even ones that share a tree node:

addRoute(router, "GET", "/path/:id", { a: true });
addRoute(router, "GET", "/path/:name", { b: true });
removeRoute(router, "GET", "/path/:name"); // "/path/:id" is still registered

Pass the pattern as you registered it. Spellings that the tree can't tell apart are equivalent (/a/ and /a, /*.md and /.md), but /path/* does not remove /path/:name, and /ab does not remove /a{b}.

removeRoute throws the same rou3: error as addRoute, quoting the pattern, for a reserved group or modifier: {...}+ / {...}, text right after a leading {/…}? ({/a}?b), or a misplaced + / (/a/pre-:x+). It does not check the rest of the invalid patterns, since no route was added for them: a malformed pattern such as {oops/x removes nothing.

For the fastest lookups, compile a router into a single function. The compiled function returns the same results as findRoute (or findAllRoutes with matchAll: true).

• compileRouter compiles at runtime (JIT) with new Function().
• compileRouterToString generates code ahead of time (AOT), for example into a build output. It needs no eval and no rou3 at runtime.

compileRouter(router, opts?)

IMPORTANT: compileRouter requires eval support with new Function() in the runtime for JIT compilation (not allowed under a CSP without unsafe-eval: use compileRouterToString at build time there).

The compiled function is a snapshot of the router: routes added or removed afterwards are not seen, compile again after changing it. Route data is kept by reference. It returns what findRoute returns (with matchAll: true, what findAllRoutes returns), except that params is a plain object where findRoute's has a null prototype.

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, opts?, legacyOpts?)

The output is a self-contained JavaScript expression (or a const =…; statement): no imports, no runtime dependency on rou3, and no eval / new Function(), so it runs under a strict CSP. It needs ES2018 (named capture groups, object spread). Like compileRouter, it is a snapshot of the router at compile time.

IMPORTANT: Route data is emitted with JSON.stringify (toJSON() applies at every depth, as in JSON). Data containing a function, symbol or bigint throws: pass opts.serialize to emit each route's data as a JavaScript expression of your own instead.

import { createRouter, addRoute } from "rou3";
import { compileRouterToString } from "rou3/compiler";
const router = createRouter();
// [add some routes with serializable data]
const compilerCode = compileRouterToString(router, { functionName: "findRoute" });
// "const findRoute=(m, p) => {}"
// Route data as code (e.g. handler imports)
compileRouterToString(router, { serialize: (data) => {handler:${data.importName}} });

findRoute and findAllRoutes match a path against patterns. The utilities below compare patterns against patterns, for example to check whether two route rules can apply to the same URL. They are tree-shaken away when you don't import them.

import { createRouter, addRoute, routesOverlap, compareRoutes, findOverlappingRoutes } from "rou3";
// Can the two patterns match a common path?
routesOverlap("/", "/protected/feed/"); // true
routesOverlap("/a/", "/b/"); // false
// How do the sets of paths they match relate?
compareRoutes("/api/", "/api/admin/"); // "superset"
compareRoutes("/api/admin/", "/api/"); // "subset"
compareRoutes("/a/:x", "/a/:y"); // "equal" (param names don't matter)
compareRoutes("/a//c", "/a/b/"); // "partial"
compareRoutes("/a/", "/b/"); // "disjoint"
// Which registered routes can match a path that the pattern matches?
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(a, b) returns true if at least one path is matched by both patterns.
• compareRoutes(a, b) reads as "a is … of b":

• findOverlappingRoutes(router, method, pattern) works like findAllRoutes, but takes a pattern instead of a path. It returns every registered route that can match a path the pattern matches, in the same least to most specific order and with the same method handling. Matches only have data (there is no single path to extract params from). A route that was registered with optional syntax is reported once.

Different patterns can end on the same node of the route tree: /users/:id and /users/:name both mean "any single segment under /users", and /users/, /users/ and /users/:rest are catch-alls under /users. routeNodeKeys(pattern) returns the node(s) a pattern lands on, naming a param segment :_0, :_1, … and a catch-all *:

import { routeNodeKeys } from "rou3";
routeNodeKeys("/users/:id"); // ["/users/:_0"]
routeNodeKeys("/users/:name"); // ["/users/:_0"] (same node as /users/:id)
routeNodeKeys("/users/*"); // ["/users/"] (same node as /users/)
routeNodeKeys("/:path/og.png"); // ["//og.png"]
routeNodeKeys("/a/:x?"); // ["/a", "/a/:_0"] (optional syntax lands on two nodes)

Routes on the same node compete: for a given path, findRoute returns at most one of them. If you keep your own per-route metadata (route rules, middleware, auth) in a map keyed by pattern text, /users/ and /users/*:rest look unrelated. Key the map by routeNodeKeys instead, to merge metadata per node or warn when one route shadows another.

routeNodeKeys(a) and routeNodeKeys(b) share a key if and only if a and b share a node.

• The result is a deduplicated array, since optional syntax registers on several nodes (/x{/a}?{/b}? registers on 4).
• Each key is itself a valid pattern for its node: routeNodeKeys(key) is [key].
• Invalid patterns throw exactly like addRoute.

Sharing a node does not mean matching the same paths. Keys drop regex constraints and widen :name and * to , so /u/:id(\d+) and /u/:slug([a-z]+) share the key /u/:_0 but never match the same path. To compare which paths two patterns match, use compareRoutes.

routeToRegExp(route) converts a pattern into an anchored RegExp with named groups for the params:

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

The regex matches exactly the paths findRoute matches on a router that only holds that route, including the router's tolerances (one optional trailing slash, empty segments, an optional trailing * that gives "" after a trailing slash, segments after a catch-all matched from the end). That makes it safe to use as a guard or scope check outside the router. Like findRoute without normalize, it compares paths as-is.

The one exception is a regex constraint that can match /, such as (.): the router applies it to one segment, but in the regex it can span several, so routeToRegExp("/foo/(.)") also matches /foo/a/b. The regex then matches more paths than the router, never fewer, so a guard built on it still runs.

The output is PCRE-compatible, so its .source also works in grep -P, rg -P, PHP preg_* and Perl. Most routes also compile without look-behind, so they work in RE2-family engines (RE2, Go regexp, Rust regex).

regExpToRoute(regexp) goes the other way. It accepts a RegExp or its source string:

import { regExpToRoute } from "rou3";
regExpToRoute(/^\/users\/(?<id>\d+)\/?$/); // "/users/:id(\\d+)"
regExpToRoute(/^\/path\/(?<param>[^/]+)\/?$/); // "/path/:param"
regExpToRoute(/^\/path(?:\/(?<_0>(?:[\s\S][^/])?\/?))??\/?$/); // "/path/**"
regExpToRoute("^\\/files\\/(?<_0>[\\s\\S])\\.png\\/?$"); // "/files/.png"
regExpToRoute(/^(?:\/(?<_0>[\s\S]))?\/_payload\.json\/?$/); // "/*/_payload.json"

It understands the regexes routeToRegExp emits, and every one of them round-trips exactly: routeToRegExp(regExpToRoute(re)).source === re.source. Anything else throws a rou3: error instead of returning a wrong pattern.

routeToRegExp("/blog/:id(\\d+){-:title}?");
// /^\/blog\/(?<id>\d+)(?:-(?<title>[^/]+?))?\/?$/
routeToRegExp("/files/:name{.:ext}?");
// /^\/files\/(?<name>[^/]+?)(?:\.(?<ext>[^/]+?))?\/?$/
routeToRegExp("/users{/:id}?/posts/:post");
// /^\/users(?:\/(?<id>[^/]+))?\/posts\/(?<post>[^/]+)\/?$/