feat(experimental): configure required and default hash params

Author: posva

packages/docs/experimental/param-parsers.md

@@ -232,7 +232,29 @@ definePage({
 </script>
 ```
 
-Hash params are optional. A parser error or a nullish result becomes `null` and does not reject the route. Without a custom getter, an absent hash becomes `null`.
+Hash params are optional by default. A parser error or a nullish result becomes `null`. Set `required: true` to reject the match instead, or provide a default:
+
+```vue
+<script setup lang="ts">
+definePage({
+  params: {
+    hash: {
+      section: {
+        parser: 'section',
+        required: true,
+        default: () => ({ heading: 'overview', tab: 'vue' }),
+      },
+    },
+  },
+})
+</script>
+```
+
+- `parser`: parser name. Omit to keep the hash string.
+- `required`: reject the match when parsing fails and no default exists. Defaults to `false`.
+- `default`: a parsed value or factory used when the hash is absent or parsing fails, including for required params. A declared default takes precedence over the getter for an absent hash.
+
+Without a custom getter or a default, an absent hash becomes `null`.
 
 The parser receives the entire hash string: an empty string when absent, or a string that starts with `#`. To extract several values, return an object from this one parser. Only the deepest matched route's hash parser runs.
 
@@ -262,4 +284,4 @@ router.push({
 })
 ```
 
-You can omit the hash param during navigation or pass `null` to clear it. Nullish values produce an empty hash without calling the setter. The setter returns the entire hash, including `#`, or an empty string. The router then runs the getter to validate and normalize the result.
+You can omit an optional hash param or one with a default during navigation. Pass `null` to clear an optional hash param. Required params without a default must be provided. Nullish values produce an empty hash without calling the setter. The setter returns the entire hash, including `#`, or an empty string. The router then runs the getter to validate and normalize the result.

packages/router/src/experimental/index.ts

@@ -78,6 +78,8 @@ export {
   type ParamParsers as _ParamParsers,
   type ParamParsers_Native as _ParamParsers_Native,
   type ParamParserTypeOf,
+  type DefinePageHashParamOptions,
+  type DefinePageHashParamOptionsAny as _DefinePageHashParamOptionsAny,
   type DefinePageQueryParamOptions,
   type DefinePageQueryParamOptionsAny as _DefinePageQueryParamOptionsAny,
   type PathParamNamesForFilePath as _PathParamNamesForFilePath,

packages/router/src/experimental/route-resolver/matchers/matcher-pattern-hash.spec.ts

@@ -74,6 +74,91 @@ describe('hash param extraction', () => {
     expect(hash.match('#intro')).toEqual({ fragment: null })
   })
 
+  it('rejects required hashes without a default', () => {
+    const hash = new MatcherPatternHashParam(
+      'fragment',
+      {
+        get: value => (value === '#allowed' ? value : miss()),
+      },
+      undefined,
+      true
+    )
+    const resolver = createFixedResolver([
+      { name: 'required', path: new MatcherPatternPathStatic('/page'), hash },
+      { name: 'fallback', path: new MatcherPatternPathStatic('/page') },
+    ])
+    expect(resolver.resolve('/page#allowed').name).toBe('required')
+    expect(resolver.resolve('/page#other').name).toBe('fallback')
+    expect(resolver.resolve('/page').name).toBe('fallback')
+    expect(() => resolver.resolve({ name: 'required', params: {} })).toThrow()
+    const nullHash = new MatcherPatternHashParam(
+      'fragment',
+      {
+        get: () => null,
+      },
+      undefined,
+      true
+    )
+    expect(() => nullHash.match('#other')).toThrow()
+  })
+
+  it.each([false, true])(
+    'uses a default for missing or rejected hashes (required: %s)',
+    required => {
+      const hash = new MatcherPatternHashParam(
+        'fragment',
+        {
+          get: value => (value === '#allowed' ? value : miss()),
+        },
+        '#default',
+        required
+      )
+      const resolver = createFixedResolver([
+        { name: 'page', path: new MatcherPatternPathStatic('/page'), hash },
+      ])
+      expect(resolver.resolve('/page').params).toEqual({ fragment: '#default' })
+      expect(resolver.resolve('/page#other').params).toEqual({
+        fragment: '#default',
+      })
+      expect(resolver.resolve('/page#allowed').params).toEqual({
+        fragment: '#allowed',
+      })
+      expect(resolver.resolve({ name: 'page', params: {} })).toMatchObject({
+        fullPath: '/page',
+        params: { fragment: '#default' },
+      })
+    }
+  )
+
+  it('uses the declared default when the hash is absent even if the getter accepts empty strings', () => {
+    const hash = new MatcherPatternHashParam(
+      'fragment',
+      {
+        get: value => value || '#parser-default',
+      },
+      '#declared-default'
+    )
+    expect(hash.match('')).toEqual({ fragment: '#declared-default' })
+    expect(hash.match('#valid')).toEqual({ fragment: '#valid' })
+  })
+
+  it('evaluates factory defaults on each miss and preserves successful falsy results', () => {
+    const hash = new MatcherPatternHashParam(
+      'fragment',
+      {
+        get: value => (value === '#valid' ? [] : undefined),
+      },
+      () => ['default'],
+      true
+    )
+    const first = hash.match('')
+    const second = hash.match('#invalid')
+    expect(first).toEqual({ fragment: ['default'] })
+    expect(second).toEqual(first)
+    expect(second.fragment).not.toBe(first.fragment)
+    expect(hash.match('#valid')).toEqual({ fragment: [] })
+  })
+
   it('keeps strings unchanged without a custom parser', () => {
     const hash = new MatcherPatternHashParam('fragment')
     expect(hash.match('#intro')).toEqual({ fragment: '#intro' })

packages/router/src/experimental/route-resolver/matchers/matcher-pattern-hash.test-d.ts

@@ -1,4 +1,6 @@
 import { expectTypeOf } from 'vitest'
+import { definePage } from '../../runtime'
+import type { DefinePageHashParamOptions } from '../../runtime'
 import { MatcherPatternHashParam } from './matcher-pattern-hash'
 
 const hash = new MatcherPatternHashParam('section', {
@@ -18,3 +20,31 @@ hash.build({ section: undefined })
 
 const stringHash = new MatcherPatternHashParam('fragment')
 expectTypeOf(stringHash.match('')).toEqualTypeOf<{ fragment: string | null }>()
+
+expectTypeOf<DefinePageHashParamOptions<'int'>['default']>().toEqualTypeOf<
+  number | (() => number) | undefined
+>()
+definePage({
+  params: {
+    hash: { count: { parser: 'int', required: true, default: () => 1 } },
+  },
+})
+definePage({
+  params: { hash: { section: { default: '#overview' } } },
+})
+definePage({
+  params: {
+    hash: {
+      // @ts-expect-error: an int parser requires a numeric default
+      count: { parser: 'int', default: 'one' },
+    },
+  },
+})
+definePage({
+  params: {
+    hash: {
+      // @ts-expect-error: hash parsers receive the entire string without a query format
+      section: { parser: 'string', format: 'array' },
+    },
+  },
+})

packages/router/src/experimental/route-resolver/matchers/matcher-pattern-hash.ts

@@ -1,3 +1,5 @@
+import { toValue } from 'vue'
+import { miss } from './errors'
 import type { MatcherPatternHash } from './matcher-pattern'
 import type { ParamParser } from './param-parsers'
 
@@ -10,15 +12,30 @@ export class MatcherPatternHashParam<
 > implements MatcherPatternHash<Record<ParamName, T | null>> {
   constructor(
     private paramName: ParamName,
-    private parser: ParamParser<T, string> = {}
+    private parser: ParamParser<T, string> = {},
+    private defaultValue?: (() => T) | T,
+    private required?: boolean
   ) {}
 
   match(hash: string): Record<ParamName, T | null> {
+    if (hash === '' && this.defaultValue !== undefined) {
+      return { [this.paramName]: toValue(this.defaultValue) } as Record<
+        ParamName,
+        T | null
+      >
+    }
     let value: T | string | null = null
     try {
       value = this.parser.get ? (this.parser.get(hash) ?? null) : hash || null
-    } catch {
-      // Hash params are optional; parser errors fall back to null.
+    } catch (error) {
+      if (this.required && this.defaultValue === undefined) throw error
+    }
+    if (value == null) {
+      if (this.defaultValue !== undefined) {
+        value = toValue(this.defaultValue)
+      } else if (this.required) {
+        miss()
+      }
     }
     return { [this.paramName]: value } as Record<ParamName, T | null>
   }

packages/router/src/experimental/runtime.ts

@@ -104,10 +104,9 @@ export interface DefinePage<FilePath extends string = string> extends Partial<
     query?: Record<string, DefinePageQueryParamOptionsAny | ParamParserType>
 
     /**
-     * One optional parameter extracted from the whole hash, including `#`, or an empty string.
-     * Parser errors fall back to `null`.
+     * One parameter extracted from the whole hash, including `#`, or an empty string.
      */
-    hash?: Record<string, ParamParserType>
+    hash?: Record<string, ParamParserType | DefinePageHashParamOptionsAny>
   }
 }
 
@@ -228,6 +227,46 @@ export interface DefinePageQueryParamOptions<
   required?: boolean
 }
 
+/**
+ * Configures one parameter extracted from the whole hash.
+ */
+export interface DefinePageHashParamOptions<
+  Parser extends ParamParserType = ParamParserType,
+> {
+  /**
+   * Parser to apply to the whole hash, including `#`. Without an explicit
+   * default, the parser receives `''` when the hash is absent.
+   * If omitted, keeps the hash string.
+   */
+  parser?: Parser
+
+  /**
+   * Value or factory used when the hash is absent, parsing fails, or the
+   * parser returns `null` or `undefined`. For an absent hash (`''`), this
+   * default is used before the parser runs, so it takes precedence over
+   * the parser's own fallback for an empty hash.
+   */
+  default?: ParamParserTypeOf<Parser> | (() => ParamParserTypeOf<Parser>)
+
+  /**
+   * Whether a parser failure or missing result prevents the route from
+   * matching when no default is provided. Optional hash params return
+   * `null` in these cases.
+   *
+   * @default false
+   */
+  required?: boolean
+}
+
+/**
+ * Distributive hash options with defaults typed by parser name.
+ *
+ * @internal
+ */
+export type DefinePageHashParamOptionsAny<
+  P extends ParamParserType = ParamParserType,
+> = P extends ParamParserType ? DefinePageHashParamOptions<P> : never
+
 /**
  * TODO: native parsers ideas:
  * - json -> just JSON.parse(value)