Add a location param to Router.getRoute

Author: zoontek

__tests__/router.tsx

@@ -96,6 +96,18 @@ test("getRoute: should match the correct route", () => {
   expect(container.textContent).toContain("Not found");
 });
 
+test("getRoute: should match the correct route for given location", () => {
+  const route = getRoute(routesToMatch, "/profile/zoontek");
+
+  expect(route).toStrictEqual({
+    key: "1pkttpl-0",
+    name: "Profile",
+    params: {
+      username: "zoontek",
+    },
+  });
+});
+
 test("useFocusReset: should focus the correct element", () => {
   const App = () => {
     const route = useRoute(routesToMatch);

docs/docs/router.md

@@ -37,14 +37,16 @@ const route = Router.useRoute(["Home", "UserArea"]);
 Takes an array of routes (a subset of the router), and returns the route and its params if one matches.
 
 - `routes` (**required**): `RouteName[]`
+- `location` (optional): `string` (defaults to the current browser location)
 
 Returns a route match (or `undefined` if nothing matches):
 
 - `name`: a route name
 - `params`: its associated params
 
 ```ts
-const route = Router.getRoute(["Home", "UserArea"]);
+const routeA = Router.getRoute(["Home", "UserArea"]);
+const routeB = Router.getRoute(["User"], "/users/1");
 ```
 
 ## Router.push

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swan-io/chicane",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "license": "MIT",
   "description": "A simple and safe router for React and TypeScript",
   "author": "Mathieu Acthernoene <[email protected]>",

src/createRouter.ts

@@ -3,6 +3,7 @@ import { useSyncExternalStoreWithSelector } from "use-sync-external-store/shim/w
 import { concatRoutes } from "./concatRoutes";
 import { areRouteEqual, first, identity } from "./helpers";
 import {
+  decodeLocation,
   getLocation,
   parseRoute,
   pushUnsafe,
@@ -123,18 +124,21 @@ export const createRouter = <
 
   const getRoute = <RouteName extends keyof FiniteRoutes | keyof AreaRoutes>(
     routeNames: ReadonlyArray<RouteName>,
+    location?: string,
   ): RouteName extends string
     ?
         | { key: string; name: RouteName; params: RoutesParams[RouteName] }
         | undefined
     : never => {
-    const location = getLocation();
+    const locationObject =
+      location != null ? decodeLocation(location) : getLocation();
+
     const matchers = rankedMatchers.filter(({ name }) =>
       routeNames.includes(name as RouteName),
     );
 
     // @ts-expect-error
-    return match(location, matchers);
+    return match(locationObject, matchers);
   };
 
   const push = <RouteName extends keyof FiniteRoutes>(

src/history.ts

@@ -30,8 +30,8 @@ export const parseRoute = (route: string): RouteObject => {
   };
 };
 
-export const decodeLocation = (url: string): Location => {
-  const route = parseRoute(url);
+export const decodeLocation = (input: string): Location => {
+  const route = parseRoute(input);
   const path = route.path.substring(1);
 
   const parsedPath =