vue-router-query-sync 1.0.1 → 2.0.0-alpha.0

package/README.md

@@ -1,213 +1,116 @@
 # vue-router-query-sync
 
-![demo](src/assets/demo.gif)
+> Draft docs for `2.0.0-alpha.0`. API only — no tests, migration guide or final docs yet.
 
-> Effortlessly sync Vue Router query parameters with your store or local refs — no boilerplate.
+A reactive, typed view of the Vue Router query string. The URL (`route.query`) is the
+single source of truth: reads parse `route.query`, writes navigate the router. The library
+holds no state of its own and never throws because of URL contents.
 
-[![npm version](https://img.shields.io/npm/v/vue-router-query-sync.svg)](https://www.npmjs.com/package/vue-router-query-sync)
-[![license](https://img.shields.io/npm/l/vue-router-query-sync.svg)](LICENSE)
+- Vue 3 + Vue Router 4 (peer dependencies).
+- Codecs + defaults per param; defaults never appear in the URL.
+- Arrays use native repeated keys (`?a=1&a=2`).
+- Batched navigation: several writes in one tick collapse into one `push`/`replace`.
+- SSR-safe: router is read via `useRouter()`/`useRoute()`, no global/module state.
 
----
-
-## ✨ What is this?
-
-`vue-router-query-sync` is a tiny, fully-typed Vue 3 utility that keeps your reactive state
-(Pinia store fields or local refs) in sync with the current URL query string — both ways.
-
-- Changes in your store update the URL query.
-- Changes in the URL query update your store.
-- Batched updates prevent excessive `router.replace` calls.
-
----
-
-## 💡 Why use this plugin?
-
-- 🔄 Keeps your app state and URL perfectly in sync — no more manual watchers or `router.replace` logic.
-- 🧠 Works with **Pinia**, **local refs**, or any reactive source.
-- 🧩 Handles multiple query keys and isolated contexts safely.
-- ⚙️ Fully typed with TypeScript and designed for Vue 3’s Composition API.
-- 🚀 Tiny footprint — optimized for production.
-
-## ✅ Requirements
-
-- Vue 3
-- Vue Router 4
-
----
-
-## 🚀 Installation
+## Install
 
 ```bash
 npm install vue-router-query-sync
-# or
-yarn add vue-router-query-sync
-# or
-pnpm add vue-router-query-sync
 ```
 
----
+## `useQueryFilters(schema)`
 
-## ⚙️ Setup
+Returns a reactive object; access fields without `.value`. The type is inferred from the schema.
 
 ```ts
-// main.ts
-import { createApp } from 'vue'
-import { createRouter, createWebHistory } from 'vue-router'
-import routerQuerySync from 'vue-router-query-sync'
-import App from './App.vue'
-
-const router = createRouter({
-  history: createWebHistory(),
-  routes: []
-})
+import { useQueryFilters, param } from 'vue-router-query-sync'
 
-createApp(App)
-  .use(router)
-  .use(routerQuerySync, { router })
-  .mount('#app')
-```
+enum SortType { Popular = 'popular', New = 'new' }
 
----
-
-## 🧩 Basic Usage
-
-You can use `useQuerySync` several times in one component.
-
-#### Sync a value with a query param named `tab`:
-
-- Visiting `?tab=favorite` sets `tab.value = 'favorite'`.
-- Changing `tab.value = 'all'` updates the URL to `?tab=all`.
-
-```ts
-import { useQuerySync } from 'vue-router-query-sync'
-
-const tab = ref<'favorite' | 'all'>('all')
+const filters = useQueryFilters({
+  sort:   param.enum(SortType, { default: SortType.Popular, history: 'push' }),
+  brands: param.stringArray(),        // default: []
+  page:   param.number({ default: 1 }),
+  from:   param.custom(dateCodec),    // default: null
+})
 
-useQuerySync(
-  'tab',
-  () => tab.value,
-  (val) => (tab.value = val)
-)
+filters.sort = SortType.New                 // write -> router navigation
+filters.brands                              // read  -> parses route.query
+filters.patch({ brands: ['lg'], page: 1 })  // several fields, ONE navigation
+filters.reset()                             // all fields back to defaults (keys removed)
 ```
 
-### Multiple values
-#### Sync a value with a query param named `brands`:
-
-- Visiting `?brands=lg%samsung` sets `brands.value = ['lg', 'samsung']`.
-- Changing `brands.value = ['lg']` updates the URL to `?brands=lg`.
+- **Read**: `route.query[key]` → `deserialize` → on `undefined`/throw → `default`.
+- **Write**: `serialize` → if `null` or equal to `serialize(default)` → the key is removed.
+- Query keys not described in the schema are left untouched.
+- `patch` / `reset` are reserved names; using them as param keys throws at creation.
+- Destructuring loses reactivity — use Vue's `toRefs(filters)`.
 
-```ts
-import { useQuerySync } from 'vue-router-query-sync'
-
-const brands = [
-    { value: 'lg', label: 'LG' },
-    { value: 'samsung', label: 'Samsung' }
-]
-
-const selectedBrands = ref<string[]>([])
-
-useQuerySync(
-    'brands',
-    () => {
-        return selectedBrands.value.length > 0 ? selectedBrands.value.join('%') : null
-    },
-    (val) => {
-        if (typeof val === 'string' && val) {
-            selectedBrands.value = val.includes('%') ? val.split('%') : [val]
-        } else {
-            selectedBrands.value = []
-        }
-    }
-)
-```
----
+## `useQueryParam(key, param)`
 
-## 🔧 API
+Single-parameter wrapper over the same logic. Returns a `WritableComputedRef`.
 
 ```ts
-function useQuerySync<T extends string | number>(
-  key: string,
-  get: () => T | null,
-  set: (val: T) => void,
-  options?: QuerySyncOptions
-): void
-
-type QuerySyncOptions = {
-  deps?: Ref<unknown>[]
-  context?: string
-}
-```
-
-- **key**: Query parameter name, e.g., `'tab'`.
-- **get**: Function returning the current value from your store/ref. Return `null` to indicate “no value”.
-- **set**: Function that writes the value to your store/ref.
-- **options.deps**: Array of refs. If provided, the initial sync runs after any of these deps change (useful when state is populated asynchronously).
-- **options.context**: If the same query key may be used multiple times on the same page, provide a unique context to avoid collisions. The actual query key becomes `${context}_${key}`.
-
----
-
-## ❗ Important
-
-If a page can have multiple components with the same query key, pass a unique `context` to avoid conflicts.
-The real key used in the URL will be `${context}_${key}`. Otherwise, use unique keys per component.
+import { useQueryParam, param } from 'vue-router-query-sync'
 
----
-
-## 🏷️ Context Example
-
-If two widgets on the same page need a `tab` param, use unique contexts:
-
-```ts
-useQuerySync('tab', () => usersStore.tab, (v) => (usersStore.tab = v), { context: 'users' })
-useQuerySync('tab', () => ordersStore.tab, (v) => (ordersStore.tab = v), { context: 'orders' })
-// URL keys will be: users_tab and orders_tab
+const tab = useQueryParam('tab', param.enum(['all', 'favorite'] as const))
+tab.value = 'favorite'
 ```
 
----
+## `param`
 
-## ⏳ Delayed/Dependent Initialization
+All options are shared: `{ default?: T; history?: 'push' | 'replace' }` (`history` defaults to
+`'replace'`). Passing `default` narrows the field type from `T | null` to `T`.
 
-If your state becomes available later (e.g., after a request), delay the initial sync with `deps`:
+| Factory | Field type | Notes |
+| --- | --- | --- |
+| `param.string(options?)` | `string \| null` | |
+| `param.number(options?)` | `number \| null` | |
+| `param.boolean(options?)` | `boolean \| null` | URL is `'true'` / `'false'` |
+| `param.stringArray(options?)` | `string[]` | repeated keys; default always `[]` |
+| `param.enum(input, options?)` | member of `input` | see below |
+| `param.custom(codec, options?)` | `T` from codec | default `null` if unset |
 
-```ts
-const isReady = ref(false)
+`param.enum` accepts either a readonly string array or a TS enum object (string or numeric).
+Numeric enums have their reverse mapping filtered out and URL strings are coerced to numbers.
+A value outside the set becomes `undefined` → `default` (behaviour mirrors `z.enum`).
 
-useQuerySync('sort', () => store.sort, (v) => (store.sort = v), { deps: [isReady] })
+## Codecs
 
-// Later when data is loaded:
-isReady.value = true
-```
-
----
+```ts
+import { defineCodec, type QueryCodec } from 'vue-router-query-sync'
 
-## 📦 Exports
+interface QueryCodec<T> {
+  serialize(value: T): string | string[] | null    // null = remove key
+  deserialize(raw: string | string[]): T | undefined // undefined = use default
+}
 
-```ts
-import routerQuerySync, { useQuerySync, replaceRouterQueue } from 'vue-router-query-sync'
+const dateCodec = defineCodec<Date | null>({
+  serialize: (d) => (d ? d.toISOString().slice(0, 10) : null),
+  deserialize: (raw) => {
+    const t = Date.parse(Array.isArray(raw) ? raw[0] : raw)
+    return Number.isNaN(t) ? undefined : new Date(t)
+  },
+})
 ```
 
-- **default**: Vue plugin to register with `app.use(routerQuerySync, { router })`.
-- **useQuerySync**: The composable described above.
-- **replaceRouterQueue**: Internal helper that batches query updates (exported in case you need manual batching).
-
-Note: `setRouter/getRouter` are internal; prefer using the plugin install.
+`defineCodec` is an identity helper for type inference. All built-in `param.*` types are codecs.
 
----
+## Batching & history
 
-## 🔒 TypeScript
+Writes made in the same tick are merged into a single navigation via `queueMicrotask`.
+If any changed param in the batch has `history: 'push'`, `router.push` is used; otherwise
+`router.replace`. Query keys are sorted for a deterministic URL.
 
-`useQuerySync` is fully typed. You can annotate the expected type if needed:
+## Playground
 
-```ts
-useQuerySync<number>('page', () => page.value, (v) => (page.value = v))
+```bash
+npm run dev
 ```
 
-Values must be `string` or `number`.
-
----
+A catalog page exercises every param type plus `reset`/`patch`, and a second route uses
+`useQueryParam`. The current `route.query` is rendered on screen.
 
-## 📄 License
+## License
 
 MIT © Ivan Chikachev
-
-

package/dist/defineCodec.d.ts

@@ -0,0 +1,3 @@
+import { QueryCodec } from './types';
+export declare function defineCodec<T>(codec: QueryCodec<T>): QueryCodec<T>;
+//# sourceMappingURL=defineCodec.d.ts.map

package/dist/defineCodec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineCodec.d.ts","sourceRoot":"","sources":["../src/defineCodec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAGzC,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAElE"}

package/dist/index.d.ts

@@ -1,13 +1,6 @@
-import { App } from 'vue';
-import { Router } from 'vue-router';
-export * from './composables/useQuerySync';
-export * from './utils/replaceRouterQueue';
-export * from './router';
-export * from './types/index';
-declare const _default: {
-    install(app: App, options: {
-        router: Router;
-    }): void;
-};
-export default _default;
+export { useQueryFilters } from './useQueryFilters';
+export { useQueryParam } from './useQueryParam';
+export { param } from './param';
+export { defineCodec } from './defineCodec';
+export type { QueryCodec, ParamOptions, Param, FilterSchema, InferFilters, QueryFilters } from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,KAAK,CAAA;AAC9B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAGxC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,4BAA4B,CAAA;AAC1C,cAAc,UAAU,CAAA;AACxB,cAAc,eAAe,CAAA;;iBAGd,GAAG,WAAW;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE;;AAD/C,wBAIC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAC/B,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC3C,YAAY,EACV,UAAU,EACV,YAAY,EACZ,KAAK,EACL,YAAY,EACZ,YAAY,EACZ,YAAY,EACb,MAAM,SAAS,CAAA"}

package/dist/index.mjs

@@ -1,77 +1,173 @@
-import { onBeforeMount as b, watch as y, onBeforeUnmount as g } from "vue";
-let v = null;
-function x(e) {
-  v = e;
-}
-function S() {
-  if (!v)
-    throw new Error(
-      "[vue-router-query-sync] Router instance not set. Call setRouter(router) before using composables."
-    );
-  return v;
-}
-let f = {};
-const a = /* @__PURE__ */ new Set();
-let Q = !1;
-function l(e, t) {
-  const s = S();
-  t === null ? e in f || a.add(e) : (f[e] = t, a.delete(e)), Q || (Q = !0, queueMicrotask(() => {
-    const c = { ...s.currentRoute.value.query };
-    a.forEach((o) => {
-      delete c[o];
-    });
-    const R = {
-      ...c,
-      ...f
-    };
-    s.replace({ query: R }), f = {}, a.clear(), Q = !1;
-  }));
-}
+import { computed as h, reactive as b } from "vue";
+import { useRoute as o, useRouter as A } from "vue-router";
 function N(e) {
-  if (e === "")
-    return e;
-  const t = Number(e);
-  return isNaN(t) ? e : t;
-}
-function B(e, t, s, c = {}) {
-  const o = S().currentRoute, { deps: m = [], context: q } = c, r = q ? `${q}_${e}` : e, d = (u, i = !1) => {
-    if (typeof u == "string") {
-      const n = N(u);
-      if (i || n !== t()) {
-        s(n);
-        const p = t();
-        p !== n && p !== null && l(r, p);
-      }
-    } else if (u === void 0) {
-      const n = t();
-      n !== null && l(r, n);
-    }
-  }, h = (u) => {
-    const i = o.value.query[r];
-    if (u === null)
-      i !== void 0 && l(r, null);
-    else {
-      const n = String(u);
-      i !== n && l(r, u);
+  if (e != null)
+    return Array.isArray(e) ? e.filter((r) => r !== null) : e;
+}
+function S(e, r) {
+  return e === r ? !0 : Array.isArray(e) && Array.isArray(r) ? e.length !== r.length ? !1 : e.every((t, u) => t === r[u]) : !1;
+}
+const f = /* @__PURE__ */ new WeakMap();
+function q(e) {
+  let r = f.get(e);
+  return r || (r = { sets: /* @__PURE__ */ new Map(), deletes: /* @__PURE__ */ new Set(), usePush: !1, scheduled: !1 }, f.set(e, r)), r;
+}
+function y(e, r, t, u) {
+  const n = q(e);
+  t === null ? (n.sets.delete(r), n.deletes.add(r)) : (n.deletes.delete(r), n.sets.set(r, t)), u === "push" && (n.usePush = !0), n.scheduled || (n.scheduled = !0, queueMicrotask(() => j(e)));
+}
+function v(e, r) {
+  const t = Object.keys(e), u = Object.keys(r);
+  if (t.length !== u.length)
+    return !1;
+  const n = (s, c) => {
+    if (Array.isArray(s) || Array.isArray(c)) {
+      const l = Array.isArray(s) ? s : [s], a = Array.isArray(c) ? c : [c];
+      return l.length === a.length && l.every((z, m) => String(z) === String(a[m]));
     }
+    return String(s) === String(c);
   };
-  b(() => {
-    m.length > 0 ? y(m, () => d(o.value.query[r])) : d(o.value.query[r]);
-  }), y(t, h), y(
-    () => o.value.query[r],
-    (u) => d(u)
-  ), g(() => {
-    l(r, null);
+  return t.every((s) => s in r && n(e[s], r[s]));
+}
+function j(e) {
+  const r = f.get(e);
+  if (!r)
+    return;
+  f.delete(e);
+  const t = e.currentRoute.value.query, u = {};
+  for (const [c, l] of Object.entries(t))
+    l !== null && (u[c] = Array.isArray(l) ? l.filter((a) => a !== null) : l);
+  r.deletes.forEach((c) => delete u[c]), r.sets.forEach((c, l) => {
+    u[l] = c;
+  });
+  const n = {};
+  for (const c of Object.keys(u).sort())
+    n[c] = u[c];
+  if (v(t, n))
+    return;
+  (r.usePush ? e.push({ query: n }) : e.replace({ query: n })).catch(() => {
   });
 }
-const E = {
-  install(e, t) {
-    x(t.router);
+function g(e, r, t) {
+  const u = N(e[r]);
+  if (u === void 0)
+    return t.default;
+  try {
+    const n = t.codec.deserialize(u);
+    return n === void 0 ? t.default : n;
+  } catch {
+    return t.default;
   }
+}
+function i(e, r, t, u) {
+  const n = t.codec.serialize(u), s = t.codec.serialize(t.default);
+  n === null || S(n, s) ? y(e, r, null, t.history) : y(e, r, n, t.history);
+}
+const k = ["patch", "reset"];
+function V(e) {
+  for (const l of k)
+    if (l in e)
+      throw new Error(
+        `[vue-router-query-sync] "${l}" is a reserved method name and cannot be used as a param key.`
+      );
+  const r = o(), t = A(), u = Object.keys(e), n = {};
+  for (const l of u)
+    n[l] = h({
+      get: () => g(r.query, l, e[l]),
+      set: (a) => i(t, l, e[l], a)
+    });
+  return b({ ...n, patch: (l) => {
+    for (const a of Object.keys(l))
+      a in e && i(t, a, e[a], l[a]);
+  }, reset: () => {
+    for (const l of u)
+      i(t, l, e[l], e[l].default);
+  } });
+}
+function C(e, r) {
+  const t = o(), u = A();
+  return h({
+    get: () => g(t.query, e, r),
+    set: (n) => i(u, e, r, n)
+  });
+}
+function d(e) {
+  return Array.isArray(e) ? e[0] ?? "" : e;
+}
+function w(e) {
+  return { codec: {
+    serialize: (t) => t === null || t === "" ? null : t,
+    deserialize: (t) => d(t)
+  }, default: (e == null ? void 0 : e.default) ?? null, history: (e == null ? void 0 : e.history) ?? "replace" };
+}
+function E(e) {
+  return { codec: {
+    serialize: (t) => t === null ? null : String(t),
+    deserialize: (t) => {
+      const u = d(t), n = Number(u);
+      return u === "" || Number.isNaN(n) ? void 0 : n;
+    }
+  }, default: (e == null ? void 0 : e.default) ?? null, history: (e == null ? void 0 : e.history) ?? "replace" };
+}
+function O(e) {
+  return { codec: {
+    serialize: (t) => t === null ? null : t ? "true" : "false",
+    deserialize: (t) => {
+      const u = d(t);
+      if (u === "true")
+        return !0;
+      if (u === "false")
+        return !1;
+    }
+  }, default: (e == null ? void 0 : e.default) ?? null, history: (e == null ? void 0 : e.history) ?? "replace" };
+}
+function R(e) {
+  return { codec: {
+    serialize: (t) => t.length === 0 ? null : [...t],
+    deserialize: (t) => Array.isArray(t) ? [...t] : [t]
+  }, default: (e == null ? void 0 : e.default) ?? [], history: (e == null ? void 0 : e.history) ?? "replace" };
+}
+function P(e) {
+  return Object.entries(e).filter(([r]) => Number.isNaN(Number(r))).map(([, r]) => r);
+}
+function Q(e, r) {
+  const t = Array.isArray(e) ? [...e] : P(e), u = new Set(t);
+  return { codec: {
+    serialize: (s) => s === null ? null : String(s),
+    deserialize: (s) => {
+      const c = d(s);
+      if (u.has(c))
+        return c;
+      const l = Number(c);
+      if (c !== "" && !Number.isNaN(l) && u.has(l))
+        return l;
+    }
+  }, default: (r == null ? void 0 : r.default) ?? null, history: (r == null ? void 0 : r.history) ?? "replace" };
+}
+function F(e, r) {
+  return {
+    codec: {
+      serialize: (u) => u === null ? null : e.serialize(u),
+      deserialize: (u) => e.deserialize(u)
+    },
+    default: (r == null ? void 0 : r.default) ?? null,
+    history: (r == null ? void 0 : r.history) ?? "replace"
+  };
+}
+const D = {
+  string: w,
+  number: E,
+  boolean: O,
+  stringArray: R,
+  enum: Q,
+  custom: F
 };
+function W(e) {
+  return e;
+}
 export {
-  E as default,
-  S as getRouter,
-  x as setRouter,
-  B as useQuerySync
+  W as defineCodec,
+  D as param,
+  V as useQueryFilters,
+  C as useQueryParam
 };

package/dist/internal/equal.d.ts

@@ -0,0 +1,2 @@
+export declare function serializedEqual(a: string | string[] | null, b: string | string[] | null): boolean;
+//# sourceMappingURL=equal.d.ts.map

package/dist/internal/equal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"equal.d.ts","sourceRoot":"","sources":["../../src/internal/equal.ts"],"names":[],"mappings":"AACA,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,GAAG,OAAO,CAWjG"}

package/dist/internal/field.d.ts

@@ -0,0 +1,5 @@
+import { LocationQuery, Router } from 'vue-router';
+import { Param } from '../types';
+export declare function readField<Out>(query: LocationQuery, key: string, p: Param<Out>): Out;
+export declare function writeField<Out>(router: Router, key: string, p: Param<Out>, value: Out): void;
+//# sourceMappingURL=field.d.ts.map

package/dist/internal/field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field.d.ts","sourceRoot":"","sources":["../../src/internal/field.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AACvD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAA;AAMrC,wBAAgB,SAAS,CAAC,GAAG,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,GAAG,CAWpF;AAGD,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI,CAQ5F"}

package/dist/internal/normalize.d.ts

@@ -0,0 +1,3 @@
+import { LocationQuery } from 'vue-router';
+export declare function normalizeRaw(value: LocationQuery[string]): string | string[] | undefined;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/internal/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../src/internal/normalize.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAG/C,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAQxF"}

package/dist/internal/queryQueue.d.ts

@@ -0,0 +1,3 @@
+import { Router } from 'vue-router';
+export declare function scheduleQuery(router: Router, key: string, value: string | string[] | null, history: 'push' | 'replace'): void;
+//# sourceMappingURL=queryQueue.d.ts.map

package/dist/internal/queryQueue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryQueue.d.ts","sourceRoot":"","sources":["../../src/internal/queryQueue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAmC,MAAM,EAAE,MAAM,YAAY,CAAA;AAsBzE,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,EAC/B,OAAO,EAAE,MAAM,GAAG,SAAS,GAC1B,IAAI,CAiBN"}

package/dist/param.d.ts

@@ -0,0 +1,39 @@
+import { Param, ParamOptions, QueryCodec } from './types';
+declare function string(): Param<string | null>;
+declare function string(options: ParamOptions<string> & {
+    default: string;
+}): Param<string>;
+declare function string(options?: ParamOptions<string>): Param<string | null>;
+declare function number(): Param<number | null>;
+declare function number(options: ParamOptions<number> & {
+    default: number;
+}): Param<number>;
+declare function number(options?: ParamOptions<number>): Param<number | null>;
+declare function boolean(): Param<boolean | null>;
+declare function boolean(options: ParamOptions<boolean> & {
+    default: boolean;
+}): Param<boolean>;
+declare function boolean(options?: ParamOptions<boolean>): Param<boolean | null>;
+declare function stringArray(options?: ParamOptions<string[]>): Param<string[]>;
+declare function enumParam<const T extends readonly string[]>(values: T, options: ParamOptions<T[number]> & {
+    default: T[number];
+}): Param<T[number]>;
+declare function enumParam<const T extends readonly string[]>(values: T, options?: ParamOptions<T[number]>): Param<T[number] | null>;
+declare function enumParam<T extends Record<string, string | number>>(enumObj: T, options: ParamOptions<T[keyof T]> & {
+    default: T[keyof T];
+}): Param<T[keyof T]>;
+declare function enumParam<T extends Record<string, string | number>>(enumObj: T, options?: ParamOptions<T[keyof T]>): Param<T[keyof T] | null>;
+declare function custom<T>(codec: QueryCodec<T>, options: ParamOptions<T> & {
+    default: T;
+}): Param<T>;
+declare function custom<T>(codec: QueryCodec<T>, options?: ParamOptions<T>): Param<T | null>;
+export declare const param: {
+    string: typeof string;
+    number: typeof number;
+    boolean: typeof boolean;
+    stringArray: typeof stringArray;
+    enum: typeof enumParam;
+    custom: typeof custom;
+};
+export {};
+//# sourceMappingURL=param.d.ts.map

package/dist/param.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"param.d.ts","sourceRoot":"","sources":["../src/param.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,22 @@
+export interface QueryCodec<T> {
+    serialize(value: T): string | string[] | null;
+    deserialize(raw: string | string[]): T | undefined;
+}
+export type ParamOptions<T> = {
+    default?: T;
+    history?: 'push' | 'replace';
+};
+export interface Param<Out> {
+    codec: QueryCodec<Out>;
+    default: Out;
+    history: 'push' | 'replace';
+}
+export type FilterSchema = Record<string, Param<unknown>>;
+export type InferFilters<S extends FilterSchema> = {
+    [K in keyof S]: S[K] extends Param<infer O> ? O : never;
+};
+export type QueryFilters<S extends FilterSchema> = InferFilters<S> & {
+    patch(partial: Partial<InferFilters<S>>): void;
+    reset(): void;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AACA,MAAM,WAAW,UAAU,CAAC,CAAC;IAE3B,SAAS,CAAC,KAAK,EAAE,CAAC,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAAA;IAE7C,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAAA;CACnD;AAGD,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI;IAC5B,OAAO,CAAC,EAAE,CAAC,CAAA;IACX,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC7B,CAAA;AAGD,MAAM,WAAW,KAAK,CAAC,GAAG;IACxB,KAAK,EAAE,UAAU,CAAC,GAAG,CAAC,CAAA;IACtB,OAAO,EAAE,GAAG,CAAA;IACZ,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;CAC5B;AAGD,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAA;AAGzD,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,YAAY,IAAI;KAChD,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK;CACxD,CAAA;AAGD,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,YAAY,IAAI,YAAY,CAAC,CAAC,CAAC,GAAG;IACnE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAA;IAC9C,KAAK,IAAI,IAAI,CAAA;CACd,CAAA"}

package/dist/useQueryFilters.d.ts

@@ -0,0 +1,3 @@
+import { FilterSchema, QueryFilters } from './types';
+export declare function useQueryFilters<S extends FilterSchema>(schema: S): QueryFilters<S>;
+//# sourceMappingURL=useQueryFilters.d.ts.map

package/dist/useQueryFilters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useQueryFilters.d.ts","sourceRoot":"","sources":["../src/useQueryFilters.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAMzD,wBAAgB,eAAe,CAAC,CAAC,SAAS,YAAY,EAAE,MAAM,EAAE,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAoClF"}

package/dist/useQueryParam.d.ts

@@ -0,0 +1,4 @@
+import { WritableComputedRef } from 'vue';
+import { Param } from './types';
+export declare function useQueryParam<Out>(key: string, p: Param<Out>): WritableComputedRef<Out>;
+//# sourceMappingURL=useQueryParam.d.ts.map

package/dist/useQueryParam.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useQueryParam.d.ts","sourceRoot":"","sources":["../src/useQueryParam.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,KAAK,CAAA;AAE9C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAIpC,wBAAgB,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAOvF"}

package/package.json

@@ -1,18 +1,20 @@
 {
   "name": "vue-router-query-sync",
-  "version": "1.0.1",
-  "description": "Vue composable for syncing router query params with store",
-  "main": "dist/index.js",
-  "module": "dist/index.mjs",
-  "types": "dist/index.d.ts",
+  "version": "2.0.0-alpha.0",
+  "description": "Reactive, typed view of Vue Router query params with codecs and defaults",
+  "type": "module",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
   "scripts": {
-    "build": "vite build"
+    "dev": "vite --config vite.dev.config.ts",
+    "build": "vite build",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint ."
   },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js"
+      "import": "./dist/index.mjs"
     }
   },
   "files": [
@@ -35,7 +37,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Ivan-Chikachev/vue-router-query-sync"
+    "url": "git+https://github.com/Ivan-Chikachev/vue-router-query-sync.git"
   },
   "peerDependencies": {
     "vue": "^3.3.13",
@@ -43,16 +45,18 @@
   },
   "devDependencies": {
     "vite-plugin-dts": "^4.5.4",
+    "@eslint/js": "^9.36.0",
     "@types/node": "^20.1.0",
-    "@typescript-eslint/eslint-plugin": "^8.4.0",
     "@vitejs/plugin-vue": "^5.2.3",
-    "@vue/eslint-config-typescript": "^12.0.0",
-    "eslint": "^8.57.0",
+    "eslint": "^9.36.0",
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-import": "^2.30.0",
     "eslint-plugin-prettier": "^5.2.1",
-    "eslint-plugin-vue": "^9.28.0",
+    "eslint-plugin-vue": "^9.33.0",
+    "globals": "^15.15.0",
+    "prettier": "^3.6.2",
     "typescript": "^5.2.0",
+    "typescript-eslint": "^8.45.0",
     "vite": "^6.3.6"
   }
 }

package/dist/composables/useQuerySync.d.ts

@@ -1,17 +0,0 @@
-import { QuerySyncOptions } from '../types';
-/**
- * Synchronizes a store value with a query parameter in the URL.
- *
- * @param key - The name of the query parameter, e.g. "tab".
- * @param get - A function that returns the current value from the store.
- * @param set - A function that updates the value in the store.
- * @param options.deps - A list of reactive dependencies that must change before synchronization occurs.
- * @param options.context - A unique context identifier, required when multiple instances use the same query key on the same page.
- *
- * ⚠️ Important:
- * If multiple components on the same page use the same query key,
- * you must provide a unique `context` to prevent conflicts.
- * Alternatively, always use unique query keys (for example, instead of "page", use "usersPage").
- */
-export declare function useQuerySync<T extends string | number>(key: string, get: () => T | null, set: (val: T) => void, options?: QuerySyncOptions): void;
-//# sourceMappingURL=useQuerySync.d.ts.map

package/dist/composables/useQuerySync.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"useQuerySync.d.ts","sourceRoot":"","sources":["../../src/composables/useQuerySync.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAgB1C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EACpD,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,CAAC,GAAG,IAAI,EACnB,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,EACrB,OAAO,GAAE,gBAAqB,QAiE/B"}

package/dist/index.js

@@ -1 +0,0 @@
-(function(u,n){typeof exports=="object"&&typeof module<"u"?n(exports,require("vue")):typeof define=="function"&&define.amd?define(["exports","vue"],n):(u=typeof globalThis<"u"?globalThis:u||self,n(u.VueRouterQuerySync={},u.Vue))})(this,(function(u,n){"use strict";let p=null;function m(e){p=e}function Q(){if(!p)throw new Error("[vue-router-query-sync] Router instance not set. Call setRouter(router) before using composables.");return p}let c={};const f=new Set;let R=!1;function l(e,t){const a=Q();t===null?e in c||f.add(e):(c[e]=t,f.delete(e)),R||(R=!0,queueMicrotask(()=>{const d={...a.currentRoute.value.query};f.forEach(i=>{delete d[i]});const q={...d,...c};a.replace({query:q}),c={},f.clear(),R=!1}))}function g(e){if(e==="")return e;const t=Number(e);return isNaN(t)?e:t}function T(e,t,a,d={}){const i=Q().currentRoute,{deps:v=[],context:b}=d,r=b?`${b}_${e}`:e,S=(o,y=!1)=>{if(typeof o=="string"){const s=g(o);if(y||s!==t()){a(s);const h=t();h!==s&&h!==null&&l(r,h)}}else if(o===void 0){const s=t();s!==null&&l(r,s)}},M=o=>{const y=i.value.query[r];if(o===null)y!==void 0&&l(r,null);else{const s=String(o);y!==s&&l(r,o)}};n.onBeforeMount(()=>{v.length>0?n.watch(v,()=>S(i.value.query[r])):S(i.value.query[r])}),n.watch(t,M),n.watch(()=>i.value.query[r],o=>S(o)),n.onBeforeUnmount(()=>{l(r,null)})}const w={install(e,t){m(t.router)}};u.default=w,u.getRouter=Q,u.setRouter=m,u.useQuerySync=T,Object.defineProperties(u,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}})}));

package/dist/router.d.ts

@@ -1,4 +0,0 @@
-import { Router } from 'vue-router';
-export declare function setRouter(router: Router): void;
-export declare function getRouter(): Router;
-//# sourceMappingURL=router.d.ts.map

package/dist/router.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAIxC,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,QAEvC;AAED,wBAAgB,SAAS,IAAI,MAAM,CAOlC"}

package/dist/types/index.d.ts

@@ -1,6 +0,0 @@
-import { Ref } from 'vue';
-export type QuerySyncOptions = {
-    deps?: Ref<unknown>[];
-    context?: string;
-};
-//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,CAAA;AAEzB,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,CAAC,EAAE,GAAG,CAAC,OAAO,CAAC,EAAE,CAAA;IACrB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA"}

package/dist/utils/replaceRouterQueue.d.ts

@@ -1,2 +0,0 @@
-export default function replaceRouterQueue(key: string, value: string | number | null): void;
-//# sourceMappingURL=replaceRouterQueue.d.ts.map

package/dist/utils/replaceRouterQueue.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"replaceRouterQueue.d.ts","sourceRoot":"","sources":["../../src/utils/replaceRouterQueue.ts"],"names":[],"mappings":"AAMA,MAAM,CAAC,OAAO,UAAU,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,QAiCpF"}