usewagen 0.0.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahmet Tinastepe
+
+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,31 @@
+# usewagen
+
+Reactive state for URL and storage in Vue. Type-safe, with the source always in charge.
+
+Documentation lives at [usewagen.dev](https://usewagen.dev).
+
+## Install
+
+```sh
+pnpm add usewagen
+```
+
+`vue` is a peer dependency. `vue-router` is only needed if you use the router composables.
+
+## Usage
+
+```ts
+import { parseAsInteger } from 'usewagen'
+import { useRouteState } from 'usewagen/router'
+import { useLocalStorage } from 'usewagen/storage'
+
+const page = useRouteState({ key: 'page', parser: parseAsInteger.withDefault(1) })
+const theme = useLocalStorage({ key: 'theme' })
+```
+
+`page` is a `Ref<number>` over `?page=` and `theme` a `Ref<string | null>` over the `theme`
+entry in `localStorage`.
+
+## License
+
+[MIT](./LICENSE)

package/client.d.ts

@@ -0,0 +1,5 @@
+declare module 'virtual:usewagen/parsers' {
+  import type { Parser } from 'usewagen'
+
+  export const parsers: Record<string, Parser<any>>
+}

package/dist/builtins-DiCjLgsG.mjs

@@ -0,0 +1,15 @@
+import { a as parseAsFloat, i as parseAsDate, o as parseAsIndex, r as parseAsBoolean, s as parseAsInteger, u as parseAsString } from "./parsers-CA8aZuF-.mjs";
+//#region src/parser/builtins.ts
+const builtinParsers = {
+	parseAsString,
+	parseAsInteger,
+	parseAsFloat,
+	parseAsIndex,
+	parseAsBoolean,
+	parseAsDate
+};
+function isBuiltinParserName(name) {
+	return Object.hasOwn(builtinParsers, name);
+}
+//#endregion
+export { isBuiltinParserName as n, builtinParsers as t };

package/dist/create-storage-DESmB4bY.d.mts

@@ -0,0 +1,38 @@
+//#region src/storage/create-storage.d.ts
+type ErrorHandler = (error: unknown) => void;
+type Unsubscribe = () => void;
+type KeyListener = () => void;
+type StorageListener = (key: string | null) => void;
+interface StorageAdapter {
+  getItem: (key: string) => string | null;
+  setItem: (key: string, value: string) => void;
+  removeItem: (key: string) => void;
+  keys: () => string[];
+  watch?: (onChange: (key: string | null) => void) => Unsubscribe;
+}
+interface StorageConfig {
+  prefix?: string;
+  crossTab?: boolean;
+  onError?: ErrorHandler;
+}
+type StorageOptions = StorageAdapter & StorageConfig;
+interface StorageInstance {
+  readonly name: string;
+  readonly prefix: string;
+  getItem: (key: string) => string | null;
+  setItem: (key: string, value: string) => void;
+  removeItem: (key: string) => void;
+  has: (key: string) => boolean;
+  keys: () => string[];
+  clear: (options?: {
+    except?: string[];
+  }) => void;
+  subscribe: {
+    (key: string, listener: KeyListener): Unsubscribe;
+    (listener: StorageListener): Unsubscribe;
+  };
+  destroy: () => void;
+}
+declare function createStorage(name: string, options: StorageOptions): StorageInstance;
+//#endregion
+export { StorageInstance as a, Unsubscribe as c, StorageConfig as i, createStorage as l, KeyListener as n, StorageListener as o, StorageAdapter as r, StorageOptions as s, ErrorHandler as t };

package/dist/index.d.mts

@@ -0,0 +1,46 @@
+import { A as unwrapDefault, C as parseAsInteger, D as parseAsStringEnum, E as parseAsString, O as parseAsStringLiteral, S as parseAsIndex, T as parseAsNumberLiteral, _ as defineParser, a as CustomParsers, b as parseAsDate, c as InferParserValue, d as UnwrapParser, f as WithParser, g as ParserWithDefault, h as ParserOptions, i as BuiltinParsers, k as tryParse, l as KnownParsers, m as Parser, o as InferInputValue, p as DefaultValue, r as StateMode, s as InferInputWritable, u as ParserInput, v as parseAsArrayOf, w as parseAsJson, x as parseAsFloat, y as parseAsBoolean } from "./types-JtRmT3qo.mjs";
+import { i as RouteStateSource, t as HistoryMode } from "./types-fVW6rBJ3.mjs";
+import { a as StorageInstance, t as ErrorHandler } from "./create-storage-DESmB4bY.mjs";
+import { App } from "vue";
+//#region src/wagen.d.ts
+interface WagenStorageOptions {
+  prefix?: string;
+  crossTab?: boolean;
+  onError?: ErrorHandler;
+  local?: StorageInstance;
+  session?: StorageInstance;
+  default?: 'local' | 'session';
+  mode?: StateMode;
+}
+interface WagenRouterOptions {
+  history?: HistoryMode;
+  source?: RouteStateSource;
+  clearOnDefault?: boolean;
+  mode?: StateMode;
+}
+type WagenParsers = Record<string, Parser<any>>;
+interface WagenConfig {
+  parsers?: WagenParsers;
+  storage?: WagenStorageOptions;
+  router?: WagenRouterOptions;
+}
+interface WagenStorage {
+  readonly local: StorageInstance;
+  readonly session: StorageInstance;
+  readonly default: StorageInstance;
+  readonly mode: StateMode;
+}
+type ResolvedWagenRouterOptions = Required<WagenRouterOptions>;
+interface Wagen {
+  readonly parsers: WagenParsers;
+  readonly storage: WagenStorage;
+  readonly router: ResolvedWagenRouterOptions;
+  install: (app: App) => void;
+  destroy: () => void;
+}
+export declare function defineWagenConfig(config: WagenConfig): WagenConfig;
+export declare function createWagen(config?: WagenConfig): Wagen;
+export declare function getActiveWagen(): Wagen;
+export declare function useWagen(): Wagen;
+//#endregion
+export { type BuiltinParsers, type CustomParsers, DefaultValue, type InferInputValue, type InferInputWritable, type InferParserValue, type KnownParsers, Parser, type ParserInput, ParserOptions, ParserWithDefault, type ResolvedWagenRouterOptions, type StateMode, type UnwrapParser, type Wagen, type WagenConfig, type WagenParsers, type WagenRouterOptions, type WagenStorage, type WagenStorageOptions, type WithParser, defineParser, parseAsArrayOf, parseAsBoolean, parseAsDate, parseAsFloat, parseAsIndex, parseAsInteger, parseAsJson, parseAsNumberLiteral, parseAsString, parseAsStringEnum, parseAsStringLiteral, tryParse, unwrapDefault };

package/dist/index.mjs

@@ -0,0 +1,4 @@
+import { a as parseAsFloat, c as parseAsJson, d as parseAsStringEnum, f as parseAsStringLiteral, i as parseAsDate, l as parseAsNumberLiteral, m as unwrapDefault, n as parseAsArrayOf, o as parseAsIndex, p as tryParse, r as parseAsBoolean, s as parseAsInteger, t as defineParser, u as parseAsString } from "./parsers-CA8aZuF-.mjs";
+import "./parser-B6hfbAwA.mjs";
+import { i as useWagen, n as defineWagenConfig, r as getActiveWagen, t as createWagen } from "./wagen-C2p8oQgu.mjs";
+export { createWagen, defineParser, defineWagenConfig, getActiveWagen, parseAsArrayOf, parseAsBoolean, parseAsDate, parseAsFloat, parseAsIndex, parseAsInteger, parseAsJson, parseAsNumberLiteral, parseAsString, parseAsStringEnum, parseAsStringLiteral, tryParse, unwrapDefault, useWagen };

package/dist/parser-B6hfbAwA.mjs

@@ -0,0 +1,2 @@
+import "./parsers-CA8aZuF-.mjs";
+export {};

package/dist/parsers-CA8aZuF-.mjs

@@ -0,0 +1,156 @@
+//#region src/messages.ts
+const PREFIX = "[usewagen]";
+const ErrorCodes = {
+	PARSE_FAILED: 0,
+	UNKNOWN_PARSER_NAME: 1,
+	WEB_STORAGE_UNAVAILABLE: 2,
+	RESERVED_PARSER_NAME: 3,
+	DUPLICATE_PARSER_NAME: 4,
+	NO_INJECTION_CONTEXT: 5,
+	NO_EFFECT_SCOPE: 6
+};
+const errorMessages = {
+	[ErrorCodes.PARSE_FAILED]: "Failed to parse the input:",
+	[ErrorCodes.UNKNOWN_PARSER_NAME]: "No parser is registered under this name; falling back to `parseAsString`. Pass it to `createWagen({ parsers })`:",
+	[ErrorCodes.WEB_STORAGE_UNAVAILABLE]: "The storage area is not accessible; falling back to in-memory storage. Values will not persist:",
+	[ErrorCodes.RESERVED_PARSER_NAME]: "Skipping a parser whose name is reserved by a built-in:",
+	[ErrorCodes.DUPLICATE_PARSER_NAME]: "A parser with this name was already found in another file — the last one wins:",
+	[ErrorCodes.NO_INJECTION_CONTEXT]: "Composables should be called inside `setup()` or a function that runs in an injection context; falling back to the active instance. Outside one, use `getActiveWagen()` or the `define*` APIs:",
+	[ErrorCodes.NO_EFFECT_SCOPE]: "Composables should be called inside `setup()` or a running effect scope; outside one the effects they create are never released, which leaks:"
+};
+function getMessage(code) {
+	return `${PREFIX} ${errorMessages[code]}`;
+}
+function warn(code, ...details) {
+	console.warn(getMessage(code), ...details);
+}
+function warnDev(code, ...details) {
+	if (process.env.NODE_ENV !== "production") warn(code, ...details);
+}
+//#endregion
+//#region src/parser/parsers.ts
+function tryParse(fn, input) {
+	try {
+		return fn(input);
+	} catch (error) {
+		warn(ErrorCodes.PARSE_FAILED, input, error);
+		return null;
+	}
+}
+function defineParser(options) {
+	const parse = options.parse;
+	const serialize = options.serialize ?? String;
+	return {
+		parse,
+		serialize,
+		withDefault(value) {
+			const parser = defineParser({
+				parse,
+				serialize
+			});
+			Object.defineProperty(parser, "defaultValue", {
+				value,
+				enumerable: true
+			});
+			return parser;
+		}
+	};
+}
+function unwrapDefault(value) {
+	return typeof value === "function" ? value() : value;
+}
+const parseAsString = defineParser({
+	parse: (v) => v,
+	serialize: String
+});
+const parseAsInteger = defineParser({
+	parse: (v) => {
+		const n = Number.parseInt(v, 10);
+		return Number.isNaN(n) ? null : n;
+	},
+	serialize: (v) => Math.trunc(v).toString()
+});
+const parseAsFloat = defineParser({
+	parse: (v) => {
+		const n = Number.parseFloat(v);
+		return Number.isNaN(n) ? null : n;
+	},
+	serialize: (v) => v.toString()
+});
+const parseAsIndex = defineParser({
+	parse: (v) => {
+		const n = Number.parseInt(v, 10);
+		return Number.isNaN(n) ? null : n - 1;
+	},
+	serialize: (v) => (Math.trunc(v) + 1).toString()
+});
+const parseAsBoolean = defineParser({
+	parse: (v) => v === "true" ? true : v === "false" ? false : null,
+	serialize: (v) => v ? "true" : "false"
+});
+function parseAsStringLiteral(values) {
+	return defineParser({
+		parse: (v) => values.includes(v) ? v : null,
+		serialize: (v) => v.toString()
+	});
+}
+function parseAsNumberLiteral(values) {
+	return defineParser({
+		parse: (v) => {
+			const n = Number.parseFloat(v);
+			return values.includes(n) ? n : null;
+		},
+		serialize: (v) => v.toString()
+	});
+}
+function parseAsStringEnum(values) {
+	return parseAsStringLiteral(values);
+}
+const parseAsDate = Object.assign(defineParser({
+	parse: (v) => {
+		const d = new Date(v.includes("T") ? v : `${v}T00:00:00.000Z`);
+		return Number.isNaN(d.getTime()) ? null : d;
+	},
+	serialize: (v) => v.toISOString().slice(0, 10)
+}), {
+	iso: () => defineParser({
+		parse: (v) => {
+			const d = new Date(v);
+			return Number.isNaN(d.getTime()) ? null : d;
+		},
+		serialize: (v) => v.toISOString()
+	}),
+	timestamp: () => defineParser({
+		parse: (v) => {
+			const n = Number.parseInt(v, 10);
+			if (Number.isNaN(n)) return null;
+			const d = new Date(n);
+			return Number.isNaN(d.getTime()) ? null : d;
+		},
+		serialize: (v) => v.getTime().toString()
+	})
+});
+function parseAsArrayOf(itemParser, separator = ",") {
+	const encodedSeparator = encodeURIComponent(separator);
+	return defineParser({
+		parse: (raw) => {
+			if (raw === "") return [];
+			return raw.split(separator).map((item) => tryParse(itemParser.parse, item.replaceAll(encodedSeparator, separator))).filter((value) => value !== null);
+		},
+		serialize: (values) => values.map((value) => itemParser.serialize(value).replaceAll(separator, encodedSeparator)).join(separator)
+	});
+}
+function parseAsJson() {
+	return defineParser({
+		parse: (v) => {
+			try {
+				return JSON.parse(v);
+			} catch {
+				return null;
+			}
+		},
+		serialize: (v) => JSON.stringify(v)
+	});
+}
+//#endregion
+export { warnDev as _, parseAsFloat as a, parseAsJson as c, parseAsStringEnum as d, parseAsStringLiteral as f, warn as g, ErrorCodes as h, parseAsDate as i, parseAsNumberLiteral as l, unwrapDefault as m, parseAsArrayOf as n, parseAsIndex as o, tryParse as p, parseAsBoolean as r, parseAsInteger as s, defineParser as t, parseAsString as u };

package/dist/router/index.d.mts

@@ -0,0 +1,42 @@
+import { f as WithParser, n as ReactiveOptions, o as InferInputValue, r as StateMode, s as InferInputWritable, t as ReactiveFields, u as ParserInput } from "../types-JtRmT3qo.mjs";
+import { i as RouteStateSource, n as ResolvedRouteStateOptions, r as RouteStateOptions, t as HistoryMode } from "../types-fVW6rBJ3.mjs";
+import { Ref } from "vue";
+//#region src/router/use-route-hash.d.ts
+interface RouteHashOptions {
+  parser?: ParserInput;
+  history?: HistoryMode;
+  clearOnDefault?: boolean;
+  mode?: StateMode;
+}
+type UseRouteHashOptions<P extends ParserInput | undefined = ParserInput | undefined> = ReactiveOptions<WithParser<RouteHashOptions, P>>;
+type RouteHashConfig = ReactiveFields<RouteHashOptions>;
+export declare function useRouteHash<P extends ParserInput | undefined = undefined>(options?: UseRouteHashOptions<P>): Ref<InferInputValue<P>, InferInputWritable<P>>;
+//#endregion
+//#region src/router/use-route-states.d.ts
+type RouteStateConfig<P extends ParserInput | undefined = ParserInput | undefined> = ReactiveFields<WithParser<RouteStateOptions, P>, 'key'>;
+interface BatchOptions {
+  history?: HistoryMode;
+}
+type Refs<TOptions extends readonly RouteStateConfig[]> = { [TOption in TOptions[number] as TOption['key']]: Ref<InferInputValue<TOption['parser']>, InferInputWritable<TOption['parser']>>; };
+type StatePatch<TOptions extends readonly RouteStateConfig[]> = Partial<{ [TOption in TOptions[number] as TOption['key']]: InferInputWritable<TOption['parser']>; }>;
+type StateSnapshot<TOptions extends readonly RouteStateConfig[]> = { [TOption in TOptions[number] as TOption['key']]: InferInputValue<TOption['parser']>; };
+interface UseRouteStatesApi<TOptions extends readonly RouteStateConfig[]> {
+  set: (patch: StatePatch<TOptions>, options?: BatchOptions) => void;
+  reset: (options?: BatchOptions) => void;
+  toObject: () => StateSnapshot<TOptions>;
+}
+type UseRouteStatesReturn<TOptions extends readonly RouteStateConfig[]> = Refs<TOptions> & UseRouteStatesApi<TOptions>;
+export declare function useRouteStates<const TOptions extends readonly RouteStateConfig[]>(configs: TOptions): UseRouteStatesReturn<TOptions>;
+//#endregion
+//#region src/router/options.d.ts
+type Exact<T, TShape> = T & Record<Exclude<keyof T, keyof TShape>, never>;
+export declare function routeStateOptions<const T extends RouteStateConfig>(options: Exact<T, RouteStateConfig>): T;
+export declare function routeStateOptions<const T extends RouteStateConfig>(options: () => Exact<T, RouteStateConfig>): () => T;
+export declare function routeHashOptions<const T extends RouteHashConfig>(options: Exact<T, RouteHashConfig>): T;
+export declare function routeHashOptions<const T extends RouteHashConfig>(options: () => Exact<T, RouteHashConfig>): () => T;
+//#endregion
+//#region src/router/use-route-state.d.ts
+type UseRouteStateOptions<P extends ParserInput | undefined = ParserInput | undefined> = ReactiveOptions<WithParser<RouteStateOptions, P>>;
+export declare function useRouteState<P extends ParserInput | undefined = undefined>(options: UseRouteStateOptions<P>): Ref<InferInputValue<P>, InferInputWritable<P>>;
+//#endregion
+export type { BatchOptions, HistoryMode, ResolvedRouteStateOptions, RouteHashConfig, RouteHashOptions, RouteStateConfig, RouteStateOptions, RouteStateSource, StateMode, UseRouteHashOptions, UseRouteStateOptions, UseRouteStatesApi, UseRouteStatesReturn };

package/dist/router/index.mjs

@@ -0,0 +1,273 @@
+import { _ as warnDev, h as ErrorCodes, m as unwrapDefault } from "../parsers-CA8aZuF-.mjs";
+import "../parser-B6hfbAwA.mjs";
+import { r as getActiveWagen } from "../wagen-C2p8oQgu.mjs";
+import { a as toValueDeep, i as resolveParser, n as parseValue, r as serializeValue, t as normalizeRaw } from "../utils-EL2EiRpH.mjs";
+import { computed, customRef, getCurrentScope, nextTick, toValue } from "vue";
+import { useRoute, useRouter } from "vue-router";
+//#region src/router/options.ts
+function routeStateOptions(options) {
+	return options;
+}
+function routeHashOptions(options) {
+	return options;
+}
+//#endregion
+//#region src/router/queue.ts
+const batches = /* @__PURE__ */ new WeakMap();
+function resolveBatchHistory(candidates, override) {
+	if (override) return override;
+	return candidates.includes("push") ? "push" : "replace";
+}
+function enqueue(router, write) {
+	let batch = batches.get(router);
+	if (!batch) {
+		const created = {
+			changes: [],
+			histories: [],
+			hash: void 0,
+			settled: Promise.resolve()
+		};
+		created.settled = nextTick().then(() => flush(router, created));
+		batches.set(router, created);
+		batch = created;
+	}
+	if (write.changes) batch.changes.push(...write.changes);
+	if (write.hash !== void 0) batch.hash = write.hash;
+	batch.histories.push(write.history);
+	return batch.settled;
+}
+function flush(router, batch) {
+	if (batches.get(router) === batch) batches.delete(router);
+	const route = router.currentRoute.value;
+	const params = { ...route.params };
+	const query = { ...route.query };
+	let changed = false;
+	for (const change of batch.changes) {
+		const target = change.source === "params" ? params : query;
+		const current = target[change.urlKey];
+		if (Array.isArray(current)) changed = true;
+		else if (change.serialized === null) changed ||= current !== void 0;
+		else changed ||= current !== change.serialized;
+		target[change.urlKey] = change.serialized === null ? void 0 : change.serialized;
+	}
+	const hash = batch.hash === void 0 ? route.hash : batch.hash ?? "";
+	changed ||= hash !== route.hash;
+	if (!changed) return Promise.resolve();
+	return router[resolveBatchHistory(batch.histories)]({
+		params,
+		query,
+		hash: hash === "" ? void 0 : hash
+	}).then(() => {}, () => {});
+}
+//#endregion
+//#region src/router/use-route-hash.ts
+function toResolvedHashOptions(options, defaults) {
+	return {
+		parser: resolveParser(options.parser),
+		history: options.history ?? defaults.history,
+		clearOnDefault: options.clearOnDefault ?? defaults.clearOnDefault,
+		mode: options.mode ?? defaults.mode
+	};
+}
+function useRouteHash(options = {}) {
+	if (!getCurrentScope()) warnDev(ErrorCodes.NO_EFFECT_SCOPE, "useRouteHash");
+	const route = useRoute();
+	const router = useRouter();
+	const defaults = getActiveWagen().router;
+	const resolvedOptions = computed(() => toResolvedHashOptions(toValueDeep(options), defaults));
+	let cache = null;
+	let generation = 0;
+	let trigger;
+	function currentHash() {
+		return route.hash === "" ? null : route.hash;
+	}
+	return customRef((track, triggerRef) => {
+		trigger = triggerRef;
+		return {
+			get: () => {
+				track();
+				const { parser, mode } = resolvedOptions.value;
+				const current = currentHash();
+				if (mode === "source") {
+					cache = null;
+					return parseValue(parser, current);
+				}
+				if (cache && cache.seen === current) return parseValue(parser, cache.raw);
+				cache = {
+					seen: current,
+					raw: current
+				};
+				return parseValue(parser, current);
+			},
+			set: (next) => {
+				const { parser, clearOnDefault, history, mode } = resolvedOptions.value;
+				const serialized = serializeValue(parser, clearOnDefault, next);
+				const optimistic = mode === "optimistic";
+				const own = ++generation;
+				if (optimistic) {
+					cache = {
+						seen: currentHash(),
+						raw: serialized
+					};
+					trigger();
+				}
+				enqueue(router, {
+					history,
+					hash: serialized
+				}).then(() => {
+					if (!optimistic || generation !== own) return;
+					cache = null;
+					trigger();
+				});
+			}
+		};
+	});
+}
+//#endregion
+//#region src/router/use-base-route-state.ts
+function useBaseRouteState() {
+	const route = useRoute();
+	const router = useRouter();
+	function createRouteStateRef(options) {
+		let cache = null;
+		let generation = 0;
+		let trigger;
+		function rawValue(urlKey, source) {
+			return source === "params" ? route.params[urlKey] : route.query[urlKey];
+		}
+		const state = customRef((track, triggerRef) => {
+			trigger = triggerRef;
+			return {
+				get: () => {
+					track();
+					const { urlKey, source, parser, mode } = toValue(options);
+					const current = normalizeRaw(rawValue(urlKey, source));
+					if (mode === "source") {
+						cache = null;
+						return parseValue(parser, current);
+					}
+					if (cache && cache.seen === current) return parseValue(parser, cache.raw);
+					cache = {
+						seen: current,
+						raw: current
+					};
+					return parseValue(parser, current);
+				},
+				set: (next) => {
+					const { parser, clearOnDefault } = toValue(options);
+					write(serializeValue(parser, clearOnDefault, next));
+				}
+			};
+		});
+		function write(serialized, history) {
+			const resolved = toValue(options);
+			const optimistic = resolved.mode === "optimistic";
+			const current = ++generation;
+			if (optimistic) {
+				cache = {
+					seen: normalizeRaw(rawValue(resolved.urlKey, resolved.source)),
+					raw: serialized
+				};
+				trigger();
+			}
+			return enqueue(router, {
+				history: history ?? resolved.history,
+				changes: [{
+					urlKey: resolved.urlKey,
+					source: resolved.source,
+					serialized
+				}]
+			}).then(() => {
+				if (!optimistic || generation !== current) return;
+				cache = null;
+				trigger();
+			});
+		}
+		return {
+			state,
+			write
+		};
+	}
+	return { createRouteStateRef };
+}
+//#endregion
+//#region src/router/utils.ts
+function toResolvedOptions(input, defaults) {
+	return {
+		key: input.key,
+		parser: resolveParser(input.parser),
+		urlKey: input.urlKey ?? input.key,
+		source: input.source ?? defaults.source,
+		history: input.history ?? defaults.history,
+		clearOnDefault: input.clearOnDefault ?? defaults.clearOnDefault,
+		mode: input.mode ?? defaults.mode
+	};
+}
+//#endregion
+//#region src/router/use-route-state.ts
+function useRouteState(options) {
+	if (!getCurrentScope()) warnDev(ErrorCodes.NO_EFFECT_SCOPE, "useRouteState");
+	const { createRouteStateRef } = useBaseRouteState();
+	const defaults = getActiveWagen().router;
+	return createRouteStateRef(computed(() => toResolvedOptions(toValueDeep(options), defaults))).state;
+}
+//#endregion
+//#region src/router/use-route-states.ts
+function useRouteStates(configs) {
+	if (!getCurrentScope()) warnDev(ErrorCodes.NO_EFFECT_SCOPE, "useRouteStates");
+	const { createRouteStateRef } = useBaseRouteState();
+	const defaults = getActiveWagen().router;
+	const resolvedList = configs.map((config) => computed(() => toResolvedOptions(toValueDeep(config), defaults)));
+	const handles = resolvedList.map((resolved) => createRouteStateRef(resolved));
+	const refs = Object.fromEntries(resolvedList.map((resolved, index) => [resolved.value.key, handles[index].state]));
+	function commit(writes, candidates, override) {
+		if (writes.length === 0) return;
+		const history = resolveBatchHistory(candidates, override);
+		for (const { handle, serialized } of writes) handle.write(serialized, history);
+	}
+	const api = {
+		set(patch, options) {
+			const writes = [];
+			const candidates = [];
+			resolvedList.forEach((resolved, index) => {
+				const { key, parser, clearOnDefault, history } = resolved.value;
+				if (!(key in patch)) return;
+				const next = patch[key];
+				writes.push({
+					handle: handles[index],
+					serialized: serializeValue(parser, clearOnDefault, next)
+				});
+				candidates.push(history);
+			});
+			commit(writes, candidates, options?.history);
+		},
+		reset(options) {
+			const writes = [];
+			const candidates = [];
+			resolvedList.forEach((resolved, index) => {
+				const { parser, clearOnDefault, history } = resolved.value;
+				const next = parser.defaultValue !== void 0 ? unwrapDefault(parser.defaultValue) : null;
+				writes.push({
+					handle: handles[index],
+					serialized: serializeValue(parser, clearOnDefault, next)
+				});
+				candidates.push(history);
+			});
+			commit(writes, candidates, options?.history);
+		},
+		toObject() {
+			const snapshot = {};
+			for (const resolved of resolvedList) {
+				const { key } = resolved.value;
+				snapshot[key] = refs[key].value;
+			}
+			return snapshot;
+		}
+	};
+	return {
+		...refs,
+		...api
+	};
+}
+//#endregion
+export { routeHashOptions, routeStateOptions, useRouteHash, useRouteState, useRouteStates };

package/dist/storage/index.d.mts

@@ -0,0 +1,37 @@
+import { f as WithParser, n as ReactiveOptions, o as InferInputValue, r as StateMode, s as InferInputWritable, u as ParserInput } from "../types-JtRmT3qo.mjs";
+import { a as StorageInstance, c as Unsubscribe, i as StorageConfig, l as createStorage, n as KeyListener, o as StorageListener, r as StorageAdapter, s as StorageOptions, t as ErrorHandler } from "../create-storage-DESmB4bY.mjs";
+import { Ref } from "vue";
+//#region src/storage/define-storage-state.d.ts
+type StorageSource = StorageInstance | 'local' | 'session';
+interface StorageStateOptions {
+  key: string;
+  storage?: StorageSource;
+  parser?: ParserInput;
+  clearOnDefault?: boolean;
+  mode?: StateMode;
+}
+interface StorageState<T = string | null, W = T | null | undefined> {
+  readonly key: string;
+  readonly storage: StorageInstance;
+  get: () => T;
+  set: (value: W) => void;
+  remove: () => void;
+  subscribe: (listener: () => void) => Unsubscribe;
+}
+export declare function defineStorageState<P extends ParserInput | undefined = undefined>(options: WithParser<StorageStateOptions, P>): StorageState<InferInputValue<P>, InferInputWritable<P>>;
+//#endregion
+//#region src/storage/presets.d.ts
+export declare function createMemoryStorage(config?: StorageConfig): StorageInstance;
+export declare function createLocalStorage(config?: StorageConfig): StorageInstance;
+export declare function createSessionStorage(config?: StorageConfig): StorageInstance;
+//#endregion
+//#region src/storage/use-storage.d.ts
+type UseStorageOptions<P extends ParserInput | undefined = ParserInput | undefined> = ReactiveOptions<WithParser<StorageStateOptions, P>>;
+type UseLocalStorageOptions<P extends ParserInput | undefined = ParserInput | undefined> = ReactiveOptions<WithParser<Omit<StorageStateOptions, 'storage'>, P>>;
+type UseSessionStorageOptions<P extends ParserInput | undefined = ParserInput | undefined> = UseLocalStorageOptions<P>;
+export declare function useStorage<T, W>(state: StorageState<T, W>): Ref<T, W>;
+export declare function useStorage<P extends ParserInput | undefined = undefined>(options: UseStorageOptions<P>): Ref<InferInputValue<P>, InferInputWritable<P>>;
+export declare function useLocalStorage<P extends ParserInput | undefined = undefined>(options: UseLocalStorageOptions<P>): Ref<InferInputValue<P>, InferInputWritable<P>>;
+export declare function useSessionStorage<P extends ParserInput | undefined = undefined>(options: UseSessionStorageOptions<P>): Ref<InferInputValue<P>, InferInputWritable<P>>;
+//#endregion
+export { type ErrorHandler, type KeyListener, type StateMode, type StorageAdapter, type StorageConfig, type StorageInstance, type StorageListener, type StorageOptions, type StorageSource, type StorageState, type StorageStateOptions, type Unsubscribe, type UseLocalStorageOptions, type UseSessionStorageOptions, type UseStorageOptions, createStorage };