feat: enable standard schema param parsers

posva · posva · commit ea8e3e216d8b · 2026-03-20T16:19:48.000+01:00
Close #2660 Only works if the param can be implicitly casted to a String
diff --git a/package.json b/package.json
@@ -75,7 +75,11 @@
     "onlyBuiltDependencies": [
       "chromedriver",
       "esbuild",
-      "geckodriver"
+      "geckodriver",
+      "simple-git-hooks"
+    ],
+    "ignoredBuiltDependencies": [
+      "@nightwatch/nightwatch-inspector"
     ]
   }
 }
diff --git a/packages/playground-file-based/package.json b/packages/playground-file-based/package.json
@@ -11,6 +11,7 @@
   },
   "dependencies": {
     "semver": "^7.7.3",
+    "valibot": "^1.3.1",
     "vue": "3.6.0-beta.5",
     "vue-router": "workspace:*",
     "zod": "^4.3.6"
diff --git a/packages/playground-file-based/src/pages/months/valibot-[month=month-valibot].vue b/packages/playground-file-based/src/pages/months/valibot-[month=month-valibot].vue
@@ -0,0 +1,10 @@
+<script lang="ts" setup>
+import { useRoute } from 'vue-router'
+
+const route = useRoute()
+</script>
+
+<template>
+  <h1>Month (valibot): {{ route.params.month }}</h1>
+  <pre>typeof: {{ typeof route.params.month }}</pre>
+</template>
diff --git a/packages/playground-file-based/src/pages/months/zod-[month=month-zod].vue b/packages/playground-file-based/src/pages/months/zod-[month=month-zod].vue
@@ -0,0 +1,22 @@
+<script lang="ts" setup>
+import { useRoute } from 'vue-router'
+
+definePage({
+  params: {
+    query: {
+      mm: {
+        parser: 'month-zod',
+        default: 0,
+      },
+    },
+  },
+})
+
+const route = useRoute()
+</script>
+
+<template>
+  <h1>Month (zod): {{ route.params.month }}</h1>
+  <pre>typeof: {{ typeof route.params.month }}</pre>
+  <pre>{{ route.params }}</pre>
+</template>
diff --git a/packages/playground-file-based/src/params/month-valibot.ts b/packages/playground-file-based/src/params/month-valibot.ts
@@ -0,0 +1,22 @@
+import * as v from 'valibot'
+
+const MonthSchema = v.pipe(
+  v.string(),
+  v.transform(Number),
+  v.integer(),
+  v.minValue(1),
+  v.maxValue(12)
+)
+
+export const parser = MonthSchema
+
+// export const parser = defineParamParser({
+//   get: value => {
+//     const result = v.safeParse(MonthSchema, value)
+//     if (!result.success) {
+//       miss()
+//     }
+//     return result.output
+//   },
+//   set: value => String(value),
+// })
diff --git a/packages/playground-file-based/src/params/month-zod.ts b/packages/playground-file-based/src/params/month-zod.ts
@@ -0,0 +1,12 @@
+import { defineParamParser } from 'vue-router/experimental'
+import { z } from 'zod'
+
+const MonthSchema = z.coerce.number().int().min(1).max(12)
+export const parser = MonthSchema
+
+// export const parser = defineParamParser({
+//   get: (value): number => {
+//     return MonthSchema.parse(value)
+//   },
+//   set: (value: number): string => String(value),
+// })
diff --git a/packages/playground-file-based/src/routes.d.ts b/packages/playground-file-based/src/routes.d.ts
@@ -14,17 +14,24 @@ import type {
   ParamValueZeroOrMore,
   ParamValueZeroOrOne,
 } from 'vue-router'
+import type {
+  _ExtractParamParserType,
+} from 'vue-router/experimental
 
 // Custom route params parsers
-type Param_date = ReturnType<NonNullable<typeof import('./params/date.ts').parser['get']>>
-type Param_npmOrg = ReturnType<NonNullable<typeof import('./params/npm-org.ts').parser['get']>>
-type Param_semver = ReturnType<NonNullable<typeof import('./params/semver.ts').parser['get']>>
-type Param_versionRange = ReturnType<NonNullable<typeof import('./params/version-range.ts').parser['get']>>
+type Param_date = _ExtractParamParserType<typeof import('./params/date.ts').parser>
+type Param_monthValibot = _ExtractParamParserType<typeof import('./params/month-valibot.ts').parser>
+type Param_monthZod = _ExtractParamParserType<typeof import('./params/month-zod.ts').parser>
+type Param_npmOrg = _ExtractParamParserType<typeof import('./params/npm-org.ts').parser>
+type Param_semver = _ExtractParamParserType<typeof import('./params/semver.ts').parser>
+type Param_versionRange = _ExtractParamParserType<typeof import('./params/version-range.ts').parser>
 
 declare module 'vue-router' {
   interface TypesConfig {
     ParamParsers:
       | 'date'
+      | 'month-valibot'
+      | 'month-zod'
       | 'npm-org'
       | 'semver'
       | 'version-range'
@@ -162,6 +169,20 @@ declare module 'vue-router/auto-routes' {
       Record<never, never>,
       | never
     >,
+    '/months/valibot-[month=month-valibot]': RouteRecordInfo<
+      '/months/valibot-[month=month-valibot]',
+      '/months/valibot-:month',
+      { month: Exclude<Param_monthValibot, unknown[]> },
+      { month: Exclude<Param_monthValibot, unknown[]> },
+      | never
+    >,
+    '/months/zod-[month=month-zod]': RouteRecordInfo<
+      '/months/zod-[month=month-zod]',
+      '/months/zod-:month',
+      { month: Exclude<Param_monthZod, unknown[]>, mm?: Exclude<Param_monthZod, unknown[]> },
+      { month: Exclude<Param_monthZod, unknown[]>, mm: Exclude<Param_monthZod, unknown[]> },
+      | never
+    >,
     '/nested/': RouteRecordInfo<
       '/nested/',
       '/nested',
@@ -391,6 +412,18 @@ declare module 'vue-router/auto-routes' {
       views:
         | never
     }
+    'src/pages/months/valibot-[month=month-valibot].vue': {
+      routes:
+        | '/months/valibot-[month=month-valibot]'
+      views:
+        | never
+    }
+    'src/pages/months/zod-[month=month-zod].vue': {
+      routes:
+        | '/months/zod-[month=month-zod]'
+      views:
+        | never
+    }
     'src/pages/nested/_parent.vue': {
       routes:
         | '/nested/'
diff --git a/packages/router/package.json b/packages/router/package.json
@@ -168,6 +168,7 @@
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-replace": "^6.0.3",
     "@rollup/plugin-terser": "^0.4.4",
+    "@standard-schema/spec": "^1.1.0",
     "@types/babel__generator": "^7.27.0",
     "@types/nightwatch": "^2.3.32",
     "@types/picomatch": "^4.0.2",
@@ -192,8 +193,10 @@
     "rollup-plugin-typescript2": "^0.36.0",
     "tsdown": "^0.20.1",
     "tsup": "^8.5.1",
+    "valibot": "^1.3.1",
     "vite": "^7.3.0",
-    "vue": "3.6.0-beta.2"
+    "vue": "3.6.0-beta.2",
+    "zod": "^4.3.6"
   },
   "peerDependencies": {
     "@pinia/colada": ">=0.21.2",
diff --git a/packages/router/src/experimental/index.ts b/packages/router/src/experimental/index.ts
@@ -42,6 +42,8 @@ export {
   defineParamParser,
   definePathParamParser,
   defineQueryParamParser,
+  normalizeParamParser as _normalizeParamParser,
+  type ExtractParamParserType as _ExtractParamParserType,
 } from './route-resolver/matchers/param-parsers'
 
 export { miss, MatchMiss as _MatchMiss } from './route-resolver/matchers/errors'
diff --git a/packages/router/src/experimental/route-resolver/matchers/param-parsers/index.ts b/packages/router/src/experimental/route-resolver/matchers/param-parsers/index.ts
@@ -4,6 +4,8 @@ import type { ParamParser } from './types'
 export { PARAM_PARSER_BOOL } from './booleans'
 export { PARAM_PARSER_INT } from './integers'
 export { PARAM_PARSER_STRING } from './strings'
+export { normalizeParamParser } from './standard-schema'
+export type { ExtractParamParserType } from './standard-schema'
 
 export const PATH_PARAM_SINGLE_DEFAULT: ParamParser<string, string> = {}
 
diff --git a/packages/router/src/experimental/route-resolver/matchers/param-parsers/standard-schema-types.ts b/packages/router/src/experimental/route-resolver/matchers/param-parsers/standard-schema-types.ts
@@ -0,0 +1,78 @@
+/**
+ * Inlined subset of `@standard-schema/spec` v1.1.0 so the distributed code
+ * has zero external type dependencies. Keep the package installed to track
+ * upstream changes.
+ *
+ * @see https://github.com/standard-schema/standard-schema
+ */
+
+/** The Standard Schema interface. */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+  /** The Standard Schema properties. */
+  readonly '~standard': StandardSchemaV1.Props<Input, Output>
+}
+
+export declare namespace StandardSchemaV1 {
+  /** The Standard Schema properties interface. */
+  interface Props<Input = unknown, Output = Input> {
+    /** The version number of the standard. */
+    readonly version: 1
+    /** The vendor name of the schema library. */
+    readonly vendor: string
+    /** Inferred types associated with the schema. */
+    readonly types?: Types<Input, Output> | undefined
+    /** Validates unknown input values. */
+    readonly validate: (
+      value: unknown
+    ) => Result<Output> | Promise<Result<Output>>
+  }
+
+  /** The Standard Schema types interface. */
+  interface Types<Input = unknown, Output = Input> {
+    /** The input type of the schema. */
+    readonly input: Input
+    /** The output type of the schema. */
+    readonly output: Output
+  }
+
+  /** The result interface of the validate function. */
+  type Result<Output> = SuccessResult<Output> | FailureResult
+
+  /** The result interface if validation succeeds. */
+  interface SuccessResult<Output> {
+    /** The typed output value. */
+    readonly value: Output
+    /** A falsy value for `issues` indicates success. */
+    readonly issues?: undefined
+  }
+
+  /** The result interface if validation fails. */
+  interface FailureResult {
+    /** The issues of failed validation. */
+    readonly issues: ReadonlyArray<Issue>
+  }
+
+  /** The issue interface of the failure output. */
+  interface Issue {
+    /** The error message of the issue. */
+    readonly message: string
+    /** The path of the issue, if any. */
+    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined
+  }
+
+  /** The path segment interface of the issue. */
+  interface PathSegment {
+    /** The key representing a path segment. */
+    readonly key: PropertyKey
+  }
+
+  /** Infers the input type of a Standard Schema. */
+  type InferInput<Schema extends StandardSchemaV1> = NonNullable<
+    Schema['~standard']['types']
+  >['input']
+
+  /** Infers the output type of a Standard Schema. */
+  type InferOutput<Schema extends StandardSchemaV1> = NonNullable<
+    Schema['~standard']['types']
+  >['output']
+}
diff --git a/packages/router/src/experimental/route-resolver/matchers/param-parsers/standard-schema.spec.ts b/packages/router/src/experimental/route-resolver/matchers/param-parsers/standard-schema.spec.ts
@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+import { MatchMiss } from '../errors'
+import { normalizeParamParser } from './standard-schema'
+
+describe('normalizeParamParser', () => {
+  it('passes through a ParamParser as-is', () => {
+    const original = {
+      get: (v: string) => Number(v),
+      set: (v: number) => String(v),
+    }
+    const result = normalizeParamParser(original)
+    expect(result).toBe(original)
+  })
+
+  it('wraps a standard schema', () => {
+    const parser = normalizeParamParser(z.coerce.number())
+    expect(parser.get?.('42')).toBe(42)
+    expect(parser.set).toBeUndefined()
+  })
+
+  it('throws MatchMiss on validation failure', () => {
+    const parser = normalizeParamParser(z.enum(['a', 'b']))
+    expect(() => parser.get?.('x')).toThrow(MatchMiss)
+  })
+})
diff --git a/packages/router/src/experimental/route-resolver/matchers/param-parsers/standard-schema.ts b/packages/router/src/experimental/route-resolver/matchers/param-parsers/standard-schema.ts
@@ -0,0 +1,53 @@
+import type { StandardSchemaV1 } from './standard-schema-types'
+import { miss } from '../errors'
+import type { ParamParser } from './types'
+import { MatcherQueryParamsValue } from '../matcher-pattern'
+
+/**
+ * Normalizes a param parser input, converting a StandardSchema-compliant object
+ * into a {@link ParamParser} if needed.
+ *
+ * @param parser - a param parser or a StandardSchema-compliant validator
+ *
+ * @internal
+ */
+export function normalizeParamParser<
+  TParam = MatcherQueryParamsValue,
+  TUrlParam = MatcherQueryParamsValue,
+  TParamRaw = TParam,
+>(
+  parser:
+    | ParamParser<TParam, TUrlParam, TParamRaw>
+    | StandardSchemaV1<unknown, TParam>
+): ParamParser<TParam, TUrlParam, TParamRaw> {
+  return '~standard' in parser
+    ? {
+        get(value: TUrlParam): TParam {
+          const result = parser['~standard'].validate(
+            value
+          ) as StandardSchemaV1.Result<TParam>
+          if (__DEV__ && result instanceof Promise) {
+            throw new TypeError(
+              'async validation is not supported for param parsers'
+            )
+          }
+          if (result.issues) {
+            miss(result.issues.map(issue => issue.message).join(', '))
+          }
+          return result.value
+        },
+      }
+    : parser
+}
+
+/**
+ * Extracts the param type from Param Parsers or StandardSchema validators.
+ *
+ * @internal
+ */
+export type ExtractParamParserType<PP> =
+  PP extends ParamParser<infer T, any, any>
+    ? T
+    : PP extends StandardSchemaV1<unknown, infer T>
+      ? T
+      : unknown
diff --git a/packages/router/src/unplugin/codegen/generateDTS.ts b/packages/router/src/unplugin/codegen/generateDTS.ts
@@ -45,6 +45,9 @@ import type {
   ParamValueZeroOrMore,
   ParamValueZeroOrOne,
 } from 'vue-router'
+import type {
+  _ExtractParamParserType,
+} from 'vue-router/experimental
 
 ${
   paramsTypesDeclaration
diff --git a/packages/router/src/unplugin/codegen/generateParamParsers.spec.ts b/packages/router/src/unplugin/codegen/generateParamParsers.spec.ts
diff --git a/packages/router/src/unplugin/codegen/generateParamParsers.ts b/packages/router/src/unplugin/codegen/generateParamParsers.ts
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml

Original file line number	Diff line number	Diff line change
`@@ -75,7 +75,11 @@`
`75`	`75`	`"onlyBuiltDependencies": [`
`76`	`76`	`"chromedriver",`
`77`	`77`	`"esbuild",`
`78`		`- "geckodriver"`
	`78`	`+ "geckodriver",`
	`79`	`+ "simple-git-hooks"`
	`80`	`+ ],`
	`81`	`+ "ignoredBuiltDependencies": [`
	`82`	`+ "@nightwatch/nightwatch-inspector"`
`79`	`83`	`]`
`80`	`84`	`}`
`81`	`85`	`}`