Skip to content

Latest commit

 

History

History
422 lines (295 loc) · 28.9 KB

migration.md

File metadata and controls

422 lines (295 loc) · 28.9 KB

Migrating from rou3 0.9 to 0.12

rou3 0.10, 0.11 and 0.12 align the route pattern syntax with URLPattern and make the router, the compiled matchers and routeToRegExp match exactly the same paths. This guide combines the migration notes of all three releases, so every "Before" column shows 0.9 behavior and every "After" column shows 0.12 behavior. Changes that a later release undid or replaced are left out.

Each section names the release that made the change. The full notes are in the GitHub releases: v0.10.0, v0.11.0, v0.12.0.

Checklist

Most apps need only the first few items:

  1. Look up routes with the raw, encoded pathname (new URL(req.url).pathname). Don't decode it first.
  2. Check every * in your routes. It now spans segments: /admin/* matches /admin/a/b. Use :name for exactly one segment.
  3. Replace params._ with a named catch-all (/**:path → params.path) or params["0"].
  4. Rename params that contain - (:user-id → :userId).
  5. Start your app once. Pattern syntax that used to be accepted with a surprising meaning now throws a rou3: error at addRoute, quoting the route. Fix each one using Patterns that now throw.
  6. If you use routeToRegExp as a guard, update snapshots and re-check: its output now matches exactly the paths the router matches.
  7. Run on Node.js 20.19 or later.

Lookup paths

Pass the encoded pathname

0.12 (#231)

addRoute percent-encodes a pattern's literal text once, like URLPattern. Lookup paths are never decoded or encoded, so pass the pathname as it appears in the URL.

Pattern Path 0.9 0.12
/café /caf%C3%A9 no match match
/café /café match no match
/a b /a%20b no match match
  • Regex constraints are not encoded: write :x(%C3%A9), not :x(é).
  • routeToRegExp, routeNodeKeys and the compiled matchers use the encoded text too (routeToRegExp("/café") is ^\/caf%C3%A9\/?$).
  • Param values are returned as they appear in the path (/users/:id on /users/a%20b gives { id: "a%20b" }), as in 0.9. Decode them in your handler if you need to.

Migrate: stop calling decodeURI() / decodeURIComponent() on the path before findRoute.

Only one trailing slash is ignored

0.10 (#210)

Lookup ignores at most one trailing slash, like the non-strict defaults of Express, find-my-way and Hono.

Pattern Path 0.9 0.12
/users/:id /users/123/ { id: "123" } { id: "123" }
/users/:id /users/123// { id: "123" } no match
/about /about// match no match
/ // match no match

Migrate: to accept repeated trailing slashes, collapse them before lookup, e.g. path.replace(/\/{2,}$/, "/").

Named params never match an empty segment

0.11 (#230), 0.12 (#232, #241)

A :name needs a value, and every segment a :name+, :name* or **:name takes needs one too (URLPattern's [^/]+(?:/[^/]+)*). Handlers no longer need to guard against "" for these params.

Pattern Path 0.9 0.12
/foo/:bar/x /foo//x { bar: "" } no match
/a/:x* /a// {} no match
/foo/:bar+ /foo/a//b { bar: "a//b" } no match
/foo/**:bar /foo//a { bar: "/a" } no match
/foo/:bar+ /foo/a/b/ { bar: "a/b" } { bar: "a/b" } (one trailing slash is still ignored)

These paths now fall through to a less specific route, or to no match. *, **, :name(.*) and regex constraints may still take empty segments.

Migrate: to accept empty segments, use *, **, :name(.*), or a constraint that allows empty, such as :id(\d*).

. / .. segments in patterns are resolved

0.12 (#246)

. and .. segments in a pattern (including %2e forms) are resolved when the route is added, the way new URL() resolves a path.

Pattern Path 0.9 0.12
/foo/../bar /bar no match match
/foo/../bar /foo/../bar match no match
/\.\./bar /../bar no match match (escaped dots stay literal)
/:id/.. accepted throws
  • A dot segment next to a param, catch-all or group throws.
  • removeRoute resolves dot segments too: removeRoute(router, "GET", "/docs/../api") removes /api.
  • Lookup paths are unchanged. They are resolved only with normalize: true, which now drops a .. that would go above the root (/x/../../foo → /foo, 0.10) and keeps the trailing slash after a trailing . / .. like WHATWG URL (/a//. → /a//, 0.12).

Migrate: escape the dots (\.\.) to match a literal .. segment.

Wildcards

* is a greedy catch-all

0.12 (#240)

* used to match one segment ([^/]*). It is now URLPattern's * ((.*)) and matches across /, also inside a segment. A trailing /foo/* still matches /foo.

Pattern Path 0.9 0.12
/foo/* /foo/a { 0: "a" } { 0: "a" }
/foo/* /foo/a/b no match { 0: "a/b" }
/foo/* /foo/ {} { 0: "" }
/foo/* /foo {} {}
/*/x /a/b/x no match { 0: "a/b" }
/*.png /a/b.png no match { 0: "a/b" }
/a/:x?/* /a/b { 0: "b" } { x: "b" }
  • Rules keyed by a trailing * now apply at every depth: "/admin/*": { auth: false } covers /admin/a/b, not just /admin/a.
  • A * before more of the route (/*/x) needs at least one segment, so it does not match /x.
  • On the same node, ** < * < **:name in findAllRoutes order.

