vue-router-query-sync 0.0.9 → 0.0.11

package/README.md

@@ -0,0 +1,175 @@
+# vue-router-query-sync
+
+![Анимация работы](src/assets/demo.gif)
+
+> Effortlessly sync Vue Router query parameters with your store or local refs — no boilerplate.
+
+[![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)
+
+---
+
+## ✨ 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 to avoid excessive router.replace calls.
+
+---
+
+## ✅ Requirements
+
+- Vue 3 (`vue@^3.3.13`)
+- Vue Router 4 (`vue-router@^4.0.3`)
+
+---
+
+## 🚀 Installation
+
+```bash
+npm install vue-router-query-sync
+# or
+yarn add vue-router-query-sync
+# or
+pnpm add vue-router-query-sync
+```
+
+---
+
+## ⚙️ Setup
+
+```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: []
+})
+
+createApp(App)
+  .use(router)
+  .use(routerQuerySync, { router })
+  .mount('#app')
+```
+
+---
+
+## 🧩 Basic Usage
+
+Sync a value with a query param named `tab`:
+
+```ts
+import { useQuerySync } from 'vue-router-query-sync'
+import { ref } from 'vue'
+
+const tab = ref<'favorite' | 'all'>('all')
+
+useQuerySync(
+  'tab',
+  () => tab.value,
+  (val) => (tab.value = val)
+)
+```
+
+Now:
+- Visiting `?tab=favorite` sets `tab.value = 'favorite'`.
+- Changing `tab.value = 'all'` updates the URL to `?tab=all`.
+
+---
+
+## 🔧 API
+
+```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.
+
+---
+
+## 🏷️ 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
+```
+
+---
+
+## ⏳ Delayed/Dependent Initialization
+
+If your state becomes available later (e.g., after a request), delay the initial sync with `deps`:
+
+```ts
+const isReady = ref(false)
+
+useQuerySync('sort', () => store.sort, (v) => (store.sort = v), { deps: [isReady] })
+
+// Later when data is loaded:
+isReady.value = true
+```
+
+---
+
+## 📦 Exports
+
+```ts
+import routerQuerySync, { useQuerySync, replaceRouterQueue } from 'vue-router-query-sync'
+```
+
+- **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.
+
+---
+
+## 🔒 TypeScript
+
+`useQuerySync` is fully typed. You can annotate the expected type if needed:
+
+```ts
+useQuerySync<number>('page', () => page.value, (v) => (page.value = v))
+```
+
+Values must be `string` or `number`.
+
+---
+
+## 📄 License
+
+MIT © Ivan Chikachev
+
+

package/dist/composables/useQuerySync.d.ts

@@ -1,4 +1,4 @@
-import { Options } from '../types';
+import { QuerySyncOptions } from '../types';
 /**
  * Синхронизирует значение из стора с query-параметром в адресной строке
  *
@@ -13,5 +13,5 @@ import { Options } from '../types';
  * обязательно передавайте уникальный `context`, чтобы не было конфликтов.
  * Или всегда использовать уникальные ключи (например вместо "page" - "usersPage").
  */
-export declare function useQuerySync<T extends string | number>(key: string, get: () => T | null, set: (val: T) => void, options?: Options): void;
+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":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AAGjC;;;;;;;;;;;;;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,OAAY,QAyDtB"}
+{"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"}

package/dist/index.d.ts

@@ -1,4 +1,13 @@
+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;
 //# 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,cAAc,4BAA4B,CAAA;AAC1C,cAAc,4BAA4B,CAAA;AAC1C,cAAc,eAAe,CAAA"}
+{"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"}

package/dist/index.js

