Debug event reference

Diagnostic notifications emitted by vuqs. Reporters observe these events; they do not control or cancel the operation that produced them.

Experimental protocol

Event codes and payloads are governed by DEBUG_PROTOCOL_VERSION, outside normal semver. The typed map is exported from @vuqs/core/debug-protocol.

import { addDebugReporter } from '@vuqs/core'

const stop = addDebugReporter((event) => {
  console.log(event.code, event.data)
})

For activation, filtering, console output, and SSR isolation, see the debugging guide.

Events

Expand a payload to see its property types and meanings. A ? marks an optional property. Events without payloads carry undefined.

Bindings

Event	Payload	Emitted when	Level
binding:created		A query binding is created.	debug
DebugEventMap['binding:created'] Property Type Meaning id string Binding identifier. keys readonly string[] Logical param names managed by the binding. managedPaths readonly string[] Raw query paths owned by the binding.
binding:disposed		A query binding leaves its Vue effect scope.	debug
DebugEventMap['binding:disposed'] Property Type Meaning id string Binding identifier. keys readonly string[] Logical param names managed by the binding. managedPaths readonly string[] Raw query paths owned by the binding.
binding:set		A binding requests a patch or replacement transaction.	debug
DebugEventMap['binding:set'] Property Type Meaning id string Binding identifier. keys readonly string[] Logical param names managed by the binding. managedPaths readonly string[] Raw query paths owned by the binding. touched readonly string[] Logical param names included in this write. touchedPaths readonly string[] Raw query paths touched by this write. values unknown Values supplied by the caller. options NavigateOptions Resolved navigation options for this write.

Transactions and navigation

Event	Payload	Emitted when	Level
tx:start		The adapter runtime assigns an id to a query transaction.	debug
DebugEventMap['tx:start'] Property Type Meaning id number Transaction identifier assigned by the adapter runtime. mode 'patch' | 'replace' Partial patch or whole-state replacement. paths readonly string[] Raw query paths involved in the operation. origin? string Description of the producer origin symbol, when supplied.
gtq:enqueue		Serialized path changes enter the adapter write queue.	debug
DebugEventMap['gtq:enqueue'] Property Type Meaning deltas Record<string, ParsedQueryValue | null> Pending raw writes by path. A null delta removes the path. pendingPathCount number Number of paths still pending in the write queue.
gtq:coalesce		Another write joins the current queue batch and its options are merged.	debug
DebugEventMap['gtq:coalesce'] Property Type Meaning previous NavigateOptions Navigation options of the existing batch. incoming NavigateOptions Navigation options of the incoming write. resolved NavigateOptions Navigation options after merging the writes. writeCount number Number of writes coalesced into the batch.
gtq:schedule		The queue schedules its next flush.	debug
DebugEventMap['gtq:schedule'] Property Type Meaning delayMs number Flush delay in milliseconds. mechanism 'microtask' | 'timer' Scheduling mechanism used for this flush.
gtq:flush		A queue batch materializes the next query and begins navigation.	debug
DebugEventMap['gtq:flush'] Property Type Meaning paths readonly string[] Raw query paths involved in the operation. query ParsedQuery Serialized query prepared by the operation. options NavigateOptions Resolved navigation options for this write.
gtq:flush-skip		A scheduled queue flush finds no pending paths.	debug
DebugEventMap['gtq:flush-skip'] Property Type Meaning reason 'no paths' Reason the operation was skipped.
gtq:settle		Committed URL paths are removed from the optimistic overlay.	debug
DebugEventMap['gtq:settle'] Property Type Meaning dropped readonly string[] Raw paths removed from the optimistic overlay.
gtq:reset	None	The adapter write queue is reset.	debug
adapter:navigate		The core or a standalone adapter requests URL navigation.	debug
DebugEventMap['adapter:navigate'] Property Type Meaning adapter string Diagnostic name of the adapter. mode 'push' | 'replace' History operation requested from the adapter. query ParsedQuery Serialized query prepared by the operation.
adapter:commit		The adapter confirms a managed navigation or the query changes externally.	debug
DebugEventMap['adapter:commit'] Property Type Meaning query ParsedQuery Final committed parsed query. paths readonly string[] Raw query paths involved in the operation. pendingPathCount number Number of paths still pending in the write queue. source 'write' | 'external' Whether the committed change came from a managed write or an external update.
adapter:error		An adapter navigation throws or rejects.	warn
DebugEventMap['adapter:error'] Property Type Meaning adapter string Diagnostic name of the adapter. error unknown Error raised by the operation. rolledBack? readonly string[] Raw paths whose pending changes were rolled back.
adapter:missing	None	useQueryAdapter() finds no adapter in the current injection scope.	debug

