react-routes-forge 1.2.0 → 1.3.0

package/dist/index-Beg7xp8k.d.ts

@@ -0,0 +1,148 @@
+/**
+ * A static route string (template or resolved), e.g. '/users/:id' or '/users/42'
+ */
+type RoutePath = `/${string}`;
+/**
+ * A route builder function that accepts params and returns a resolved path.
+ */
+type RouteBuilder<TParams extends RouteParams = RouteParams> = (params: TParams) => RoutePath;
+/**
+ * Acceptable param value types for route builders.
+ */
+type RouteParam = string | number | boolean;
+type RouteParams = Record<string, RouteParam>;
+/**
+ * A leaf node in a route definition: either a static path or a builder function.
+ */
+type RouteLeaf = RoutePath | RouteBuilder;
+/**
+ * Recursively defines a route map: each key is either a leaf or a nested map.
+ */
+type RouteMap = {
+    [key: string]: RouteLeaf | RouteMap;
+};
+/**
+ * Annotatable shape of a route map for `defineRoutes()`.
+ * Each key is either a static path string or a nested route tree.
+ */
+type RouteTree = {
+    [key: string]: string | RouteTree;
+};
+/**
+ * Matches a single ASCII word character (`[A-Za-z0-9_]`), mirroring the
+ * runtime param regex used by the path utilities.
+ */
+type IsWordChar<C extends string> = C extends "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z" | "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z" | "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "_" ? true : false;
+/**
+ * The leading run of word characters in a string, e.g. `"name.json"` → `"name"`
+ * and `"id?"` → `"id"`.
+ */
+type WordRun<S extends string> = S extends `${infer C}${infer Rest}` ? IsWordChar<C> extends true ? `${C}${WordRun<Rest>}` : "" : "";
+/**
+ * `WordRun` of a segment, mapped to `never` when empty so it never pollutes a
+ * param union. For non-literal input (e.g. a `DynamicRoute` value whose object
+ * members widen the captured segment to `string`) it falls back to `string`,
+ * keeping param access valid without attempting literal extraction.
+ */
+type ExtractWord<S extends string> = string extends S ? string : WordRun<S> extends "" ? never : WordRun<S>;
+/**
+ * Extracts param names from a path template string.
+ * e.g. '/users/:id/posts/:postId' → 'id' | 'postId'
+ */
+type ExtractParams<T extends string> = T extends `${string}:${infer Segment}/${infer Rest}` ? ExtractWord<Segment> | ExtractParams<`/${Rest}`> : T extends `${string}:${infer Segment}` ? ExtractWord<Segment> : T extends `${infer Prefix}/*` ? "*" | ExtractParams<Prefix> : never;
+/**
+ * Builds a params object type from a path template.
+ * e.g. '/users/:id' → { id: RouteParam }
+ */
+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;
+    /**
+     * When `false`, param values are substituted verbatim instead of being
+     * URL-encoded. Defaults to `true` — param values are run through
+     * `encodeURIComponent` so characters like `/`, `?`, `#` cannot break the
+     * URL structure.
+     */
+    encode?: boolean;
+    /**
+     * URL hash fragment to append after the query string (e.g. `"section"` → `#section`).
+     * The leading `#` is added automatically.
+     */
+    hash?: string;
+};
+/**
+ * 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;
+};
+/**
+ * A single breadcrumb entry produced by `getBreadcrumbs()`.
+ *
+ * @see {@link getBreadcrumbs}
+ */
+type BreadcrumbItem = {
+    /** Dot-joined key from the route tree, e.g. `"USERS.EDIT"`. */
+    key: string;
+    /** Human-readable label derived from the key (or from `labelResolver`). */
+    label: string;
+    /** The resolved path (params filled in), e.g. `"/users/edit/42"`. */
+    path: string;
+    /** `true` if this is the current page (exact match). */
+    isCurrent: boolean;
+};
+/**
+ * Options for `getBreadcrumbs()`.
+ *
+ * @see {@link getBreadcrumbs}
+ */
+type BreadcrumbOptions = {
+    /**
+     * Static label map keyed by the dot-joined key (e.g. `"USERS.EDIT"`).
+     * Takes precedence over `labelResolver`.
+     */
+    labels?: Record<string, string>;
+    /**
+     * Custom label resolver. Receives the dot-joined key
+     * (e.g. `"USERS.BCC.EDIT"`) and returns the display label.
+     *
+     * @default
+     * The default implementation takes the last key segment,
+     * replaces underscores with spaces, and capitalises the
+     * first letter (e.g. `"PRODUCT_DETAILS"` → `"Product Details"`).
+     */
+    labelResolver?: (key: string) => string;
+};
+/**
+ * Options for `matchPath()`.
+ */
+type MatchPathOptions = {
+    /** When true, match requires an exact end of path string (default: true). */
+    end?: boolean;
+    /** When true, perform case-sensitive matching (default: false). */
+    caseSensitive?: boolean;
+};
+
+export type { BuildPathOptions as B, ExtractParams as E, FlatRoute as F, MatchPathOptions as M, PathParams as P, QueryParams as Q, RouteParams as R, BreadcrumbOptions as a, BreadcrumbItem as b, RoutePath as c, RouteTree as d, RouteBuilder as e, RouteLeaf as f, RouteMap as g, RouteParam as h };

package/dist/index.cjs

