feat(experimental)!: normalize query values to arrays (#2824)

BREAKING CHANGE: in the new experimental router, all query values are arrays by default, to simplify type checks. Using param parsers still allow to extract one single value and are unchanged

Author: posva

packages/docs/experimental/param-parsers.md

@@ -147,11 +147,11 @@ export const parser = defineParamParserRaw<Set<string>>({
 
 Here is a table of the different meaningful combinations of return values from `set` and how the router treats them for path and query params:
 
-| `set` returns        | Path param                | Query param                                                      |
-| -------------------- | ------------------------- | ---------------------------------------------------------------- |
-| `null` / `undefined` | param is omitted          | param is omitted (`undefined`) or rendered empty (`null`, `?k=`) |
-| `string`             | single segment (`/value`) | single entry (`?k=value`)                                        |
-| `string[]`           | repeatable (`/a/b/c`)     | repeated entries (`?k=a&k=b`)                                    |
+| `set` returns        | Path param                | Query param                                                               |
+| -------------------- | ------------------------- | ------------------------------------------------------------------------- |
+| `null` / `undefined` | param is omitted          | param is omitted (`undefined`) or rendered without a value (`null`, `?k`) |
+| `string`             | single segment (`/value`) | single entry (`?k=value`)                                                 |
+| `string[]`           | repeatable (`/a/b/c`)     | repeated entries (`?k=a&k=b`)                                             |
 
 :::
 

packages/docs/experimental/router-resolver.md

@@ -55,6 +55,27 @@ declare module 'vue-router' {
 }
 ```
 
+## Query values are arrays
+
+In the experimental router, every key in `route.query` has an array value. A key without a value gives `[null]`, and a missing key is `undefined`:
+
+```ts
+// /search?q=vue&tag=a&tag=b&debug
+route.query.q // ['vue']
+route.query.tag // ['a', 'b']
+route.query.debug // [null]
+route.query.page // undefined
+```
+
+When you navigate, also pass arrays. A non array value still works, but it shows a deprecation warning in development:
+
+```ts
+router.push({ query: { q: ['vue'] } }) // [!code ++]
+router.push({ query: { q: 'vue' } }) // [!code --]
+```
+
+An empty array is the same as a missing key: `{ tag: [] }` and `{}` give the same location.
+
 ## With Data Loaders
 
 If you use [Data Loaders](../data-loaders/), install the plugin **before** the router:

packages/docs/experimental/scroll-restoration.md

@@ -57,7 +57,7 @@ Note that the `key` determines which pages share a saved position. By default, g
 import { useScrollRestoration } from 'vue-router/experimental'
 
 useScrollRestoration({
-  key: to => to.path + `?p=${to.query.p}` + to.hash,
+  key: to => to.path + `?p=${to.query.p?.[0]}` + to.hash,
 })
 ```
 

packages/router/src/diagnostics.ts

@@ -38,6 +38,13 @@ export const diagnostics = /*#__PURE__*/ defineDiagnostics({
         `Route "${p.name}" uses beforeEnter, which is deprecated in the experimental router.`,
       fix: 'Move the condition to the route meta field and check to.meta in router.beforeEach().',
     },
+    // --- experimental/route-resolver/resolver-fixed.ts ---
+    VUE_ROUTER_D0002: {
+      why: (p: { key: string; value: string }) =>
+        `The query value of "${p.key}" is not an array (${p.value}). Non array query values are deprecated in the experimental router.`,
+      fix: (p: { key: string; value: string }) =>
+        `Wrap the value in an array: \`{ ${JSON.stringify(p.key)}: [${p.value}] }\`. Use undefined to remove the key.`,
+    },
 
     // --- router.ts ---
     VUE_ROUTER_R0001: {

packages/router/src/experimental/data-loaders/defineColadaLoader.ts

@@ -43,7 +43,7 @@ import type {
 } from '../../typed-routes'
 import { useRoute, useRouter } from '../../useApi'
 import type { Router } from '../../router'
-import type { LocationQuery } from '../query'
+import type { LocationQuery } from '../../query'
 import { diagnostics } from '../../diagnostics'
 
 /**

packages/router/src/experimental/data-loaders/utils.ts

@@ -1,4 +1,4 @@
-import type { LocationQuery } from '../query'
+import type { LocationQuery } from '../../query'
 import type { Router } from '../../router'
 import type { RouteLocationNormalizedLoaded } from '../../typed-routes'
 import type { DataLoaderEntryBase, UseDataLoader } from './createDataLoader'

packages/router/src/experimental/location.spec.ts

@@ -28,7 +28,7 @@ describe('parseURL', () => {
       fullPath: '/foo?f=foo#hash',
       path: '/foo',
       hash: '#hash',
-      query: { f: 'foo' },
+      query: { f: ['foo'] },
     })
   })
 
@@ -37,7 +37,7 @@ describe('parseURL', () => {
       fullPath: '/?f=foo',
       path: '/',
       hash: '',
-      query: { f: 'foo' },
+      query: { f: ['foo'] },
     })
   })
 
@@ -64,7 +64,7 @@ describe('parseURL', () => {
       fullPath: '/parent/foo?f=foo#hash',
       path: '/parent/foo',
       hash: '#hash',
-      query: { f: 'foo' },
+      query: { f: ['foo'] },
     })
   })
 
@@ -73,7 +73,7 @@ describe('parseURL', () => {
       fullPath: '/parent/bar?f=foo',
       path: '/parent/bar',
       hash: '',
-      query: { f: 'foo' },
+      query: { f: ['foo'] },
     })
   })
 
@@ -92,8 +92,8 @@ describe('parseURL', () => {
       path: '/foo',
       hash: '',
       query: {
-        a: 'one',
-        b: 'two',
+        a: ['one'],
+        b: ['two'],
       },
     })
   })
@@ -112,7 +112,7 @@ describe('parseURL', () => {
       fullPath: '/foo?a=one#bar',
       path: '/foo',
       hash: '#bar',
-      query: { a: 'one' },
+      query: { a: ['one'] },
     })
   })
 
@@ -136,7 +136,7 @@ describe('parseURL', () => {
       fullPath: '/foo/?a=two#?a=one',
       path: '/foo/',
       hash: '#?a=one',
-      query: { a: 'two' },
+      query: { a: ['two'] },
     })
   })
 
@@ -231,7 +231,7 @@ describe('parseURL', () => {
       fullPath: '/parent/bar?o=o',
       path: '/parent/bar',
       hash: '',
-      query: { o: 'o' },
+      query: { o: ['o'] },
     })
   })
 

packages/router/src/experimental/query.spec.ts

@@ -10,10 +10,10 @@ describe('parseQuery', () => {
 
   it('works with leading ?', () => {
     expect(parseQuery('?foo=a')).toEqual({
-      foo: 'a',
+      foo: ['a'],
     })
     expect(parseQuery('foo=a')).toEqual({
-      foo: 'a',
+      foo: ['a'],
     })
     expect(parseQuery('?')).toEqual({})
   })
@@ -27,28 +27,28 @@ describe('parseQuery', () => {
 
   it('decodes values in query', () => {
     expect(parseQuery('e=%25')).toEqual({
-      e: '%',
+      e: ['%'],
     })
   })
 
   it('parses empty string values', () => {
     expect(parseQuery('e=&c=a')).toEqual({
-      e: '',
-      c: 'a',
+      e: [''],
+      c: ['a'],
     })
   })
 
   it('allows = inside values', () => {
     expect(parseQuery('e=c=a')).toEqual({
-      e: 'c=a',
+      e: ['c=a'],
     })
   })
 
   it('parses empty values as null', () => {
     expect(parseQuery('e&b&c=a')).toEqual({
-      e: null,
-      b: null,
-      c: 'a',
+      e: [null],
+      b: [null],
+      c: ['a'],
     })
   })
 
@@ -69,13 +69,13 @@ describe('parseQuery', () => {
 
   it('decodes the + as space', () => {
     expect(parseQuery('a+b=c+d')).toEqual({
-      'a b': 'c d',
+      'a b': ['c d'],
     })
   })
 
   it('decodes the encoded + as +', () => {
     expect(parseQuery('a%2Bb=c%2Bd')).toEqual({
-      'a+b': 'c+d',
+      'a+b': ['c+d'],
     })
   })
 
@@ -96,33 +96,33 @@ describe('parseQuery', () => {
   it('does not pollute the prototype with __proto__', () => {
     const result = parseQuery('__proto__=polluted') as Record<string, unknown>
     expect(Object.getPrototypeOf(result)).toBe(null)
-    expect(result['__proto__']).toBe('polluted')
+    expect(result['__proto__']).toEqual(['polluted'])
     expect(({} as Record<string, unknown>).polluted).toBeUndefined()
   })
 
   it('treats constructor as a regular key', () => {
     const result = parseQuery('constructor=foo')
     expect(Object.getPrototypeOf(result)).toBe(null)
-    expect(result).toEqual({ constructor: 'foo' })
+    expect(result).toEqual({ constructor: ['foo'] })
     expect(Object.prototype.constructor).toBe(Object)
   })
 })
 
 describe('normalizeQuery', () => {
   it('removes keys with undefined values', () => {
-    expect(normalizeQuery({ a: undefined, b: 'x' })).toEqual({ b: 'x' })
+    expect(normalizeQuery({ a: undefined, b: 'x' })).toEqual({ b: ['x'] })
   })
 
-  it('preserves null values', () => {
-    expect(normalizeQuery({ a: null })).toEqual({ a: null })
+  it('wraps null values in an array', () => {
+    expect(normalizeQuery({ a: null })).toEqual({ a: [null] })
   })
 
   it('coerces numbers to strings', () => {
-    expect(normalizeQuery({ a: 1 })).toEqual({ a: '1' })
+    expect(normalizeQuery({ a: 1 })).toEqual({ a: ['1'] })
   })
 
-  it('preserves string values', () => {
-    expect(normalizeQuery({ a: 'x' })).toEqual({ a: 'x' })
+  it('wraps string values in an array', () => {
+    expect(normalizeQuery({ a: 'x' })).toEqual({ a: ['x'] })
   })
 
   it('coerces values inside arrays', () => {
@@ -137,6 +137,10 @@ describe('normalizeQuery', () => {
     })
   })
 
+  it('keeps existing arrays', () => {
+    expect(normalizeQuery({ a: ['x'], b: [] })).toEqual({ a: ['x'], b: [] })
+  })
+
   it('handles empty / undefined input', () => {
     expect(normalizeQuery(undefined)).toEqual({})
     expect(normalizeQuery({})).toEqual({})

packages/router/src/experimental/query.ts

@@ -1,10 +1,6 @@
 import { decode, PLUS_RE } from './encoding'
 import { isArray } from '../utils'
-
-/**
- * NOTE: some types here are duplicated from ../query.ts
- * because they will change to always have (string | null)[] values
- */
+import { diagnostics } from '../diagnostics'
 
 /**
  * Possible values in normalized {@link LocationQuery}. `null` renders the query
@@ -22,14 +18,12 @@ export type LocationQueryValue = string | null
 export type LocationQueryValueRaw = LocationQueryValue | number | undefined
 
 /**
- * Normalized query object that appears in {@link RouteLocationNormalized}
+ * Normalized query object that appears in {@link RouteLocationNormalized}.
+ * Every present key has an array value. `?a` gives `{ a: [null] }`.
  *
  * @public
  */
-export type LocationQuery = Record<
-  string,
-  LocationQueryValue | LocationQueryValue[]
->
+export type LocationQuery = Record<string, LocationQueryValue[]>
 
 /**
  * Loose {@link LocationQuery} object that can be passed to functions like
@@ -63,25 +57,21 @@ export function experimental_parseQuery(search: string): LocationQuery {
     const key = decode(eqPos < 0 ? searchParam : searchParam.slice(0, eqPos))
     const value = eqPos < 0 ? null : decode(searchParam.slice(eqPos + 1))
 
-    if (key in query) {
-      let currentValue = query[key]
-      if (!isArray(currentValue)) {
-        currentValue = query[key] = [currentValue]
-      }
-      ;(currentValue as LocationQueryValue[]).push(value)
-    } else {
-      query[key] = value
-    }
+    query[key] ??= []
+    query[key].push(value)
   }
   return query
 }
 
 /**
  * Transforms a {@link LocationQueryRaw} into a {@link LocationQuery} by casting
- * numbers into strings, removing keys with an undefined value and replacing
- * undefined with null in arrays. Uses `Object.create(null)` so the returned
+ * numbers into strings, wrapping non array values in an array, removing keys
+ * with an undefined value and replacing undefined with null in arrays. Uses `Object.create(null)` so the returned
  * object cannot be exploited via prototype pollution.
  *
+ * FIXME: remove once only arrays are accepted in {@link LocationQueryRaw}.
+ * Normalization will then only cast numbers and remove undefined keys.
+ *
  * @param query - query object to normalize
  * @returns a normalized query object
  */
@@ -93,13 +83,27 @@ export function experimental_normalizeQuery(
   for (const key in query) {
     const value = query[key]
     if (value !== undefined) {
-      normalizedQuery[key] = isArray(value)
-        ? value.map(v => (v == null ? null : '' + v))
-        : value == null
-          ? value
-          : '' + value
+      normalizedQuery[key] = (isArray(value) ? value : [value]).map(v =>
+        v == null ? null : '' + v
+      )
     }
   }
 
   return normalizedQuery
 }
+
+/**
+ * Warns about raw query values that are not arrays. Dev only.
+ * FIXME: remove with the non array normalization in
+ * {@link experimental_normalizeQuery}.
+ *
+ * @param query - raw query passed by the user
+ */
+export function warnNonArrayQueryValues(query: LocationQueryRaw | undefined) {
+  for (const key in query) {
+    const value = query[key]
+    if (value !== undefined && !isArray(value)) {
+      diagnostics.VUE_ROUTER_D0002({ key, value: JSON.stringify(value) })
+    }
+  }
+}