feat: add inferred types for extracted attrs

danielroe · danielroe · commit aca0792a260b · 2026-02-13T10:37:08.000Z
diff --git a/src/converters.ts b/src/converters.ts
@@ -8,19 +8,34 @@ const collator = new Intl.Collator('en-US')
 
 // --- Types -------------------------------------------------------------------
 
-export interface VueRoute {
+/**
+ * Maps an `attrs` record to typed optional properties on the route.
+ *
+ * Each key becomes an optional property whose value is a single literal
+ * from the array. The attr is only set when exactly one mode matches.
+ *
+ * @example
+ * type R = InferAttrs<{ mode: ['client', 'server'] }>
+ * // { mode?: 'client' | 'server' }
+ */
+export type InferAttrs<T extends Record<string, string[]>> = {
+  [K in keyof T]?: T[K][number]
+}
+
+// eslint-disable-next-line ts/no-empty-object-type
+export type VueRoute<Attrs extends Record<string, string[]> = {}> = {
   name?: string
   path: string
   file?: string
   /** Named view files keyed by view name. Only present when named views exist. */
   components?: Record<string, string>
   modes?: string[]
-  children: VueRoute[]
+  children: VueRoute<Attrs>[]
   meta?: Record<string, unknown>
-  [key: string]: unknown
-}
+} & ([keyof Attrs] extends [never] ? { [key: string]: unknown } : InferAttrs<Attrs>)
 
