perf: add support for attrs and compiling parsePath

danielroe · danielroe · commit 7533586b8145 · 2026-02-13T09:49:56.000Z
diff --git a/README.md b/README.md
@@ -371,6 +371,42 @@ interface ParsedPath {
 }
 ```
 
+### `compileParsePath(options?)`
+
+Pre-compile parsing options into a reusable function. Useful in hot paths (e.g., dev server file watchers) where `parsePath` would otherwise reconstruct the same regexes on every call.
+
+```ts
+function compileParsePath(options?: ParsePathOptions): CompiledParsePath
+
+interface CompiledParsePath {
+  (filePaths: string[]): ParsedPath[]
+}
+```
+
+Returns a callable with the same signature as `parsePath` (minus the options argument). The regexes for root stripping, extension matching, and mode detection are built once at compile time.
+
+```js
+import { addFile, buildTree, compileParsePath, toVueRouter4 } from 'unrouting'
+
+const opts = { roots: ['pages/'], modes: ['client', 'server'] }
+
+// Compile once at startup
+const parse = compileParsePath(opts)
+const tree = buildTree(initialFiles, opts)
+
+// In a file watcher callback &mdash; no regex re-compilation
+addFile(tree, 'pages/new-page.vue', parse)
+const routes = toVueRouter4(tree)
+```
+
+The compiled function can be passed directly to `addFile` as the options argument:
+
+```js
+// These are equivalent, but the compiled version avoids re-building regexes:
+addFile(tree, file, parse) // pre-compiled (fast)
+addFile(tree, file, opts) // raw options (re-compiles each call)
+```
+
 ### `parseSegment(segment, absolutePath?, warn?)`
 
 Parse a single filesystem segment into typed tokens. Useful for modules that need to parse custom paths (e.g., i18n locale-specific routes).
diff --git a/src/converters.ts b/src/converters.ts
@@ -17,6 +17,7 @@ export interface VueRoute {
   modes?: string[]
   children: VueRoute[]
   meta?: Record<string, unknown>
+  [key: string]: unknown
 }
 
 export interface VueRouterEmitOptions {
@@ -29,6 +30,27 @@ export interface VueRouterEmitOptions {
 
   /** Called when two routes resolve to the same generated name. */
   onDuplicateRouteName?: (name: string, file: string, existingFile: string) => void
+
+  /**
+   * Collapse mode arrays into single-value attributes.
+   *
+   * Each key becomes a top-level property on the route. Modes that match a
+   * value in the array are collapsed: when a route has exactly one matching
+   * mode, the attribute is set to that value string. When a route has multiple
+   * matching modes, the attribute is set to the array of matching modes.
+   * When none match, the attribute is omitted.
+   *
+   * @example
+   * // Input: route has modes: ['server']
+   * toVueRouter4(tree, { attrs: { mode: ['client', 'server'] } })
+   * // Output: { ..., mode: 'server' }  (no `modes` property)
+   *
+   * @example
+   * // Custom method-based routing
+   * toVueRouter4(tree, { attrs: { method: ['get', 'post'] } })
+   * // For a route with modes: ['get'] &rarr; { ..., method: 'get' }
+   */
+  attrs?: Record<string, string[]>
 }
 
 export interface Rou3Route {
@@ -95,10 +117,81 @@ function flattenTree(tree: RouteTree): FlatFileInfo[] {
 
 // --- Vue Router 4 ------------------------------------------------------------
 
+/**
+ * Cached intermediate result stored on the tree.
+ * @internal
+ */
+interface CachedVueRouterResult {
+  /** The computed routes (used as template for cloning). */
+  routes: VueRoute[]
+  /** The options fingerprint &mdash; if options change, cache is invalid. */
+  optionsKey: string
+}
+
+/** Deep-clone a VueRoute array. */
+function cloneRoutes(routes: VueRoute[]): VueRoute[] {
+  return routes.map(r => cloneRoute(r))
+}
+
+function cloneRoute(route: VueRoute): VueRoute {
+  const clone: VueRoute = {
+    path: route.path,
+    file: route.file,
+    children: route.children.length ? cloneRoutes(route.children) : [],
+  }
+  if (route.name !== undefined)
+    clone.name = route.name
+  if (route.modes)
+    clone.modes = [...route.modes]
+  if (route.meta) {
+    clone.meta = { ...route.meta }
+    if (route.meta.groups)
+      clone.meta.groups = [...(route.meta.groups as string[])]
+  }
+  if (route.components)
+    clone.components = { ...route.components }
+
+  // Clone any extra attrs (e.g. mode, method)
+  for (const key of Object.keys(route)) {
+    if (!(key in clone)) {
+      clone[key] = route[key]
+    }
+  }
+
+  return clone
+}
+
+function optionsToKey(options?: VueRouterEmitOptions): string {
+  if (!options)
+    return ''
+  const parts: string[] = []
+  if (options.getRouteName)
+    parts.push('n')
+  if (options.onDuplicateRouteName)
+    parts.push('d')
+  if (options.attrs) {
+    for (const [k, v] of Object.entries(options.attrs)) {
+      parts.push(`a:${k}=${v.join(',')}`)
+    }
+  }
+  return parts.join('|')
+}
+
 /**
  * Convert a route tree to Vue Router 4 route definitions.
+ *
+ * Results are cached on the tree and deep-cloned on return, so mutations
+ * to the returned array do not affect the cache. The cache is automatically
+ * invalidated when `addFile` / `removeFile` mark the tree as dirty.
  */
 export function toVueRouter4(tree: RouteTree, options?: VueRouterEmitOptions): VueRoute[] {
+  const key = optionsToKey(options)
+  const cached = (tree as any)['~cachedVueRouter'] as CachedVueRouterResult | undefined
+
+  if (!tree['~dirty'] && cached && cached.optionsKey === key) {
+    return cloneRoutes(cached.routes)
+  }
+
   const fileInfos = flattenTree(tree)
 
   fileInfos.sort((a, b) =>
@@ -157,7 +250,13 @@ export function toVueRouter4(tree: RouteTree, options?: VueRouterEmitOptions): V
     parent.push(route)
   }
 
-  return prepareRoutes(routes, undefined, options)
+  const result = prepareRoutes(routes, undefined, options)
+
+  // Cache on the tree
+  ;(tree as any)['~cachedVueRouter'] = { routes: result, optionsKey: key } satisfies CachedVueRouterResult
+  tree['~dirty'] = false
+
+  return cloneRoutes(result)
 }
 
 // --- rou3 --------------------------------------------------------------------
@@ -381,6 +480,7 @@ function prepareRoutes(
   names = new Map<string, string>(),
 ): VueRoute[] {
   const getRouteName = options?.getRouteName || defaultGetRouteName
+  const attrs = options?.attrs
 
   for (const route of routes) {
     route.scoreSegments = computeScoreSegments(route)
@@ -420,15 +520,35 @@ function prepareRoutes(
         out.components[v.viewName] = v.path
     }
 
-    // Modes
+    // Collect modes from all sibling files
     const allModes = new Set<string>()
     for (const f of route.siblingFiles) {
       if (f.modes) {
         for (const m of f.modes) allModes.add(m)
       }
     }
-    if (allModes.size > 0)
+
+    // Apply attrs: collapse modes into named attributes
+    if (attrs && allModes.size > 0) {
+      let modesConsumed = false
+      for (const [attrName, attrValues] of Object.entries(attrs)) {
+        const matched = attrValues.filter(v => allModes.has(v))
+        if (matched.length === 1) {
+          out[attrName] = matched[0]
+          modesConsumed = true
+        }
+        else if (matched.length > 1) {
+          out[attrName] = matched
+          modesConsumed = true
+        }
+      }
+      // Only emit `modes` if not fully consumed by attrs
+      if (!modesConsumed)
+        out.modes = [...allModes]
+    }
+    else if (allModes.size > 0) {
       out.modes = [...allModes]
+    }
 
     return out
   })
diff --git a/src/index.ts b/src/index.ts
@@ -1,8 +1,8 @@
 export type { RegExpRoute, Rou3Route, ToVueRouterSegmentOptions, VueRoute, VueRouterEmitOptions } from './converters'
 export { toRegExp, toRou3, toVueRouter4, toVueRouterPath, toVueRouterSegment } from './converters'
 
-export type { ParsedPath, ParsedPathSegment, ParsedPathSegmentToken, ParsePathOptions, SegmentType } from './parse'
-export { parsePath, parseSegment } from './parse'
+export type { CompiledParsePath, ParsedPath, ParsedPathSegment, ParsedPathSegmentToken, ParsePathOptions, SegmentType } from './parse'
+export { compileParsePath, parsePath, parseSegment } from './parse'
 
 export type { BuildTreeOptions, InputFile, RouteNode, RouteNodeFile, RouteTree } from './tree'
 export { addFile, buildTree, isPageNode, removeFile, walkTree } from './tree'
diff --git a/src/parse.ts b/src/parse.ts
@@ -43,18 +43,67 @@ export interface ParsedPath {
 
 const VIEW_MATCH_RE = /@([\w-]+)(?:\.|$)/
 const VIEW_STRIP_RE = /@[\w-]+/
+const DEFAULT_EXT_RE = /\.\w+$/
 
 export function parsePath(filePaths: string[], options: ParsePathOptions = {}): ParsedPath[] {
   const EXT_RE = options.extensions
     ? new RegExp(`\\.(${options.extensions.map(ext => ext.replace(/^\./, '').replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')})$`)
-    : /\.\w+$/
+    : DEFAULT_EXT_RE
 
   const sortedRoots = [...options.roots || []].sort((a, b) => b.length - a.length)
   const PREFIX_RE = sortedRoots.length > 0
     ? new RegExp(`^(?:${sortedRoots.map(root => escapeStringRegexp(withTrailingSlash(root))).join('|')})`)
     : undefined
 
   const supportedModes = options.modes || []
+
+  return parsePathInner(filePaths, EXT_RE, PREFIX_RE, supportedModes, options.warn)
+}
+
+/**
+ * Pre-compile parsing options for repeated calls.
+ *
+ * Returns a callable that has the same signature as `parsePath` (minus options)
+ * but reuses pre-built regexes and mode lists, avoiding re-compilation on each
+ * invocation.
+ *
+ * @example
+ * const parse = compileParsePath({ roots: ['pages/'], modes: ['client', 'server'] })
+ * const result = parse(['pages/index.vue'])
+ */
+export interface CompiledParsePath {
+  (filePaths: string[]): ParsedPath[]
+  /**
+   * @internal
+   */
+  '~compiled': true
+}
+
+export function compileParsePath(options: ParsePathOptions = {}): CompiledParsePath {
+  const EXT_RE = options.extensions
+    ? new RegExp(`\\.(${options.extensions.map(ext => ext.replace(/^\./, '').replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')})$`)
+    : DEFAULT_EXT_RE
+
+  const sortedRoots = [...options.roots || []].sort((a, b) => b.length - a.length)
+  const PREFIX_RE = sortedRoots.length > 0
+    ? new RegExp(`^(?:${sortedRoots.map(root => escapeStringRegexp(withTrailingSlash(root))).join('|')})`)
+    : undefined
+
+  const supportedModes = options.modes || []
+  const warn = options.warn
+
+  const fn = (filePaths: string[]) => parsePathInner(filePaths, EXT_RE, PREFIX_RE, supportedModes, warn)
+  ;(fn as CompiledParsePath)['~compiled'] = true
+  return fn as CompiledParsePath
+}
+
+function parsePathInner(
+  filePaths: string[],
+  EXT_RE: RegExp,
+  PREFIX_RE: RegExp | undefined,
+  supportedModes: string[],
+  warn?: (message: string) => void,
+): ParsedPath[] {
   const results: ParsedPath[] = []
 
   for (let filePath of filePaths) {
@@ -95,7 +144,7 @@ export function parsePath(filePaths: string[], options: ParsePathOptions = {}):
 
     results.push({
       file: originalFilePath,
-      segments: segments.map(s => parseSegment(s, originalFilePath, options.warn)),
+      segments: segments.map(s => parseSegment(s, originalFilePath, warn)),
       meta: hasMeta
         ? {
             ...(hasModes ? { modes } : undefined),
diff --git a/src/tree.ts b/src/tree.ts
diff --git a/test/unit/converters.spec.ts b/test/unit/converters.spec.ts
