feat: add children route names generic to generated RouteNamedMap and adjust docs and tests

docs/.vitepress/twoslash-files.ts

@@ -6,27 +6,44 @@ declare module 'vue-router/auto-routes' {
     ParamValueOneOrMore,
     ParamValueZeroOrMore,
     ParamValueZeroOrOne,
+    RouteMeta,
   } from 'vue-router'
 
+  /**
+   * Route name map generated by unplugin-vue-router
+   */
   export interface RouteNamedMap {
-    '/': RouteRecordInfo<'/', '/', Record<never, never>, Record<never, never>>
+    '/': RouteRecordInfo<
+      '/',
+      '/',
+      Record<never, never>,
+      Record<never, never>,
+      RouteMeta,
+      never
+    >
     '/users': RouteRecordInfo<
       '/users',
       '/users',
       Record<never, never>,
-      Record<never, never>
+      Record<never, never>,
+      RouteMeta,
+      never
     >
     '/users/[id]': RouteRecordInfo<
       '/users/[id]',
       '/users/:id',
       { id: ParamValue<true> },
-      { id: ParamValue<false> }
+      { id: ParamValue<false> },
+      RouteMeta,
+      '/users/[id]/edit'
     >
     '/users/[id]/edit': RouteRecordInfo<
       '/users/[id]/edit',
       '/users/:id/edit',
       { id: ParamValue<true> },
-      { id: ParamValue<false> }
+      { id: ParamValue<false> },
+      RouteMeta,
+      never
     >
   }
 }

docs/.vitepress/twoslash/code/typed-router.ts

@@ -5,27 +5,41 @@ declare module 'vue-router/auto-routes' {
     ParamValueOneOrMore,
     ParamValueZeroOrMore,
     ParamValueZeroOrOne,
+    RouteMeta,
   } from 'vue-router'
 
   export interface RouteNamedMap {
-    '/': RouteRecordInfo<'/', '/', Record<never, never>, Record<never, never>>
+    '/': RouteRecordInfo<
+      '/',
+      '/',
+      Record<never, never>,
+      Record<never, never>,
+      RouteMeta,
+      never
+    >
     '/users': RouteRecordInfo<
       '/users',
       '/users',
       Record<never, never>,
-      Record<never, never>
+      Record<never, never>,
+      RouteMeta,
+      never
     >
     '/users/[id]': RouteRecordInfo<
       '/users/[id]',
       '/users/:id',
       { id: ParamValue<true> },
-      { id: ParamValue<false> }
+      { id: ParamValue<false> },
+      RouteMeta,
+      '/users/[id]/edit'
     >
     '/users/[id]/edit': RouteRecordInfo<
       '/users/[id]/edit',
       '/users/:id/edit',
       { id: ParamValue<true> },
-      { id: ParamValue<false> }
+      { id: ParamValue<false> },
+      RouteMeta,
+      never
     >
   }
 }

docs/guide/typescript.md