@@ -0,0 +1,2 @@
+"use strict";var w=Object.defineProperty;var M=Object.getOwnPropertyDescriptor;var W=Object.getOwnPropertyNames;var K=Object.prototype.hasOwnProperty;var L=(e,t)=>{for(var n in t)w(e,n,{get:t[n],enumerable:!0})},U=(e,t,n,r)=>{if(t&&typeof t=="object"||typeof t=="function")for(let s of W(t))!K.call(e,s)&&s!==n&&w(e,s,{get:()=>t[s],enumerable:!(r=M(t,s))||r.enumerable});return e};var q=e=>U(w({},"__esModule",{value:!0}),e);var re={};L(re,{appendQuery:()=>S,build:()=>Q,buildPath:()=>d,clearPathCache:()=>E,defineRoutes:()=>_,devWarn:()=>h,extractParamNames:()=>m,extractParamsFromPath:()=>T,extractQueryFromPath:()=>N,flattenRoutes:()=>y,getBreadcrumbs:()=>j,getParamNames:()=>D,isActivePath:()=>$,isDynamic:()=>f,joinPaths:()=>C,matchPath:()=>b});module.exports=q(re);var H=()=>/[.*+?^${}()|[\]\\]/g,O=()=>/(^|\/):([A-Za-z0-9_]+)(\?)?/g;function z(){return globalThis.process?.env?.NODE_ENV==="production"}function h(e){z()||console.warn(e)}function E(){k.clear(),v.clear()}function R(e){return e.replace(H(),"\\$&")}function A(e){let t=e.endsWith("/*"),n=t?e.slice(0,-2):e,r="",s=0;for(let o of n.matchAll(O())){let c=o.index??0,i=o[0];r+=R(n.slice(s,c));let[,a="",,u]=o;r+=u?`(?:${R(a)}([^/]+))?`:`${R(a)}([^/]+)`,s=c+(i?.length??0)}return r+R(n.slice(s))+(t?"(?:/(.*))?":"")}function Z(e,t){return new RegExp(`:${R(t)}\\?(?![A-Za-z0-9_])`).test(e)}var k=new Map,G=/^/;function B(e){if(e==="/")return G;let t=k.get(e);if(t!==void 0)return t;let n=new RegExp(`^${A(e)}(?=/|$)`);return k.set(e,n),n}function X(e){try{return decodeURIComponent(e)}catch{return e}}function S(e,t,n){let r=e.indexOf("#"),s=r===-1?e:e.slice(0,r),o=r===-1?"":e.slice(r+1),c=new URLSearchParams;if(t)for(let[u,l]of Object.entries(t))l!=null&&(Array.isArray(l)?l.forEach(g=>{g!=null&&c.append(u,String(g))}):c.append(u,String(l)));let i=s,a=c.toString();return a&&(i+=(i.includes("?")?"&":"?")+a),n?i+="#"+n:o&&(i+="#"+o),i}function N(e,t){let n=e.indexOf("#"),r=n===-1?e:e.slice(0,n),s=r.indexOf("?");if(s===-1)return{};let o=new URLSearchParams(r.slice(s+1)),c={};for(let i of new Set(o.keys())){let u=o.getAll(i).map(l=>t?.coerceBooleans&&(l==="true"||l==="false")?l==="true":t?.coerceNumbers&&l.trim()!==""&&!isNaN(Number(l))?Number(l):l);c[i]=u.length>1?u:u[0]??""}return c}function d(e,t,n,r){let s=m(e),o=s.filter(i=>(t[i]===void 0||t[i]===null)&&!Z(e,i)&&i!=="*"),c=s.reduce((i,a)=>{let u=t[a],l=u==null;if(a==="*"){if(l)return i.replace(/\/\*$/,"")||"/";let P=r?.encode===!1?String(u):String(u).split("/").map(p=>encodeURIComponent(p)).join("/");return i.replace(/\/\*$/,`/${P}`)}let g=new RegExp(`(^|/):${R(a)}\\??(?![A-Za-z0-9_])`,"g");return i.replace(g,(P,p)=>{if(l)return P.endsWith("?")?"":`${p}:${a}`;let x=r?.encode===!1?String(u):encodeURIComponent(String(u));return`${p}${x}`})},e);if(o.length>0){if(r?.strict)throw new RangeError(`[route-forge] Missing required param(s) ${o.map(i=>`":${i}"`).join(", ")} in template "${e}".`);h(`[route-forge] Unresolved params in path "${c}". Check that all :param segments have matching keys.`)}return S(c,n,r?.hash)}function m(e){let t=[...e.matchAll(O())].map(n=>n[2]);return e.endsWith("/*")&&t.push("*"),t}function f(e){return O().test(e)||e.endsWith("/*")}function $(e,t,n={exact:!0,caseSensitive:!1}){let r=(e.split("?")[0]??"").replace(/\/+$/,"")||"/",s=t.replace(/\/+$/,"")||"/",o=n.caseSensitive?s:s.toLowerCase(),c=n.caseSensitive?r:r.toLowerCase();return(n.exact?b(o):B(o)).test(c)}function T(e,t){let n=t.split("?")[0]??"",r=m(e),s=n.match(b(e));if(!s)return{};let o={};return r.forEach((c,i)=>{let a=s[i+1];a!==void 0&&(o[c]=X(a))}),o}function C(...e){return"/"+e.map(r=>r.replace(/^\/+/,"").replace(/\/+$/,"")).filter(Boolean).join("/")}function Q(e,t,n,r){return d(e,t,n,r)}function D(e){return m(e)}var v=new Map;function b(e,t){let n=t?.end??!0,r=t?.caseSensitive?"":"i",s=`${e}:${n}:${r}`,o=v.get(s);if(o!==void 0)return o;let c=A(e),i=n?`^${c}$`:`^${c}(?=/|$)`,a=new RegExp(i,r);return v.set(s,a),a}function y(e,t=""){let n=[];for(let r of Object.keys(e)){let s=t?`${t}.${r}`:r,o=e[r];typeof o=="string"?n.push({key:s,path:o}):o instanceof String?n.push({key:s,path:o.valueOf()}):typeof o=="object"&&o!==null&&n.push(...y(o,s))}return n}function V(e){let t=e.split("."),n=t[t.length-1]??e;return(n==="ROOT"&&t.length>1?t[t.length-2]:n).replace(/_/g," ").toLowerCase().replace(/^\w/,s=>s.toUpperCase())}function j(e,t,n){let r=Array.isArray(e)?e:y(e),s=t.split("?")[0]??"",o=n?.labelResolver??V,c=n?.labels??{},i=[];for(let a of r){let u=b(a.path),l=s.match(u);if(l){let p=T(a.path,l[0]),x=f(a.path)?d(a.path,p):a.path;i.push({key:a.key,resolvedPath:x,template:a.path,isCurrent:!0});continue}let g=B(a.path),P=s.match(g);if(P){let p=P[0],x=T(a.path,p),I=f(a.path)?d(a.path,x):a.path;i.push({key:a.key,resolvedPath:I,template:a.path,isCurrent:!1})}}return i.sort((a,u)=>a.template.length-u.template.length),i.map(a=>({key:a.key,label:c[a.key]??o(a.key),path:a.resolvedPath,isCurrent:a.isCurrent}))}var J=e=>typeof e=="object"&&e!==null&&!Array.isArray(e)&&Object.getPrototypeOf(e)===Object.prototype;function Y(e,t){e.startsWith("/")||h(`[route-forge] Route "${t}" does not start with "/": "${e}".`),e.includes("*")&&!e.endsWith("/*")&&h(`[route-forge] Route "${t}" uses "*" outside a trailing "/*" splat; only a trailing splat is supported: "${e}".`)}function ee(e){let t=new Map,n=new Set,r=y(e);for(let s of r){let o=t.get(s.path);o===void 0?t.set(s.path,s.key):n.has(s.path)||(n.add(s.path),h(`[route-forge] Duplicate route path "${s.path}" for "${o}" and "${s.key}". Only one of them will be reachable.`))}for(let s=0;s<r.length;s++){let o=r[s];if(f(o.path))for(let c=s+1;c<r.length;c++){let i=r[c];if(!f(i.path)&&$(i.path,o.path,{exact:!0})){let a=`${o.key}->${i.key}`;n.has(a)||(n.add(a),h(`[route-forge] Route "${i.key}" ("${i.path}") is shadowed by dynamic route "${o.key}" ("${o.path}"). Place static routes before dynamic parameters in route trees.`))}}}}function te(e){let t=new String(e);return t.build=(n,r)=>d(e,{},n,r),t}function ne(e){let t=m(e),n=new String(e);return n.build=(r,s,o)=>d(e,r,s,o),n.paramNames=t,n}function F(e){let t={};for(let n in e){if(!Object.prototype.hasOwnProperty.call(e,n))continue;let r=e[n];typeof r=="string"?(Y(r,n),t[n]=f(r)?ne(r):te(r)):J(r)&&(t[n]=F(r))}return t}function _(e){let t=F(e);return ee(t),t}0&&(module.exports={appendQuery,build,buildPath,clearPathCache,defineRoutes,devWarn,extractParamNames,extractParamsFromPath,extractQueryFromPath,flattenRoutes,getBreadcrumbs,getParamNames,isActivePath,isDynamic,joinPaths,matchPath});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/core/utils.ts","../src/core/defineRoutes.ts"],"sourcesContent":["// Core\nexport { defineRoutes } from \"./core/defineRoutes\";\nexport { appendQuery, buildPath, extractParamNames, extractQueryFromPath, isDynamic } from \"./core/utils\";\n\n// Types\nexport type {\n  RoutePath,\n  RouteBuilder,\n  RouteParam,\n  RouteParams,\n  QueryParams,\n  RouteLeaf,\n  RouteMap,\n  RouteTree,\n  ExtractParams,\n  PathParams,\n  BuildPathOptions,\n  FlatRoute,\n  BreadcrumbItem,\n  BreadcrumbOptions,\n  MatchPathOptions,\n} from \"./types\";\nexport type { StaticRoute, DynamicRoute } from \"./core/defineRoutes\";\n\n// Utilities\nexport {\n  isActivePath,\n  extractParamsFromPath,\n  matchPath,\n  joinPaths,\n  build,\n  getParamNames,\n  flattenRoutes,\n  getBreadcrumbs,\n  devWarn,\n  clearPathCache,\n} from \"./core/utils\";\n","import type {\n  BreadcrumbItem,\n  BreadcrumbOptions,\n  BuildPathOptions,\n  FlatRoute,\n  QueryParams,\n  RouteParams,\n} from \"../types\";\n\n/** Returns a fresh RegExp each call — avoids shared `lastIndex` state on /g patterns. */\nconst ESCAPE_RE = () => /[.*+?^${}()|[\\]\\\\]/g;\n\n/**\n * Matches a `:param` token that starts a URL segment.\n *\n * A param is only recognized when its `:` sits at the very start of the\n * template or is immediately preceded by `/`, so a literal colon inside a\n * segment (e.g. `/users/foo:bar`) is not treated as a param. Param names are\n * restricted to `[A-Za-z0-9_]` (matching React Router), so any static suffix\n * (e.g. `.json` in `/files/:name.json`) stays a literal. The optional `?`\n * marker (`:param?`) is captured separately so it can be handled as a\n * whole-segment modifier.\n */\nconst PARAM_SEGMENT_RE = () => /(^|\\/):([A-Za-z0-9_]+)(\\?)?/g;\n\n/** Returns `true` when running in a production bundle (suppresses dev warnings). */\nfunction isProduction(): boolean {\n  const runtimeProcess = (\n    globalThis as typeof globalThis & {\n      process?: { env?: Record<string, string | undefined> };\n    }\n  ).process;\n  return runtimeProcess?.env?.NODE_ENV === \"production\";\n}\n\n/**\n * Emits a `console.warn` in non-production environments.\n * Shared by the core utilities and `defineRoutes()` so the production check\n * lives in one place.\n */\nexport function devWarn(message: string): void {\n  if (!isProduction()) {\n    console.warn(message);\n  }\n}\n\n/**\n * Clears internal regex cache maps (PREFIX_CACHE and PATH_CACHE).\n * Useful in test suites to prevent cached patterns from leaking across test cases.\n */\nexport function clearPathCache(): void {\n  PREFIX_CACHE.clear();\n  PATH_CACHE.clear();\n}\n\nfunction escapeRegex(value: string): string {\n  return value.replace(ESCAPE_RE(), \"\\\\$&\");\n}\n\n/**\n * Convert a route template into an unanchored `RegExp` source string.\n *\n * - Required `:name` segments become a capturing group `([^/]+)`.\n * - Optional `:name?` segments become `(?:([^/]+))?` — the whole segment is\n *   optional, matching React Router semantics.\n * - A trailing splat (`/*`) becomes `(?:/(.*))?`, capturing the remainder of\n *   the path (including slashes) or nothing at all.\n * - Everything else is regex-escaped literally.\n */\nfunction createTemplatePattern(template: string): string {\n  const splat = template.endsWith(\"/*\");\n  const base = splat ? template.slice(0, -2) : template;\n  let pattern = \"\";\n  let cursor = 0;\n\n  for (const match of base.matchAll(PARAM_SEGMENT_RE())) {\n    const start = match.index ?? 0;\n    const token = match[0];\n\n    pattern += escapeRegex(base.slice(cursor, start));\n\n    const [, boundary = \"\", , optional] = match;\n    pattern += optional\n      ? `(?:${escapeRegex(boundary)}([^/]+))?`\n      : `${escapeRegex(boundary)}([^/]+)`;\n\n    cursor = start + (token?.length ?? 0);\n  }\n\n  return pattern + escapeRegex(base.slice(cursor)) + (splat ? \"(?:/(.*))?\" : \"\");\n}\n\n/** Returns `true` when `name` is an optional (`:name?`) param in `template`. */\nfunction isOptionalParam(template: string, name: string): boolean {\n  return new RegExp(`:${escapeRegex(name)}\\\\?(?![A-Za-z0-9_])`).test(template);\n}\n\n/**\n * Returns a `RegExp` that matches `template` as a path prefix, honoring\n * segment boundaries (`/users` matches `/users/42` but not `/usersettings`).\n *\n * The root template `/` is a prefix of every path.\n *\n * Compiled patterns are cached per template: the resulting `RegExp` has no\n * `/g` flag, so repeated `.test()`/`.exec()` calls are side-effect free and\n * sharing instances across callers is safe.\n */\nconst PREFIX_CACHE = new Map<string, RegExp>();\nconst ROOT_PREFIX_RE = /^/;\n\nfunction matchPrefix(template: string): RegExp {\n  if (template === \"/\") return ROOT_PREFIX_RE;\n  const cached = PREFIX_CACHE.get(template);\n  if (cached !== undefined) return cached;\n  const re = new RegExp(`^${createTemplatePattern(template)}(?=/|$)`);\n  PREFIX_CACHE.set(template, re);\n  return re;\n}\n\n/** Decode a URL-encoded param value, falling back to the raw value on error. */\nfunction safeDecode(value: string): string {\n  try {\n    return decodeURIComponent(value);\n  } catch {\n    return value;\n  }\n}\n\n/**\n * Append a query string and/or hash fragment to a path that may already\n * contain a query or hash.\n *\n * - Existing query pairs are preserved; new ones are joined with `&`.\n * - The query string is always inserted before any hash fragment, so an\n *   existing `#section` on `path` is kept unless a new `hash` is given.\n *\n * @example\n * ```ts\n * appendQuery(\"/users?tab=list\", { page: 2 }); // → \"/users?tab=list&page=2\"\n * appendQuery(\"/users#top\", { tab: \"list\" });  // → \"/users?tab=list#top\"\n * ```\n */\nexport function appendQuery(path: string, query?: QueryParams, hash?: string): string {\n  const hashIdx = path.indexOf(\"#\");\n  const base = hashIdx === -1 ? path : path.slice(0, hashIdx);\n  const existingHash = hashIdx === -1 ? \"\" : path.slice(hashIdx + 1);\n\n  const searchParams = new URLSearchParams();\n  if (query) {\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\n  let result = base;\n  const queryString = searchParams.toString();\n  if (queryString) {\n    result += (result.includes(\"?\") ? \"&\" : \"?\") + queryString;\n  }\n\n  if (hash) {\n    result += \"#\" + hash;\n  } else if (existingHash) {\n    result += \"#\" + existingHash;\n  }\n\n  return result;\n}\n\n/**\n * Parse the query string out of a path (or bare query string) into a plain\n * object. Repeated keys become arrays; a single key is a scalar string.\n *\n * With `{ coerceBooleans: true }`, the strings `\"true\"`/`\"false\"` are\n * converted to actual booleans.\n *\n * @example\n * ```ts\n * extractQueryFromPath(\"/users/42?tab=profile&tag=a&tag=b\");\n * // → { tab: \"profile\", tag: [\"a\", \"b\"] }\n * extractQueryFromPath(\"/search?active=true\", { coerceBooleans: true });\n * // → { active: true }\n * ```\n */\nexport function extractQueryFromPath(\n  path: string,\n  options?: { coerceBooleans?: boolean; coerceNumbers?: boolean },\n): QueryParams {\n  const hashIdx = path.indexOf(\"#\");\n  const noHash = hashIdx === -1 ? path : path.slice(0, hashIdx);\n  const queryIdx = noHash.indexOf(\"?\");\n  if (queryIdx === -1) return {};\n\n  const params = new URLSearchParams(noHash.slice(queryIdx + 1));\n  const result: QueryParams = {};\n\n  for (const key of new Set(params.keys())) {\n    const values = params.getAll(key);\n    const parsed = values.map((v) => {\n      if (options?.coerceBooleans && (v === \"true\" || v === \"false\")) {\n        return v === \"true\";\n      }\n      if (options?.coerceNumbers && v.trim() !== \"\" && !isNaN(Number(v))) {\n        return Number(v);\n      }\n      return v;\n    });\n    result[key] = parsed.length > 1 ? parsed : (parsed[0] ?? \"\");\n  }\n\n  return result;\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) =>\n      (params[name] === undefined || params[name] === null) &&\n      !isOptionalParam(template, name) &&\n      // A missing splat simply drops the `/*` suffix (matching React Router,\n      // where `/files/*` also matches `/files`).\n      name !== \"*\",\n  );\n\n  const resolved = paramNames.reduce((path, name) => {\n    const value = params[name];\n    const missing = value === undefined || value === null;\n\n    if (name === \"*\") {\n      if (missing) return path.replace(/\\/\\*$/, \"\") || \"/\";\n      // Splat values are path-like: preserve `/` separators but still\n      // encode characters that could break the URL (`?`, `#`, spaces, …).\n      const encoded =\n        options?.encode === false\n          ? String(value)\n          : String(value)\n              .split(\"/\")\n              .map((segment) => encodeURIComponent(segment))\n              .join(\"/\");\n      return path.replace(/\\/\\*$/, `/${encoded}`);\n    }\n\n    const re = new RegExp(\n      `(^|/):${escapeRegex(name)}\\\\??(?![A-Za-z0-9_])`,\n      \"g\",\n    );\n\n    return path.replace(re, (match, boundary) => {\n      if (missing) {\n        // Optional segment: drop the whole `/segment`. Required: keep the\n        // `:name` placeholder so strict mode can report it.\n        return match.endsWith(\"?\") ? \"\" : `${boundary}:${name}`;\n      }\n\n      const encoded =\n        options?.encode === false\n          ? String(value)\n          : encodeURIComponent(String(value));\n      return `${boundary}${encoded}`;\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    devWarn(\n      `[route-forge] Unresolved params in path \"${resolved}\". ` +\n        `Check that all :param segments have matching keys.`,\n    );\n  }\n\n  return appendQuery(resolved, query, options?.hash);\n}\n\nexport function extractParamNames(template: string): string[] {\n  const names = [...template.matchAll(PARAM_SEGMENT_RE())].map(\n    (match) => match[2] as string,\n  );\n  if (template.endsWith(\"/*\")) names.push(\"*\");\n  return names;\n}\n\nexport function isDynamic(path: string): boolean {\n  return PARAM_SEGMENT_RE().test(path) || path.endsWith(\"/*\");\n}\n\n/**\n * Test whether `currentPath` matches `template`, mirroring React Router's\n * `NavLink` matching semantics:\n *\n * - Case-insensitive by default (pass `caseSensitive: true` to opt out).\n * - Trailing slashes are tolerated (`/users/` matches `/users`).\n * - `exact: true` (the default) requires a full match; `exact: false`\n *   matches any path that starts with the template.\n */\nexport function isActivePath(\n  currentPath: string,\n  template: string,\n  options: { exact?: boolean; caseSensitive?: boolean } = {\n    exact: true,\n    caseSensitive: false,\n  },\n): boolean {\n  const pathname = (currentPath.split(\"?\")[0] ?? \"\").replace(/\\/+$/, \"\") || \"/\";\n  const normalizedTemplate = template.replace(/\\/+$/, \"\") || \"/\";\n  const target = options.caseSensitive\n    ? normalizedTemplate\n    : normalizedTemplate.toLowerCase();\n  const candidate = options.caseSensitive ? pathname : pathname.toLowerCase();\n  const regex = options.exact ? matchPath(target) : matchPrefix(target);\n\n  return regex.test(candidate);\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 match = pathWithoutSearch.match(matchPath(template));\n\n  if (!match) return {};\n\n  const result: Record<string, string> = {};\n  paramNames.forEach((name, index) => {\n    const raw = match[index + 1];\n    if (raw !== undefined) result[name] = safeDecode(raw);\n  });\n  return result;\n}\n\nexport function joinPaths(...segments: string[]): string {\n  const processed = segments.map((segment) =>\n    segment.replace(/^\\/+/, \"\").replace(/\\/+$/, \"\"),\n  );\n  const filtered = processed.filter(Boolean);\n  return \"/\" + filtered.join(\"/\");\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 * Convert a route template string into an anchored `RegExp` for matching paths.\n *\n * Each `:param` segment becomes a capturing group so the returned regex\n * can be used with `.test()` or `.exec()`.\n *\n * Query strings are **not** stripped — callers should split on `\"?\"` first\n * (see {@link isActivePath} or {@link extractParamsFromPath} for higher-level\n * helpers that handle this automatically).\n *\n * @param template - A route template, e.g. `\"/users/:id\"` or `\"/users/:id/posts/:postId\"`.\n * @returns A `RegExp` anchored with `^` and `$` that captures param values.\n *\n * @example\n * ```ts\n * const re = matchPath(\"/users/:id\");\n * re.test(\"/users/42\");          // true\n * re.exec(\"/users/42\");          // [\"/users/42\", \"42\"]\n * re.test(\"/users/42/posts\");    // false (exact match)\n * re.test(\"/users/42?page=1\");   // true (query is part of captured value)\n * ```\n *\n * Compiled patterns are cached per template (the regex has no `/g` flag, so\n * sharing instances across callers is safe).\n */\nconst PATH_CACHE = new Map<string, RegExp>();\n\nexport function matchPath(\n  template: string,\n  options?: { end?: boolean; caseSensitive?: boolean },\n): RegExp {\n  const end = options?.end ?? true;\n  const flags = options?.caseSensitive ? \"\" : \"i\";\n  const cacheKey = `${template}:${end}:${flags}`;\n\n  const cached = PATH_CACHE.get(cacheKey);\n  if (cached !== undefined) return cached;\n\n  const basePattern = createTemplatePattern(template);\n  const pattern = end ? `^${basePattern}$` : `^${basePattern}(?=/|$)`;\n  const re = new RegExp(pattern, flags);\n  PATH_CACHE.set(cacheKey, re);\n  return re;\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\nfunction deriveBreadcrumbLabel(key: string): string {\n  const parts = key.split(\".\");\n  const last = parts[parts.length - 1] ?? key;\n  // Use the parent segment when the leaf is the conventional \"ROOT\" key,\n  // so USERS.ROOT → \"Users\" rather than \"Root\".\n  const raw = last === \"ROOT\" && parts.length > 1 ? parts[parts.length - 2]! : last;\n  return raw\n    .replace(/_/g, \" \")\n    .toLowerCase()\n    .replace(/^\\w/, (c) => c.toUpperCase());\n}\n\n/**\n * Build a breadcrumb trail from a route tree or a flat route list.\n *\n * For a given `currentPath`, it walks the route tree and returns every route\n * that is an ancestor of (or an exact match to) the current page.  Ancestors\n * are matched by prefix (e.g. `/users` matches `/users/edit/42/posts`).\n *\n * Dynamic params in ancestor paths are automatically resolved from the\n * matched portion of the URL.\n *\n * @param routes - A route tree (output of `defineRoutes`) or a pre-flattened\n *                 array from `flattenRoutes()`.\n * @param currentPath - The current URL (with or without query string).\n * @param options - Optional label resolver.\n * @returns An array of {@link BreadcrumbItem} ordered by depth\n *          (most general first), where the last item is the current page.\n *\n * @example\n * ```ts\n * const PATHS = defineRoutes({\n *   HOME: \"/\",\n *   USERS: { ROOT: \"/users\", EDIT: \"/users/edit/:id\" },\n * } as const);\n *\n * getBreadcrumbs(PATHS, \"/users/edit/42\");\n * // → [\n * //     { key: \"HOME\",       label: \"Home\",  path: \"/\",             isCurrent: false },\n * //     { key: \"USERS.ROOT\", label: \"Users\", path: \"/users\",        isCurrent: false },\n * //     { key: \"USERS.EDIT\", label: \"Edit\",  path: \"/users/edit/42\", isCurrent: true  },\n * //   ]\n * ```\n */\nexport function getBreadcrumbs(\n  routes: Record<string, unknown> | FlatRoute[],\n  currentPath: string,\n  options?: BreadcrumbOptions,\n): BreadcrumbItem[] {\n  const flat = Array.isArray(routes)\n    ? routes\n    : flattenRoutes(routes);\n  const pathname = currentPath.split(\"?\")[0] ?? \"\";\n  const labelFn = options?.labelResolver ?? deriveBreadcrumbLabel;\n  const labels = options?.labels ?? {};\n\n  const items: Array<{\n    key: string;\n    resolvedPath: string;\n    template: string;\n    isCurrent: boolean;\n  }> = [];\n\n  for (const route of flat) {\n    const exactRe = matchPath(route.path);\n    const exactMatch = pathname.match(exactRe);\n\n    if (exactMatch) {\n      const params = extractParamsFromPath(route.path, exactMatch[0]);\n      const resolved = isDynamic(route.path)\n        ? buildPath(route.path, params)\n        : route.path;\n      items.push({\n        key: route.key,\n        resolvedPath: resolved,\n        template: route.path,\n        isCurrent: true,\n      });\n      continue;\n    }\n\n    const prefixRe = matchPrefix(route.path);\n    const prefixMatch = pathname.match(prefixRe);\n\n    if (prefixMatch) {\n      const matchedPortion = prefixMatch[0];\n      const params = extractParamsFromPath(route.path, matchedPortion);\n      const resolved = isDynamic(route.path)\n        ? buildPath(route.path, params)\n        : route.path;\n      items.push({\n        key: route.key,\n        resolvedPath: resolved,\n        template: route.path,\n        isCurrent: false,\n      });\n    }\n  }\n\n  items.sort((a, b) => a.template.length - b.template.length);\n\n  return items.map((item) => ({\n    key: item.key,\n    label: labels[item.key] ?? labelFn(item.key),\n    path: item.resolvedPath,\n    isCurrent: item.isCurrent,\n  }));\n}\n\n","import {\n  buildPath,\n  devWarn,\n  extractParamNames,\n  flattenRoutes,\n  isActivePath,\n  isDynamic,\n} from \"./utils\";\nimport type {\n  BuildPathOptions,\n  ExtractParams,\n  PathParams,\n  QueryParams,\n  RoutePath,\n  RouteTree,\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\n/**\n * A dynamic route is a template string with a `:param` or trailing `/*` splat,\n * augmented with a `.build()` helper and a `.paramNames` array.\n *\n * Exported so consumers (e.g. the hooks entry) can type against it.\n */\nexport type StaticRoute<T extends string> = T & {\n  build(query?: QueryParams, options?: BuildPathOptions): RoutePath;\n};\n\nexport type DynamicRoute<T extends string> =\n  T extends `${string}:${string}` | `${string}/*`\n    ? T & {\n        build(params: PathParams<T>, query?: QueryParams, options?: BuildPathOptions): RoutePath;\n        paramNames: Array<ExtractParams<T>>;\n      }\n    : StaticRoute<T>;\n\ntype ResolvedRoutes<T extends RouteTree> = {\n  [K in keyof T]: T[K] extends RouteTree\n    ? ResolvedRoutes<T[K]>\n    : T[K] extends string\n      ? DynamicRoute<T[K]>\n      : never;\n};\n\nconst isRouteGroup = (value: unknown): value is RouteTree =>\n  typeof value === \"object\" &&\n  value !== null &&\n  !Array.isArray(value) &&\n  Object.getPrototypeOf(value) === Object.prototype;\n\n/**\n * Validate a single route template and warn (dev-only) about common mistakes:\n * missing leading `/` and non-trailing `*` splats.\n */\nfunction validateTemplate(template: string, key: string): void {\n  if (!template.startsWith(\"/\")) {\n    devWarn(\n      `[route-forge] Route \"${key}\" does not start with \"/\": \"${template}\".`,\n    );\n  }\n\n  if (template.includes(\"*\") && !template.endsWith(\"/*\")) {\n    devWarn(\n      `[route-forge] Route \"${key}\" uses \"*\" outside a trailing \"/*\" splat; only a trailing splat is supported: \"${template}\".`,\n    );\n  }\n}\n\n/**\n * Warn (dev-only) when two routes resolve to the same path template or shadow each other.\n */\nfunction detectDuplicatePaths(routes: Record<string, unknown>): void {\n  const seen = new Map<string, string>();\n  const warned = new Set<string>();\n  const flat = flattenRoutes(routes);\n\n  for (const route of flat) {\n    const existing = seen.get(route.path);\n    if (existing === undefined) {\n      seen.set(route.path, route.key);\n    } else if (!warned.has(route.path)) {\n      warned.add(route.path);\n      devWarn(\n        `[route-forge] Duplicate route path \"${route.path}\" for \"${existing}\" and \"${route.key}\". ` +\n          `Only one of them will be reachable.`,\n      );\n    }\n  }\n\n  // Shadowing check: warn when a static path matches a dynamic path defined before it\n  for (let i = 0; i < flat.length; i++) {\n    const r1 = flat[i]!;\n    if (!isDynamic(r1.path)) continue;\n\n    for (let j = i + 1; j < flat.length; j++) {\n      const r2 = flat[j]!;\n      if (isDynamic(r2.path)) continue;\n\n      if (isActivePath(r2.path, r1.path, { exact: true })) {\n        const pairKey = `${r1.key}->${r2.key}`;\n        if (!warned.has(pairKey)) {\n          warned.add(pairKey);\n          devWarn(\n            `[route-forge] Route \"${r2.key}\" (\"${r2.path}\") is shadowed by dynamic route \"${r1.key}\" (\"${r1.path}\"). Place static routes before dynamic parameters in route trees.`,\n          );\n        }\n      }\n    }\n  }\n}\n\nfunction wrapStaticPath<T extends string>(template: T): StaticRoute<T> {\n  const wrapped = new String(template) as unknown as StaticRoute<T> & {\n    build: (query?: QueryParams, options?: BuildPathOptions) => RoutePath;\n  };\n  wrapped.build = (query?: QueryParams, options?: BuildPathOptions) =>\n    buildPath(template, {}, query, options) as RoutePath;\n\n  return wrapped as unknown as StaticRoute<T>;\n}\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 RouteTree>(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      validateTemplate(value, key);\n      result[key] = (\n        isDynamic(value) ? wrapDynamicPath(value) : wrapStaticPath(value)\n      ) as ResolvedRoutes<T>[typeof key];\n    } else if (isRouteGroup(value)) {\n      result[key] = processRouteMap(\n        value as RouteTree,\n      ) as unknown as ResolvedRoutes<T>[typeof key];\n    }\n  }\n\n  return result;\n}\n\nexport function defineRoutes<T extends RouteTree>(\n  routes: T,\n): ResolvedRoutes<T> {\n  const result = processRouteMap(routes);\n  detectDuplicatePaths(result as unknown as Record<string, unknown>);\n  return result;\n}\n"],"mappings":"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","names":["index_exports","__export","appendQuery","build","buildPath","clearPathCache","defineRoutes","devWarn","extractParamNames","extractParamsFromPath","extractQueryFromPath","flattenRoutes","getBreadcrumbs","getParamNames","isActivePath","isDynamic","joinPaths","matchPath","__toCommonJS","ESCAPE_RE","PARAM_SEGMENT_RE","isProduction","devWarn","message","clearPathCache","PREFIX_CACHE","PATH_CACHE","escapeRegex","value","createTemplatePattern","template","splat","base","pattern","cursor","match","start","token","boundary","optional","isOptionalParam","name","ROOT_PREFIX_RE","matchPrefix","cached","re","safeDecode","appendQuery","path","query","hash","hashIdx","existingHash","searchParams","key","v","result","queryString","extractQueryFromPath","options","noHash","queryIdx","params","parsed","buildPath","paramNames","extractParamNames","unresolved","resolved","missing","encoded","segment","p","names","isDynamic","isActivePath","currentPath","pathname","normalizedTemplate","target","candidate","matchPath","extractParamsFromPath","resolvedPath","pathWithoutSearch","index","raw","joinPaths","segments","build","getParamNames","end","flags","cacheKey","basePattern","flattenRoutes","routes","prefix","entries","fullKey","deriveBreadcrumbLabel","parts","last","c","getBreadcrumbs","flat","labelFn","labels","items","route","exactRe","exactMatch","prefixRe","prefixMatch","matchedPortion","b","item","isRouteGroup","value","validateTemplate","template","key","devWarn","detectDuplicatePaths","routes","seen","warned","flat","flattenRoutes","route","existing","i","r1","isDynamic","j","r2","isActivePath","pairKey","wrapStaticPath","wrapped","query","options","buildPath","wrapDynamicPath","paramNames","extractParamNames","params","processRouteMap","result","defineRoutes"]}