-export interface VueRouterEmitOptions {
+// eslint-disable-next-line ts/no-empty-object-type
+export interface VueRouterEmitOptions<Attrs extends Record<string, string[]> = {}> {
   /**
    * Custom route name generator.
    * Receives `/`-separated name (e.g. `'users/id'`), returns final name.
@@ -32,13 +47,16 @@ export interface VueRouterEmitOptions {
   onDuplicateRouteName?: (name: string, file: string, existingFile: string) => void
 
   /**
-   * Collapse mode arrays into single-value attributes.
+   * Collapse modes into single-value attributes.
+   *
+   * Each key becomes a typed top-level property on the route. When a route has
+   * exactly one matching mode the attribute is set to that value string; when
+   * none or multiple modes match, the attribute is omitted and the raw `modes`
+   * array is emitted instead.
    *
-   * 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.
+   * The return type of `toVueRouter4` infers typed properties from the attrs
+   * definition so that, e.g., `attrs: { mode: ['client', 'server'] }` produces
+   * routes with `mode?: 'client' | 'server'`.
    *
    * @example
    * // Input: route has modes: ['server']
@@ -50,7 +68,7 @@ export interface VueRouterEmitOptions {
    * toVueRouter4(tree, { attrs: { method: ['get', 'post'] } })
    * // For a route with modes: ['get'] &rarr; { ..., method: 'get' }
    */
-  attrs?: Record<string, string[]>
+  attrs?: Attrs
 }
 
 export interface Rou3Route {
@@ -161,7 +179,7 @@ function cloneRoute(route: VueRoute): VueRoute {
   return clone
 }
 
-function optionsToKey(options?: VueRouterEmitOptions): string {
+function optionsToKey(options?: VueRouterEmitOptions<Record<string, string[]>>): string {
   if (!options)
     return ''
   const parts: string[] = []
@@ -184,12 +202,16 @@ function optionsToKey(options?: VueRouterEmitOptions): string {
  * 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)
+export function toVueRouter4<const Attrs extends Record<string, string[]> = never>(
+  tree: RouteTree,
+  // eslint-disable-next-line ts/no-empty-object-type
+  options?: VueRouterEmitOptions<[Attrs] extends [never] ? {} : Attrs>,
+): VueRoute<[Attrs] extends [never] ? {} : Attrs>[] { // eslint-disable-line ts/no-empty-object-type
+  const key = optionsToKey(options as VueRouterEmitOptions<Record<string, string[]>>)
   const cached = (tree as any)['~cachedVueRouter'] as CachedVueRouterResult | undefined
 
   if (!tree['~dirty'] && cached && cached.optionsKey === key) {
-    return cloneRoutes(cached.routes)
+    return cloneRoutes(cached.routes) as VueRoute<any>[]
   }
 
   const fileInfos = flattenTree(tree)
@@ -250,13 +272,13 @@ export function toVueRouter4(tree: RouteTree, options?: VueRouterEmitOptions): V
     parent.push(route)
   }
 
-  const result = prepareRoutes(routes, undefined, options)
+  const result = prepareRoutes(routes, undefined, options as VueRouterEmitOptions<Record<string, string[]>>)
 
   // Cache on the tree
   ;(tree as any)['~cachedVueRouter'] = { routes: result, optionsKey: key } satisfies CachedVueRouterResult
   tree['~dirty'] = false
 
-  return cloneRoutes(result)
+  return cloneRoutes(result) as VueRoute<any>[]
 }
 
 // --- rou3 --------------------------------------------------------------------
@@ -476,7 +498,7 @@ function defaultGetRouteName(rawName: string): string {
 function prepareRoutes(
   routes: IntermediateRoute[],
   parent?: IntermediateRoute,
-  options?: VueRouterEmitOptions,
+  options?: VueRouterEmitOptions<Record<string, string[]>>,
   names = new Map<string, string>(),
 ): VueRoute[] {
   const getRouteName = options?.getRouteName || defaultGetRouteName
@@ -537,10 +559,6 @@ function prepareRoutes(
           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)
diff --git a/src/index.ts b/src/index.ts
@@ -1,4 +1,4 @@
-export type { RegExpRoute, Rou3Route, ToVueRouterSegmentOptions, VueRoute, VueRouterEmitOptions } from './converters'
+export type { InferAttrs, RegExpRoute, Rou3Route, ToVueRouterSegmentOptions, VueRoute, VueRouterEmitOptions } from './converters'
 export { toRegExp, toRou3, toVueRouter4, toVueRouterPath, toVueRouterSegment } from './converters'
 
 export type { CompiledParsePath, ParsedPath, ParsedPathSegment, ParsedPathSegmentToken, ParsePathOptions, SegmentType } from './parse'
diff --git a/test/unit/converters.spec.ts b/test/unit/converters.spec.ts
@@ -1127,11 +1127,11 @@ describe('attrs option', () => {
     expect(routes[0].modes).toBeUndefined()
   })
 
-  it('collapses multiple modes into an array attr', () => {
+  it('omits attr and emits modes when multiple modes match', () => {
     const t = buildTree(['page.client.vue', 'page.server.vue'], { modes: ['client', 'server'] })
     const routes = toVueRouter4(t, { attrs: { mode: ['client', 'server'] } })
-    expect(routes[0].mode).toEqual(['client', 'server'])
-    expect(routes[0].modes).toBeUndefined()
+    expect(routes[0].mode).toBeUndefined()
+    expect(routes[0].modes).toEqual(['client', 'server'])
   })
 
   it('does not add attr when no modes match', () => {
@@ -1178,6 +1178,44 @@ describe('attrs option', () => {
     expect(second[0].mode).toBe('server')
     expect(first[0]).not.toBe(second[0])
   })
+
+  it('infers typed attrs from options', () => {
+    const t = buildTree(['page.server.vue'], { modes: ['client', 'server'] })
+    const routes = toVueRouter4(t, { attrs: { mode: ['client', 'server'] } })
+
+    // Type-level: mode is typed as 'client' | 'server' | undefined
+    const mode = routes[0].mode
+    expect(mode).toBe('server')
+
+    // Verify the type is narrow (not `unknown`)
+    if (typeof mode === 'string') {
+      // mode is 'client' | 'server' here
+      expect(['client', 'server']).toContain(mode)
+    }
+  })
+
+  it('infers typed attrs for multiple attr definitions', () => {
+    const t = buildTree(['page.client.vue'], { modes: ['client', 'server', 'get', 'post'] })
+    const routes = toVueRouter4(t, {
+      attrs: {
+        mode: ['client', 'server'],
+        method: ['get', 'post'],
+      },
+    })
+    // Both mode and method should be typed properties
+    const _mode: 'client' | 'server' | undefined = routes[0].mode
+    const _method: 'get' | 'post' | undefined = routes[0].method
+    expect(_mode).toBe('client')
+    expect(_method).toBeUndefined()
+  })
+
+  it('preserves index signature when no attrs option given', () => {
+    const t = buildTree(['page.vue'])
+    const routes = toVueRouter4(t)
+    // Without attrs, routes should still have index signature for backward compat
+    const _val: unknown = routes[0].anyProperty
+    expect(_val).toBeUndefined()
+  })
 })
 
 describe('compileParsePath', () => {

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-export type { RegExpRoute, Rou3Route, ToVueRouterSegmentOptions, VueRoute, VueRouterEmitOptions } from './converters'`
	`1`	`+export type { InferAttrs, RegExpRoute, Rou3Route, ToVueRouterSegmentOptions, VueRoute, VueRouterEmitOptions } from './converters'`
`2`	`2`	`export { toRegExp, toRou3, toVueRouter4, toVueRouterPath, toVueRouterSegment } from './converters'`
`3`	`3`
`4`	`4`	`export type { CompiledParsePath, ParsedPath, ParsedPathSegment, ParsedPathSegmentToken, ParsePathOptions, SegmentType } from './parse'`