A managed adapter:commit is emitted after successful navigation, before queue settlement. Its source distinguishes managed writes from external query changes. A testing adapter without memory does not emit a managed commit when simulation leaves its query unchanged.

Parsing and defaults

Event	Payload	Emitted when	Level
engine:clear-on-default		The engine omits a value that equals its resolved default.	debug
DebugEventMap['engine:clear-on-default'] Property Type Meaning id string Binding identifier. keys readonly string[] Logical param names managed by the binding. key string Logical param name. paths readonly string[] Raw query paths involved in the operation. defaultValue unknown Resolved default used for the equality comparison.
engine:parse-miss		A value present in the URL cannot be decoded by its query param.	warn
DebugEventMap['engine:parse-miss'] Property Type Meaning path string Raw query path that could not be decoded. raw unknown Value received from the parsed query.

Module coordination

Event	Payload	Emitted when	Level
hooks:subscribe		A module subscribes to a query hook.	debug
DebugEventMap['hooks:subscribe'] Property Type Meaning event string Name of the module signal.
hooks:emit		A query hook synchronously dispatches to its subscribers.	debug
DebugEventMap['hooks:emit'] Property Type Meaning event string Name of the module signal. args readonly unknown[] Arguments passed to the signal handlers.
pipeline:tap		A module registers one or more query pipeline transforms.	debug
DebugEventMap['pipeline:tap'] Property Type Meaning stages readonly QueryPipelineStage[] Pipeline stages receiving the transform. enforce Enforce Ordering band of the transform within each stage.

Runtime defaults

Event	Payload	Emitted when	Level
rd:set		A runtime-default layer sets one or more values.	debug
DebugEventMap['rd:set'] Property Type Meaning defaults Record<string, unknown> Runtime default values supplied by the caller.
rd:clear	None	The runtime-default layer is cleared explicitly.	debug
rd:reset		A query context change resets the runtime-default layer.	debug
DebugEventMap['rd:reset'] Property Type Meaning context string Context identifier associated with this change.
rd:register		The runtime-default layer is registered or disposed.	debug
DebugEventMap['rd:register'] Property Type Meaning state 'registered' | 'disposed' Whether the runtime default layer was registered or disposed.

Context

Event	Payload	Emitted when	Level
ctx:build		The context module builds a query for another context.	debug
DebugEventMap['ctx:build'] Property Type Meaning kept readonly string[] Logical params preserved in the target context. dropped readonly string[] Logical params removed when building the target query.
ctx:switch		switchTo() requests navigation to another query context.	debug
DebugEventMap['ctx:switch'] Property Type Meaning to string Target context identifier.
ctx:change		The active query context changes.	debug
DebugEventMap['ctx:change'] Property Type Meaning context string Context identifier associated with this change. valid readonly string[] Logical params valid in the new context. invalid readonly string[] Logical params invalid in the new context.

Storage

Event	Payload	Emitted when	Level
storage:restore-start		The storage module starts its initialization policy.	debug
DebugEventMap['storage:restore-start'] Property Type Meaning key string Storage key of the state mirror. policy 'if-empty' | 'never' Configured storage restore policy.
storage:restore		Storage initialization reaches a terminal outcome.	debug
DebugEventMap['storage:restore'] Property Type Meaning key string Storage key of the state mirror. outcome 'mirror-only' | 'load-error' | 'url-won' | 'empty' | 'invalid' | 'restored' | 'failed' | 'server-skip' | 'disposed' Result of the initial restore or mirror decision.
storage:write		A storage revision starts saving or removing a snapshot.	debug
DebugEventMap['storage:write'] Property Type Meaning key string Storage key of the state mirror. revision number Revision of the state being persisted. operation 'save' | 'remove' Storage lifecycle operation being attempted or reporting an error. query ParsedQuery Serialized explicit state being mirrored.
storage:coalesce		A newer storage revision replaces one that has not started yet.	debug
DebugEventMap['storage:coalesce'] Property Type Meaning key string Storage key of the state mirror. from number Revision replaced by a newer pending write. to number Revision of the newer pending write.
storage:error		A storage load, validation, serialization, save, removal, or restore operation fails.	warn
DebugEventMap['storage:error'] Property Type Meaning key string Storage key of the state mirror. operation 'save' | 'remove' | 'serialize' | 'load' | 'snapshot' | 'restore' Storage lifecycle operation being attempted or reporting an error. error unknown Error raised by the operation.

