@queryweave/vue-router 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QueryWeave contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,18 @@
+# `@queryweave/vue-router`
+
+A `QueryAdapter` backed by Vue Router.
+
+```ts
+import { createVueRouterAdapter } from "@queryweave/vue-router";
+
+const adapter = createVueRouterAdapter(router, {
+  onNavigationFailure: (outcome) => report(outcome),
+});
+```
+
+It normalizes router query values, keeps path and hash, observes route changes, and reports
+navigation failures instead of throwing. It owns no codec logic, no validation logic, and no Vue
+binding logic, and depends on `@queryweave/core` alone — router synchronization can be adopted
+without the Vue binding.
+
+Vue and Vue Router are peer dependencies.

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+import { QueryAdapter } from "@queryweave/core";
+import { NavigationFailure, Router } from "vue-router";
+//#region src/index.d.ts
+/**
+ * Vue Router adapter.
+ *
+ * This package owns synchronization only. It never decodes, validates, applies defaults, or
+ * duplicates the Vue binding.
+ */
+/** Reported when a router transition is rejected or redirected. */
+type VueRouterNavigationOutcome = {
+  readonly ok: true;
+} | {
+  readonly ok: false;
+  readonly failure: NavigationFailure | Error;
+};
+/** Options accepted by {@link createVueRouterAdapter}. */
+interface VueRouterAdapterOptions {
+  /** Invoked instead of throwing when the router rejects a transition. */
+  readonly onNavigationFailure?: ((outcome: VueRouterNavigationOutcome) => void) | undefined;
+}
+/** A Vue Router adapter with deterministic cleanup. */
+interface VueRouterQueryAdapter extends QueryAdapter {
+  readonly router: Router;
+  dispose(): void;
+}
+/**
+ * Create an adapter backed by a Vue Router instance.
+ *
+ * Path and hash are preserved on every transition; unmanaged query keys are preserved by the
+ * runtime that owns the model.
+ */
+declare function createVueRouterAdapter(router: Router, options?: VueRouterAdapterOptions): VueRouterQueryAdapter;
+//#endregion
+export { VueRouterAdapterOptions, VueRouterNavigationOutcome, VueRouterQueryAdapter, createVueRouterAdapter };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;;;;;KAYY;WACG;;WACA;WAAoB,SAAS,oBAAoB;;;UAG/C;;WAEN,wBAAwB,SAAS;;;UAI3B,8BAA8B;WACpC,QAAQ;EACjB;;;;;;;;iBA+Cc,uBACd,QAAQ,QACR,UAAS,0BACR"}

package/dist/index.js

