feat(param-parsers): add include/exclude options

Close #2706

Author: posva

packages/router/src/unplugin/codegen/generateParamParsers.spec.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, test } from 'vitest'
 import {
   warnMissingParamParsers,
   collectMissingParamParsers,
@@ -8,13 +8,17 @@ import {
   generatePathParamsOptions,
   generateCustomParamParsersList,
   generateNormalizedParamParsersDeclarations,
+  scanParamParserFiles,
   type ParamParsersMap,
 } from './generateParamParsers'
 import { PrefixTree } from '../core/tree'
-import { resolveOptions } from '../options'
+import { DEFAULT_PARAM_PARSERS_OPTIONS, resolveOptions } from '../options'
 import { ImportsMap } from '../core/utils'
 import type { TreePathParam } from '../core/treeNodeValue'
 import { mockWarn } from '../../tests/vitest-mock-warn'
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 
 const DEFAULT_OPTIONS = resolveOptions({})
 
@@ -785,3 +789,69 @@ describe('generateNormalizedParamParsersDeclarations', () => {
     )
   })
 })
+
+// Per-test temp folder via the recommended vitest `test.extend` fixture pattern.
+// Each test gets a fresh isolated directory; cleanup runs after `use` resolves.
+const parsersTest = test.extend<{ parsersDir: string }>({
+  parsersDir: async ({}, use) => {
+    const dir = mkdtempSync(join(tmpdir(), 'vue-router-param-parsers-'))
+    writeFileSync(join(dir, 'uuid.ts'), 'export const parser = {}')
+    writeFileSync(join(dir, 'slug.ts'), 'export const parser = {}')
+    writeFileSync(join(dir, 'uuid.test.ts'), 'test code')
+    writeFileSync(join(dir, 'slug.spec.ts'), 'test code')
+    writeFileSync(join(dir, 'legacy.js'), 'module.exports = {}')
+    writeFileSync(join(dir, 'legacy.test.js'), 'module.exports = {}')
+    writeFileSync(join(dir, 'README.md'), '# parsers')
+    mkdirSync(join(dir, 'nested'))
+    writeFileSync(join(dir, 'nested', 'deep.ts'), 'export const parser = {}')
+    await use(dir)
+    rmSync(dir, { recursive: true, force: true })
+  },
+})
+
+describe('scanParamParserFiles', () => {
+  parsersTest(
+    'picks parsers and ignores tests/specs/nested by default',
+    async ({ parsersDir }) => {
+      const files = await scanParamParserFiles(
+        parsersDir,
+        DEFAULT_PARAM_PARSERS_OPTIONS.include,
+        DEFAULT_PARAM_PARSERS_OPTIONS.exclude
+      )
+      expect(files.sort()).toEqual(['slug.ts', 'uuid.ts'])
+    }
+  )
+
+  parsersTest(
+    'respects a custom include that adds js',
+    async ({ parsersDir }) => {
+      const files = await scanParamParserFiles(
+        parsersDir,
+        ['*.{ts,js}'],
+        DEFAULT_PARAM_PARSERS_OPTIONS.exclude
+      )
+      expect(files.sort()).toEqual(['legacy.js', 'slug.ts', 'uuid.ts'])
+    }
+  )
+
+  parsersTest('respects a custom exclude', async ({ parsersDir }) => {
+    const files = await scanParamParserFiles(parsersDir, ['*.ts'], ['uuid*'])
+    expect(files.sort()).toEqual(['slug.spec.ts', 'slug.ts'])
+  })
+
+  parsersTest(
+    'returns no files when include is empty',
+    async ({ parsersDir }) => {
+      const files = await scanParamParserFiles(parsersDir, [], [])
+      expect(files).toEqual([])
+    }
+  )
+
+  parsersTest(
+    'never picks nested files even without exclude',
+    async ({ parsersDir }) => {
+      const files = await scanParamParserFiles(parsersDir, ['*.ts'], [])
+      expect(files.some(f => f.includes('nested'))).toBe(false)
+    }
+  )
+})

packages/router/src/unplugin/codegen/generateParamParsers.ts

@@ -2,6 +2,7 @@ import type { TreePathParam, TreeQueryParam } from '../core/treeNodeValue'
 import type { ImportsMap } from '../core/utils'
 import type { PrefixTree } from '../core/tree'
 import { toStringLiteral } from '../utils'
+import { glob } from 'tinyglobby'
 
 export type ParamParsersMap = Map<
   string,
@@ -21,6 +22,27 @@ const NATIVE_PARAM_PARSERS_TYPES = {
   bool: 'boolean',
 } satisfies Record<(typeof _NATIVE_PARAM_PARSERS)[number], string>
 
