react-routes-forge 1.0.3 → 1.1.0

package/README.md

@@ -1,170 +1,625 @@
-# react-routes-forge
-
-Type-safe route definitions with automatic path builders for React apps.
-
-## Why react-routes-forge?
-
-`react-routes-forge` eliminates the duplicate template/builder pattern used in route definitions. One source of truth defines:
-
-- static path templates for routing
-- dynamic path builders for navigation
-- typed params for safer runtime usage
-
-## Installation
-
-```bash
-npm install react-routes-forge
-```
-
-## Quick start
-
-```ts
-import { defineRoutes } from "react-routes-forge";
-
-export const PATHS = defineRoutes({
-  HOME: "/",
-  LOGIN: "/login",
-  USERS: {
-    ROOT: "/users",
-    ADD: "/users/add",
-    EDIT: "/users/edit/:id",
-    DETAILS: "/users/:id",
-  },
-  ROLES: {
-    PERMISSIONS: "/roles/permissions/:name",
-  },
-} as const);
-```
-
-## Usage
-
-### Router definitions
-
-Use route templates directly in route declarations.
-
-```tsx
-import { PATHS } from './paths';
-
-<Route path={PATHS.HOME} />
-<Route path={PATHS.USERS.EDIT} />
-<Route path={PATHS.ROLES.PERMISSIONS} />
-```
-
-### Navigation
-
-Build resolved paths from dynamic templates.
-
-```ts
-navigate(PATHS.USERS.EDIT.build({ id: 42 }));
-navigate(PATHS.ROLES.PERMISSIONS.build({ name: "admin" }));
-navigate(PATHS.HOME);
-```
-
-### Dynamic routes keep plain-string behavior
-
-Dynamic routes remain usable as strings while gaining helper methods.
-
-```ts
-PATHS.USERS.EDIT; // '/users/edit/:id'
-PATHS.USERS.EDIT.build({ id: 42 }); // '/users/edit/42'
-PATHS.USERS.EDIT.paramNames; // ['id']
-```
-
-## API
-
-### `defineRoutes(routeMap)`
-
-Create a typed route object from a nested route definition.
-
-- static routes remain plain strings
-- dynamic routes gain `.build(params)` and `.paramNames`
-
-### `build(template, params)`
-
-Resolve a route template without using `defineRoutes`.
-
-```ts
-import { build } from "react-routes-forge";
-
-build("/users/:id/posts/:postId", { id: 1, postId: 42 });
-// '/users/1/posts/42'
-```
-
-### `isActivePath(currentPath, template, options?)`
-
-Check whether a path matches a template.
-
-```ts
-import { isActivePath } from "react-routes-forge";
-
-isActivePath("/users/42", "/users/:id");
-isActivePath("/users/42/posts", "/users/:id");
-isActivePath("/users/42/posts", "/users/:id", { exact: false });
-```
-
-### `extractParamsFromPath(template, resolvedPath)`
-
-Extract path params from a resolved route.
-
-```ts
-import { extractParamsFromPath } from "react-routes-forge";
-
-extractParamsFromPath("/users/:id", "/users/42");
-// { id: '42' }
-```
-
-### `joinPaths(...segments)`
-
-Join path fragments and normalise slashes.
-
-```ts
-import { joinPaths } from "react-routes-forge";
-
-joinPaths("/api/", "/v1/", "/users");
-// '/api/v1/users'
-```
-
-### `getParamNames(template)`
-
-Return all parameter names from a template.
-
-```ts
-import { getParamNames } from "react-routes-forge";
-
-getParamNames("/users/:id/posts/:postId");
-// ['id', 'postId']
-```
-
-## React hooks
-
-Import only when using React Router.
-
-### `useRouteParams<T>()`
-
-Typed wrapper around React Router's `useParams`.
-
-```tsx
-import { useRouteParams } from "react-routes-forge";
-
-function EditUser() {
-  const { id } = useRouteParams<"/users/edit/:id">();
-  return <div>{id}</div>;
-}
-```
-
-### `useNavigateTo()`
-
-Thin, typed wrapper around React Router's `useNavigate()`.
-
-```tsx
-import { useNavigateTo } from "react-routes-forge";
-
-function Component() {
-  const navigateTo = useNavigateTo();
-  return (
-    <button onClick={() => navigateTo(PATHS.USERS.EDIT.build({ id: 42 }))}>
-      Edit
-    </button>
-  );
-}
-```
+# react-routes-forge
+
+**Type-safe route definitions with automatic path builders for React apps.**
+
+One source of truth for your routes — templates for `<Route path={...} />` and typed builders for navigation — with no duplication and no manual string concatenation.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](#license)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](#)
+
+---
+
+## Table of contents
+
+- [Why react-routes-forge?](#why-react-routes-forge)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Cheat sheet](#cheat-sheet)
+- [Core concepts](#core-concepts)
+- [API reference](#api-reference)
+  - [`defineRoutes(routeMap)`](#defineroutesroutemap)
+  - [`build(template, params, query?, options?)`](#buildtemplate-params-query-options)
+  - [`isActivePath(currentPath, template, options?)`](#isactivepathcurrentpath-template-options)
+  - [`extractParamsFromPath(template, resolvedPath)`](#extractparamsfrompathtemplate-resolvedpath)
+  - [`joinPaths(...segments)`](#joinpathssegments)
+  - [`getParamNames(template)`](#getparamnamestemplate)
+  - [`flattenRoutes(routes)`](#flattenroutesroutes)
+- [React hooks](#react-hooks)
+  - [`useRouteParams<T>()`](#useroutparamst)
+  - [`useNavigateTo()`](#usenavigateto)
+  - [`useResolvedPath(template, params, query?, options?)`](#useresolvedpathtemplate-params-query-options)
+- [Query string support](#query-string-support)
+- [Strict mode](#strict-mode)
+- [Migrating from the old pattern](#migrating-from-the-old-pattern)
+- [Known behaviours & gotchas](#known-behaviours--gotchas)
+- [TypeScript support](#typescript-support)
+- [Testing](#testing)
+- [Requirements](#requirements)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Why react-routes-forge?
+
+Most React apps end up with route definitions like this:
+
+```ts
+// ❌ The common pattern
+export const PATHS = {
+  USERS: {
+    ROOT: "/users",
+    DETAILS: "/users/:id",
+  },
+};
+```
+
+Dynamic routes typically need a **second** entry alongside the template — a hand-written function to build the real URL. As the app grows, the two drift apart, and nothing stops the template and the builder from disagreeing.
+
+`react-routes-forge` collapses both into a single key:
+
+```ts
+// ✅ One key, two uses
+export const PATHS = defineRoutes({
+  USERS: {
+    ROOT: "/users",
+    DETAILS: "/users/:id",
+  },
+} as const);
+
+PATHS.USERS.ROOT; // '/users'            → static, used directly
+PATHS.USERS.DETAILS; // '/users/:id'        → use in <Route path={...} />
+PATHS.USERS.DETAILS.build({ id: 42 }); // '/users/42'        → use when navigating
+```
+
+You get:
+
+- **Single source of truth** — no duplicate template/builder pairs to keep in sync
+- **Compile-time param safety** — `.build()` is typed from the path string itself; missing or misspelled params are TypeScript errors
+- **Query string support** — built into `.build()`, no manual `URLSearchParams` wrangling
+- **Zero runtime dependencies** for the core API — React Router is an optional peer dependency, only required if you use the hooks
+- **Deep nesting supported out of the box** — organize routes into as many nested groups as your app needs
+
+---
+
+## Installation
+
+```bash
+npm install react-routes-forge
+# or
+pnpm add react-routes-forge
+# or
+yarn add react-routes-forge
+# or
+bun add react-routes-forge
+```
+
+React Router is an **optional** peer dependency — only needed if you use the bundled hooks (`useRouteParams`, `useNavigateTo`, `useResolvedPath`).
+
+```bash
+npm install react-router-dom   # only if you're using the hooks
+# or
+pnpm add react-router-dom
+# or
+yarn add react-router-dom
+# or
+bun add react-router-dom
+```
+
+> **Note:** this package ships ESM-only. See [Known behaviours & gotchas](#known-behaviours--gotchas) for details.
+
+---
+
+## Quick start
+
+```ts
+// paths.ts
+import { defineRoutes } from "react-routes-forge";
+
+export const PATHS = defineRoutes({
+  HOME: "/",
+  LOGIN: "/login",
+  USERS: {
+    ROOT: "/users",
+    ADD: "/users/add",
+    EDIT: "/users/edit/:id",
+    DETAILS: "/users/:id",
+  },
+  ROLES: {
+    PERMISSIONS: "/roles/permissions/:name",
+  },
+} as const);
+```
+
+```tsx
+// App.tsx — static paths and dynamic templates both work directly as strings
+import { Routes, Route } from "react-router-dom";
+import { PATHS } from "./paths";
+
+<Routes>
+  <Route path={PATHS.HOME} element={<Home />} />
+  <Route path={PATHS.USERS.ROOT} element={<UserList />} />
+  <Route path={PATHS.USERS.EDIT} element={<EditUser />} />
+  <Route path={PATHS.ROLES.PERMISSIONS} element={<RolePermissions />} />
+</Routes>;
+```
+
+```ts
+// Navigating — call .build() to resolve a dynamic path into a real URL
+navigate(PATHS.USERS.EDIT.build({ id: 42 })); // '/users/edit/42'
+navigate(PATHS.ROLES.PERMISSIONS.build({ name: "admin" })); // '/roles/permissions/admin'
+navigate(PATHS.HOME); // '/'
+```
+
+That's the entire API surface you need for most apps. Everything below covers the rest of the toolkit.
+
+---
+
+## Cheat sheet
+
+Quick reference for everything the package exports. Click through to the full section for details and examples.
+
+| Export                                                                                         | Kind     | Purpose                                                   |
+| ---------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------- |
+| [`defineRoutes(routeMap)`](#defineroutesroutemap)                                              | function | Builds the typed `PATHS` object from a nested route map   |
+| [`build(template, params, query?, options?)`](#buildtemplate-params-query-options)             | function | Resolve a template into a URL without `defineRoutes`      |
+| [`isActivePath(currentPath, template, options?)`](#isactivepathcurrentpath-template-options)   | function | Check if a path matches a template (nav-highlighting)     |
+| [`extractParamsFromPath(template, resolvedPath)`](#extractparamsfrompathtemplate-resolvedpath) | function | Pull param values back out of a resolved URL              |
+| [`joinPaths(...segments)`](#joinpathssegments)                                                 | function | Join and normalize path segments                          |
+| [`getParamNames(template)`](#getparamnamestemplate)                                            | function | List the `:param` names in a template                     |
+| [`flattenRoutes(routes)`](#flattenroutesroutes)                                                | function | Flatten a `PATHS` tree for sitemaps / duplicate detection |
+| [`useRouteParams<T>()`](#useroutparamst)                                                       | hook     | Typed wrapper around React Router's `useParams`           |
+| [`useNavigateTo()`](#usenavigateto)                                                            | hook     | Typed wrapper around React Router's `useNavigate`         |
+| [`useResolvedPath(...)`](#useresolvedpathtemplate-params-query-options)                        | hook     | Resolve a template to a string without navigating         |
+| `.build(params, query?, options?)`                                                             | method   | On every dynamic route — resolves to a concrete URL       |
+| `.paramNames`                                                                                  | property | On every dynamic route — the param names it expects       |
+
+---
+
+## Core concepts
+
+| Route type  | Example                 | Behaves as                              | Gains                                                |
+| ----------- | ----------------------- | --------------------------------------- | ---------------------------------------------------- |
+| **Static**  | `HOME: '/'`             | Plain string primitive                  | Nothing extra — use it directly                      |
+| **Dynamic** | `DETAILS: '/users/:id'` | String-like (coercible to its template) | `.build(params, query?, options?)` and `.paramNames` |
+
+`defineRoutes()` walks your route object recursively, leaving static paths untouched and wrapping any path containing a `:param` segment so it can carry a builder alongside its template string.
+
+---
+
+## API reference
+
+### `defineRoutes(routeMap)`
+
+Creates a fully typed route object from a nested plain object.
+
+- Static paths are returned as-is — use them directly anywhere a string is expected (e.g. `<Route path={...} />`).
+- Dynamic paths (containing `:param`) gain:
+  - **`.build(params, query?, options?)`** — resolves the template into a concrete URL
+  - **`.paramNames`** — array of the param names extracted from the template, e.g. `['id']`
+
+Nesting is unlimited — organize routes into as many groups and sub-groups as your app needs.
+
+```ts
+const PATHS = defineRoutes({
+  SERVICES: {
+    ROOT: "/services",
+    BENEFICIARY_CARE_CENTER: {
+      DETAILS: "/services/beneficiary-care-center/:id",
+      EDIT: "/services/beneficiary-care-center/edit/:id",
+    },
+  },
+} as const);
+
+PATHS.SERVICES.ROOT; // '/services'
+PATHS.SERVICES.BENEFICIARY_CARE_CENTER.EDIT.build({ id: 7 }); // '/services/beneficiary-care-center/edit/7'
+PATHS.SERVICES.BENEFICIARY_CARE_CENTER.EDIT.paramNames; // ['id']
+```
+
+> Always pass `as const` to `defineRoutes()` — it preserves the literal string types that power `.build()`'s compile-time param checking.
+
+---
+
+### `build(template, params, query?, options?)`
+
+Standalone path resolver — for building a URL without going through `defineRoutes`, or for adding a query string to a **static** path (which has no `.build()` of its own).
+
+```ts
+import { build } from "react-routes-forge";
+
+build("/users/:id/posts/:postId", { id: 1, postId: 42 });
+// → '/users/1/posts/42'
+
+// Append a query string to any path — including static ones
+build("/users", {}, { sort: "asc" });
+// → '/users?sort=asc'
+
+// Strict mode — throw instead of warn when a param is missing
+build("/users/:id", {}, undefined, { strict: true });
+// ✗ throws RangeError: [route-forge] Missing required param(s) ":id" in template "/users/:id".
+```
+
+---
+
+### `isActivePath(currentPath, template, options?)`
+
+Checks whether a resolved path matches a route template — the building block for nav-highlighting ("is this link active?"). Query strings on `currentPath` are ignored automatically.
+
+```ts
+import { isActivePath } from "react-routes-forge";
+
+isActivePath("/users/42", "/users/:id"); // true
+isActivePath("/users/42/posts", "/users/:id"); // false (exact match by default)
+isActivePath("/users/42/posts", "/users/:id", { exact: false }); // true  (prefix match)
+isActivePath("/users/42?tab=profile", "/users/:id"); // true  (query string ignored)
+```
+
+A common real-world use — highlighting the active nav link:
+
+```tsx
+function NavLink({ to, children }: { to: string; children: React.ReactNode }) {
+  const location = useLocation();
+  const active = isActivePath(location.pathname, to, { exact: false });
+
+  return (
+    <Link to={to} className={active ? "nav-link active" : "nav-link"}>
+      {children}
+    </Link>
+  );
+}
+```
+
+---
+
+### `extractParamsFromPath(template, resolvedPath)`
+
+Extracts param values back out of a resolved URL, given its template. Also strips query strings before matching.
+
+```ts
+import { extractParamsFromPath } from "react-routes-forge";
+
+extractParamsFromPath("/users/:id", "/users/42");
+// → { id: '42' }
+
+extractParamsFromPath("/a/:x/b/:y", "/a/foo/b/bar");
+// → { x: 'foo', y: 'bar' }
+```
+
+---
+
+### `joinPaths(...segments)`
+
+Safely joins path segments, normalizing duplicate/missing slashes.
+
+```ts
+import { joinPaths } from "react-routes-forge";
+
+joinPaths("/users", "edit", ":id"); // → '/users/edit/:id'
+joinPaths("/api/", "/v1/", "/users"); // → '/api/v1/users'
+```
+
+---
+
+### `getParamNames(template)`
+
+Returns the list of param names present in a template string.
+
+```ts
+import { getParamNames } from "react-routes-forge";
+
+getParamNames("/users/:id/posts/:postId"); // → ['id', 'postId']
+getParamNames("/users"); // → []
+```
+
+---
+
+### `flattenRoutes(routes)`
+
+Walks a `defineRoutes()` tree and returns a flat array of `{ key, path }` entries, where `key` is the dot-joined path from the root (e.g. `"SERVICES.BENEFICIARY_CARE_CENTER.EDIT"`) and `path` is the raw template string.
+
+Primary uses:
+
+- **Sitemap generation** — one call gives you every route in the app.
+- **Duplicate detection** — catch the same path string defined under two different keys before it ships.
+
+```ts
+import { defineRoutes, flattenRoutes } from "react-routes-forge";
+
+const PATHS = defineRoutes({
+  HOME: "/",
+  USERS: {
+    ROOT: "/users",
+    EDIT: "/users/edit/:id",
+  },
+} as const);
+
+flattenRoutes(PATHS);
+// [
+//   { key: 'HOME',       path: '/' },
+//   { key: 'USERS.ROOT', path: '/users' },
+//   { key: 'USERS.EDIT', path: '/users/edit/:id' },
+// ]
+
+// Detect duplicate paths across the tree
+const flat = flattenRoutes(PATHS);
+const paths = flat.map((r) => r.path);
+const dupes = paths.filter((p, i) => paths.indexOf(p) !== i);
+if (dupes.length) console.warn("Duplicate route paths:", dupes);
+```
+
+A useful pattern is running the duplicate check once at app startup (or in a test) so a copy-paste route collision fails fast instead of surfacing as a confusing routing bug later:
+
+```ts
+// routes.test.ts
+it("has no duplicate route paths", () => {
+  const paths = flattenRoutes(PATHS).map((r) => r.path);
+  const dupes = paths.filter((p, i) => paths.indexOf(p) !== i);
+  expect(dupes).toEqual([]);
+});
+```
+
+---
+
+## React hooks
+
+Import these only if you're using React Router — they're tree-shakeable and won't be bundled unless imported.
+
+### `useRouteParams<T>()`
+
+Typed wrapper around React Router's `useParams`. Pass the route's template string as a generic to get a correctly typed params object back — no casting, and it works for any number of `:param` segments.
+
+```tsx
+import { useRouteParams } from "react-routes-forge";
+
+// Route: '/users/edit/:id'
+function EditUser() {
+  const { id } = useRouteParams<"/users/edit/:id">();
+  return <div>Editing user {id}</div>;
+}
+
+// Multiple params also work correctly
+// Route: '/posts/:postId/comments/:commentId'
+function Comment() {
+  const { postId, commentId } =
+    useRouteParams<"/posts/:postId/comments/:commentId">();
+  // ...
+}
+```
+
+---
+
+### `useNavigateTo()`
+
+Thin, typed wrapper around `useNavigate()` that accepts a resolved path (the output of `.build()`) along with the usual navigation options.
+
+```tsx
+import { useNavigateTo } from "react-routes-forge";
+import { PATHS } from "./paths";
+
+function Component() {
+  const navigateTo = useNavigateTo();
+
+  return (
+    <button onClick={() => navigateTo(PATHS.USERS.EDIT.build({ id: 42 }))}>
+      Edit
+    </button>
+  );
+}
+
+navigateTo(PATHS.HOME, { replace: true });
+navigateTo(PATHS.USERS.ROOT, { state: { from: "settings" } });
+```
+
+---
+
+### `useResolvedPath(template, params, query?, options?)`
+
+Resolves a path template to a concrete URL string without navigating — useful for `<Link to={...} />`, preloading, or building a URL for something other than `navigate()`. Backed by React Router's `generatePath`, so it correctly supports splat (`*`) and optional (`:param?`) segments. Accepts the same `query` and `options` as [`build()`](#buildtemplate-params-query-options).
+
+```tsx
+import { useResolvedPath } from "react-routes-forge";
+
+const path = useResolvedPath("/users/:id", { id: 42 });
+// → '/users/42'
+
+const path = useResolvedPath("/users/:id", { id: 42 }, { tab: "info" });
+// → '/users/42?tab=info'
+
+// Strict mode — throws RangeError instead of warning on missing params
+const path = useResolvedPath("/users/:id", {}, undefined, { strict: true });
+```
+
+---
+
+## Query string support
+
+Every path-resolving function — `.build()`, `build()`, and `useResolvedPath()` — accepts an optional query object as its second-to-last argument.
+
+```ts
+navigate(
+  PATHS.USERS.DETAILS.build({ id: 42 }, { tab: "billing", sort: "asc" }),
+);
+// → '/users/42?tab=billing&sort=asc'
+```
+
+**Array values** are serialized as repeated keys:
+
+```ts
+build("/search", {}, { tags: ["admin", "moderator"] });
+// → '/search?tags=admin&tags=moderator'
+```
+
+**`null` and `undefined` values are dropped**, so you can pass optional filters without conditionally building the object:
+
+```ts
+build("/users", {}, { sort: "asc", filter: undefined });
+// → '/users?sort=asc'
+```
+
+Static routes don't have a fluent `.build()` (there's nothing to interpolate), so use the standalone `build()` util to attach a query string to them:
+
+```ts
+import { build } from "react-routes-forge";
+
+build(PATHS.USERS.ROOT, {}, { sort: "asc", page: 2 });
+// → '/users?sort=asc&page=2'
+```
+
+---
+
+## Strict mode
+
+By default, a missing required param leaves the `:param` placeholder in the resolved string and logs a `console.warn` — useful for catching bugs during development without crashing the app.
+
+Pass `{ strict: true }` as the last argument to any builder to throw a `RangeError` instead:
+
+```ts
+build("/users/:id", {}, undefined, { strict: true });
+// ✗ throws RangeError: [route-forge] Missing required param(s) ":id" in template "/users/:id".
+```
+
+This is consistent across the whole API surface:
+
+| API                                    | Default (no `strict`)                         | `{ strict: true }`  |
+| -------------------------------------- | --------------------------------------------- | ------------------- |
+| `.build()` (fluent, on dynamic routes) | `console.warn`, leaves `:param` in the string | throws `RangeError` |
+| `build()` / `buildPath()` (standalone) | `console.warn`, leaves `:param` in the string | throws `RangeError` |
+| `useResolvedPath()`                    | `console.warn`, leaves `:param` in the string | throws `RangeError` |
+
+A common pattern is enabling strict mode only in tests or development builds:
+
+```ts
+const opts = { strict: process.env.NODE_ENV === "test" };
+navigate(PATHS.USERS.EDIT.build({ id: userId }, undefined, opts));
+```
+
+---
+
+## Migrating from the old pattern
+
+If your routes currently look like this:
+
+```ts
+// ❌ Before
+export const PATHS = {
+  SERVICES: {
+    ROOT: "/services",
+    DETAILS: "/services/:id",
+  },
+};
+
+navigate(`/services/${id}`);
+navigate(`${PATHS.SERVICES.ROOT}/${id}`);
+```
+
+Drop the manual string concatenation and wrap the object in `defineRoutes()`:
+
+```ts
+// ✅ After
+export const PATHS = defineRoutes({
+  SERVICES: {
+    ROOT: "/services",
+    DETAILS: "/services/:id",
+  },
+} as const);
+```
+
+Update call sites to use `.build()` instead of template literals or hand-written helper functions:
+
+```ts
+// Before
+navigate(`/services/${id}`);
+navigate(`${PATHS.SERVICES.ROOT}/${id}`);
+
+// After
+navigate(PATHS.SERVICES.DETAILS.build({ id }));
+```
+
+Everywhere the template string itself was used (e.g. `<Route path={PATHS.SERVICES.DETAILS} />`) needs no changes at all.
+
+---
+
+## Known behaviours & gotchas
+
+### Dynamic routes are `String` objects, not primitives
+
+`defineRoutes` wraps dynamic paths in [`String` objects](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/String) so that `.build()` and `.paramNames` can be attached as properties. This means:
+
+```ts
+// ✓ These all work as expected
+String(PATHS.USERS.EDIT); // '/users/edit/:id'
+`${PATHS.USERS.EDIT}`; // '/users/edit/:id'
+PATHS.USERS.EDIT == "/users/edit/:id"; // true  (loose equality)
+
+// ✗ Watch out for these
+typeof PATHS.USERS.EDIT; // 'object' ← not 'string'
+PATHS.USERS.EDIT === "/users/edit/:id"; // false    ← strict equality fails
+```
+
+Prefer template literals or explicit `String()` coercion when comparing dynamic route values, and avoid using them as plain object/`Map` keys. Static routes (`HOME`, `USERS.ROOT`, …) remain genuine string primitives and are unaffected.
+
+### `useResolvedPath` vs. the library's own `buildPath`
+
+`useResolvedPath` delegates to React Router's `generatePath` when all params are present, which correctly handles splat (`*`) and optional (`:param?`) segments that the library's own regex-based substitution does not. If params are missing, it falls back to the same `buildPath`/strict-mode behaviour described above — so failure modes stay consistent, but full splat/optional support is only guaranteed via the hook, not via `.build()`.
+
+### ESM-only package
+
+This package ships **ESM only** (`"type": "module"`, no `require` export condition). Consumers on a plain CommonJS setup (`require('react-routes-forge')`) are not supported. All modern bundlers (Vite, Webpack ≥ 5, esbuild, Rollup) handle ESM packages transparently. If you're in a CJS-only environment, you'll need a bundler transform or a compatibility shim.
+
+---
+
+## TypeScript support
+
+Written in strict TypeScript with no `any` in the public API surface. Param types for `.build()` are inferred directly from each path template via a recursive template-literal type, so:
+
+```ts
+PATHS.USERS.EDIT.build({ id: 42 }); // ✓ compiles
+PATHS.USERS.EDIT.build({}); // ✗ compile error — 'id' is required
+PATHS.USERS.EDIT.build({ userId: 42 }); // ✗ compile error — 'id' expected, not 'userId'
+```
+
+`.paramNames` is similarly typed as a literal array of the exact param names in the template, not a generic `string[]`.
+
+---
+
+## Testing
+
+The package ships with a full test suite covering the core builder/utility functions and the React hooks, including strict-mode behaviour, query string edge cases (arrays, `null`/`undefined` filtering), nested route groups, and duplicate-path detection via `flattenRoutes`.
+
+```bash
+npm test            # run the full suite once
+npm run test:watch  # watch mode
+
+# equivalent with other package managers
+pnpm test / pnpm test:watch
+yarn test / yarn test:watch
+bun test / bun test:watch
+```
+
+If you're contributing, new behaviour should come with a matching test — the existing suite is organized by function/hook, so add cases alongside the relevant `describe` block rather than starting a new file.
+
+---
+
+## Requirements
+
+- **React** ≥ 17 (peer dependency)
+- **react-router-dom** ≥ 6 (optional peer dependency — required only for the bundled hooks)
+- **Node.js** ≥ 18
+- **TypeScript** ≥ 5 recommended for full type inference (the package works with plain JavaScript too, just without compile-time param checking)
+
+---
+
+## Contributing
+
+Issues and pull requests are welcome.
+
+1. Fork the repo and create a branch for your change.
+2. Add or update tests for any behavioural change — see [Testing](#testing).
+3. Run `npm run lint` and `npm test` before opening a PR.
+4. Keep commit messages conventional (`feat:`, `fix:`, `docs:`, …) — this repo uses [standard-version](https://github.com/conventional-changelog/standard-version) for releases.
+
+---
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -33,8 +33,37 @@ type ExtractParams<T extends string> = T extends `${string}:${infer Param}/${inf
 type PathParams<T extends string> = ExtractParams<T> extends never ? never : {
     [K in ExtractParams<T>]: RouteParam;
 };
+/**
+ * Acceptable query param value types for route builders.
+ */
+type QueryParams = Record<string, RouteParam | RouteParam[] | null | undefined>;
+/**
+ * Options accepted by `buildPath` (4th positional argument).
+ *
+ * @example
+ * // Throws a RangeError when a :param segment is missing rather than
+ * // silently leaving the colon-placeholder in the output string.
+ * buildPath('/users/:id', {}, undefined, { strict: true });
+ */
+type BuildPathOptions = {
+    /**
+     * When `true`, `buildPath` throws a `RangeError` if any `:param`
+     * placeholder is left unresolved instead of emitting a console.warn.
+     * Useful in dev/test environments to catch missing params early.
+     */
+    strict?: boolean;
+};
+/**
+ * A single entry produced by `flattenRoutes()`.
+ */
+type FlatRoute = {
+    /** Dot-joined key path from the root, e.g. `"SERVICES.BCC.EDIT"`. */
+    key: string;
+    /** The raw path template string, e.g. `"/services/bcc/edit/:id"`. */
+    path: string;
+};
 
-declare function buildPath(template: string, params: Record<string, RouteParam>): string;
+declare function buildPath(template: string, params: RouteParams, query?: QueryParams, options?: BuildPathOptions): string;
 declare function extractParamNames(template: string): string[];
 declare function isDynamic(path: string): boolean;
 declare function isActivePath(currentPath: string, template: string, options?: {
@@ -42,14 +71,31 @@ declare function isActivePath(currentPath: string, template: string, options?: {
 }): boolean;
 declare function extractParamsFromPath(template: string, resolvedPath: string): Record<string, string>;
 declare function joinPaths(...segments: string[]): string;
-declare function build(template: string, params: Record<string, RouteParam>): string;
+declare function build(template: string, params: RouteParams, query?: QueryParams, options?: BuildPathOptions): string;
 declare function getParamNames(template: string): string[];
+/**
+ * Walk a `defineRoutes` output tree and return a flat array of
+ * `{ key, path }` entries where `key` is the dot-joined key path from
+ * the root (e.g. `"SERVICES.BCC.EDIT"`) and `path` is the raw template
+ * string (e.g. `"/services/bcc/edit/:id"`).
+ *
+ * Useful for:
+ * - Generating sitemaps from a single source of truth.
+ * - Detecting duplicate path strings across branches at startup:
+ *
+ * @example
+ * const flat = flattenRoutes(PATHS);
+ * const paths = flat.map((r) => r.path);
+ * const dupes = paths.filter((p, i) => paths.indexOf(p) !== i);
+ * if (dupes.length) console.warn('Duplicate paths:', dupes);
+ */
+declare function flattenRoutes(routes: Record<string, unknown>, prefix?: string): FlatRoute[];
 
 type RouteInput = {
     [key: string]: string | RouteInput;
 };
 type DynamicRoute<T extends string> = T extends `${string}:${string}` ? T & {
-    build(params: PathParams<T>): RoutePath;
+    build(params: PathParams<T>, query?: QueryParams, options?: BuildPathOptions): RoutePath;
     paramNames: Array<ExtractParams<T>>;
 } : T;
 type ResolvedRoutes<T extends RouteInput> = {
@@ -65,16 +111,13 @@ declare function defineRoutes<T extends RouteInput>(routes: T): ResolvedRoutes<T
 /**
  * A typed wrapper around React Router's `useParams`.
  *
- * Pass the route's path template as a const generic to get a properly typed
- * params object back — no casting needed.
- *
  * @example
  * ```tsx
- * // Route is defined as '/users/edit/:id'
- * const { id } = useRouteParams<'/users/edit/:id'>();
+ * // Route: '/a/:x/b/:y/c/:z'
+ * const { x, y, z } = useRouteParams<'/a/:x/b/:y/c/:z'>();
  * ```
  */
-declare function useRouteParams<T extends string, K extends string = T extends `${string}:${infer P}/${infer R}` ? P | (R extends `${string}:${infer Q}` ? Q : never) : T extends `${string}:${infer P}` ? P : never>(): Record<K, string>;
+declare function useRouteParams<T extends string>(): Record<ExtractParams<T>, string>;
 type NavigateOptions = {
     replace?: boolean;
     state?: unknown;
@@ -95,13 +138,19 @@ declare function useNavigateTo(): (path: string, options?: NavigateOptions) => v
  * Resolves a dynamic path template against params using React Router's
  * `generatePath`, with proper typing.
  *
- * Useful when you need the resolved path string without navigating.
+ * Accepts the same `options` bag as `build()` / `buildPath()`:
+ * - (default) soft-fail: `console.warn` and return the partial path with unresolved `:param` placeholders.
+ * - `{ strict: true }`: throw a `RangeError` on missing params — matching `.build()`'s strict behaviour.
+ *
+ * When all params are present, resolution is delegated to React Router's `generatePath`,
+ * which correctly handles splat (`*`) and optional (`:param?`) segments.
  *
  * @example
  * ```tsx
  * const path = useResolvedPath('/users/:id', { id: 42 }); // → '/users/42'
+ * const path = useResolvedPath('/users/:id', {}, undefined, { strict: true }); // throws RangeError
  * ```
  */
-declare function useResolvedPath(template: string, params: Record<string, RouteParam>): string;
+declare function useResolvedPath(template: string, params: RouteParams, query?: QueryParams, options?: BuildPathOptions): string;
 
-export { type ExtractParams, type PathParams, type RouteBuilder, type RouteLeaf, type RouteMap, type RouteParam, type RouteParams, type RoutePath, build, buildPath, defineRoutes, extractParamNames, extractParamsFromPath, getParamNames, isActivePath, isDynamic, joinPaths, useNavigateTo, useResolvedPath, useRouteParams };
+export { type BuildPathOptions, type ExtractParams, type FlatRoute, type PathParams, type QueryParams, type RouteBuilder, type RouteLeaf, type RouteMap, type RouteParam, type RouteParams, type RoutePath, build, buildPath, defineRoutes, extractParamNames, extractParamsFromPath, flattenRoutes, getParamNames, isActivePath, isDynamic, joinPaths, useNavigateTo, useResolvedPath, useRouteParams };

package/dist/index.js

@@ -1,2 +1,2 @@
-var c=()=>/:([^/]+)/g,f=()=>/[.*+?^${}()|[\]\\]/g;function g(t){return t.replace(f(),"\\$&")}function R(t){return g(t).replace(c(),"([^/]+)")}function i(t,e){let r=a(t).reduce((u,s)=>{let p=e[s],x=p===void 0?`:${s}`:String(p);return u.replace(new RegExp(`:${g(s)}(?=/|$)`,"g"),x)},t);return globalThis.process?.env?.NODE_ENV!=="production"&&r.includes(":")&&console.warn(`[route-forge] Unresolved params in path "${r}". Check that all :param segments have matching keys.`),r}function a(t){return[...t.matchAll(c())].map(e=>e[1])}function m(t){return c().test(t)}function d(t,e,n={exact:!0}){let r=R(e);return(n.exact?new RegExp(`^${r}$`):new RegExp(`^${r}`)).test(t)}function l(t,e){let n=a(t),r=new RegExp(`^${R(t)}$`),o=e.match(r);return o?Object.fromEntries(n.map((u,s)=>[u,o[s+1]??""])):{}}function T(...t){return"/"+t.map(e=>e.replace(/^\/+|\/+$/g,"")).filter(Boolean).join("/")}function y(t,e){return i(t,e)}function h(t){return a(t)}var v=t=>typeof t=="object"&&t!==null;function $(t){let e=a(t),n=new String(t);return n.build=r=>i(t,r),n.paramNames=e,n}function P(t){let e={};for(let n in t){if(!Object.prototype.hasOwnProperty.call(t,n))continue;let r=t[n];typeof r=="string"?e[n]=m(r)?$(r):r:v(r)&&(e[n]=P(r))}return e}function b(t){return P(t)}import{useParams as N,useNavigate as E,generatePath as w}from"react-router-dom";function k(){return N()}function D(){let t=E();return(e,n)=>{t(e,n)}}function A(t,e){return w(t,Object.fromEntries(Object.entries(e).map(([n,r])=>[n,String(r)])))}export{y as build,i as buildPath,b as defineRoutes,a as extractParamNames,l as extractParamsFromPath,h as getParamNames,d as isActivePath,m as isDynamic,T as joinPaths,D as useNavigateTo,A as useResolvedPath,k as useRouteParams};
+var l=()=>/:([^/]+)/g,x=()=>/[.*+?^${}()|[\]\\]/g;function f(t){return t.replace(x(),"\\$&")}function R(t){return f(t).replace(l(),"([^/]+)")}function P(t,e){if(!e)return t;let r=new URLSearchParams;for(let[s,a]of Object.entries(e))a!=null&&(Array.isArray(a)?a.forEach(i=>{i!=null&&r.append(s,String(i))}):r.append(s,String(a)));let n=r.toString();return n?t+(t.includes("?")?"&":"?")+n:t}function p(t,e,r,n){let s=u(t),a=s.filter(o=>e[o]===void 0||e[o]===null),i=s.reduce((o,c)=>{let m=e[c],h=m==null?`:${c}`:String(m);return o.replace(new RegExp(`:${f(c)}(?=/|$)`,"g"),h)},t);if(a.length>0){if(n?.strict)throw new RangeError(`[route-forge] Missing required param(s) ${a.map(c=>`":${c}"`).join(", ")} in template "${t}".`);globalThis.process?.env?.NODE_ENV!=="production"&&console.warn(`[route-forge] Unresolved params in path "${i}". Check that all :param segments have matching keys.`)}return P(i,r)}function u(t){return[...t.matchAll(l())].map(e=>e[1])}function g(t){return l().test(t)}function T(t,e,r={exact:!0}){let n=t.split("?")[0]??"",s=R(e);return(r.exact?new RegExp(`^${s}$`):new RegExp(`^${s}`)).test(n)}function v(t,e){let r=e.split("?")[0]??"",n=u(t),s=new RegExp(`^${R(t)}$`),a=r.match(s);return a?Object.fromEntries(n.map((i,o)=>[i,a[o+1]??""])):{}}function b(...t){return"/"+t.map(e=>e.replace(/^\/+|\/+$/g,"")).filter(Boolean).join("/")}function E(t,e,r,n){return p(t,e,r,n)}function N(t){return u(t)}function d(t,e=""){let r=[];for(let n of Object.keys(t)){let s=e?`${e}.${n}`:n,a=t[n];typeof a=="string"?r.push({key:s,path:a}):a instanceof String?r.push({key:s,path:a.valueOf()}):typeof a=="object"&&a!==null&&r.push(...d(a,s))}return r}var O=t=>typeof t=="object"&&t!==null;function k(t){let e=u(t),r=new String(t);return r.build=(n,s,a)=>p(t,n,s,a),r.paramNames=e,r}function y(t){let e={};for(let r in t){if(!Object.prototype.hasOwnProperty.call(t,r))continue;let n=t[r];typeof n=="string"?e[r]=g(n)?k(n):n:O(n)&&(e[r]=y(n))}return e}function w(t){return y(t)}import{useParams as $,useNavigate as A,generatePath as Q}from"react-router-dom";function j(){return $()}function B(){let t=A();return(e,r)=>{t(e,r)}}function S(t,e,r,n){if(!u(t).every(o=>e[o]!==void 0&&e[o]!==null))return p(t,e,r,n);let i=Q(t,Object.fromEntries(Object.entries(e).map(([o,c])=>[o,String(c)])));return P(i,r)}export{E as build,p as buildPath,w as defineRoutes,u as extractParamNames,v as extractParamsFromPath,d as flattenRoutes,N as getParamNames,T as isActivePath,g as isDynamic,b as joinPaths,B as useNavigateTo,S as useResolvedPath,j as useRouteParams};
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/core/utils.ts","../src/core/defineRoutes.ts","../src/hooks/index.ts"],"sourcesContent":["import type { RouteParam } from '../types';\n\n/** Returns a fresh RegExp each call — avoids shared `lastIndex` state on /g patterns. */\nconst PATH_PARAM_RE = () => /:([^/]+)/g;\nconst ESCAPE_RE = () => /[.*+?^${}()|[\\]\\\\]/g;\n\nfunction escapeRegex(value: string): string {\n  return value.replace(ESCAPE_RE(), '\\\\$&');\n}\n\nfunction createTemplatePattern(template: string): string {\n  return escapeRegex(template).replace(PATH_PARAM_RE(), '([^/]+)');\n}\n\nexport function buildPath(\n  template: string,\n  params: Record<string, RouteParam>\n): string {\n  const paramNames = extractParamNames(template);\n\n  const resolved = paramNames.reduce((path, name) => {\n    const value = params[name];\n    const replacement = value === undefined ? `:${name}` : String(value);\n    return path.replace(new RegExp(`:${escapeRegex(name)}(?=/|$)`, 'g'), replacement);\n  }, template);\n\n  const runtimeProcess = (globalThis as typeof globalThis & {\n    process?: {\n      env?: Record<string, string | undefined>;\n    };\n  }).process;\n\n  if (runtimeProcess?.env?.NODE_ENV !== 'production' && resolved.includes(':')) {\n    console.warn(\n      `[route-forge] Unresolved params in path \"${resolved}\". ` +\n        `Check that all :param segments have matching keys.`\n    );\n  }\n\n  return resolved;\n}\n\nexport function extractParamNames(template: string): string[] {\n  return [...template.matchAll(PATH_PARAM_RE())].map((match) => match[1] as string);\n}\n\nexport function isDynamic(path: string): boolean {\n  return PATH_PARAM_RE().test(path);\n}\n\nexport function isActivePath(\n  currentPath: string,\n  template: string,\n  options: { exact?: boolean } = { exact: true }\n): boolean {\n  const pattern = createTemplatePattern(template);\n  const regex = options.exact\n    ? new RegExp(`^${pattern}$`)\n    : new RegExp(`^${pattern}`);\n\n  return regex.test(currentPath);\n}\n\nexport function extractParamsFromPath(\n  template: string,\n  resolvedPath: string\n): Record<string, string> {\n  const paramNames = extractParamNames(template);\n  const regex = new RegExp(`^${createTemplatePattern(template)}$`);\n  const match = resolvedPath.match(regex);\n\n  if (!match) return {};\n\n  return Object.fromEntries(\n    paramNames.map((name, index) => [name, match[index + 1] ?? ''])\n  );\n}\n\nexport function joinPaths(...segments: string[]): string {\n  return (\n    '/' +\n    segments\n      .map((segment) => segment.replace(/^\\/+|\\/+$/g, ''))\n      .filter(Boolean)\n      .join('/')\n  );\n}\n\nexport function build(\n  template: string,\n  params: Record<string, RouteParam>\n): string {\n  return buildPath(template, params);\n}\n\nexport function getParamNames(template: string): string[] {\n  return extractParamNames(template);\n}\n","import { buildPath, extractParamNames, isDynamic } from './utils';\nimport type { ExtractParams, PathParams, RoutePath } from '../types';\n\n// Re-export so consumers that import from 'core/defineRoutes' get the full surface\nexport { buildPath, extractParamNames, isDynamic } from './utils';\n\ntype RouteInput = {\n  [key: string]: string | RouteInput;\n};\n\ntype DynamicRoute<T extends string> = T extends `${string}:${string}`\n  ? T & {\n      build(params: PathParams<T>): RoutePath;\n      paramNames: Array<ExtractParams<T>>;\n    }\n  : T;\n\ntype ResolvedRoutes<T extends RouteInput> = {\n  [K in keyof T]: T[K] extends RouteInput\n    ? ResolvedRoutes<T[K]>\n    : T[K] extends string\n    ? DynamicRoute<T[K]>\n    : never;\n};\n\nconst isRouteGroup = (value: unknown): value is RouteInput =>\n  typeof value === 'object' && value !== null;\n\nfunction wrapDynamicPath<T extends string>(template: T): DynamicRoute<T> {\n  const paramNames = extractParamNames(template);\n  const wrapped = new String(template) as unknown as DynamicRoute<T> & {\n    build: (params: PathParams<T>) => RoutePath;\n    paramNames: Array<ExtractParams<T>>;\n  };\n\n  wrapped.build = (params: PathParams<T>) => buildPath(template, params) as RoutePath;\n  wrapped.paramNames = paramNames as Array<ExtractParams<T>>;\n\n  return wrapped as unknown as DynamicRoute<T>;\n}\n\nfunction processRouteMap<T extends RouteInput>(routes: T): ResolvedRoutes<T> {\n  const result = {} as ResolvedRoutes<T>;\n\n  for (const key in routes) {\n    if (!Object.prototype.hasOwnProperty.call(routes, key)) continue;\n\n    const value = routes[key];\n\n    if (typeof value === 'string') {\n      result[key] = (isDynamic(value)\n        ? wrapDynamicPath(value)\n        : value) as ResolvedRoutes<T>[typeof key];\n    } else if (isRouteGroup(value)) {\n      result[key] = processRouteMap(value as RouteInput) as unknown as ResolvedRoutes<T>[typeof key];\n    }\n  }\n\n  return result;\n}\n\nexport function defineRoutes<T extends RouteInput>(routes: T): ResolvedRoutes<T> {\n  return processRouteMap(routes);\n}\n","/**\n * React integration hooks for route-forge.\n * These are thin wrappers — import only if you're using React Router.\n */\n\nimport { useParams, useNavigate, generatePath } from 'react-router-dom';\nimport type { RouteParam } from '../types';\n\n// ─── useRouteParams ──────────────────────────────────────────────────────────\n\n/**\n * A typed wrapper around React Router's `useParams`.\n *\n * Pass the route's path template as a const generic to get a properly typed\n * params object back — no casting needed.\n *\n * @example\n * ```tsx\n * // Route is defined as '/users/edit/:id'\n * const { id } = useRouteParams<'/users/edit/:id'>();\n * ```\n */\nexport function useRouteParams<\n  T extends string,\n  // Extracts ':id' → 'id', ':postId' → 'postId', etc.\n  K extends string = T extends `${string}:${infer P}/${infer R}`\n    ? P | (R extends `${string}:${infer Q}` ? Q : never)\n    : T extends `${string}:${infer P}`\n    ? P\n    : never,\n>(): Record<K, string> {\n  return useParams() as Record<K, string>;\n}\n\n// ─── useNavigateTo ──────────────────────────────────────────────────────────\n\ntype NavigateOptions = {\n  replace?: boolean;\n  state?: unknown;\n};\n\n/**\n * A typed `navigate` helper that accepts a resolved path (output of `.build()`)\n * or a plain static path, with optional navigation options.\n *\n * @example\n * ```tsx\n * const navigateTo = useNavigateTo();\n * navigateTo(PATHS.USERS.EDIT.build({ id: 42 }));\n * navigateTo(PATHS.HOME, { replace: true });\n * ```\n */\nexport function useNavigateTo() {\n  const navigate = useNavigate();\n\n  return (path: string, options?: NavigateOptions) => {\n    navigate(path, options);\n  };\n}\n\n// ─── useResolvedPath ─────────────────────────────────────────────────────────\n\n/**\n * Resolves a dynamic path template against params using React Router's\n * `generatePath`, with proper typing.\n *\n * Useful when you need the resolved path string without navigating.\n *\n * @example\n * ```tsx\n * const path = useResolvedPath('/users/:id', { id: 42 }); // → '/users/42'\n * ```\n */\nexport function useResolvedPath(\n  template: string,\n  params: Record<string, RouteParam>\n): string {\n  return generatePath(\n    template,\n    Object.fromEntries(Object.entries(params).map(([k, v]) => [k, String(v)]))\n  );\n}\n"],"mappings":"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","names":["PATH_PARAM_RE","ESCAPE_RE","escapeRegex","value","createTemplatePattern","template","buildPath","params","resolved","extractParamNames","path","name","replacement","match","isDynamic","isActivePath","currentPath","options","pattern","extractParamsFromPath","resolvedPath","paramNames","regex","index","joinPaths","segments","segment","build","getParamNames","isRouteGroup","value","wrapDynamicPath","template","paramNames","extractParamNames","wrapped","params","buildPath","processRouteMap","routes","result","key","isDynamic","defineRoutes","useParams","useNavigate","generatePath","useRouteParams","useNavigateTo","navigate","path","options","useResolvedPath","template","params","k","v"]}
+{"version":3,"sources":["../src/core/utils.ts","../src/core/defineRoutes.ts","../src/hooks/index.ts"],"sourcesContent":["import type { QueryParams, RouteParam, RouteParams, BuildPathOptions, FlatRoute } from \"../types\";\n\n/** Returns a fresh RegExp each call — avoids shared `lastIndex` state on /g patterns. */\nconst PATH_PARAM_RE = () => /:([^/]+)/g;\nconst ESCAPE_RE = () => /[.*+?^${}()|[\\]\\\\]/g;\n\nfunction escapeRegex(value: string): string {\n  return value.replace(ESCAPE_RE(), \"\\\\$&\");\n}\n\nfunction createTemplatePattern(template: string): string {\n  return escapeRegex(template).replace(PATH_PARAM_RE(), \"([^/]+)\");\n}\n\nexport function appendQuery(path: string, query?: QueryParams): string {\n  if (!query) return path;\n\n  const searchParams = new URLSearchParams();\n  for (const [key, value] of Object.entries(query)) {\n    if (value === undefined || value === null) continue;\n    if (Array.isArray(value)) {\n      value.forEach((v) => {\n        if (v !== undefined && v !== null) searchParams.append(key, String(v));\n      });\n    } else {\n      searchParams.append(key, String(value));\n    }\n  }\n\n  const queryString = searchParams.toString();\n  if (!queryString) return path;\n\n  return path + (path.includes(\"?\") ? \"&\" : \"?\") + queryString;\n}\n\nexport function buildPath(\n  template: string,\n  params: RouteParams,\n  query?: QueryParams,\n  options?: BuildPathOptions,\n): string {\n  const paramNames = extractParamNames(template);\n  const unresolved = paramNames.filter(\n    (name) => params[name] === undefined || params[name] === null,\n  );\n\n  const resolved = paramNames.reduce((path, name) => {\n    const value = params[name];\n    const replacement = value === undefined || value === null ? `:${name}` : String(value);\n    return path.replace(\n      new RegExp(`:${escapeRegex(name)}(?=/|$)`, \"g\"),\n      replacement,\n    );\n  }, template);\n\n  if (unresolved.length > 0) {\n    if (options?.strict) {\n      throw new RangeError(\n        `[route-forge] Missing required param(s) ${unresolved.map((p) => `\":${p}\"`).join(\", \")} in template \"${template}\".`,\n      );\n    }\n\n    const runtimeProcess = (\n      globalThis as typeof globalThis & {\n        process?: {\n          env?: Record<string, string | undefined>;\n        };\n      }\n    ).process;\n\n    if (runtimeProcess?.env?.NODE_ENV !== \"production\") {\n      console.warn(\n        `[route-forge] Unresolved params in path \"${resolved}\". ` +\n          `Check that all :param segments have matching keys.`,\n      );\n    }\n  }\n\n  return appendQuery(resolved, query);\n}\n\nexport function extractParamNames(template: string): string[] {\n  return [...template.matchAll(PATH_PARAM_RE())].map(\n    (match) => match[1] as string,\n  );\n}\n\nexport function isDynamic(path: string): boolean {\n  return PATH_PARAM_RE().test(path);\n}\n\nexport function isActivePath(\n  currentPath: string,\n  template: string,\n  options: { exact?: boolean } = { exact: true },\n): boolean {\n  const pathWithoutSearch = currentPath.split(\"?\")[0] ?? \"\";\n  const pattern = createTemplatePattern(template);\n  const regex = options.exact\n    ? new RegExp(`^${pattern}$`)\n    : new RegExp(`^${pattern}`);\n\n  return regex.test(pathWithoutSearch);\n}\n\nexport function extractParamsFromPath(\n  template: string,\n  resolvedPath: string,\n): Record<string, string> {\n  const pathWithoutSearch = resolvedPath.split(\"?\")[0] ?? \"\";\n  const paramNames = extractParamNames(template);\n  const regex = new RegExp(`^${createTemplatePattern(template)}$`);\n  const match = pathWithoutSearch.match(regex);\n\n  if (!match) return {};\n\n  return Object.fromEntries(\n    paramNames.map((name, index) => [name, match[index + 1] ?? \"\"]),\n  );\n}\n\nexport function joinPaths(...segments: string[]): string {\n  return (\n    \"/\" +\n    segments\n      .map((segment) => segment.replace(/^\\/+|\\/+$/g, \"\"))\n      .filter(Boolean)\n      .join(\"/\")\n  );\n}\n\nexport function build(\n  template: string,\n  params: RouteParams,\n  query?: QueryParams,\n  options?: BuildPathOptions,\n): string {\n  return buildPath(template, params, query, options);\n}\n\nexport function getParamNames(template: string): string[] {\n  return extractParamNames(template);\n}\n\n/**\n * Walk a `defineRoutes` output tree and return a flat array of\n * `{ key, path }` entries where `key` is the dot-joined key path from\n * the root (e.g. `\"SERVICES.BCC.EDIT\"`) and `path` is the raw template\n * string (e.g. `\"/services/bcc/edit/:id\"`).\n *\n * Useful for:\n * - Generating sitemaps from a single source of truth.\n * - Detecting duplicate path strings across branches at startup:\n *\n * @example\n * const flat = flattenRoutes(PATHS);\n * const paths = flat.map((r) => r.path);\n * const dupes = paths.filter((p, i) => paths.indexOf(p) !== i);\n * if (dupes.length) console.warn('Duplicate paths:', dupes);\n */\nexport function flattenRoutes(\n  routes: Record<string, unknown>,\n  prefix = \"\",\n): FlatRoute[] {\n  const entries: FlatRoute[] = [];\n\n  for (const key of Object.keys(routes)) {\n    const fullKey = prefix ? `${prefix}.${key}` : key;\n    const value = routes[key];\n\n    if (typeof value === \"string\") {\n      // Plain static string leaf.\n      entries.push({ key: fullKey, path: value });\n    } else if (value instanceof String) {\n      // String-object leaf (wrapped dynamic path from defineRoutes).\n      entries.push({ key: fullKey, path: value.valueOf() });\n    } else if (typeof value === \"object\" && value !== null) {\n      // Nested route group — recurse.\n      entries.push(\n        ...flattenRoutes(value as Record<string, unknown>, fullKey),\n      );\n    }\n    // Anything else (functions, numbers, …) is silently skipped.\n  }\n\n  return entries;\n}\n\n","import { buildPath, extractParamNames, isDynamic } from \"./utils\";\nimport type {\n  BuildPathOptions,\n  ExtractParams,\n  PathParams,\n  QueryParams,\n  RoutePath,\n} from \"../types\";\n\n// Re-export so consumers that import from 'core/defineRoutes' get the full surface\nexport { buildPath, extractParamNames, isDynamic } from \"./utils\";\n\ntype RouteInput = {\n  [key: string]: string | RouteInput;\n};\n\ntype DynamicRoute<T extends string> = T extends `${string}:${string}`\n  ? T & {\n      build(params: PathParams<T>, query?: QueryParams, options?: BuildPathOptions): RoutePath;\n      paramNames: Array<ExtractParams<T>>;\n    }\n  : T;\n\ntype ResolvedRoutes<T extends RouteInput> = {\n  [K in keyof T]: T[K] extends RouteInput\n    ? ResolvedRoutes<T[K]>\n    : T[K] extends string\n      ? DynamicRoute<T[K]>\n      : never;\n};\n\nconst isRouteGroup = (value: unknown): value is RouteInput =>\n  typeof value === \"object\" && value !== null;\n\nfunction wrapDynamicPath<T extends string>(template: T): DynamicRoute<T> {\n  const paramNames = extractParamNames(template);\n  const wrapped = new String(template) as unknown as DynamicRoute<T> & {\n    build: (params: PathParams<T>, query?: QueryParams, options?: BuildPathOptions) => RoutePath;\n    paramNames: Array<ExtractParams<T>>;\n  };\n\n  wrapped.build = (params: PathParams<T>, query?: QueryParams, options?: BuildPathOptions) =>\n    buildPath(template, params, query, options) as RoutePath;\n  wrapped.paramNames = paramNames as Array<ExtractParams<T>>;\n\n  return wrapped as unknown as DynamicRoute<T>;\n}\n\nfunction processRouteMap<T extends RouteInput>(routes: T): ResolvedRoutes<T> {\n  const result = {} as ResolvedRoutes<T>;\n\n  for (const key in routes) {\n    if (!Object.prototype.hasOwnProperty.call(routes, key)) continue;\n\n    const value = routes[key];\n\n    if (typeof value === \"string\") {\n      result[key] = (\n        isDynamic(value) ? wrapDynamicPath(value) : value\n      ) as ResolvedRoutes<T>[typeof key];\n    } else if (isRouteGroup(value)) {\n      result[key] = processRouteMap(\n        value as RouteInput,\n      ) as unknown as ResolvedRoutes<T>[typeof key];\n    }\n  }\n\n  return result;\n}\n\nexport function defineRoutes<T extends RouteInput>(\n  routes: T,\n): ResolvedRoutes<T> {\n  return processRouteMap(routes);\n}\n","/**\n * React integration hooks for route-forge.\n * These are thin wrappers — import only if you're using React Router.\n */\n\nimport { useParams, useNavigate, generatePath } from \"react-router-dom\";\nimport type {\n  ExtractParams,\n  QueryParams,\n  RouteParams,\n  BuildPathOptions,\n} from \"../types\";\nimport { appendQuery, extractParamNames, buildPath } from \"../core/utils\";\n\n// ─── useRouteParams ──────────────────────────────────────────────────────────\n\n/**\n * A typed wrapper around React Router's `useParams`.\n *\n * @example\n * ```tsx\n * // Route: '/a/:x/b/:y/c/:z'\n * const { x, y, z } = useRouteParams<'/a/:x/b/:y/c/:z'>();\n * ```\n */\nexport function useRouteParams<T extends string>(): Record<\n  ExtractParams<T>,\n  string\n> {\n  return useParams() as Record<ExtractParams<T>, string>;\n}\n\n// ─── useNavigateTo ──────────────────────────────────────────────────────────\n\ntype NavigateOptions = {\n  replace?: boolean;\n  state?: unknown;\n};\n\n/**\n * A typed `navigate` helper that accepts a resolved path (output of `.build()`)\n * or a plain static path, with optional navigation options.\n *\n * @example\n * ```tsx\n * const navigateTo = useNavigateTo();\n * navigateTo(PATHS.USERS.EDIT.build({ id: 42 }));\n * navigateTo(PATHS.HOME, { replace: true });\n * ```\n */\nexport function useNavigateTo() {\n  const navigate = useNavigate();\n\n  return (path: string, options?: NavigateOptions) => {\n    navigate(path, options);\n  };\n}\n\n// ─── useResolvedPath ─────────────────────────────────────────────────────────\n\n/**\n * Resolves a dynamic path template against params using React Router's\n * `generatePath`, with proper typing.\n *\n * Accepts the same `options` bag as `build()` / `buildPath()`:\n * - (default) soft-fail: `console.warn` and return the partial path with unresolved `:param` placeholders.\n * - `{ strict: true }`: throw a `RangeError` on missing params — matching `.build()`'s strict behaviour.\n *\n * When all params are present, resolution is delegated to React Router's `generatePath`,\n * which correctly handles splat (`*`) and optional (`:param?`) segments.\n *\n * @example\n * ```tsx\n * const path = useResolvedPath('/users/:id', { id: 42 }); // → '/users/42'\n * const path = useResolvedPath('/users/:id', {}, undefined, { strict: true }); // throws RangeError\n * ```\n */\nexport function useResolvedPath(\n  template: string,\n  params: RouteParams,\n  query?: QueryParams,\n  options?: BuildPathOptions,\n): string {\n  const paramNames = extractParamNames(template);\n  const hasAllParams = paramNames.every(\n    (name) => params[name] !== undefined && params[name] !== null,\n  );\n\n  if (!hasAllParams) {\n    // Let buildPath own all missing-param behaviour (warn/throw) —\n    // avoids re-implementing (and duplicating) the same check here.\n    return buildPath(template, params, query, options);\n  }\n\n  // All params present — use generatePath for correct splat / optional-segment handling.\n  const path = generatePath(\n    template,\n    Object.fromEntries(Object.entries(params).map(([k, v]) => [k, String(v)])),\n  );\n\n  return appendQuery(path, query);\n}\n"],"mappings":"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","names":["PATH_PARAM_RE","ESCAPE_RE","escapeRegex","value","createTemplatePattern","template","appendQuery","path","query","searchParams","key","v","queryString","buildPath","params","options","paramNames","extractParamNames","unresolved","name","resolved","replacement","p","match","isDynamic","isActivePath","currentPath","pathWithoutSearch","pattern","extractParamsFromPath","resolvedPath","regex","index","joinPaths","segments","segment","build","getParamNames","flattenRoutes","routes","prefix","entries","fullKey","isRouteGroup","value","wrapDynamicPath","template","paramNames","extractParamNames","wrapped","params","query","options","buildPath","processRouteMap","routes","result","key","isDynamic","defineRoutes","useParams","useNavigate","generatePath","useRouteParams","useParams","useNavigateTo","navigate","useNavigate","path","options","useResolvedPath","template","params","query","extractParamNames","name","buildPath","generatePath","k","v","appendQuery"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-routes-forge",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "Type-safe route definitions with automatic path builders for React apps",
   "type": "module",
   "author": {
@@ -62,14 +62,19 @@
     }
   },
   "devDependencies": {
-    "react-router-dom": "^6.0.0",
     "@commitlint/cli": "^21.0.2",
     "@commitlint/config-conventional": "^21.0.2",
-    "@types/node": "^26.1.1",
+    "@testing-library/react": "^16.3.2",
     "@types/bun": "^1.3.14",
+    "@types/jsdom": "^28.0.3",
+    "@types/node": "^26.1.1",
+    "@types/react": "^19.2.17",
     "husky": "^9.0.0",
+    "jsdom": "^29.1.1",
+    "react-router-dom": "^6.0.0",
     "standard-version": "^9.5.0",
     "tsup": "^8.0.0",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "vitest": "^4.1.10"
   }
 }