package/dist/index.d.cts

@@ -0,0 +1,142 @@
+import { Q as QueryParams, R as RouteParams, B as BuildPathOptions, F as FlatRoute, a as BreadcrumbOptions, b as BreadcrumbItem, P as PathParams, c as RoutePath, E as ExtractParams, d as RouteTree } from './index-Beg7xp8k.cjs';
+export { M as MatchPathOptions, e as RouteBuilder, f as RouteLeaf, g as RouteMap, h as RouteParam } from './index-Beg7xp8k.cjs';
+
+/**
+ * Emits a `console.warn` in non-production environments.
+ * Shared by the core utilities and `defineRoutes()` so the production check
+ * lives in one place.
+ */
+declare function devWarn(message: string): void;
+/**
+ * Clears internal regex cache maps (PREFIX_CACHE and PATH_CACHE).
+ * Useful in test suites to prevent cached patterns from leaking across test cases.
+ */
+declare function clearPathCache(): void;
+/**
+ * Append a query string and/or hash fragment to a path that may already
+ * contain a query or hash.
+ *
+ * - Existing query pairs are preserved; new ones are joined with `&`.
+ * - The query string is always inserted before any hash fragment, so an
+ *   existing `#section` on `path` is kept unless a new `hash` is given.
+ *
+ * @example
+ * ```ts
+ * appendQuery("/users?tab=list", { page: 2 }); // → "/users?tab=list&page=2"
+ * appendQuery("/users#top", { tab: "list" });  // → "/users?tab=list#top"
+ * ```
+ */
+declare function appendQuery(path: string, query?: QueryParams, hash?: string): string;
+/**
+ * Parse the query string out of a path (or bare query string) into a plain
+ * object. Repeated keys become arrays; a single key is a scalar string.
+ *
+ * With `{ coerceBooleans: true }`, the strings `"true"`/`"false"` are
+ * converted to actual booleans.
+ *
+ * @example
+ * ```ts
+ * extractQueryFromPath("/users/42?tab=profile&tag=a&tag=b");
+ * // → { tab: "profile", tag: ["a", "b"] }
+ * extractQueryFromPath("/search?active=true", { coerceBooleans: true });
+ * // → { active: true }
+ * ```
+ */
+declare function extractQueryFromPath(path: string, options?: {
+    coerceBooleans?: boolean;
+    coerceNumbers?: boolean;
+}): QueryParams;
+declare function buildPath(template: string, params: RouteParams, query?: QueryParams, options?: BuildPathOptions): string;
+declare function extractParamNames(template: string): string[];
+declare function isDynamic(path: string): boolean;
+/**
+ * Test whether `currentPath` matches `template`, mirroring React Router's
+ * `NavLink` matching semantics:
+ *
+ * - Case-insensitive by default (pass `caseSensitive: true` to opt out).
+ * - Trailing slashes are tolerated (`/users/` matches `/users`).
+ * - `exact: true` (the default) requires a full match; `exact: false`
+ *   matches any path that starts with the template.
+ */
+declare function isActivePath(currentPath: string, template: string, options?: {
+    exact?: boolean;
+    caseSensitive?: boolean;
+}): boolean;
+declare function extractParamsFromPath(template: string, resolvedPath: string): Record<string, string>;
+declare function joinPaths(...segments: string[]): string;
+declare function build(template: string, params: RouteParams, query?: QueryParams, options?: BuildPathOptions): string;
+declare function getParamNames(template: string): string[];
+declare function matchPath(template: string, options?: {
+    end?: boolean;
+    caseSensitive?: boolean;
+}): RegExp;
+/**
+ * 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[];
+/**
+ * Build a breadcrumb trail from a route tree or a flat route list.
+ *
+ * For a given `currentPath`, it walks the route tree and returns every route
+ * that is an ancestor of (or an exact match to) the current page.  Ancestors
+ * are matched by prefix (e.g. `/users` matches `/users/edit/42/posts`).
+ *
+ * Dynamic params in ancestor paths are automatically resolved from the
+ * matched portion of the URL.
+ *
+ * @param routes - A route tree (output of `defineRoutes`) or a pre-flattened
+ *                 array from `flattenRoutes()`.
+ * @param currentPath - The current URL (with or without query string).
+ * @param options - Optional label resolver.
+ * @returns An array of {@link BreadcrumbItem} ordered by depth
+ *          (most general first), where the last item is the current page.
+ *
+ * @example
+ * ```ts
+ * const PATHS = defineRoutes({
+ *   HOME: "/",
+ *   USERS: { ROOT: "/users", EDIT: "/users/edit/:id" },
+ * } as const);
+ *
+ * getBreadcrumbs(PATHS, "/users/edit/42");
+ * // → [
+ * //     { key: "HOME",       label: "Home",  path: "/",             isCurrent: false },
+ * //     { key: "USERS.ROOT", label: "Users", path: "/users",        isCurrent: false },
+ * //     { key: "USERS.EDIT", label: "Edit",  path: "/users/edit/42", isCurrent: true  },
+ * //   ]
+ * ```
+ */
+declare function getBreadcrumbs(routes: Record<string, unknown> | FlatRoute[], currentPath: string, options?: BreadcrumbOptions): BreadcrumbItem[];
+
+/**
+ * A dynamic route is a template string with a `:param` or trailing `/*` splat,
+ * augmented with a `.build()` helper and a `.paramNames` array.
+ *
+ * Exported so consumers (e.g. the hooks entry) can type against it.
+ */
+type StaticRoute<T extends string> = T & {
+    build(query?: QueryParams, options?: BuildPathOptions): RoutePath;
+};
+type DynamicRoute<T extends string> = T extends `${string}:${string}` | `${string}/*` ? T & {
+    build(params: PathParams<T>, query?: QueryParams, options?: BuildPathOptions): RoutePath;
+    paramNames: Array<ExtractParams<T>>;
+} : StaticRoute<T>;
+type ResolvedRoutes<T extends RouteTree> = {
+    [K in keyof T]: T[K] extends RouteTree ? ResolvedRoutes<T[K]> : T[K] extends string ? DynamicRoute<T[K]> : never;
+};
+declare function defineRoutes<T extends RouteTree>(routes: T): ResolvedRoutes<T>;
+
+export { BreadcrumbItem, BreadcrumbOptions, BuildPathOptions, type DynamicRoute, ExtractParams, FlatRoute, PathParams, QueryParams, RouteParams, RoutePath, RouteTree, type StaticRoute, appendQuery, build, buildPath, clearPathCache, defineRoutes, devWarn, extractParamNames, extractParamsFromPath, extractQueryFromPath, flattenRoutes, getBreadcrumbs, getParamNames, isActivePath, isDynamic, joinPaths, matchPath };