@@ -0,0 +1,103 @@
+import { watch } from "vue";
+
+//#region src/index.ts
+function toEntries(query) {
+	const entries = [];
+	for (const [key, value] of Object.entries(query)) {
+		if (value === null) {
+			entries.push([key, ""]);
+			continue;
+		}
+		if (typeof value === "string") {
+			entries.push([key, value]);
+			continue;
+		}
+		if (value === void 0) continue;
+		for (const item of value) entries.push([key, item ?? ""]);
+	}
+	return entries;
+}
+function toRawQuery(output) {
+	const query = {};
+	for (const [key, value] of output) {
+		const existing = query[key];
+		if (existing === void 0) {
+			query[key] = value;
+			continue;
+		}
+		if (typeof existing === "string") {
+			query[key] = [existing, value];
+			continue;
+		}
+		existing.push(value);
+	}
+	return query;
+}
+/**
+* Create an adapter backed by a Vue Router instance.
+*
+* Path and hash are preserved on every transition; unmanaged query keys are preserved by the
+* runtime that owns the model.
+*/
+function createVueRouterAdapter(router, options = {}) {
+	const listeners = /* @__PURE__ */ new Set();
+	let stopWatching;
+	let disposed = false;
+	const read = () => toEntries(router.currentRoute.value.query);
+	const notify = () => {
+		const input = read();
+		for (const listener of [...listeners]) listener(input);
+	};
+	const report = (outcome) => {
+		options.onNavigationFailure?.(outcome);
+	};
+	const navigate = async (next, mode) => {
+		if (disposed) throw new Error("This Vue Router query adapter was disposed.");
+		const route = router.currentRoute.value;
+		const target = {
+			path: route.path,
+			hash: route.hash,
+			query: toRawQuery(next)
+		};
+		try {
+			const failure = await (mode === "replace" ? router.replace(target) : router.push(target));
+			report(failure === void 0 || failure === null ? { ok: true } : {
+				ok: false,
+				failure
+			});
+		} catch (error) {
+			report({
+				ok: false,
+				failure: error instanceof Error ? error : new Error(String(error))
+			});
+		}
+	};
+	const attach = () => {
+		stopWatching ??= watch(() => router.currentRoute.value.fullPath, () => {
+			notify();
+		}, { flush: "post" });
+	};
+	return {
+		router,
+		read,
+		push: async (next) => navigate(next, "push"),
+		replace: async (next) => navigate(next, "replace"),
+		subscribe: (listener) => {
+			attach();
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		dispose: () => {
+			disposed = true;
+			listeners.clear();
+			stopWatching?.();
+			stopWatching = void 0;
+		}
+	};
+}
+
+//#endregion
+export { createVueRouterAdapter };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import type { QueryAdapter, QueryChangeListener, QueryEntry, QueryOutput } from \"@queryweave/core\";\nimport { watch } from \"vue\";\nimport type { LocationQuery, LocationQueryRaw, NavigationFailure, Router } from \"vue-router\";\n\n/**\n * Vue Router adapter.\n *\n * This package owns synchronization only. It never decodes, validates, applies defaults, or\n * duplicates the Vue binding.\n */\n\n/** Reported when a router transition is rejected or redirected. */\nexport type VueRouterNavigationOutcome =\n  | { readonly ok: true }\n  | { readonly ok: false; readonly failure: NavigationFailure | Error };\n\n/** Options accepted by {@link createVueRouterAdapter}. */\nexport interface VueRouterAdapterOptions {\n  /** Invoked instead of throwing when the router rejects a transition. */\n  readonly onNavigationFailure?: ((outcome: VueRouterNavigationOutcome) => void) | undefined;\n}\n\n/** A Vue Router adapter with deterministic cleanup. */\nexport interface VueRouterQueryAdapter extends QueryAdapter {\n  readonly router: Router;\n  dispose(): void;\n}\n\nfunction toEntries(query: LocationQuery): QueryOutput {\n  const entries: QueryEntry[] = [];\n  for (const [key, value] of Object.entries(query)) {\n    if (value === null) {\n      entries.push([key, \"\"]);\n      continue;\n    }\n    if (typeof value === \"string\") {\n      entries.push([key, value]);\n      continue;\n    }\n    if (value === undefined) {\n      continue;\n    }\n    for (const item of value) {\n      entries.push([key, item ?? \"\"]);\n    }\n  }\n  return entries;\n}\n\nfunction toRawQuery(output: QueryOutput): LocationQueryRaw {\n  const query: Record<string, string | string[]> = {};\n  for (const [key, value] of output) {\n    const existing = query[key];\n    if (existing === undefined) {\n      query[key] = value;\n      continue;\n    }\n    if (typeof existing === \"string\") {\n      query[key] = [existing, value];\n      continue;\n    }\n    existing.push(value);\n  }\n  return query;\n}\n\n/**\n * Create an adapter backed by a Vue Router instance.\n *\n * Path and hash are preserved on every transition; unmanaged query keys are preserved by the\n * runtime that owns the model.\n */\nexport function createVueRouterAdapter(\n  router: Router,\n  options: VueRouterAdapterOptions = {},\n): VueRouterQueryAdapter {\n  const listeners = new Set<QueryChangeListener>();\n  let stopWatching: (() => void) | undefined;\n  let disposed = false;\n\n  const read = (): QueryOutput => toEntries(router.currentRoute.value.query);\n\n  const notify = (): void => {\n    const input = read();\n    for (const listener of [...listeners]) {\n      listener(input);\n    }\n  };\n\n  const report = (outcome: VueRouterNavigationOutcome): void => {\n    options.onNavigationFailure?.(outcome);\n  };\n\n  const navigate = async (next: QueryOutput, mode: \"push\" | \"replace\"): Promise<void> => {\n    if (disposed) {\n      throw new Error(\"This Vue Router query adapter was disposed.\");\n    }\n    const route = router.currentRoute.value;\n    const target = { path: route.path, hash: route.hash, query: toRawQuery(next) };\n    try {\n      const failure = await (mode === \"replace\" ? router.replace(target) : router.push(target));\n      report(failure === undefined || failure === null ? { ok: true } : { ok: false, failure });\n    } catch (error) {\n      report({ ok: false, failure: error instanceof Error ? error : new Error(String(error)) });\n    }\n  };\n\n  const attach = (): void => {\n    stopWatching ??= watch(\n      () => router.currentRoute.value.fullPath,\n      () => {\n        notify();\n      },\n      { flush: \"post\" },\n    );\n  };\n\n  return {\n    router,\n    read,\n    push: async (next) => navigate(next, \"push\"),\n    replace: async (next) => navigate(next, \"replace\"),\n    subscribe: (listener) => {\n      attach();\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n    dispose: () => {\n      disposed = true;\n      listeners.clear();\n      stopWatching?.();\n      stopWatching = undefined;\n    },\n  };\n}\n"],"mappings":";;;AA4BA,SAAS,UAAU,OAAmC;CACpD,MAAM,UAAwB,CAAC;CAC/B,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,KAAK,GAAG;EAChD,IAAI,UAAU,MAAM;GAClB,QAAQ,KAAK,CAAC,KAAK,EAAE,CAAC;GACtB;EACF;EACA,IAAI,OAAO,UAAU,UAAU;GAC7B,QAAQ,KAAK,CAAC,KAAK,KAAK,CAAC;GACzB;EACF;EACA,IAAI,UAAU,QACZ;EAEF,KAAK,MAAM,QAAQ,OACjB,QAAQ,KAAK,CAAC,KAAK,QAAQ,EAAE,CAAC;CAElC;CACA,OAAO;AACT;AAEA,SAAS,WAAW,QAAuC;CACzD,MAAM,QAA2C,CAAC;CAClD,KAAK,MAAM,CAAC,KAAK,UAAU,QAAQ;EACjC,MAAM,WAAW,MAAM;EACvB,IAAI,aAAa,QAAW;GAC1B,MAAM,OAAO;GACb;EACF;EACA,IAAI,OAAO,aAAa,UAAU;GAChC,MAAM,OAAO,CAAC,UAAU,KAAK;GAC7B;EACF;EACA,SAAS,KAAK,KAAK;CACrB;CACA,OAAO;AACT;;;;;;;AAQA,SAAgB,uBACd,QACA,UAAmC,CAAC,GACb;CACvB,MAAM,4BAAY,IAAI,IAAyB;CAC/C,IAAI;CACJ,IAAI,WAAW;CAEf,MAAM,aAA0B,UAAU,OAAO,aAAa,MAAM,KAAK;CAEzE,MAAM,eAAqB;EACzB,MAAM,QAAQ,KAAK;EACnB,KAAK,MAAM,YAAY,CAAC,GAAG,SAAS,GAClC,SAAS,KAAK;CAElB;CAEA,MAAM,UAAU,YAA8C;EAC5D,QAAQ,sBAAsB,OAAO;CACvC;CAEA,MAAM,WAAW,OAAO,MAAmB,SAA4C;EACrF,IAAI,UACF,MAAM,IAAI,MAAM,6CAA6C;EAE/D,MAAM,QAAQ,OAAO,aAAa;EAClC,MAAM,SAAS;GAAE,MAAM,MAAM;GAAM,MAAM,MAAM;GAAM,OAAO,WAAW,IAAI;EAAE;EAC7E,IAAI;GACF,MAAM,UAAU,OAAO,SAAS,YAAY,OAAO,QAAQ,MAAM,IAAI,OAAO,KAAK,MAAM;GACvF,OAAO,YAAY,UAAa,YAAY,OAAO,EAAE,IAAI,KAAK,IAAI;IAAE,IAAI;IAAO;GAAQ,CAAC;EAC1F,SAAS,OAAO;GACd,OAAO;IAAE,IAAI;IAAO,SAAS,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,KAAK,CAAC;GAAE,CAAC;EAC1F;CACF;CAEA,MAAM,eAAqB;EACzB,iBAAiB,YACT,OAAO,aAAa,MAAM,gBAC1B;GACJ,OAAO;EACT,GACA,EAAE,OAAO,OAAO,CAClB;CACF;CAEA,OAAO;EACL;EACA;EACA,MAAM,OAAO,SAAS,SAAS,MAAM,MAAM;EAC3C,SAAS,OAAO,SAAS,SAAS,MAAM,SAAS;EACjD,YAAY,aAAa;GACvB,OAAO;GACP,UAAU,IAAI,QAAQ;GACtB,aAAa;IACX,UAAU,OAAO,QAAQ;GAC3B;EACF;EACA,eAAe;GACb,WAAW;GACX,UAAU,MAAM;GAChB,eAAe;GACf,eAAe;EACjB;CACF;AACF"}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@queryweave/vue-router",
+  "version": "0.1.0-alpha.1",
+  "description": "Vue Router adapter contracts for QueryWeave.",
+  "keywords": [
+    "query",
+    "state",
+    "url",
+    "vue",
+    "vue-router"
+  ],
+  "homepage": "https://github.com/boussadjra/queryweave#readme",
+  "bugs": {
+    "url": "https://github.com/boussadjra/queryweave/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/boussadjra/queryweave.git",
+    "directory": "packages/vue-router"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@queryweave/core": "0.1.0-alpha.1"
+  },
+  "devDependencies": {
+    "vue": "3.5.40",
+    "vue-router": "5.2.0",
+    "@queryweave/typescript-config": "0.0.0"
+  },
+  "peerDependencies": {
+    "vue": ">=3.5.0 <4",
+    "vue-router": ">=5.2.0 <6"
+  },
+  "engines": {
+    "node": ">=24.18.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc -p tsconfig.json",
+    "test:types": "tsc -p tsconfig.json",
+    "package:check": "publint --strict && attw --pack . --profile esm-only",
+    "clean": "node ../../scripts/clean-package.mjs"
+  }
+}