Engine & Router

The core of Zynq is ZynqEngine: it parses the URL into state, serializes state to query params, and commits changes back to the URL. It does not depend on any framework; it only needs a Router adapter.

Router interface

From @zynq/core, the Router type is:

interface Router {
  getParams(): Record<string, string | null>
  push(params: Record<string, string | null>): void
  replace(params: Record<string, string | null>): void
}

• getParams() — Returns the current query parameters as key → string or null.
• push(params) — Navigate with new query params (new history entry).
• replace(params) — Update query params in place (no new history entry).

Each framework integration implements this against its router (e.g. Vue Router, React Router, Angular Router).

ZynqEngine

import { ZynqEngine, s } from '@zynq/core'
import type { Schema } from '@zynq/core'

const schema: Schema = { page: s.number(1), search: s.string('') }
const engine = new ZynqEngine(schema, routerAdapter)

parse(): state from URL

Reads the current URL (via router.getParams()) and decodes it into state using the schema:

const state = engine.parse()
// state.page, state.search with correct types and defaults

serialize(state): params for URL

Takes (possibly partial) state and returns a record of query param key → string or null. Values equal to the codec default are typically returned as null so they can be omitted from the URL.

const params = engine.serialize({ page: 2, search: 'hello' })
// { page: '2', search: 'hello' } (defaults omitted as null)

commit(state, mode?): update the URL

Merges the given state into the current params and updates the URL:

• commit(state, 'replace') — Default. Replaces current query (no new history entry).
• commit(state, 'push') — Pushes a new history entry.

engine.commit({ page: 2 }, 'replace')

Framework integrations (e.g. Vue’s useZynq) call parse, serialize, and commit for you and keep state in sync when the user changes the URL (back/forward) or when your app changes state.

Framework adapters

• Vue — VueRouterAdapter uses useRouter() and useRoute() to implement Router. Used internally by useZynq. See Vue integration.
• React — Planned adapter for React Router.
• Angular — Planned adapter for Angular Router.

If you use @zynq/core without a framework package, you must implement Router yourself and call engine.parse(), engine.serialize(), and engine.commit() when the URL or your state changes.