@@ -50,6 +50,7 @@ import type {
   ParamValueOneOrMore,
   ParamValueZeroOrMore,
   ParamValueZeroOrOne,
+  RouteMeta,
 } from 'vue-router'
 declare module 'vue-router/auto-routes' {
   export interface RouteNamedMap {
@@ -60,7 +61,20 @@ declare module 'vue-router/auto-routes' {
       // these are the raw param types (accept numbers, strings, booleans, etc)
       { path: ParamValue<true> },
       // these are the normalized params as found in useRoute().params
-      { path: ParamValue<false> }
+      { path: ParamValue<false> },
+      // these are the `meta` fields
+      RouteMeta,
+      // this is a union of all children route names
+      // if the route does not have nested routes, pass `never` or omit this generic entirely
+      'custom-dynamic-child-name'
+    >
+    'custom-dynamic-child-name': RouteRecordInfo<
+      'custom-dynamic-child-name',
+      '/added-during-runtime/[...path]/child',
+      { path: ParamValue<true> },
+      { path: ParamValue<false> },
+      RouteMeta,
+      never
     >
   }
 }
@@ -76,13 +90,19 @@ import { useRoute, type RouteLocationNormalizedLoaded } from 'vue-router'
 // ---cut-end---
 // @errors: 2322 2339
 // @moduleResolution: bundler
-// these are all valid
-const userWithIdCasted = useRoute() as RouteLocationNormalizedLoaded<'/users/[id]'>
-userWithIdCasted.params.id
-const userWithIdTypeParam = useRoute<'/users/[id]'>()
-userWithIdTypeParam.params.id
-// 👇 this one is the easiest to write because it autocompletes
-const userWithIdParam = useRoute('/users/[id]')
-userWithIdParam.params
-//              ^?
+// These are all valid ways to get a typed route and return the
+// provided route's and any of its child routes' typings.
+// Note that `/users/[id]/edit` is a child route
+// of `/users/[id]` in this example.
+
+// Not recommended, since this leaves out any child routes' typings.
+const userRouteWithIdCasted = useRoute() as RouteLocationNormalizedLoaded<'/users/[id]'>
+userRouteWithIdCasted.params.id
+// Better way, but no autocompletion.
+const userRouteWithIdTypeParam = useRoute<'/users/[id]'>()
+userRouteWithIdTypeParam.params.id
+// 👇 This one is the easiest to write because it autocompletes.
+const userRouteWithIdParam = useRoute('/users/[id]')
+userRouteWithIdParam.name
+//                   ^?
 ```

docs/introduction.md

@@ -102,31 +102,43 @@ After adding this plugin, **start the dev server** (usually `npm run dev`) **to
 // It's recommended to commit this file.
 // Make sure to add this file to your tsconfig.json file as an "includes" or "files" entry.
 
-import type {
-  RouteRecordInfo,
-  ParamValue,
-  ParamValueOneOrMore,
-  ParamValueZeroOrMore,
-  ParamValueZeroOrOne,
-} from 'vue-router'
-
 declare module 'vue-router/auto-routes' {
+  import type {
+    RouteRecordInfo,
+    ParamValue,
+    ParamValueOneOrMore,
+    ParamValueZeroOrMore,
+    ParamValueZeroOrOne,
+    RouteMeta,
+  } from 'vue-router'
+
   /**
    * Route name map generated by unplugin-vue-router
    */
   export interface RouteNamedMap {
-    '/': RouteRecordInfo<'/', '/', Record<never, never>, Record<never, never>>
+    '/': RouteRecordInfo<
+      '/',
+      '/',
+      Record<never, never>,
+      Record<never, never>,
+      RouteMeta,
+      never
+    >
     '/about': RouteRecordInfo<
       '/about',
       '/about',
       Record<never, never>,
-      Record<never, never>
+      Record<never, never>,
+      RouteMeta,
+      never
     >
     '/users/[id]': RouteRecordInfo<
-      '/[id]',
-      '/:id',
+      '/users/[id]',
+      '/users/:id',
       { id: ParamValue<true> },
-      { id: ParamValue<false> }
+      { id: ParamValue<false> },
+      RouteMeta,
+      never
     >
   }
 }

package.json

@@ -111,6 +111,7 @@
     "vitest": "vitest --typecheck",
     "docs": "vitepress dev docs",
     "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs",
     "lint": "prettier -c '{src,test,e2e,examples,playground}/**/*.{ts,vue}'",
     "play": "npm -C playground run dev",
     "play:build": "npm -C playground run build",
@@ -198,5 +199,17 @@
     "vuefire": "^3.2.1",
     "webpack": "^5.97.1",
     "yorkie": "^2.0.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "@parcel/watcher",
+      "esbuild",
+      "protobufjs",
+      "vue-demi",
+      "yorkie"
+    ],
+    "patchedDependencies": {
+      "vue-router": "patches/vue-router.patch"
+    }
   }
 }

patches/vue-router.patch

@@ -0,0 +1,73 @@
+diff --git a/dist/vue-router.d.ts b/dist/vue-router.d.ts
+index 8f2c2e5a39d50cf517b4aa512d363f402ce2255a..0c9864363cae71d34327a78025629d34240e38e7 100644
+--- a/dist/vue-router.d.ts
++++ b/dist/vue-router.d.ts
+@@ -871,6 +871,22 @@ export declare type RouteMap = TypesConfig extends Record<'RouteNamedMap', infer
+  */
+ export declare type RouteMapGeneric = Record<string | symbol, RouteRecordInfo>;
+
++/**
++ * Returns a union of route names from children of the route with given route name
++ */
++export type GetDeepChildrenRouteNames<T extends keyof RouteMap> =
++  RouteMap[T] extends RouteRecordInfo<any, any, any, any, any, infer N>
++    ? N extends any
++      ? N | GetDeepChildrenRouteNames<N>
++      : never
++    : never
++
++/**
++ * Returns a union of given route name and the route names of children of that route
++ */
++export type RouteNameWithChildren<T extends keyof RouteMap> =
++  RouteMapGeneric extends RouteMap ? T : T | GetDeepChildrenRouteNames<T>
++
+ /**
+  * Interface to type `meta` fields in route records.
+  *
+@@ -1148,7 +1164,14 @@ export declare interface _RouteRecordBase extends PathParserOptions {
+  * Helper type to define a Typed `RouteRecord`
+  * @see {@link RouteRecord}
+  */
+-export declare interface RouteRecordInfo<Name extends string | symbol = string, Path extends string = string, ParamsRaw extends RouteParamsRawGeneric = RouteParamsRawGeneric, Params extends RouteParamsGeneric = RouteParamsGeneric, Meta extends RouteMeta = RouteMeta> {
++export declare interface RouteRecordInfo<
++    Name extends string | symbol = string,
++    Path extends string = string,
++    ParamsRaw extends RouteParamsRawGeneric = RouteParamsRawGeneric,
++    Params extends RouteParamsGeneric = RouteParamsGeneric,
++    Meta extends RouteMeta = RouteMeta,
++    _ChildrenRouteNames extends string | symbol = never,
++> {
+     name: Name;
+     path: Path;
+     paramsRaw: ParamsRaw;
+@@ -1740,11 +1763,14 @@ export declare interface UseLinkReturn<Name extends keyof RouteMap = keyof Route
+     navigate(e?: MouseEvent): Promise<void | NavigationFailure>;
+ }
+
+-/**
++type GetRouteLocationNormalizedLoaded<Name extends keyof RouteMap> =
++  Name extends any ? RouteLocationNormalizedLoaded<Name> : never;
++
++/**
+  * Returns the current route location. Equivalent to using `$route` inside
+  * templates.
+  */
+-export declare function useRoute<Name extends keyof RouteMap = keyof RouteMap>(_name?: Name): RouteLocationNormalizedLoaded<Name>;
++export declare function useRoute<CurrentRouteName extends keyof RouteMap = keyof RouteMap>(_currentRouteName?: CurrentRouteName): GetRouteLocationNormalizedLoaded<RouteNameWithChildren<CurrentRouteName>>;
+
+ /**
+  * Returns the router instance. Equivalent to using `$router` inside
+diff --git a/dist/vue-router.mjs b/dist/vue-router.mjs
+index 399f57cd8150fe8bb96686110b859d7745e5fc8d..b5fbc8ecf857a5b0ce9dda54c323e59785700766 100644
+--- a/dist/vue-router.mjs
++++ b/dist/vue-router.mjs
+@@ -3774,7 +3774,7 @@ function useRouter() {
+  * Returns the current route location. Equivalent to using `$route` inside
+  * templates.
+  */
+-function useRoute(_name) {
++function useRoute(_currentRouteName) {
+     return inject(routeLocationKey);
+ }
+

playground/src/router.ts

@@ -1,6 +1,6 @@
 import { createRouter, createWebHistory } from 'vue-router'
 import { routes, handleHotUpdate } from 'vue-router/auto-routes'
-import type { RouteRecordInfo, ParamValue } from 'vue-router'
+import type { RouteRecordInfo, ParamValue, RouteMeta } from 'vue-router'
 
 export const router = createRouter({
   history: createWebHistory(),
@@ -31,7 +31,17 @@ declare module 'vue-router/auto-routes' {
       'custom-dynamic-name',
       '/added-during-runtime/[...path]',
       { path: ParamValue<true> },
-      { path: ParamValue<false> }
+      { path: ParamValue<false> },
+      RouteMeta,
+      'custom-dynamic-child-name'
+    >
+    'custom-dynamic-child-name': RouteRecordInfo<
+      'custom-dynamic-child-name',
+      '/added-during-runtime/[...path]/child',
+      { path: ParamValue<true> },
+      { path: ParamValue<false> },
+      RouteMeta,
+      never
     >
   }
 }