feat: make defineParamParser() more intuitive

posva · posva · commit 8715b2115f5f · 2026-05-05T16:25:47.000+02:00
Now it takes a single type param that defines what the param becomes. I
find this to be more intuitive than the previous version:

```ts
 export const parser = defineParamParser&lt;number&gt;({
   get: value =&gt; {
     if (value == null) return null
     if (Array.isArray(value)) {
       return value
         .filter(v =&gt; v != null)
         .map(Number)
         .filter(v =&gt; !Number.isNaN(v))
     }

     return Number.isNaN(Number(value))
       ? miss(`"${value}" is not a valid number`)
       : Number(value)
   },

   set: value =&gt;
     Array.isArray(value)
       ? value.map(String)
       : value == null
         ? null
         : String(value),
 })
```
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
@@ -48,9 +48,9 @@ export function definePathParamParser<
   TParam,
   // path params are parsed by the router as these
   // we use extend to allow infering a more specific type
-  TUrlParam extends string | string[] | null,
+  TUrlParam extends string | string[] | null = string | string[] | null,
   // we can allow pushing with extra values
-  TParamRaw,
+  TParamRaw = TParam,
 >(parser: Required<ParamParser<TParam, TUrlParam, TParamRaw>>) {
   return parser
 }
@@ -74,10 +74,54 @@ export function defineQueryParamParser<
 }
 
 /**
- * Alias for {@link defineQueryParamParser}. Implementing a param parser like this
- * works for path, query, and hash params.
+ * Defines a param parser that works with any kind of param (path, repeatable, optional, query, hash, ...)
+ *
+ * @example
+ *
+ * Here is an example that allows arbitrary numbers (NaN values are filtered
+ * out). It supports repeatable params, so it can be used both as a path param
+ * parser and a query param parser.
+ *
+ * ```ts
+ * export const parser = defineParamParser<number>({
+ *   get: value => {
+ *     if (value == null) return null
+ *     if (Array.isArray(value)) {
+ *       return value
+ *         .filter(v => v != null)
+ *         .map(Number)
+ *         .filter(v => !Number.isNaN(v))
+ *     }
+ *
+ *     return Number.isNaN(Number(value))
+ *       ? miss(`"${value}" is not a valid number`)
+ *       : Number(value)
+ *   },
+ *
+ *   set: value =>
+ *     Array.isArray(value)
+ *       ? value.map(String)
+ *       : value == null
+ *         ? null
+ *         : String(value),
+ * })
+ * ```
  *
  * @see {@link defineQueryParamParser}
  * @see {@link definePathParamParser}
  */
-export const defineParamParser = defineQueryParamParser
+export function defineParamParser<
+  TParam,
+  // we can allow pushing with extra values
+  TParamRaw = TParam,
+>(
+  parser: Required<
+    ParamParser<
+      TParam | TParam[] | null,
+      MatcherQueryParamsValue,
+      TParamRaw | TParamRaw[] | null
+    >
+  >
+) {
+  return parser
+}
diff --git a/packages/router/src/experimental/route-resolver/matchers/param-parsers/types.ts b/packages/router/src/experimental/route-resolver/matchers/param-parsers/types.ts
@@ -4,17 +4,22 @@ import type { MatcherQueryParamsValue } from '../matcher-pattern'
  * Defines a parser that can read a param from the url (string-based) and
  * transform it into a more complex type, or vice versa.
  *
+ * @param TParam - the type of the param after parsing as exposed in `route.params`
+ * @param TUrlParam - this is the most permissive type that can be passed to
+ * get and returned by set. By default it's the type of query path params
+ * (stricter as they do not allow `null` within an array or `undefined`)
+ * @param TParamRaw - the type that can be passed as a location when
+ * navigating: `router.push({ params: {}})` it's sometimes more permissive than
+ * TParam, for example allowing nullish values
+ *
  * @see MatcherPattern
  */
 export interface ParamParser<
-  // type of the param after parsing as exposed in `route.params`
+  // the final type in route.params
   TParam = MatcherQueryParamsValue,
-  // this is the most permissive type that can be passed to get and returned by
-  // set. By default it's the type of query path params (stricter as they do
-  // not allow `null` within an array or `undefined`)
+  // what gets passed to `get`
   TUrlParam = MatcherQueryParamsValue,
-  // the type that can be passed as a location when navigating: `router.push({ params: { }})`
-  // it's sometimes more permissive than TParam, for example allowing nullish values
+  // a potentially more permissive type
   TParamRaw = TParam,
 > {
   get?: (value: NoInfer<TUrlParam>) => TParam
