Shared query types

Types shared by codecs, schemas, adapters, serialization, and query state.

Import these types from @vuqs/core. Function-specific options and return types are documented beside their functions.

ParsedQueryValue

type ParsedQueryValue
  = | string
    | number
    | boolean
    | null
    | undefined
    | ParsedQueryValue[]
    | { [key: string]: ParsedQueryValue }

ParsedQuery

type ParsedQuery = Record<string, ParsedQueryValue>

ParsedQueryRaw

type ParsedQueryRaw = Record<string, ParsedQueryValue>

QueryStateSchema

type QueryStateSchema = Record<string, AnyDefinedQueryParam>

QueryStateSchemaInput

type QueryStateSchemaInput = Record<string, Codec<any> | AnyDefinedQueryParam>

Value contracts of a param

type ExplicitValueOf<TParam> = /* the decoded value before default resolution */
type ResolvedValueOf<TParam> = /* the value after applicable defaults, when defined */
type ContributionOf<TParam> = /* the value a default source can supply */
type GuaranteedOf<TParam> = /* true when a static default guarantees a resolved value */

QueryStateValues

type QueryStateValues<TSchema extends QueryStateSchema> = {
  [Key in keyof TSchema]?: ExplicitValueOf<TSchema[Key]> | undefined
}

QueryStateWriteValues

type QueryStateWriteValues<TSchema extends QueryStateSchema> = QueryStateValues<TSchema>

QueryStateResolvedValues

type QueryStateResolvedValues<TSchema extends QueryStateSchema> = {
  [Key in keyof TSchema]?: ResolvedValueOf<TSchema[Key]> | undefined
}

QueryStateContributions

type QueryStateContributions<TSchema extends QueryStateSchema> = {
  [Key in keyof TSchema]?: ContributionOf<TSchema[Key]> | undefined
}

QueryStateValueOf

type QueryStateValueOf<TDefinition> = ExplicitValueOf<TDefinition>

QueryStateValueAt

type QueryStateValueAt<TSchema extends QueryStateSchema, TKey extends string>
  = TSchema extends { [Key in TKey]: infer TDefinition }
    ? QueryStateValueOf<TDefinition>
    : never

QueryStateContributionAt

type QueryStateContributionAt<TSchema extends QueryStateSchema, TKey extends string>
  = TSchema extends { [Key in TKey]: infer TDefinition }
    ? ContributionOf<TDefinition>
    : never

QueryStateRefValue

type QueryStateRefValue<TDefinition extends AnyDefinedQueryParam>
  = [GuaranteedOf<TDefinition>] extends [true]
    ? ResolvedValueOf<TDefinition>
    : ResolvedValueOf<TDefinition> | undefined

QueryStateRefInput

type QueryStateRefInput<TDefinition extends AnyDefinedQueryParam>
  = [GuaranteedOf<TDefinition>] extends [true]
    ? ExplicitValueOf<TDefinition>
    : ExplicitValueOf<TDefinition> | undefined

ParsedQuery is the adapter's input; ParsedQueryRaw is serialized output. They share the same recursive node shape.

QueryStateSchemaInput accepts codecs or definitions. QueryStateSchema contains normalized definitions. Use defineQuerySchema when deriving types from codec shorthand.

QueryStateValues and QueryStateWriteValues hold explicit values: a composed param keeps its defaulted children optional, and explicit undefined is allowed. Writer behavior determines omission semantics: patch and the serializer preserve omitted params; replace and whole-object refs clear them.

QueryStateResolvedValues holds the values after applicable defaults. QueryStateContributions is what setDefaults and registered default sources accept.

QueryStateRefValue resolves the static default distinction: a param that guarantees a value yields the resolved type; another param yields it with undefined. QueryStateRefInput is the matching write type. Module read policies can affect which values are present at runtime.

Related types

Contract	Reference
Codec inputs and modifiers	codecs, createCodec
Param definitions and builders	queryParam
Reactive values, actions, and options	useQueryStates
Single ref and module composition	useQueryState
Binding and whole-object ref	toQueryRef
Per-param refs	toQueryRefs
Adapter and navigation	QueryAdapter
Serializer	createSerializer
Engine reads and default layers	createQueryStateEngine
Module projections and factories	defineQueryModule
Transactions	QueryCore
Built-in modules	Modules