@andabove/vuqs 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.1.0 — 2026-05-18
+
+Initial public release.
+
+### Added
+
+- `useQueryState(key, parser)` — binds a typed Vue `Ref` to a URL query parameter via Vue Router. Supports `Ref<T>` (with default) and `Ref<T | null>` (without).
+- Built-in parsers: `parseAsString`, `parseAsInteger`, `parseAsFloat`, `parseAsBoolean`
+- Collection parsers: `parseAsArrayOf(itemParser, separator?)`
+- Enum / literal parsers: `parseAsStringLiteral(values)`, `parseAsStringEnum(values)`
+- JSON parser: `parseAsJson<T>(parseFn)` — validator-agnostic; pass any `(raw: unknown) => T | null` function (Zod, Valibot, etc.)
+- `createParser(config)` — public factory for building custom parsers with the full builder API
+- Builder pattern: `.withDefault(value)` and `.withOptions({ mode })` on all parsers
+- History mode option: `mode: "replace" | "push"` (defaults to `"replace"`)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 andabove
+
+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,5 @@
+# @andabove/vuqs
+
+Type-safe URL query state for Vue 3 — like `ref`, but stored in the URL.
+
+Documentation lives in the [repository root README](https://github.com/andabove/vuqs#readme).

package/dist/index.d.mts

@@ -0,0 +1,154 @@
+import { Ref } from 'vue';
+
+/** JSON primitive values. */
+type JsonPrimitive = string | number | boolean | null;
+/** JSON object values (recursive). */
+interface JsonObject {
+    [key: string]: JsonValue;
+}
+/** JSON array values (recursive). */
+type JsonArray = JsonValue[];
+/** Any value that `JSON.stringify` can round-trip without data loss. */
+type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+/**
+ * Controls how the router updates the URL when the query param changes.
+ * Defaults to "replace" to avoid polluting browser history with every keystroke.
+ */
+interface QueryStateOptions {
+    mode?: "replace" | "push";
+}
+/**
+ * A parser without a default value. The ref it produces is `T | null`,
+ * where null means the query param is absent from the URL.
+ *
+ * Use `.withDefault(value)` to narrow the type to `T` and get a clean URL
+ * when the value equals the default.
+ */
+interface Parser<T> {
+    parse(value: string): T | null;
+    serialize(value: T): string;
+    eq(a: T, b: T): boolean;
+    withDefault(defaultValue: T): ParserWithDefault<T>;
+    withOptions(options: QueryStateOptions): Parser<T>;
+    readonly defaultValue: undefined;
+    readonly options: QueryStateOptions;
+}
+/**
+ * A parser with a known default value. The ref it produces is `Ref<T>` —
+ * never null. When the value equals the default, the query param is removed
+ * from the URL, keeping URLs clean.
+ */
+interface ParserWithDefault<T> {
+    parse(value: string): T | null;
+    serialize(value: T): string;
+    eq(a: T, b: T): boolean;
+    withDefault(defaultValue: T): ParserWithDefault<T>;
+    withOptions(options: QueryStateOptions): ParserWithDefault<T>;
+    readonly defaultValue: T;
+    readonly options: QueryStateOptions;
+}
+
+interface ParserConfig<T> {
+    parse: (value: string) => T | null;
+    serialize: (value: T) => string;
+    eq?: (a: T, b: T) => boolean;
+}
+/**
+ * Creates a typed parser you can pass to `useQueryState`.
+ * Exported so consumers can build custom parsers.
+ */
+declare function createParser<T>(config: ParserConfig<T>, opts?: QueryStateOptions): Parser<T>;
+/** Accepts any string as-is. A noop for serialization. */
+declare const parseAsString: Parser<string>;
+/** Parses with `parseInt` (base 10). Returns null for non-numeric strings. */
+declare const parseAsInteger: Parser<number>;
+/** Parses with `parseFloat`. Returns null for non-numeric strings. */
+declare const parseAsFloat: Parser<number>;
+/**
+ * Parses "true" and "false" only. Any other string (e.g. "1", "yes")
+ * returns null rather than coercing, keeping the URL as the source of truth.
+ */
+declare const parseAsBoolean: Parser<boolean>;
+/**
+ * Validates the query value against a readonly list of string literals.
+ * Returns null if the value is not in the list.
+ *
+ * @example
+ * const sort = useQueryState('sort', parseAsStringLiteral(['asc', 'desc'] as const))
+ */
+declare function parseAsStringLiteral<const Literal extends string>(validValues: readonly Literal[]): Parser<Literal>;
+/**
+ * Validates the query value against a TypeScript string enum.
+ * Returns null if the value is not a member of the enum.
+ *
+ * @example
+ * enum Status { Active = 'active', Inactive = 'inactive' }
+ * const status = useQueryState('status', parseAsStringEnum<Status>(Object.values(Status)))
+ */
+declare function parseAsStringEnum<Enum extends string>(validValues: Enum[]): Parser<Enum>;
+/**
+ * Serializes/deserializes a JSON value in the query string.
+ *
+ * Pass any `(raw: unknown) => T | null` function to validate the parsed JSON.
+ * This is validator-agnostic — works with Zod, Valibot, or any custom logic.
+ * Returns null if the string is not valid JSON or the parse function returns null.
+ *
+ * Uses deep equality (`JSON.stringify` comparison) for the `eq` check so
+ * that setting to the default value still cleans the URL correctly.
+ *
+ * `T` must be JSON-serialisable (`JsonValue`). The `parseFn` must return only
+ * values that `JSON.stringify` can round-trip (no `Date`, `BigInt`, `Map`, etc.).
+ *
+ * @example
+ * // with Valibot
+ * const schema = v.object({ q: v.string() })
+ * const filter = useQueryState('filter', parseAsJson((raw) => {
+ *   const r = v.safeParse(schema, raw)
+ *   return r.success ? r.output : null
+ * }))
+ *
+ * @example
+ * // with Zod
+ * const schema = z.object({ q: z.string() })
+ * const filter = useQueryState('filter', parseAsJson((raw) => {
+ *   const r = schema.safeParse(raw)
+ *   return r.success ? r.data : null
+ * }))
+ */
+declare function parseAsJson<T extends JsonValue>(parseFn: (raw: unknown) => T | null): Parser<T>;
+/**
+ * Encodes an array as a comma-separated query string value.
+ * The separator character is URI-encoded inside item values so it is safe
+ * to use in items that contain the separator character.
+ *
+ * An empty array serializes to an empty string, and an empty string parses
+ * back to an empty array.
+ *
+ * @example
+ * const tags = useQueryState('tags', parseAsArrayOf(parseAsString))
+ * // ?tags=a,b,c  →  ['a', 'b', 'c']
+ */
+declare function parseAsArrayOf<ItemType>(itemParser: Parser<ItemType> | ParserWithDefault<ItemType>, separator?: string): Parser<ItemType[]>;
+
+/**
+ * Binds a typed ref to a URL query parameter.
+ *
+ * When a parser with a default is provided the ref type is `Ref<T>` and the
+ * query param is removed from the URL whenever the value equals the default,
+ * keeping URLs clean (e.g. `/products` instead of `/products?filter=all`).
+ *
+ * When no default is provided the ref type is `Ref<T | null>`, where null
+ * means the param is absent from the URL.
+ *
+ * @example
+ * // Ref<string | null> — null when ?q is absent
+ * const search = useQueryState('q', parseAsString)
+ *
+ * // Ref<number> — URL is clean when page === 1
+ * const page = useQueryState('page', parseAsInteger.withDefault(1))
+ */
+declare function useQueryState<T>(name: string, parser: ParserWithDefault<T>): Ref<T>;
+declare function useQueryState<T>(name: string, parser: Parser<T>): Ref<T | null>;
+
+export { createParser, parseAsArrayOf, parseAsBoolean, parseAsFloat, parseAsInteger, parseAsJson, parseAsString, parseAsStringEnum, parseAsStringLiteral, useQueryState };
+export type { JsonArray, JsonObject, JsonPrimitive, JsonValue, Parser, ParserWithDefault, QueryStateOptions };

package/dist/index.d.ts

@@ -0,0 +1,154 @@
+import { Ref } from 'vue';
+
+/** JSON primitive values. */
+type JsonPrimitive = string | number | boolean | null;
+/** JSON object values (recursive). */
+interface JsonObject {
+    [key: string]: JsonValue;
+}
+/** JSON array values (recursive). */
+type JsonArray = JsonValue[];
+/** Any value that `JSON.stringify` can round-trip without data loss. */
+type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+/**
+ * Controls how the router updates the URL when the query param changes.
+ * Defaults to "replace" to avoid polluting browser history with every keystroke.
+ */
+interface QueryStateOptions {
+    mode?: "replace" | "push";
+}
+/**
+ * A parser without a default value. The ref it produces is `T | null`,
+ * where null means the query param is absent from the URL.
+ *
+ * Use `.withDefault(value)` to narrow the type to `T` and get a clean URL
+ * when the value equals the default.
+ */
+interface Parser<T> {
+    parse(value: string): T | null;
+    serialize(value: T): string;
+    eq(a: T, b: T): boolean;
+    withDefault(defaultValue: T): ParserWithDefault<T>;
+    withOptions(options: QueryStateOptions): Parser<T>;
+    readonly defaultValue: undefined;
+    readonly options: QueryStateOptions;
+}
+/**
+ * A parser with a known default value. The ref it produces is `Ref<T>` —
+ * never null. When the value equals the default, the query param is removed
+ * from the URL, keeping URLs clean.
+ */
+interface ParserWithDefault<T> {
+    parse(value: string): T | null;
+    serialize(value: T): string;
+    eq(a: T, b: T): boolean;
+    withDefault(defaultValue: T): ParserWithDefault<T>;
+    withOptions(options: QueryStateOptions): ParserWithDefault<T>;
+    readonly defaultValue: T;
+    readonly options: QueryStateOptions;
+}
+
+interface ParserConfig<T> {
+    parse: (value: string) => T | null;
+    serialize: (value: T) => string;
+    eq?: (a: T, b: T) => boolean;
+}
+/**
+ * Creates a typed parser you can pass to `useQueryState`.
+ * Exported so consumers can build custom parsers.
+ */
+declare function createParser<T>(config: ParserConfig<T>, opts?: QueryStateOptions): Parser<T>;
+/** Accepts any string as-is. A noop for serialization. */
+declare const parseAsString: Parser<string>;
+/** Parses with `parseInt` (base 10). Returns null for non-numeric strings. */
+declare const parseAsInteger: Parser<number>;
+/** Parses with `parseFloat`. Returns null for non-numeric strings. */
+declare const parseAsFloat: Parser<number>;
+/**
+ * Parses "true" and "false" only. Any other string (e.g. "1", "yes")
+ * returns null rather than coercing, keeping the URL as the source of truth.
+ */
+declare const parseAsBoolean: Parser<boolean>;
+/**
+ * Validates the query value against a readonly list of string literals.
+ * Returns null if the value is not in the list.
+ *
+ * @example
+ * const sort = useQueryState('sort', parseAsStringLiteral(['asc', 'desc'] as const))
+ */
+declare function parseAsStringLiteral<const Literal extends string>(validValues: readonly Literal[]): Parser<Literal>;
+/**
+ * Validates the query value against a TypeScript string enum.
+ * Returns null if the value is not a member of the enum.
+ *
+ * @example
+ * enum Status { Active = 'active', Inactive = 'inactive' }
+ * const status = useQueryState('status', parseAsStringEnum<Status>(Object.values(Status)))
+ */
+declare function parseAsStringEnum<Enum extends string>(validValues: Enum[]): Parser<Enum>;
+/**
+ * Serializes/deserializes a JSON value in the query string.
+ *
+ * Pass any `(raw: unknown) => T | null` function to validate the parsed JSON.
+ * This is validator-agnostic — works with Zod, Valibot, or any custom logic.
+ * Returns null if the string is not valid JSON or the parse function returns null.
+ *
+ * Uses deep equality (`JSON.stringify` comparison) for the `eq` check so
+ * that setting to the default value still cleans the URL correctly.
+ *
+ * `T` must be JSON-serialisable (`JsonValue`). The `parseFn` must return only
+ * values that `JSON.stringify` can round-trip (no `Date`, `BigInt`, `Map`, etc.).
+ *
+ * @example
+ * // with Valibot
+ * const schema = v.object({ q: v.string() })
+ * const filter = useQueryState('filter', parseAsJson((raw) => {
+ *   const r = v.safeParse(schema, raw)
+ *   return r.success ? r.output : null
+ * }))
+ *
+ * @example
+ * // with Zod
+ * const schema = z.object({ q: z.string() })
+ * const filter = useQueryState('filter', parseAsJson((raw) => {
+ *   const r = schema.safeParse(raw)
+ *   return r.success ? r.data : null
+ * }))
+ */
+declare function parseAsJson<T extends JsonValue>(parseFn: (raw: unknown) => T | null): Parser<T>;
+/**
+ * Encodes an array as a comma-separated query string value.
+ * The separator character is URI-encoded inside item values so it is safe
+ * to use in items that contain the separator character.
+ *
+ * An empty array serializes to an empty string, and an empty string parses
+ * back to an empty array.
+ *
+ * @example
+ * const tags = useQueryState('tags', parseAsArrayOf(parseAsString))
+ * // ?tags=a,b,c  →  ['a', 'b', 'c']
+ */
+declare function parseAsArrayOf<ItemType>(itemParser: Parser<ItemType> | ParserWithDefault<ItemType>, separator?: string): Parser<ItemType[]>;
+
+/**
+ * Binds a typed ref to a URL query parameter.
+ *
+ * When a parser with a default is provided the ref type is `Ref<T>` and the
+ * query param is removed from the URL whenever the value equals the default,
+ * keeping URLs clean (e.g. `/products` instead of `/products?filter=all`).
+ *
+ * When no default is provided the ref type is `Ref<T | null>`, where null
+ * means the param is absent from the URL.
+ *
+ * @example
+ * // Ref<string | null> — null when ?q is absent
+ * const search = useQueryState('q', parseAsString)
+ *
+ * // Ref<number> — URL is clean when page === 1
+ * const page = useQueryState('page', parseAsInteger.withDefault(1))
+ */
+declare function useQueryState<T>(name: string, parser: ParserWithDefault<T>): Ref<T>;
+declare function useQueryState<T>(name: string, parser: Parser<T>): Ref<T | null>;
+
+export { createParser, parseAsArrayOf, parseAsBoolean, parseAsFloat, parseAsInteger, parseAsJson, parseAsString, parseAsStringEnum, parseAsStringLiteral, useQueryState };
+export type { JsonArray, JsonObject, JsonPrimitive, JsonValue, Parser, ParserWithDefault, QueryStateOptions };

package/dist/index.mjs

@@ -0,0 +1,132 @@
+import { useRouteQuery } from '@vueuse/router';
+
+function createParser(config, opts = {}) {
+  const eq = config.eq ?? ((a, b) => a === b);
+  return {
+    parse: config.parse,
+    serialize: config.serialize,
+    eq,
+    defaultValue: void 0,
+    options: opts,
+    withDefault(defaultValue) {
+      return createParserWithDefault(config, defaultValue, opts);
+    },
+    withOptions(options) {
+      return createParser(config, { ...opts, ...options });
+    }
+  };
+}
+function createParserWithDefault(config, defaultVal, opts = {}) {
+  const eq = config.eq ?? ((a, b) => a === b);
+  return {
+    parse: config.parse,
+    serialize: config.serialize,
+    eq,
+    defaultValue: defaultVal,
+    options: opts,
+    withDefault(defaultValue) {
+      return createParserWithDefault(config, defaultValue, opts);
+    },
+    withOptions(options) {
+      return createParserWithDefault(config, defaultVal, { ...opts, ...options });
+    }
+  };
+}
+const parseAsString = createParser({
+  parse: (value) => value,
+  serialize: (value) => value
+});
+const parseAsInteger = createParser({
+  parse: (value) => {
+    const n = parseInt(value, 10);
+    return isNaN(n) ? null : n;
+  },
+  serialize: (value) => String(Math.round(value))
+});
+const parseAsFloat = createParser({
+  parse: (value) => {
+    const n = parseFloat(value);
+    return isNaN(n) ? null : n;
+  },
+  serialize: (value) => String(value)
+});
+const parseAsBoolean = createParser({
+  parse: (value) => {
+    if (value === "true") return true;
+    if (value === "false") return false;
+    return null;
+  },
+  serialize: (value) => String(value)
+});
+function parseAsStringLiteral(validValues) {
+  return createParser({
+    parse: (query) => validValues.includes(query) ? query : null,
+    serialize: (value) => value
+  });
+}
+function parseAsStringEnum(validValues) {
+  return parseAsStringLiteral(validValues);
+}
+function parseAsJson(parseFn) {
+  return createParser({
+    parse: (str) => {
+      try {
+        return parseFn(JSON.parse(str));
+      } catch {
+        return null;
+      }
+    },
+    serialize: (value) => JSON.stringify(value),
+    eq: (a, b) => a === b || JSON.stringify(a) === JSON.stringify(b)
+  });
+}
+function parseAsArrayOf(itemParser, separator = ",") {
+  return createParser({
+    parse: (query) => {
+      if (query === "") return [];
+      return query.split(separator).map((item) => {
+        try {
+          return itemParser.parse(decodeURIComponent(item));
+        } catch {
+          return null;
+        }
+      }).filter((value) => value !== null);
+    },
+    serialize: (values) => values.map((value) => encodeURIComponent(itemParser.serialize(value))).join(separator),
+    eq: (a, b) => {
+      if (a === b) return true;
+      if (a.length !== b.length) return false;
+      const itemEq = itemParser.eq.bind(itemParser);
+      return a.every((value, index) => itemEq(value, b[index]));
+    }
+  });
+}
+
+function resolveRawString(v) {
+  if (v === null || v === void 0) return null;
+  if (Array.isArray(v)) return v[0] ?? null;
+  return v;
+}
+function useQueryState(name, parser) {
+  const hasDefault = parser.defaultValue !== void 0;
+  const defaultValue = hasDefault ? parser.defaultValue : null;
+  const mode = parser.options.mode ?? "replace";
+  return useRouteQuery(name, null, {
+    mode,
+    transform: {
+      get(v) {
+        const str = resolveRawString(v);
+        if (str === null) return defaultValue;
+        const parsed = parser.parse(str);
+        return parsed ?? defaultValue;
+      },
+      set(v) {
+        if (v === null) return null;
+        if (hasDefault && parser.eq(v, defaultValue)) return null;
+        return parser.serialize(v);
+      }
+    }
+  });
+}
+
+export { createParser, parseAsArrayOf, parseAsBoolean, parseAsFloat, parseAsInteger, parseAsJson, parseAsString, parseAsStringEnum, parseAsStringLiteral, useQueryState };

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@andabove/vuqs",
+  "version": "0.1.0",
+  "description": "Type-safe URL query state for Vue 3 — like ref, but stored in the URL",
+  "keywords": [
+    "composable",
+    "query-state",
+    "search-params",
+    "type-safe",
+    "url",
+    "vue",
+    "vue-router",
+    "vue3"
+  ],
+  "homepage": "https://github.com/andabove/vuqs#readme",
+  "bugs": {
+    "url": "https://github.com/andabove/vuqs/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/andabove/vuqs",
+    "directory": "packages/vuqs"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@vueuse/router": "^14.3.0",
+    "happy-dom": "^20.9.0",
+    "typescript": "^5.9.2",
+    "unbuild": "^3.6.1",
+    "valibot": "^1.4.0",
+    "vitest": "^4.1.7",
+    "vue": "^3.5.34",
+    "vue-router": "^4",
+    "vue-tsc": "^3.3.1"
+  },
+  "peerDependencies": {
+    "@vueuse/router": "^14.0.0",
+    "vue": ">=3.5",
+    "vue-router": "^4"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "typecheck": "vue-tsc --noEmit -p tsconfig.json"
+  }
+}