API: serializer & pure functions

Schema-bound serialization and query helpers. The serializer and pure functions are framework-free: no Vue, no router. The advanced createQueryStateEngine section documents the reactive Vue core and calls out its effect-scope requirement. See Building URLs for serializer usage.

createSerializer @vuqs/core

Builds a reusable, schema-bound function that turns values into a query.

function createSerializer<TSchema>(
  schema: TSchema,
  options?: CreateSerializerOptions,
): Serializer<TSchema, ParsedQuery, ParsedQueryRaw | string>

Parameters

• schema: TSchema
  • The params to serialize, keyed by logical name.
• options?: CreateSerializerOptions
  • clearOnDefault?: boolean: default true. Drop a value when it equals its codec default.
  • stringify?: (query: ParsedQueryRaw) => string: enables string output. Provide it to return a query string instead of a query object.
  • parse?: (search: string) => ParsedQuery: enables a string base. Provide it to accept a raw query string as the base argument.
  • stringify and parse are symmetric opt-ins.

Returns

• serialize: Serializer
  • Callable two ways: serialize(values) builds a fresh query from values, and serialize(base, values) patches values over a base query.
  • Write semantics match the reactive writers: null clears, undefined/absent skips, a value sets. Unmanaged base params are always preserved.
  • Throws if a string base is passed without a parse option.

Example

import { createSerializer } from '@vuqs/core'
import qs from 'qs'

const serialize = createSerializer(schema)
serialize({ q: 'phone' })                  // { q: 'phone' }
serialize(route.query, { page: 2 })        // patch over the current query
serialize(route.query, { currency: null }) // clear a param

const toUrl = createSerializer(schema, {
  stringify: q => qs.stringify(q, { addQueryPrefix: true }),
})
toUrl({ q: 'phone', page: 2 })             // '?q=phone&page=2'

Pure functions @vuqs/core

Framework-free helpers over a schema and a parsed query. createSerializer and the engine use these functions. They are also available for custom link-building or query-reading logic.

parseQueryStates

function parseQueryStates<TSchema>(schema: TSchema, query: ParsedQuery): QueryStateValues<TSchema>

Parses each param's selection out of a query. Absent or invalid params are omitted (not set to undefined or their default); defaults resolve in the engine, not here.

serializeQueryStates

function serializeQueryStates<TSchema>(schema: TSchema, values: QueryStateValues<TSchema>): ParsedQueryRaw

Serializes a value map into a compacted nested query object. Pass selected values only: a param equal to its default should be omitted first (see dropDefaults).

buildQuery

function buildQuery<TSchema>(schema: TSchema, currentQuery: ParsedQuery, values: QueryStateValues<TSchema>): ParsedQueryRaw

Strips every managed key from currentQuery, then writes values back. Unmanaged params are preserved; a managed key absent from values is dropped.

dropDefaults

function dropDefaults<TSchema>(schema: TSchema, values: QueryStateValues<TSchema>): QueryStateValues<TSchema>

Drops params whose value equals their codec default (and absent params). The clearOnDefault rule as a reusable function.

getManagedKeys

function getManagedKeys<TSchema>(schema: TSchema): string[]

Every query key the schema manages, across all params, in declaration order.

omitManagedKeys

function omitManagedKeys<TSchema>(schema: TSchema, query: ParsedQuery): ParsedQueryRaw

Removes every managed key from a query (on a clone), pruning only ancestors left empty by the removal. Unmanaged params, even empty ones, are untouched.

assertUniquePaths

function assertUniquePaths<TSchema>(schema: TSchema): void

Throws if any query path is declared by more than one param. Called internally by the composables.

Path helpers @vuqs/core

Dot-path read/write/delete over a parsed query, plus the normalizers used when writing custom codecs.

function getPath(query: ParsedQuery, path: string): ParsedQueryValue
function setPath<T>(query: T, path: string, value: ParsedQueryValue): T
function deletePath(query: ParsedQuery, path: string): void
function getQueryString(raw: ParsedQueryValue): string | undefined
function getQueryStringArray(raw: ParsedQueryValue): string[] | undefined

getQueryString collapses a raw value to string | undefined; getQueryStringArray does the same for a list.

structuralEq @vuqs/core

function structuralEq(a: unknown, b: unknown): boolean

The deep structural comparison used as the default codec eq.

createQueryStateEngine @vuqs/core

The reactive engine behind useQueryState and useQueryStates: atomic transactions, the adapter-scoped optimistic overlay, reconciliation, write coalescing, and navigation.

function createQueryStateEngine<TSchema>(options: QueryStateEngineOptions<TSchema>): QueryStateEngine<TSchema>

Parameters

• options: QueryStateEngineOptions<TSchema>
  • The schema, adapter, and resolved navigation, coalescing, and default behavior. See QueryStateEngineOptions.

Returns

• engine: QueryStateEngine<TSchema>
  • The reactive reads, defaults, transaction-based query I/O, resolved options, and pipeline facets a module receives.

Bindings using the same adapter share the optimistic overlay, write queue, and transaction-start registry. The engine is exposed for building higher layers and must run inside a Vue effect scope. See QueryStateEngineOptions.