@@ -1 +1 @@
-(function(n,e){typeof exports=="object"&&typeof module<"u"?e(exports,require("vue"),require("vue-router")):typeof define=="function"&&define.amd?define(["exports","vue","vue-router"],e):(n=typeof globalThis<"u"?globalThis:n||self,e(n.VueRouterQuerySync={},n.Vue,n.VueRouter))})(this,(function(n,e,R){"use strict";let f={};const d=new Set;let m=!1;function c(r,s){const a=e.getCurrentInstance();if(!a)throw new Error("useReplaceRouterQueue must be called within a Vue component setup.");const l=a.appContext.config.globalProperties.$router;if(!l)throw new Error("Router not found. Ensure app.use(router) is called in your main.ts.");s===null?r in f||d.add(r):(f[r]=s,d.delete(r)),m||(m=!0,queueMicrotask(()=>{const o={...l.currentRoute.value.query};d.forEach(y=>{delete o[y]});const p={...o,...f};l.replace({query:p}),f={},d.clear(),m=!1}))}function w(r,s,a,l={}){const o=R.useRoute();console.log("!!!!",o);const{deps:p=[],context:y}=l,u=y?`${y}_${r}`:r,q=(t,h=!1)=>{if(typeof t=="string"){const i=isNaN(Number(t))?t:Number(t);if(h||i!==s()){a(i);const Q=s();Q!==i&&Q!==null&&c(u,Q)}}else{const i=s();i!==null&&c(u,i)}};e.onBeforeMount(()=>{p.length>0?e.watch(p,()=>q(o.query[u])):q(o.query[u])}),e.watch(s,t=>{const h=o.query[u];t===null?h!==void 0&&c(u,null):h!==String(t)&&c(u,t)}),e.watch(()=>o.query[u],t=>{q(t)}),e.onBeforeUnmount(()=>{c(u,null)})}n.useQuerySync=w,Object.defineProperty(n,Symbol.toStringTag,{value:"Module"})}));
+(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"}})}));

package/dist/index.mjs

@@ -1,57 +1,68 @@
-import { getCurrentInstance as h, onBeforeMount as R, watch as q, onBeforeUnmount as w } from "vue";
-import { useRoute as b } from "vue-router";
-let p = {};
-const d = /* @__PURE__ */ new Set();
-let Q = !1;
-function s(u, n) {
-  const c = h();
-  if (!c)
-    throw new Error("useReplaceRouterQueue must be called within a Vue component setup.");
-  const l = c.appContext.config.globalProperties.$router;
-  if (!l)
-    throw new Error("Router not found. Ensure app.use(router) is called in your main.ts.");
-  n === null ? u in p || d.add(u) : (p[u] = n, d.delete(u)), Q || (Q = !0, queueMicrotask(() => {
-    const o = { ...l.currentRoute.value.query };
-    d.forEach((f) => {
-      delete o[f];
+import { onBeforeMount as h, watch as y, onBeforeUnmount as N } from "vue";
+let v = null;
+function x(e) {
+  v = e;
+}
+function b() {
+  if (!v)
+    throw new Error(
+      "[vue-router-query-sync] Router instance not set. Call setRouter(router) before using composables."
+    );
+  return v;
+}
+let i = {};
+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(() => {
+    const c = { ...s.currentRoute.value.query };
+    a.forEach((o) => {
+      delete c[o];
     });
-    const i = {
-      ...o,
-      ...p
+    const R = {
+      ...c,
+      ...i
     };
-    l.replace({ query: i }), p = {}, d.clear(), Q = !1;
+    s.replace({ query: R }), i = {}, a.clear(), q = !1;
   }));
 }
-function N(u, n, c, l = {}) {
-  const o = b();
-  console.log("!!!!", o);
-  const { deps: i = [], context: f } = l, t = f ? `${f}_${u}` : u, m = (e, a = !1) => {
-    if (typeof e == "string") {
-      const r = isNaN(Number(e)) ? e : Number(e);
-      if (a || r !== n()) {
-        c(r);
-        const y = n();
-        y !== r && y !== null && s(t, y);
+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()) {
+        s(n);
+        const p = u();
+        p !== n && p !== null && l(r, p);
       }
     } else {
-      const r = n();
-      r !== null && s(t, r);
+      const n = u();
+      n !== null && l(r, n);
     }
   };
-  R(() => {
-    i.length > 0 ? q(i, () => m(o.query[t])) : m(o.query[t]);
-  }), q(n, (e) => {
-    const a = o.query[t];
-    e === null ? a !== void 0 && s(t, null) : a !== String(e) && s(t, e);
-  }), q(
-    () => o.query[t],
-    (e) => {
-      m(e);
+  h(() => {
+    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(
+    () => o.value.query[r],
+    (t) => {
+      d(t);
     }
-  ), w(() => {
-    s(t, null);
+  ), N(() => {
+    l(r, null);
   });
 }
+const w = {
+  install(e, u) {
+    x(u.router);
+  }
+};
 export {
-  N as useQuerySync
+  w as default,
+  b as getRouter,
+  x as setRouter,
+  g as useQuerySync
 };

package/dist/router.d.ts

@@ -0,0 +1,4 @@
+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

@@ -0,0 +1 @@
+{"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,5 +1,5 @@
 import { Ref } from 'vue';
-export type Options = {
+export type QuerySyncOptions = {
     deps?: Ref<unknown>[];
     context?: string;
 };

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

@@ -1 +1 @@
-{"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,OAAO,GAAG;IACpB,IAAI,CAAC,EAAE,GAAG,CAAC,OAAO,CAAC,EAAE,CAAA;IACrB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA"}
+{"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.map

@@ -1 +1 @@
-{"version":3,"file":"replaceRouterQueue.d.ts","sourceRoot":"","sources":["../../src/utils/replaceRouterQueue.ts"],"names":[],"mappings":"AAOA,MAAM,CAAC,OAAO,UAAU,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,QAyCpF"}
+{"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vue-router-query-sync",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "Vue composable for syncing router query params with store",
   "main": "dist/index.js",
   "module": "dist/index.mjs",