Migrate:

  • To match exactly one segment, use /users/:id (or /users/:id? to also match /users). For 0.9's exact behavior, use /users{/([^\x2f]*)}?.
  • Inside a segment, replace * with ([^\x2f]*): /*.png becomes /([^\x2f]*).png.

** has a numbered key, and _ is deprecated

0.12 (#234)

A bare ** is an unnamed capture, as in URLPattern. It is keyed "0", "1", … together with * and unnamed (…) groups, in pattern order across the whole pattern.

Pattern Path 0.9 0.12
/foo/** /foo/a/b { _: "a/b" } { 0: "a/b", _: "a/b" }
/foo/** /foo { _: "" } {}
  • params._ still works but is deprecated.
  • A ** that matches zero segments leaves its key out (it used to set _: "").
  • Unnamed keys after a ** shift up, and so do keys after an optional group holding unnamed captures (a left-out group still uses up its numbers): /x{(\d+)}?/* on /x/b gives { 1: "b" }.
  • In routeToRegExp output, the ** group is named _0, _1, … instead of _.

Migrate: name the capture (/foo/**:path → params.path), or read params["0"] ?? "".

Segments after a catch-all are matched

0.10 (#216)

Segments after ** used to be silently dropped, so /a/**/b behaved like /a/**. They are now matched from the end of the path.

Pattern Path 0.9 0.12
/**/_payload.json /blog/post/_payload.json { _: "blog/post/_payload.json" } { 0: "blog/post", _: "blog/post" }
/a/**/b /a/x/y { _: "x/y" } no match
/a/:x+/b /a/x/y { x: "x/y" } no match
/**.md /a/b.md { _: "a/b.md" } { 0: "a/b" }
  • /a/**/b also matches /a/b (** over zero segments).
  • removeRoute(router, "GET", "/a/**/b") no longer removes /a/**.
  • On paths that a route with segments after a catch-all matches, matches are ranked from the last segment backwards (literal > regex param > param > catch-all). Routers without such routes rank as before.

Migrate: if you relied on the trailing segments being ignored, register /a/** instead.

(.*) and :name(.*) are catch-alls

0.12 (#242)

A written (.*) is the same as *, and :name(.*) is a * keyed by name. Both match across segments, as routeToRegExp already did.

Pattern Path 0.9 0.12
/foo/(.*) /foo/a/b no match { 0: "a/b" }
/foo/:p(.*) /foo/a/b no match { p: "a/b" }
/foo/:p(.*) /foo/ no match { p: "" }
  • :p(.*)?, (.*)+ and other modifiers on these groups throw, as they do on *.
  • Other constraints that can match / ((.+), (.*?), ([^x]*)) still stay within one segment.

Migrate: for a single-segment value, use :p or :p([^\x2f]*).

One catch-all per route

0.10 (#216), 0.12 (#240, #242)

A route can hold only one of *, **, :x+, :x*, (.*) or :x(.*). A second one throws rou3: a route can have only one ....

Pattern 0.9 on the path Write instead
/**/**, /a/:x+/b/:y+ accepted one catch-all
/**/*.png { _: "a/b.png" } on /a/b.png /**/:file.png
/file-*-*.png { 0: "a", 1: "b" } on /file-a-b.png /file-:a-*.png, or ([^\x2f]*) for one of them
/*/x/*, /*/**, /*/:p+ accepted a named :param for all but one

Params

A - ends a param name

0.11 (#222, #230)

Param names are [A-Za-z_]\w*, as in URLPattern. A -, { or } ends a name.

Pattern Path 0.9 0.12
/api/:test-id /api/abc { "test-id": "abc" } no match
/api/:test-id /api/abc-id { "test-id": "abc-id" } { test: "abc" }
/blog/:year-:month /blog/2024-05 { "year-": "2024-0", month: "5" } { year: "2024", month: "05" }
/blog/:id{-:title}? /blog/1-hi { "id-": "1-h", title: "i" } { id: "1", title: "hi" }
/:a{b}? /xb { ab: "xb" } { a: "x" }

InferRouteParams reads names the same way, so the types change too.

Migrate: rename params that contain -, e.g. :test-id → :testId or :test_id.

Several captures in one segment

0.11 (#230), 0.12 (#233, #236, #238)

As in URLPattern, a :name takes as little as it can, and a * or a regex constraint takes as much as it can. An optional :name? after a capture in the same segment is matched in place, so the capture before it takes what it can.

Pattern Path 0.9 0.12
/:name.:ext /a.tar.gz { name: "a.tar", ext: "gz" } { name: "a", ext: "tar.gz" }
/:a-:b /x-y-z { "a-": "x-y-", b: "z" } { a: "x", b: "y-z" }
/:a(\d+):b? /12 { a: "1", b: "2" } { a: "12" }
/*-:x? /-- { 0: "", x: "-" } { 0: "-" }
  • After plain text nothing changes: pre-:x? matches pre- and pre-<value>.
  • Constrained and literal in-segment params rank above plain ones on the same node, whatever the registration order: /f/:name.png and /f/:name.:ext(png|jpg) both beat /f/:name.:ext on /f/a.png.
  • These segments now match in time linear in their length (closes the ReDoS class of CVE-2024-45296).

Migrate: to keep the old split, constrain the capture: /:name.:ext(\w+) gives { name: "a.tar", ext: "gz" }, and /:a(\d):b? gives { a: "1", b: "2" }.

prefix-:param? makes only the param optional

0.11 (#230)

A ? on a param that does not start its segment makes only that param optional, not the whole segment.

Pattern Path 0.9 0.12
/a/pre-:x? /a/pre-b { x: "b" } { x: "b" }
/a/pre-:x? /a/pre- no match match (no x)
/a/pre-:x? /a match no match

Migrate: to make the whole segment optional, write /a/{pre-:x}?.

Backslash escapes mean a literal character

0.11 (#228)

Outside a regex constraint, \x is a literal x, as in URLPattern. 0.9 kept the backslash in static segments, while routeToRegExp dropped it.

Pattern Path 0.9 0.12
/foo\.bar /foo.bar no match match
/a\*b /a*b no match match
/a/\(:x /a/(1 no match { x: "1" }

\\ is a literal backslash. A \/ or a trailing \ throws.

Migrate: if a route really needs a backslash in the path, write \\.

Regex constraints

0.11 (#226, #228), 0.12 (#245)

The router tests a constraint against one segment while routeToRegExp puts it inside a whole-path regex, so constructs that behave differently in the two now throw.

Pattern Problem Write instead
/:slug((?!admin)\w+) look-around /:slug(\w+) plus a static /admin route (a static route always wins)
/:x(^\d+$) anchor /:x(\d+) (constraints already match the whole segment)
/:x((a)) capturing group inside a constraint /:x((?:a))
/a/(), /a/(?:a|b), /a/(?<n>x) empty or (? group /a/:x((?:a|b)), /a/:n(x)
/:x([[a-z]--a]) -- / && in a class (URLPattern's v-flag set operations) escape them: [a\-\-z], [a\&\&b]

Look-arounds have no direct replacement: register the excluded paths as their own routes, or check the value in your handler.

Groups

0.12 (#236, #239)

A regex group right after a {…} group that ends in a param is an unnamed capture next to the param, not the param's constraint. A pattern that starts with a {/…} group no longer gets an extra / in front.

Pattern Path 0.9 0.12
/{:foo}(.*) /foobarbaz { foo: "foobarbaz" } { foo: "f", 0: "oobarbaz" }
{/:a}?/b /b no match {}
{/:a}?/b /x/b no match { a: "x" }
{/:a}?/b //b {} no match
  • /{:foo}?(…), /:foo{}(…) and /:foo{(x)}? change the same way. Write the constraint on the param instead: /:foo(.*).
  • A {:name}? group that follows text and ends its segment is read as :name?: /a/*{:x}? is /a/*:x?.
  • Text right after a leading {/…}? ({/a}?b, {/:a}?.png) throws.

Patterns that now throw

addRoute (and routeToRegExp) throw rou3: <what> (<route as written>) for syntax that 0.9 accepted with a surprising meaning, so these show up at startup. Besides the catch-all, constraint, dot-segment and group cases above:

Pattern 0.9 Write instead
/a/:x(\d+)+, /a/pre-:x+ dropped the constraint or prefix (/a/:x(\d+)+ matched /a/1/2 as { x: "1/2" }) + / * only after a whole-segment :name (/a/:x+)
/a/**?, /a/*+, /:x??, /p/**:x? accepted, with an unclear meaning /p/:x* for an optional catch-all
/foo? never matched (lookup paths have no query) /foo\? for a literal ?
/a**b read as two wildcards /a*b, or /a\*\*b for literal stars
/a/**:x.json, /a/**:x(\d+) param named "x.json" / "x(\d+)" a plain **:name as the whole last segment
/:0, /:1st, /:café, /:id$ accepted as names /:v1, /:_1, /:cafe, /:id\$
/a/:, /a/x: literal : /a/\:
/a/:x/:x, /a/:x.:x later value won, or a raw SyntaxError unique names
/files/:path/**:path, /a/:_/** duplicate name, raw SyntaxError in routeToRegExp unique names
/a/{b, /a/b}, /a/{{b}} literal or mis-parsed braces \{ / \} for literal braces, no nested groups
/a/{b}+, /a{/b}* threw a non-rou3: error not supported (only {…} and {…}?)
/a/(b (a ( that does not close in its segment) threw a raw SyntaxError close it, or escape it as \(
/{:foo}{*}, /{:foo}?*, /{:foo}(x)?, /*{*} accepted write the modifier or constraint on the param
a raw tab, LF or CR ("/a\tb") accepted %09, %0A, %0D (or \t, \n, \r inside a constraint)
U+FFFD–U+FFFF in a pattern accepted not allowed (used internally)

See invalid patterns for the full list.

Router API

Method-agnostic routes are no longer hidden by method routes (0.11, #223). A route added with method "" could disappear when a route for a specific method landed on the same tree node, even if that route didn't match. Both are now always considered, and the more specific one wins. On a tie, the method route still wins.

addRoute(router, "", "/u/*", "any");
addRoute(router, "GET", "/u/:id(\\d+)", "get");

findRoute(router, "GET", "/u/abc"); // 0.9: undefined    0.12: "any"
findAllRoutes(router, "GET", "/u/42"); // 0.9: ["get"]   0.12: ["any", "get"]

A "" middleware or auth route is no longer silently dropped from findAllRoutes (or compiled matchAll), and a more specific "" route now beats a broader method route.

removeRoute removes only the route you pass (0.10, #202). Removing /a/:id used to also remove /a/:userId, and removing /a/** also removed /a/**:rest. If you relied on that, call removeRoute once per registered pattern.

findAllRoutes lists each addRoute call once (0.12). /a/:x?/:y? on /a/b used to be returned twice ({ x } and { y }); it is now returned once, with the variant findRoute picks.

Results (0.11, #219):

  • findRoute and findAllRoutes return a fresh { data, params } object on every call. Static matches no longer expose internal fields (such as paramsRegexp), and mutating a result no longer affects later lookups.
  • Falsy route data (0, false, "") is returned as-is instead of null. Missing data is still null.

RouterContext properties are marked @internal (0.12). Don't read or write the router's tree directly.

Types

  • InferRouteParams types optional params (:id?, :id*) and a trailing whole-segment *, (.*) or :name(.*) as string | undefined (0.10, #198; 0.12). Handle undefined, e.g. params.id ?? "".
  • Names are read like the router: constraints and modifiers are stripped (:id(\d+) → id), and - ends a name (/blog/:year-:month → { year, month }).
  • A bare ** key is string | undefined, plus a deprecated _?: string. **<text> is one key.
  • compileRouter<T>(router, { matchAll: true }) is typed as returning an array (0.11).
  • RouterCompilerOptions is deprecated in favor of CompileRouterToStringOptions and CompileRouterOptions (0.11).

Compiler

0.11 (#225)

compileRouterToString takes an options object: compileRouterToString(router, { functionName, matchAll, serialize }). The (router, "name", opts) form still works but is deprecated.

Route data in the generated code always goes through JSON.stringify, so the output is always valid code:

Route data 0.9 output 0.12 output
new Date(0) invalid code "1970-01-01T00:00:00.000Z"
{ toJSON: () => ({ a: 1 }) } invalid code { a: 1 }
{ toJSON: () => "code" } emitted code as raw JS the string "code"
a function, symbol or bigint (anywhere in the data) silently dropped, or a raw TypeError throws a rou3: error

Migrate: if your data contains functions or used toJSON() to emit code, pass serialize: (data) => "<js expression>".

routeToRegExp and regExpToRoute

routeToRegExp(p) now matches exactly the paths findRoute matches on a router holding only p, so it is safe to use as a guard. If you use it for scope or permission checks, upgrade.

  • /api/** no longer matches /apifoo (0.10).
  • Catch-alls match line terminators the way the router does (0.10). In 0.9, /admin/**:p didn't match /admin/x\ry, which the router routed.
  • Segments after ** are kept (0.10).
  • All the router changes above apply: * spans segments, literal text is percent-encoded, :name+ / :name* / **:name use [^/]+(?:/[^/]+)*, and ** groups are named _0, _1, … instead of _.
  • The regex text changed for almost every route. Update snapshots and string comparisons. Most routes no longer use look-behind, so the regexes also compile in RE2, Go regexp and Rust regex. Output for segments with several params no longer backtracks polynomially.
  • An empty required segment at the end (/a/:x on /a//) used to leave its group undefined; the route no longer matches at all.
  • On engines without duplicate named groups (Node 20 / 22), a group right before or after a trailing * that can't be inlined throws rou3: the regex for "…" repeats a named group… (/{b}?/*, /files/*{.:ext}?/raw).

regExpToRoute (0.11, #218; 0.12):

Input 0.9 0.12
/\/users\/(?<id>\d+)/ /users/:id(\d+) throws (unanchored)
/^\/users/ /users throws (unanchored)
/^\/a\/(?<x>\p{L}+)$/u /a/:x(\p{L}+) throws (u / v flag)
/^\/users$/ /users /users
  • It reads regexes from older routeToRegExp versions (old _ groups included), except output for patterns that now throw, such as :x(\d+)+. Some routes come back in an equivalent form, e.g. /a/:x?/:y? → /a{/:x/:y?}?, and an unnamed catch-all comes back as **.
  • It throws on a literal char that a route would encode, on a raw tab/LF/CR or -- / && inside a constraint class, and on a hand-written trailing \/([^/]*)\/?$, which no route matches anymore.

Migrate: anchor hand-written regexes with ^…$ and drop the u / v flags.

Overlap and routeNodeKeys

  • findOverlappingRoutes reports a route with optional parts once, and reports distinct routes separately even when they share the same data object (0.11, #220).
  • compareRoutes("/a/*", "/a/**") is "equal" (it was "subset"), since * is now a catch-all. /a/:x* equals /a{/**:y}? and is a subset of /a/** (0.12).
  • routeNodeKeys("/a/*") gives ["/a/**"], and param segments are keyed :_0, :_1, … (0.12).

Runtime

package.json declares "engines": { "node": ">=20.19.0" } (0.11, #224).