@uxf/router 11.126.0 → 11.127.0

package/README.md

@@ -108,6 +108,61 @@ Add configuration to `tsconfig.json`
 }
 ```
 
+## routeToUrl
+
+Builds a URL from a route name and its params. Path params are substituted into the bracketed segments; anything left over becomes the query string.
+
+```ts
+routeToUrl("blog/detail", { id: 12 }); /* "/blog/[id]" -> "/blog/12" */
+routeToUrl("admin/index", { param1: 3 }); /* "/admin?param1=3" */
+routeToUrl("localized-route", { term: "x" }, { locale: "cs" }); /* "/cs/domu?term=x" */
+routeToUrl("index", {}, { shouldBeAbsolute: true }); /* "https://www.uxf.cz/" */
+```
+
+**A missing required param throws.** Any bracketed segment still present after substitution means the URL would be broken, so it fails loudly rather than shipping a href containing `[id]`:
+
+```ts
+routeToUrl("blog/detail", {});
+// Error: Missing parameter '[id]' for route 'blog/detail'.
+```
+
+**Optional catch-all segments may be omitted entirely.** For a path like `/catch-all-optional/[[...pathParams]]`, the segment is stripped whether the key is absent, `null`, `undefined`, `""` or `[]`:
+
+```ts
+routeToUrl("optionalCatchAll", {}); /* "/catch-all-optional" */
+routeToUrl("optionalCatchAll", { pathParams: null }); /* "/catch-all-optional" */
+routeToUrl("optionalCatchAll", { pathParams: ["a", "b"] }); /* "/catch-all-optional/a/b" */
+```
+
+A **required** catch-all (`[...pathParams]`) is not optional: an empty array throws `Parameter 'pathParams' can not be empty array for route '…'`, and omitting the key throws the missing-parameter error above.
+
+## getRouteInfo
+
+Resolves a pathname back to the route that declared it, or `null` when nothing matches. The result is `RouteInfo` = `{ pathname: string; routeName: string; routeDefinition: RouteDefinition }` — note it carries the pathname, not parsed params.
+
+```ts
+getRouteInfo(
+    "/blog/12",
+); /* { pathname: "/blog/12", routeName: "blog/detail", routeDefinition: { path: "/blog/[id]", … } } */
+getRouteInfo("/not-a-route"); /* null */
+```
+
+**Candidates are ordered by specificity, not by declaration order** — fewest catch-all segments first, then fewest dynamic segments, then most static segments. A localized route is ranked by its most specific variant. So a static path is never shadowed by a dynamic one declared before it:
+
+```ts
+const routes = {
+    hotelDetail: { path: "/hotel/[hotel-id]" },
+    hotelCreate: { path: "/hotel/create-hotel" },
+    hotelCatchAll: { path: "/hotel/[...rest]" },
+} as const;
+
+getRouteInfo("/hotel/create-hotel")?.routeName; /* "hotelCreate", not "hotelDetail" */
+getRouteInfo("/hotel/12")?.routeName; /* "hotelDetail" */
+getRouteInfo("/hotel/12/a/b")?.routeName; /* "hotelCatchAll" - only when nothing more specific matches */
+```
+
+`createRouteMatcher` delegates to `getRouteInfo`, so it follows the same ordering — which is what makes active-route detection in navigation and layouts agree with the resolved route.
+
 ## useQueryParams
 
 Hooks live in the client entry (`@app-routes/client`):

package/create-router.js

@@ -2,9 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createRouter = createRouter;
 const empty_object_1 = require("@uxf/core/constants/empty-object");
+const is_empty_1 = require("@uxf/core/utils/is-empty");
+const is_not_empty_1 = require("@uxf/core/utils/is-not-empty");
 const qs_1 = require("@uxf/core/utils/qs");
 const throw_error_1 = require("@uxf/core/utils/throw-error");
 const sitemap_generator_1 = require("./sitemap-generator");
+const path_specificity_1 = require("./utils/path-specificity");
 const path_to_regex_1 = require("./utils/path-to-regex");
 /**
  * Arguments can be:
@@ -32,8 +35,15 @@ function createRouter(routes, routerOptions) {
                 : Object.values(routeDefinition.path).map((path) => (0, path_to_regex_1.pathToRegex)(path)),
         },
     }), {});
+    const routeNamesBySpecificity = Object.entries(routes)
+        .map(([routeName, routeDefinition]) => ({
+        routeName,
+        specificity: (0, path_specificity_1.getRouteSpecificity)(routeDefinition.path),
+    }))
+        .sort((a, b) => (0, path_specificity_1.comparePathSpecificity)(a.specificity, b.specificity))
+        .map((entry) => entry.routeName);
     const routeToUrl = (...args) => {
-        var _a;
+        var _a, _b;
         const { route, params, options } = decodeArgs(args);
         let pathname = typeof routes[route].path === "string"
             ? routes[route].path
@@ -51,10 +61,7 @@ function createRouter(routes, routerOptions) {
                 pathname = pathname.replace(segment, value);
             }
             else if (pathname.includes(catchAllSegmentsOptional)) {
-                if ((Array.isArray(value) && value.length === 0) ||
-                    value === null ||
-                    value === undefined ||
-                    value === "") {
+                if ((Array.isArray(value) && (0, is_empty_1.isEmpty)(value)) || value === null || value === undefined || value === "") {
                     pathname = pathname.replace(`/${catchAllSegmentsOptional}`, "");
                 }
                 else if (Array.isArray(value)) {
@@ -68,7 +75,7 @@ function createRouter(routes, routerOptions) {
             else if (pathname.includes(catchAllSegments)) {
                 // catch all segments
                 if (Array.isArray(value)) {
-                    if (value.length === 0) {
+                    if ((0, is_empty_1.isEmpty)(value)) {
                         throw new Error(`Parameter '${key}' can not be empty array for route '${String(route)}'`);
                     }
                     pathname = pathname.replace(catchAllSegments, value.join("/"));
@@ -81,20 +88,31 @@ function createRouter(routes, routerOptions) {
                 restParams[key] = value;
             }
         });
-        if (Object.keys(restParams).length > 0) {
+        // Optional catch-all segments must be stripped even when their key is absent from `params`
+        // (the loop above only visits provided keys). Otherwise a literal `/[[...xxx]]` leaks into the
+        // URL and Next.js — unable to know the brackets were an unsubstituted placeholder — falls back
+        // to a full-document navigation.
+        pathname = pathname.replace(/\/\[\[\.\.\.[^\]]+\]\]/g, "");
+        // Any bracketed segment still present means a required param was never provided; the resulting
+        // URL would be broken, so fail loudly instead of shipping it.
+        const firstUnresolved = (_b = pathname.match(/\[\[?\.\.\.[^\]]+\]\]?|\[[^\]]+\]/)) === null || _b === void 0 ? void 0 : _b.at(0);
+        if (firstUnresolved) {
+            throw new Error(`Missing parameter '${firstUnresolved}' for route '${String(route)}'.`);
+        }
+        if ((0, is_not_empty_1.isNotEmpty)(Object.keys(restParams))) {
             pathname = `${pathname}?${(0, qs_1.stringify)(restParams, { arrayFormat: "repeat" })}`;
         }
         return (options === null || options === void 0 ? void 0 : options.shouldBeAbsolute) ? `${routerOptions.baseUrl}${pathname}` : pathname;
     };
     const getRouteInfo = (pathname) => {
-        const entry = Object.entries(routesWithRegex).find(([, routeDefinition]) => routeDefinition.regex.some((regex) => regex.test(pathname)));
-        if (!entry) {
+        const routeName = routeNamesBySpecificity.find((name) => routesWithRegex[name].regex.some((regex) => regex.test(pathname)));
+        if (!routeName) {
             return null;
         }
         return {
             pathname,
-            routeName: entry[0],
-            routeDefinition: entry[1],
+            routeName,
+            routeDefinition: routesWithRegex[routeName],
         };
     };
     return {
@@ -121,7 +139,7 @@ function createRouter(routes, routerOptions) {
                 if ((routeInfo === null || routeInfo === void 0 ? void 0 : routeInfo.routeName) !== requiredRouteName) {
                     return false;
                 }
-                if (!requiredParams || Object.keys(requiredParams).length === 0) {
+                if (!requiredParams || (0, is_empty_1.isEmpty)(Object.keys(requiredParams))) {
                     return true;
                 }
                 for (const [paramName, paramValue] of Object.entries(requiredParams)) {

package/create-router.test.js

@@ -99,6 +99,16 @@ const DATA = [
         actual: routeToUrl("optionalCatchAllSegments", { pathParams: "", queryParam: "value" }),
         expected: "/catch-all-optional?queryParam=value",
     },
+    {
+        // key omitted entirely — the optional segment must still be stripped
+        actual: routeToUrl("optionalCatchAllSegments", {}),
+        expected: "/catch-all-optional",
+    },
+    {
+        // key omitted but a query param is present
+        actual: routeToUrl("optionalCatchAllSegments", { queryParam: "value" }),
+        expected: "/catch-all-optional?queryParam=value",
+    },
     {
         actual: routeToUrl("routeWithoutParams"),
         expected: "/route-without-params",
@@ -139,6 +149,14 @@ const DATA = [
 test("routeToUrl", () => {
     DATA.map(({ actual, expected }) => expect(actual).toBe(expected));
 });
+test("routeToUrl throws when a required param is missing", () => {
+    expect(() => 
+    // @ts-expect-error param2 is required, so this call is invalid on purpose — the point is the runtime guard
+    routeToUrl("manyParameters", { param1: "value-1" })).toThrow("Missing parameter '[param2]' for route 'manyParameters'.");
+    expect(() => 
+    // @ts-expect-error pathParams is required, so this call is invalid on purpose — the point is the runtime guard
+    routeToUrl("catchAllSegments", {})).toThrow("Missing parameter '[...pathParams]' for route 'catchAllSegments'.");
+});
 test("create route matcher", () => {
     expect(createRouteMatcher("manyParameters", { param1: "value-1" })("/many-parameters/value-1/form/any", {
         param1: "value-1",
@@ -178,3 +196,37 @@ test("create-router has no client-only imports", () => {
     expect(source).not.toMatch(/from "react"/);
     expect(source).not.toMatch(/from "react-dom"/);
 });
+describe("getRouteInfo", () => {
+    const { getRouteInfo, createRouteMatcher: matcher } = (0, create_router_1.createRouter)({
+        hotelDetail: { path: "/hotel/[hotel-id]" },
+        hotelEdit: { path: "/hotel/[hotel-id]/edit" },
+        hotelTab: { path: "/hotel/[hotel-id]/[tab]" },
+        hotelCreate: { path: "/hotel/create-hotel" },
+        hotelCatchAll: { path: "/hotel/[...rest]" },
+    }, {});
+    it("resolves a static path declared after a matching dynamic one", () => {
+        var _a;
+        expect((_a = getRouteInfo("/hotel/create-hotel")) === null || _a === void 0 ? void 0 : _a.routeName).toBe("hotelCreate");
+    });
+    it("resolves dynamic paths", () => {
+        var _a, _b, _c;
+        expect((_a = getRouteInfo("/hotel/12")) === null || _a === void 0 ? void 0 : _a.routeName).toBe("hotelDetail");
+        expect((_b = getRouteInfo("/hotel/12/edit")) === null || _b === void 0 ? void 0 : _b.routeName).toBe("hotelEdit");
+        expect((_c = getRouteInfo("/hotel/12/rooms")) === null || _c === void 0 ? void 0 : _c.routeName).toBe("hotelTab");
+    });
+    it("falls back to a catch-all only when nothing more specific matches", () => {
+        var _a;
+        expect((_a = getRouteInfo("/hotel/12/a/b")) === null || _a === void 0 ? void 0 : _a.routeName).toBe("hotelCatchAll");
+    });
+    it("returns null when nothing matches", () => {
+        expect(getRouteInfo("/not-a-route")).toBeNull();
+    });
+    it("exposes the matched route definition", () => {
+        var _a;
+        expect((_a = getRouteInfo("/hotel/create-hotel")) === null || _a === void 0 ? void 0 : _a.routeDefinition.path).toBe("/hotel/create-hotel");
+    });
+    it("makes createRouteMatcher agree with getRouteInfo", () => {
+        expect(matcher("hotelCreate")("/hotel/create-hotel")).toBe(true);
+        expect(matcher("hotelDetail")("/hotel/create-hotel")).toBe(false);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@uxf/router",
-    "version": "11.126.0",
+    "version": "11.127.0",
     "description": "UXF Router",
     "author": "UXFans <dev@uxf.cz>",
     "homepage": "https://gitlab.com/uxf-npm/router#readme",
@@ -26,12 +26,12 @@
         "true-case-path": "2.2.1"
     },
     "peerDependencies": {
-        "@uxf/core": "11.126.0",
+        "@uxf/core": "11.127.0",
         "next": ">= 12",
         "superstruct": "^2.0.2"
     },
     "devDependencies": {
-        "@uxf/core": "11.126.0",
+        "@uxf/core": "11.127.0",
         "next": "16.3.0",
         "superstruct": "^2.0.2"
     }

package/utils/path-specificity.d.ts

@@ -0,0 +1,16 @@
+export type PathSpecificity = {
+    catchAllSegmentCount: number;
+    dynamicSegmentCount: number;
+    staticSegmentCount: number;
+};
+export declare function getPathSpecificity(path: string): PathSpecificity;
+/**
+ * Orders route candidates from the most to the least specific: fewest catch-all segments first, then
+ * fewest dynamic segments, then most static segments. Used so that a pathname resolves to the most
+ * specific matching route instead of whichever route happens to be declared first.
+ */
+export declare function comparePathSpecificity(a: PathSpecificity, b: PathSpecificity): number;
+/**
+ * Specificity of a route definition's path. A localized route is ranked by its most specific variant.
+ */
+export declare function getRouteSpecificity(path: string | Partial<Record<string, string>>): PathSpecificity;

package/utils/path-specificity.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPathSpecificity = getPathSpecificity;
+exports.comparePathSpecificity = comparePathSpecificity;
+exports.getRouteSpecificity = getRouteSpecificity;
+const is_not_nil_1 = require("@uxf/core/utils/is-not-nil");
+const LEAST_SPECIFIC = {
+    catchAllSegmentCount: Number.MAX_SAFE_INTEGER,
+    dynamicSegmentCount: Number.MAX_SAFE_INTEGER,
+    staticSegmentCount: 0,
+};
+function getPathSpecificity(path) {
+    const segments = path.split("/").filter((segment) => segment !== "");
+    const dynamicSegments = segments.filter((segment) => segment.startsWith("["));
+    const catchAllSegments = dynamicSegments.filter((segment) => segment.startsWith("[...") || segment.startsWith("[[..."));
+    return {
+        catchAllSegmentCount: catchAllSegments.length,
+        dynamicSegmentCount: dynamicSegments.length,
+        staticSegmentCount: segments.length - dynamicSegments.length,
+    };
+}
+/**
+ * Orders route candidates from the most to the least specific: fewest catch-all segments first, then
+ * fewest dynamic segments, then most static segments. Used so that a pathname resolves to the most
+ * specific matching route instead of whichever route happens to be declared first.
+ */
+function comparePathSpecificity(a, b) {
+    return (a.catchAllSegmentCount - b.catchAllSegmentCount ||
+        a.dynamicSegmentCount - b.dynamicSegmentCount ||
+        b.staticSegmentCount - a.staticSegmentCount);
+}
+/**
+ * Specificity of a route definition's path. A localized route is ranked by its most specific variant.
+ */
+function getRouteSpecificity(path) {
+    var _a;
+    const paths = typeof path === "string" ? [path] : Object.values(path).filter(is_not_nil_1.isNotNil);
+    return (_a = paths.map(getPathSpecificity).sort(comparePathSpecificity).at(0)) !== null && _a !== void 0 ? _a : LEAST_SPECIFIC;
+}

package/utils/path-specificity.test.d.ts

@@ -0,0 +1 @@
+export {};

package/utils/path-specificity.test.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const path_specificity_1 = require("./path-specificity");
+describe("getPathSpecificity", () => {
+    it("counts static, dynamic and catch-all segments", () => {
+        expect((0, path_specificity_1.getPathSpecificity)("/hotel/create-hotel")).toEqual({
+            catchAllSegmentCount: 0,
+            dynamicSegmentCount: 0,
+            staticSegmentCount: 2,
+        });
+        expect((0, path_specificity_1.getPathSpecificity)("/hotel/[hotel-id]/edit")).toEqual({
+            catchAllSegmentCount: 0,
+            dynamicSegmentCount: 1,
+            staticSegmentCount: 2,
+        });
+        expect((0, path_specificity_1.getPathSpecificity)("/hotel/[...rest]")).toEqual({
+            catchAllSegmentCount: 1,
+            dynamicSegmentCount: 1,
+            staticSegmentCount: 1,
+        });
+        expect((0, path_specificity_1.getPathSpecificity)("/hotel/[[...rest]]")).toEqual({
+            catchAllSegmentCount: 1,
+            dynamicSegmentCount: 1,
+            staticSegmentCount: 1,
+        });
+    });
+    it("handles the root path", () => {
+        expect((0, path_specificity_1.getPathSpecificity)("/")).toEqual({
+            catchAllSegmentCount: 0,
+            dynamicSegmentCount: 0,
+            staticSegmentCount: 0,
+        });
+    });
+});
+describe("comparePathSpecificity", () => {
+    const sortPaths = (paths) => [...paths].sort((a, b) => (0, path_specificity_1.comparePathSpecificity)((0, path_specificity_1.getPathSpecificity)(a), (0, path_specificity_1.getPathSpecificity)(b)));
+    it("puts a static path before a dynamic one", () => {
+        expect(sortPaths(["/hotel/[hotel-id]", "/hotel/create-hotel"])).toEqual([
+            "/hotel/create-hotel",
+            "/hotel/[hotel-id]",
+        ]);
+    });
+    it("puts catch-all segments last", () => {
+        expect(sortPaths(["/hotel/[...rest]", "/hotel/[hotel-id]", "/hotel/detail"])).toEqual([
+            "/hotel/detail",
+            "/hotel/[hotel-id]",
+            "/hotel/[...rest]",
+        ]);
+    });
+    it("prefers more static segments when the dynamic count is equal", () => {
+        expect(sortPaths(["/hotel/[hotel-id]/[tab]", "/hotel/[hotel-id]/edit"])).toEqual([
+            "/hotel/[hotel-id]/edit",
+            "/hotel/[hotel-id]/[tab]",
+        ]);
+    });
+});
+describe("getRouteSpecificity", () => {
+    it("accepts a plain path", () => {
+        expect((0, path_specificity_1.getRouteSpecificity)("/hotel/[hotel-id]")).toEqual({
+            catchAllSegmentCount: 0,
+            dynamicSegmentCount: 1,
+            staticSegmentCount: 1,
+        });
+    });
+    it("ranks a localized route by its most specific variant", () => {
+        expect((0, path_specificity_1.getRouteSpecificity)({ cs: "/hotel/[hotel-id]", en: "/hotel/detail" })).toEqual({
+            catchAllSegmentCount: 0,
+            dynamicSegmentCount: 0,
+            staticSegmentCount: 2,
+        });
+    });
+});