+/**
+ * Scans a folder for param parser files matching `include` while filtering out `exclude`.
+ * Only flat matches are returned (no nested folders). Exported solely to make this
+ * filesystem-touching behavior testable.
+ *
+ * @internal
+ */
+export function scanParamParserFiles(
+  folder: string,
+  include: string[],
+  exclude: string[]
+): Promise<string[]> {
+  if (!include.length) return Promise.resolve([])
+  return glob(include as string[], {
+    cwd: folder,
+    onlyFiles: true,
+    ignore: exclude as string[],
+    expandDirectories: false,
+  })
+}
+
 export function warnMissingParamParsers(
   tree: PrefixTree,
   paramParsers: ParamParsersMap

packages/router/src/unplugin/core/context.ts

@@ -28,6 +28,7 @@ import type { ParamParsersMap } from '../codegen/generateParamParsers'
 import {
   generateParamParsersTypesDeclarations,
   generateCustomParamParsersList,
+  scanParamParserFiles,
   warnMissingParamParsers,
   collectMissingParamParsers,
 } from '../codegen/generateParamParsers'
@@ -73,8 +74,14 @@ export function createRoutesContext(options: ResolvedOptions) {
       return
     }
 
-    const PARAM_PARSER_GLOB = '*.{ts,js}'
-    const isParamParserMatch = picomatch(PARAM_PARSER_GLOB)
+    const paramParsersInclude = options.experimental.paramParsers?.include ?? []
+    const paramParsersExclude = options.experimental.paramParsers?.exclude ?? []
+    const isParamParserExcluded = paramParsersExclude.length
+      ? picomatch(paramParsersExclude)
+      : () => false
+    const isParamParserIncluded = paramParsersInclude.length
+      ? picomatch(paramParsersInclude)
+      : () => false
 
     // get the initial list of pages
     await Promise.all([
@@ -125,19 +132,23 @@ export function createRoutesContext(options: ResolvedOptions) {
                     return false
                   }
 
-                  return !isParamParserMatch(relative(folder, filePath))
+                  const fileName = relative(folder, filePath)
+                  return (
+                    !isParamParserIncluded(fileName) ||
+                    isParamParserExcluded(fileName)
+                  )
                 },
               }),
               folder
             )
           )
         }
 
-        return glob(PARAM_PARSER_GLOB, {
-          cwd: folder,
-          onlyFiles: true,
-          expandDirectories: false,
-        }).then(paramParserFiles => {
+        return scanParamParserFiles(
+          folder,
+          paramParsersInclude,
+          paramParsersExclude
+        ).then(paramParserFiles => {
           for (const file of paramParserFiles) {
             const fileName = parsePathe(file).name
             const name = camelCase(fileName)

packages/router/src/unplugin/options.ts

@@ -262,13 +262,31 @@ export interface ParamParsersOptions {
    * @default `['src/params']`
    */
   dir?: string | string[]
+
+  /**
+   * Glob pattern(s) of files to include when scanning param parser folders. Only flat
+   * matches are supported (no nested files).
+   *
+   * @default `['*.ts']`
+   */
+  include?: string | string[]
+
+  /**
+   * Glob pattern(s) of files to ignore when scanning param parser folders. Useful to skip
+   * test files that live next to their implementations.
+   *
+   * @default `['*.test.{ts,js}', '*.spec.{ts,js}']`
+   */
+  exclude?: string | string[]
 }
 
 /**
  * Default options for experimental param parsers.
  */
 export const DEFAULT_PARAM_PARSERS_OPTIONS = {
   dir: ['src/params'],
+  include: ['*.ts'],
+  exclude: ['*.test.{ts,js}', '*.spec.{ts,js}'],
 } satisfies Required<ParamParsersOptions>
 
 /**
@@ -394,6 +412,18 @@ export function resolveOptions(options: Options) {
       : []
   ).map(dir => resolve(root, dir))
 
+  const paramParsersInclude = paramParsers?.include
+    ? isArray(paramParsers.include)
+      ? paramParsers.include
+      : [paramParsers.include]
+    : DEFAULT_PARAM_PARSERS_OPTIONS.include
+
+  const paramParsersExclude = paramParsers?.exclude
+    ? isArray(paramParsers.exclude)
+      ? paramParsers.exclude
+      : [paramParsers.exclude]
+    : DEFAULT_PARAM_PARSERS_OPTIONS.exclude
+
   const autoExportsDataLoaders = options.experimental?.autoExportsDataLoaders
     ? (isArray(options.experimental.autoExportsDataLoaders)
         ? options.experimental.autoExportsDataLoaders
@@ -408,6 +438,8 @@ export function resolveOptions(options: Options) {
     paramParsers: paramParsers && {
       ...paramParsers,
       dir: paramParsersDir,
+      include: paramParsersInclude,
+      exclude: paramParsersExclude,
     },
   }