Serialization

Event	Payload	Emitted when	Level
serializer:clear-on-default		The standalone serializer omits a value equal to its default.	debug
DebugEventMap['serializer:clear-on-default'] Property Type Meaning key string Logical param name.
serializer:build		The standalone serializer finishes building a query object.	debug
DebugEventMap['serializer:build'] Property Type Meaning query ParsedQuery Serialized query prepared by the operation.

Custom module logs

Event	Payload	Emitted when	Level
module:log		A third-party module writes through createDebugLogger().	debug
DebugEventMap['module:log'] Property Type Meaning namespace string Source tag supplied to the custom logger. message string Message supplied by the module author. values readonly unknown[] Structured console arguments supplied by the module author.
module:warn		A third-party module warns through createDebugLogger().	warn
DebugEventMap['module:warn'] Property Type Meaning namespace string Source tag supplied to the custom logger. message string Message supplied by the module author. values readonly unknown[] Structured console arguments supplied by the module author.

Event shape @vuqs/core

Every reporter receives the same frozen envelope. DebugEvent, DebugContext, and DebugLevel are exported from @vuqs/core:

interface DebugContext {
  readonly runtimeId?: string
  readonly bindingId?: string
  readonly transactionIds?: readonly number[]
  readonly batchId?: number
}

interface DebugEvent {
  readonly code: string
  readonly scope: string
  readonly level: DebugLevel
  readonly seq: number
  readonly timestamp: number
  readonly monotonicTime?: number
  readonly context?: DebugContext
  readonly data: unknown
}

Properties

Property	Type	Description
code	string	The event code.
scope	string	The event's scope.
level	'debug' | 'warn'	The diagnostic level.
seq	number	The global monotonic event sequence.
timestamp	number	Epoch milliseconds from Date.now().
monotonicTime	number	Optional high-resolution time from performance.now().
context	DebugContext	Optional runtime, binding, transaction and batch identifiers.
data	unknown	The payload for the event code.

The strict KnownDebugEvent union narrows data from code. Import it and the complete DebugEventMap from @vuqs/core/debug-protocol when building protocol-aware tooling.

DebugEmissionContext

type DebugEmissionContext = Omit<DebugContext, 'runtimeId'>

The context supplied by an emitter. The channel supplies runtimeId. This type is exported from @vuqs/core.

Correlation

seq orders events across the global debug stream. Context identifiers relate events to an adapter runtime, binding, transaction, or navigation batch. Context fields are optional because not every event belongs to each of those operations.

A batchId identifies one write window, and every queue event in that window shares it. gtq:enqueue lists its own transaction. gtq:flush, adapter:navigate, adapter:commit and gtq:settle list every observed transaction in the batch in ascending order.

• A navigation keeps the context captured when it flushed. Its gtq:settle carries that context even when observation detaches and resumes before the navigation completes. A later batch on the same path does not inherit it.
• A gtq:settle caused by an external query change carries the open batch's context, when one exists. transactionIds lists every transaction in that batch, not the writers of each settled path.
• A gtq:settle lists every path it removes, including paths written while no reporter was attached.
• Writes made without an attached reporter are recorded in no batch, and attaching later does not recover their transaction ids. The flush of such a write that is still queued when a reporter attaches has a batchId without transactionIds. The settlement of a navigation invoked before a reporter attached has neither.

For operation sequences and their console results, see Write lifecycle.

Summary policies and console examples are documented in Summary and trace.