vue-router-query-sync 0.0.13 → 1.0.1

package/README.md

@@ -16,14 +16,22 @@
 
 - Changes in your store update the URL query.
 - Changes in the URL query update your store.
-- Batched updates to avoid excessive router.replace calls.
+- 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@^3.3.13`)
-- Vue Router 4 (`vue-router@^4.0.3`)
+- Vue 3
+- Vue Router 4
 
 ---
 
@@ -63,11 +71,15 @@ createApp(App)
 
 ## 🧩 Basic Usage
 
-Sync a value with a query param named `tab`:
+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'
-import { ref } from 'vue'
 
 const tab = ref<'favorite' | 'all'>('all')
 
@@ -78,10 +90,36 @@ useQuerySync(
 )
 ```
 
-Now:
-- Visiting `?tab=favorite` sets `tab.value = 'favorite'`.
-- Changing `tab.value = 'all'` updates the URL to `?tab=all`.
+### 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`.
 
+```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 = []
+        }
+    }
+)
+```
 ---
 
 ## 🔧 API

package/dist/composables/useQuerySync.d.ts

@@ -1,17 +1,17 @@
 import { QuerySyncOptions } from '../types';
 /**
- * Синхронизирует значение из стора с query-параметром в адресной строке
+ * Synchronizes a store value with a query parameter in the URL.
  *
- * @param key - имя параметра в query, например "tab"
- * @param get - функция, возвращающая текущее значение из стора
- * @param set - функция, устанавливающая значение в стор
- * @param options.deps - список зависимостей, чтобы синхронизировать только после их изменения
- * @param options.context - конекст использования query-параметра, обязателен, если на странице нессколько одинаковых query-параметра
+ * @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.
  *
- * ⚠️ Важно:
- * Если на одной странице может быть несколько компонентов с одинаковыми query-ключами —
- * обязательно передавайте уникальный `context`, чтобы не было конфликтов.
- * Или всегда использовать уникальные ключи (например вместо "page" - "usersPage").
+ * ⚠️ 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 +1 @@
-{"version":3,"file":"useQuerySync.d.ts","sourceRoot":"","sources":["../../src/composables/useQuerySync.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAI1C;;;;;;;;;;;;;GAaG;AAEH,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,QAyD/B"}
+{"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 +1 @@
-(function(e,n){typeof exports=="object"&&typeof module<"u"?n(exports,require("vue")):typeof define=="function"&&define.amd?define(["exports","vue"],n):(e=typeof globalThis<"u"?globalThis:e||self,n(e.VueRouterQuerySync={},e.Vue))})(this,(function(e,n){"use strict";let p=null;function m(t){p=t}function R(){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 h=!1;function i(t,o){const a=R();o===null?t in c||f.add(t):(c[t]=o,f.delete(t)),h||(h=!0,queueMicrotask(()=>{const d={...a.currentRoute.value.query};f.forEach(l=>{delete d[l]});const v={...d,...c};a.replace({query:v}),c={},f.clear(),h=!1}))}function g(t,o,a,d={}){const l=R().currentRoute,{deps:S=[],context:b}=d,r=b?`${b}_${t}`:t,q=(u,y=!1)=>{if(typeof u=="string"){const s=isNaN(Number(u))?u:Number(u);if(y||s!==o()){a(s);const Q=o();Q!==s&&Q!==null&&i(r,Q)}}else{const s=o();s!==null&&i(r,s)}};n.onBeforeMount(()=>{S.length>0?n.watch(S,()=>q(l.value.query[r])):q(l.value.query[r])}),n.watch(o,u=>{const y=l.value.query[r];u===null?y!==void 0&&i(r,null):y!==String(u)&&i(r,u)}),n.watch(()=>l.value.query[r],u=>{q(u)}),n.onBeforeUnmount(()=>{i(r,null)})}const w={install(t,o){m(o.router)}};e.default=w,e.getRouter=R,e.setRouter=m,e.useQuerySync=g,Object.defineProperties(e,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}})}));
+(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/index.mjs

@@ -1,68 +1,77 @@
-import { onBeforeMount as h, watch as y, onBeforeUnmount as N } from "vue";
+import { onBeforeMount as b, watch as y, onBeforeUnmount as g } from "vue";
 let v = null;
 function x(e) {
   v = e;
 }
-function b() {
+function S() {
   if (!v)
     throw new Error(
       "[vue-router-query-sync] Router instance not set. Call setRouter(router) before using composables."
     );
   return v;
 }
-let i = {};
+let f = {};
 const a = /* @__PURE__ */ new Set();
-let q = !1;
-function l(e, u) {
-  const s = b();
-  u === null ? e in i || a.add(e) : (i[e] = u, a.delete(e)), q || (q = !0, queueMicrotask(() => {
+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,
-      ...i
+      ...f
     };
-    s.replace({ query: R }), i = {}, a.clear(), q = !1;
+    s.replace({ query: R }), f = {}, a.clear(), Q = !1;
   }));
 }
-function g(e, u, s, c = {}) {
-  const o = b().currentRoute, { deps: m = [], context: Q } = c, r = Q ? `${Q}_${e}` : e, d = (t, f = !1) => {
-    if (typeof t == "string") {
-      const n = isNaN(Number(t)) ? t : Number(t);
-      if (f || n !== u()) {
+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 = u();
+        const p = t();
         p !== n && p !== null && l(r, p);
       }
-    } else {
-      const n = u();
+    } 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);
+    }
   };
-  h(() => {
+  b(() => {
     m.length > 0 ? y(m, () => d(o.value.query[r])) : d(o.value.query[r]);
-  }), y(u, (t) => {
-    const f = o.value.query[r];
-    t === null ? f !== void 0 && l(r, null) : f !== String(t) && l(r, t);
-  }), y(
+  }), y(t, h), y(
     () => o.value.query[r],
-    (t) => {
-      d(t);
-    }
-  ), N(() => {
+    (u) => d(u)
+  ), g(() => {
     l(r, null);
   });
 }
-const w = {
-  install(e, u) {
-    x(u.router);
+const E = {
+  install(e, t) {
+    x(t.router);
   }
 };
 export {
-  w as default,
-  b as getRouter,
+  E as default,
+  S as getRouter,
   x as setRouter,
-  g as useQuerySync
+  B as useQuerySync
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vue-router-query-sync",
-  "version": "0.0.13",
+  "version": "1.0.1",
   "description": "Vue composable for syncing router query params with store",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -20,12 +20,16 @@
   ],
   "keywords": [
     "vue",
+    "vue3",
+    "vue plugin",
     "router",
     "query",
     "sync",
     "pinia",
     "store",
-    "composable"
+    "composable",
+    "router query",
+    "query sync"
   ],
   "author": "Ivan Chikachev <ivan-chikachev@mail.ru>",
   "license": "MIT",