usewagen 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # usewagen
 
-Reactive state for URL and storage in Vue. Type-safe, with the value in exactly one place.
+Reactive state for URL and storage in Vue. Type-safe, with the source always in charge.
 
 Documentation lives at [usewagen.dev](https://usewagen.dev).
 

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { C as parseAsStringLiteral, S as parseAsStringEnum, T as unwrapDefault, _ as parseAsIndex, a as InferParserValue, b as parseAsNumberLiteral, c as DefaultValue, d as ParserWithDefault, f as defineParser, g as parseAsFloat, h as parseAsDate, i as InferInputWritable, l as Parser, m as parseAsBoolean, n as CustomParsers, o as KnownParsers, p as parseAsArrayOf, r as InferInputValue, s as ParserInput, t as BuiltinParsers, u as ParserOptions, v as parseAsInteger, w as tryParse, x as parseAsString, y as parseAsJson } from "./types-CNt2lcP1.mjs";
-import { i as RouteStateSource, t as HistoryMode } from "./types-CuwASQTi.mjs";
+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
@@ -10,11 +10,13 @@ interface WagenStorageOptions {
   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 {
@@ -26,6 +28,7 @@ interface WagenStorage {
   readonly local: StorageInstance;
   readonly session: StorageInstance;
   readonly default: StorageInstance;
+  readonly mode: StateMode;
 }
 type ResolvedWagenRouterOptions = Required<WagenRouterOptions>;
 interface Wagen {
@@ -35,9 +38,9 @@ interface Wagen {
   install: (app: App) => void;
   destroy: () => void;
 }
-declare function defineWagenConfig(config: WagenConfig): WagenConfig;
-declare function createWagen(config?: WagenConfig): Wagen;
-declare function getActiveWagen(): Wagen;
-declare function useWagen(): Wagen;
+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 Wagen, type WagenConfig, type WagenParsers, type WagenRouterOptions, type WagenStorage, type WagenStorageOptions, createWagen, defineParser, defineWagenConfig, getActiveWagen, parseAsArrayOf, parseAsBoolean, parseAsDate, parseAsFloat, parseAsIndex, parseAsInteger, parseAsJson, parseAsNumberLiteral, parseAsString, parseAsStringEnum, parseAsStringLiteral, tryParse, unwrapDefault, useWagen };
+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

@@ -1,4 +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-C9_CPUdF.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/router/index.d.mts

@@ -1,28 +1,19 @@
-import { i as InferInputWritable, r as InferInputValue, s as ParserInput } from "../types-CNt2lcP1.mjs";
-import { i as RouteStateSource, n as ResolvedRouteStateOptions, r as RouteStateOptions, t as HistoryMode } from "../types-CuwASQTi.mjs";
-import { n as ReactiveOptions, t as ReactiveFields } from "../options-BKybciek.mjs";
+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<Omit<RouteHashOptions, 'parser'> & {
-  parser?: P;
-}, 'parser'>;
-declare function useRouteHash<P extends ParserInput | undefined = undefined>(options?: UseRouteHashOptions<P>): Ref<InferInputValue<P>, InferInputWritable<P>>;
-//#endregion
-//#region src/router/use-route-state.d.ts
-type UseRouteStateOptions<P extends ParserInput | undefined = ParserInput | undefined> = ReactiveOptions<Omit<RouteStateOptions, 'parser'> & {
-  parser?: P;
-}, 'parser'>;
-declare function useRouteState<P extends ParserInput | undefined = undefined>(options: UseRouteStateOptions<P>): Ref<InferInputValue<P>, InferInputWritable<P>>;
+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<Omit<RouteStateOptions, 'parser'> & {
-  parser?: P;
-}, 'key' | 'parser'>;
+type RouteStateConfig<P extends ParserInput | undefined = ParserInput | undefined> = ReactiveFields<WithParser<RouteStateOptions, P>, 'key'>;
 interface BatchOptions {
   history?: HistoryMode;
 }
@@ -35,6 +26,17 @@ interface UseRouteStatesApi<TOptions extends readonly RouteStateConfig[]> {
   toObject: () => StateSnapshot<TOptions>;
 }
 type UseRouteStatesReturn<TOptions extends readonly RouteStateConfig[]> = Refs<TOptions> & UseRouteStatesApi<TOptions>;
-declare function useRouteStates<const TOptions extends readonly RouteStateConfig[]>(configs: TOptions): UseRouteStatesReturn<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, type HistoryMode, type ResolvedRouteStateOptions, type RouteHashOptions, type RouteStateConfig, type RouteStateOptions, type RouteStateSource, type UseRouteHashOptions, type UseRouteStateOptions, type UseRouteStatesApi, type UseRouteStatesReturn, useRouteHash, useRouteState, useRouteStates };
+export type { BatchOptions, HistoryMode, ResolvedRouteStateOptions, RouteHashConfig, RouteHashOptions, RouteStateConfig, RouteStateOptions, RouteStateSource, StateMode, UseRouteHashOptions, UseRouteStateOptions, UseRouteStatesApi, UseRouteStatesReturn };

package/dist/router/index.mjs

@@ -1,15 +1,72 @@
 import { _ as warnDev, h as ErrorCodes, m as unwrapDefault } from "../parsers-CA8aZuF-.mjs";
 import "../parser-B6hfbAwA.mjs";
-import { r as getActiveWagen } from "../wagen-C9_CPUdF.mjs";
-import { i as toValueDeep, n as serializeValue, r as resolveParser, t as parseValue } from "../utils-B-885gDp.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
+		clearOnDefault: options.clearOnDefault ?? defaults.clearOnDefault,
+		mode: options.mode ?? defaults.mode
 	};
 }
 function useRouteHash(options = {}) {
@@ -18,77 +75,120 @@ function useRouteHash(options = {}) {
 	const router = useRouter();
 	const defaults = getActiveWagen().router;
 	const resolvedOptions = computed(() => toResolvedHashOptions(toValueDeep(options), defaults));
-	return customRef((track) => ({
-		get: () => {
-			track();
-			const raw = route.hash === "" ? void 0 : route.hash;
-			return parseValue(resolvedOptions.value.parser, raw);
-		},
-		set: (next) => {
-			const { parser, history, clearOnDefault } = resolvedOptions.value;
-			const serialized = serializeValue(parser, clearOnDefault, next);
-			nextTick(() => {
-				if ((route.hash === "" ? null : route.hash) === serialized) return;
-				router[history]({
-					query: route.query,
-					params: route.params,
-					hash: serialized === null ? void 0 : serialized
+	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 hasChanged(change) {
-		const current = change.source === "params" ? route.params[change.urlKey] : route.query[change.urlKey];
-		if (Array.isArray(current)) return true;
-		if (change.serialized === null) return current !== void 0;
-		return current !== change.serialized;
-	}
-	function navigate(changes, history) {
-		const changed = changes.filter(hasChanged);
-		if (changed.length === 0) return;
-		const params = { ...route.params };
-		const query = { ...route.query };
-		for (const change of changed) {
-			const target = change.source === "params" ? params : query;
-			target[change.urlKey] = change.serialized === null ? void 0 : change.serialized;
+	function createRouteStateRef(options) {
+		let cache = null;
+		let generation = 0;
+		let trigger;
+		function rawValue(urlKey, source) {
+			return source === "params" ? route.params[urlKey] : route.query[urlKey];
 		}
-		router[history]({
-			params,
-			query,
-			hash: route.hash
+		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 createRouteStateRef(options) {
-		return customRef((track) => ({
-			get: () => {
-				track();
-				const { urlKey, source, parser } = toValue(options);
-				const raw = source === "params" ? route.params[urlKey] : route.query[urlKey];
-				return parseValue(parser, raw);
-			},
-			set: (next) => {
-				const { urlKey, source, parser, history, clearOnDefault } = toValue(options);
-				const serialized = serializeValue(parser, clearOnDefault, next);
-				nextTick(() => {
-					navigate([{
-						urlKey,
-						source,
-						serialized
-					}], history);
-				});
+		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,
-		navigate
-	};
+	return { createRouteStateRef };
 }
 //#endregion
 //#region src/router/utils.ts
@@ -99,7 +199,8 @@ function toResolvedOptions(input, defaults) {
 		urlKey: input.urlKey ?? input.key,
 		source: input.source ?? defaults.source,
 		history: input.history ?? defaults.history,
-		clearOnDefault: input.clearOnDefault ?? defaults.clearOnDefault
+		clearOnDefault: input.clearOnDefault ?? defaults.clearOnDefault,
+		mode: input.mode ?? defaults.mode
 	};
 }
 //#endregion
@@ -108,58 +209,51 @@ 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)));
+	return createRouteStateRef(computed(() => toResolvedOptions(toValueDeep(options), defaults))).state;
 }
 //#endregion
 //#region src/router/use-route-states.ts
-function resolveBatchHistory(candidates, override) {
-	if (override) return override;
-	return candidates.includes("push") ? "push" : "replace";
-}
 function useRouteStates(configs) {
 	if (!getCurrentScope()) warnDev(ErrorCodes.NO_EFFECT_SCOPE, "useRouteStates");
-	const { createRouteStateRef, navigate } = useBaseRouteState();
+	const { createRouteStateRef } = useBaseRouteState();
 	const defaults = getActiveWagen().router;
 	const resolvedList = configs.map((config) => computed(() => toResolvedOptions(toValueDeep(config), defaults)));
-	const refs = Object.fromEntries(resolvedList.map((resolved) => [resolved.value.key, createRouteStateRef(resolved)]));
+	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 changes = [];
-			const historyCandidates = [];
-			for (const resolved of resolvedList) {
-				const { key, urlKey, source, parser, clearOnDefault, history } = resolved.value;
-				if (!(key in patch)) continue;
+			const writes = [];
+			const candidates = [];
+			resolvedList.forEach((resolved, index) => {
+				const { key, parser, clearOnDefault, history } = resolved.value;
+				if (!(key in patch)) return;
 				const next = patch[key];
-				changes.push({
-					urlKey,
-					source,
+				writes.push({
+					handle: handles[index],
 					serialized: serializeValue(parser, clearOnDefault, next)
 				});
-				historyCandidates.push(history);
-			}
-			if (changes.length === 0) return;
-			const history = resolveBatchHistory(historyCandidates, options?.history);
-			nextTick(() => {
-				navigate(changes, history);
+				candidates.push(history);
 			});
+			commit(writes, candidates, options?.history);
 		},
 		reset(options) {
-			const changes = [];
-			const historyCandidates = [];
-			for (const resolved of resolvedList) {
-				const { urlKey, source, parser, clearOnDefault, history } = resolved.value;
+			const writes = [];
+			const candidates = [];
+			resolvedList.forEach((resolved, index) => {
+				const { parser, clearOnDefault, history } = resolved.value;
 				const next = parser.defaultValue !== void 0 ? unwrapDefault(parser.defaultValue) : null;
-				changes.push({
-					urlKey,
-					source,
+				writes.push({
+					handle: handles[index],
 					serialized: serializeValue(parser, clearOnDefault, next)
 				});
-				historyCandidates.push(history);
-			}
-			const history = resolveBatchHistory(historyCandidates, options?.history);
-			nextTick(() => {
-				navigate(changes, history);
+				candidates.push(history);
 			});
+			commit(writes, candidates, options?.history);
 		},
 		toObject() {
 			const snapshot = {};
@@ -176,4 +270,4 @@ function useRouteStates(configs) {
 	};
 }
 //#endregion
-export { useRouteHash, useRouteState, useRouteStates };
+export { routeHashOptions, routeStateOptions, useRouteHash, useRouteState, useRouteStates };

package/dist/storage/index.d.mts

@@ -1,6 +1,5 @@
-import { i as InferInputWritable, r as InferInputValue, s as ParserInput } from "../types-CNt2lcP1.mjs";
+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 { n as ReactiveOptions } from "../options-BKybciek.mjs";
 import { Ref } from "vue";
 //#region src/storage/define-storage-state.d.ts
 type StorageSource = StorageInstance | 'local' | 'session';
@@ -9,6 +8,7 @@ interface StorageStateOptions {
   storage?: StorageSource;
   parser?: ParserInput;
   clearOnDefault?: boolean;
+  mode?: StateMode;
 }
 interface StorageState<T = string | null, W = T | null | undefined> {
   readonly key: string;
@@ -18,26 +18,20 @@ interface StorageState<T = string | null, W = T | null | undefined> {
   remove: () => void;
   subscribe: (listener: () => void) => Unsubscribe;
 }
-declare function defineStorageState<P extends ParserInput | undefined = undefined>(options: Omit<StorageStateOptions, 'parser'> & {
-  parser?: P;
-}): StorageState<InferInputValue<P>, InferInputWritable<P>>;
+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
-declare function createMemoryStorage(config?: StorageConfig): StorageInstance;
-declare function createLocalStorage(config?: StorageConfig): StorageInstance;
-declare function createSessionStorage(config?: StorageConfig): StorageInstance;
+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<Omit<StorageStateOptions, 'parser'> & {
-  parser?: P;
-}, 'parser'>;
-type UseLocalStorageOptions<P extends ParserInput | undefined = ParserInput | undefined> = ReactiveOptions<Omit<StorageStateOptions, 'parser' | 'storage'> & {
-  parser?: P;
-}, 'parser'>;
+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>;
-declare function useStorage<T, W>(state: StorageState<T, W>): Ref<T, W>;
-declare function useStorage<P extends ParserInput | undefined = undefined>(options: UseStorageOptions<P>): Ref<InferInputValue<P>, InferInputWritable<P>>;
-declare function useLocalStorage<P extends ParserInput | undefined = undefined>(options: UseLocalStorageOptions<P>): Ref<InferInputValue<P>, InferInputWritable<P>>;
-declare function useSessionStorage<P extends ParserInput | undefined = undefined>(options: UseSessionStorageOptions<P>): Ref<InferInputValue<P>, InferInputWritable<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 StorageAdapter, type StorageConfig, type StorageInstance, type StorageListener, type StorageOptions, type StorageSource, type StorageState, type StorageStateOptions, type Unsubscribe, type UseLocalStorageOptions, type UseSessionStorageOptions, type UseStorageOptions, createLocalStorage, createMemoryStorage, createSessionStorage, createStorage, defineStorageState, useLocalStorage, useSessionStorage, useStorage };
+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 };

package/dist/storage/index.mjs

@@ -1,31 +1,61 @@
 import { _ as warnDev, h as ErrorCodes } from "../parsers-CA8aZuF-.mjs";
-import { a as createLocalStorage, c as createStorage, o as createMemoryStorage, r as getActiveWagen, s as createSessionStorage } from "../wagen-C9_CPUdF.mjs";
-import { i as toValueDeep, n as serializeValue, r as resolveParser, t as parseValue } from "../utils-B-885gDp.mjs";
+import { a as createLocalStorage, c as createStorage, o as createMemoryStorage, r as getActiveWagen, s as createSessionStorage } from "../wagen-C2p8oQgu.mjs";
+import { a as toValueDeep, i as resolveParser, n as parseValue, r as serializeValue } from "../utils-EL2EiRpH.mjs";
 import { computed, customRef, getCurrentScope, onWatcherCleanup, toValue, watch } from "vue";
 //#region src/storage/define-storage-state.ts
 function defineStorageState(options) {
 	const { key } = options;
 	const clearOnDefault = options.clearOnDefault ?? true;
 	const parser = resolveParser(options.parser);
-	function storage() {
+	let cache = null;
+	function resolved() {
 		const source = options.storage;
-		if (source && typeof source !== "string") return source;
-		const { storage } = getActiveWagen();
-		return source ? storage[source] : storage.default;
+		const mode = options.mode;
+		if (mode !== void 0 && source !== void 0 && typeof source !== "string") return {
+			instance: source,
+			optimistic: mode === "optimistic"
+		};
+		const wagen = getActiveWagen();
+		return {
+			instance: source === void 0 ? wagen.storage.default : typeof source === "string" ? wagen.storage[source] : source,
+			optimistic: (mode ?? wagen.storage.mode) === "optimistic"
+		};
+	}
+	function write(serialized) {
+		const { instance, optimistic } = resolved();
+		if (optimistic) cache = {
+			seen: instance.getItem(key),
+			raw: serialized
+		};
+		if (serialized === null) instance.removeItem(key);
+		else instance.setItem(key, serialized);
+		if (optimistic) cache = {
+			seen: instance.getItem(key),
+			raw: serialized
+		};
 	}
 	return {
 		key,
 		get storage() {
-			return storage();
+			return resolved().instance;
 		},
-		get: () => parseValue(parser, storage().getItem(key)),
-		set: (next) => {
-			const serialized = serializeValue(parser, clearOnDefault, next);
-			if (serialized === null) storage().removeItem(key);
-			else storage().setItem(key, serialized);
+		get: () => {
+			const { instance, optimistic } = resolved();
+			const current = instance.getItem(key);
+			if (!optimistic) {
+				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);
 		},
-		remove: () => storage().removeItem(key),
-		subscribe: (listener) => storage().subscribe(key, listener)
+		set: (next) => write(serializeValue(parser, clearOnDefault, next)),
+		remove: () => write(null),
+		subscribe: (listener) => resolved().instance.subscribe(key, listener)
 	};
 }
 //#endregion
@@ -33,18 +63,19 @@ function defineStorageState(options) {
 function isStorageState(input) {
 	return typeof input === "object" && input !== null && typeof input.get === "function";
 }
-function withResolvedStorage(options, wagen) {
+function withWagenDefaults(options, wagen) {
 	const source = options.storage;
-	if (source && typeof source !== "string") return options;
+	const storage = source === void 0 ? wagen.storage.default : typeof source === "string" ? wagen.storage[source] : source;
 	return {
 		...options,
-		storage: source ? wagen.storage[source] : wagen.storage.default
+		storage,
+		mode: options.mode ?? wagen.storage.mode
 	};
 }
 function useStorageState(input) {
 	if (isStorageState(input)) return computed(() => input);
 	const wagen = getActiveWagen();
-	return computed(() => defineStorageState(withResolvedStorage(toValueDeep(input), wagen)));
+	return computed(() => defineStorageState(withWagenDefaults(toValueDeep(input), wagen)));
 }
 function useStorage(input) {
 	if (!getCurrentScope()) warnDev(ErrorCodes.NO_EFFECT_SCOPE, "useStorage");

package/dist/{types-CNt2lcP1.d.mts → types-JtRmT3qo.d.mts}

@@ -1,3 +1,4 @@
+import { MaybeRefOrGetter, Ref } from "vue";
 //#region src/parser/parsers.d.ts
 type ParserOptions<T> = {
   parse: (raw: string) => T | null;
@@ -49,7 +50,12 @@ type NamedParserRef = { [K in keyof KnownParsers]: {
 type ParserInput = (Parser<any> & {
   name?: never;
 }) | NamedParserRef;
-type InferInputValue<P> = [P] extends [undefined] ? string | null : P extends ParserWithDefault<infer T> ? T : P extends Parser<infer T> ? T | null : P extends {
+type UnwrapParser<P> = P extends Ref<infer U> ? U : P extends (() => infer U) ? U : P;
+type WithParser<T, P extends ParserInput | undefined> = Omit<T, 'parser'> & {
+  parser?: P;
+};
+type InferInputValue<P> = ResolveInputValue<UnwrapParser<P>>;
+type ResolveInputValue<P> = [P] extends [undefined] ? string | null : P extends ParserWithDefault<infer T> ? T : P extends Parser<infer T> ? T | null : P extends {
   name: infer K;
   defaultValue: any;
 } ? K extends keyof KnownParsers ? InferParserValue<KnownParsers[K]> : string : P extends {
@@ -57,4 +63,10 @@ type InferInputValue<P> = [P] extends [undefined] ? string | null : P extends Pa
 } ? K extends keyof KnownParsers ? InferParserValue<KnownParsers[K]> | null : string | null : string | null;
 type InferInputWritable<P> = InferInputValue<P> | null | undefined;
 //#endregion
-export { parseAsStringLiteral as C, parseAsStringEnum as S, unwrapDefault as T, parseAsIndex as _, InferParserValue as a, parseAsNumberLiteral as b, DefaultValue as c, ParserWithDefault as d, defineParser as f, parseAsFloat as g, parseAsDate as h, InferInputWritable as i, Parser as l, parseAsBoolean as m, CustomParsers as n, KnownParsers as o, parseAsArrayOf as p, InferInputValue as r, ParserInput as s, BuiltinParsers as t, ParserOptions as u, parseAsInteger as v, tryParse as w, parseAsString as x, parseAsJson as y };
+//#region src/types.d.ts
+type StateMode = 'optimistic' | 'source';
+type MaybeRefsOrGetters<T> = { [K in keyof T]: MaybeRefOrGetter<T[K]>; };
+type ReactiveFields<T, TStatic extends keyof T = never> = MaybeRefsOrGetters<Omit<T, TStatic>> & Pick<T, TStatic>;
+type ReactiveOptions<T, TStatic extends keyof T = never> = MaybeRefOrGetter<ReactiveFields<T, TStatic>>;
+//#endregion
+export { unwrapDefault as A, parseAsInteger as C, parseAsStringEnum as D, parseAsString as E, parseAsStringLiteral as O, parseAsIndex as S, parseAsNumberLiteral as T, defineParser as _, CustomParsers as a, parseAsDate as b, InferParserValue as c, UnwrapParser as d, WithParser as f, ParserWithDefault as g, ParserOptions as h, BuiltinParsers as i, tryParse as k, KnownParsers as l, Parser as m, ReactiveOptions as n, InferInputValue as o, DefaultValue as p, StateMode as r, InferInputWritable as s, ReactiveFields as t, ParserInput as u, parseAsArrayOf as v, parseAsJson as w, parseAsFloat as x, parseAsBoolean as y };

package/dist/{types-CuwASQTi.d.mts → types-fVW6rBJ3.d.mts}

@@ -1,4 +1,4 @@
-import { c as DefaultValue, s as ParserInput } from "./types-CNt2lcP1.mjs";
+import { p as DefaultValue, r as StateMode, u as ParserInput } from "./types-JtRmT3qo.mjs";
 //#region src/parser/resolve.d.ts
 type ResolvedParser<T> = {
   parse: (raw: string) => T | null;
@@ -16,6 +16,7 @@ interface RouteStateOptions {
   source?: RouteStateSource;
   history?: HistoryMode;
   clearOnDefault?: boolean;
+  mode?: StateMode;
 }
 type ResolvedRouteStateOptions = Omit<Required<RouteStateOptions>, 'parser'> & {
   parser: ResolvedParser<any>;

package/dist/{utils-B-885gDp.mjs → utils-EL2EiRpH.mjs}

@@ -1,5 +1,5 @@
 import { g as warn, h as ErrorCodes, m as unwrapDefault, u as parseAsString } from "./parsers-CA8aZuF-.mjs";
-import { r as getActiveWagen } from "./wagen-C9_CPUdF.mjs";
+import { r as getActiveWagen } from "./wagen-C2p8oQgu.mjs";
 import { n as isBuiltinParserName, t as builtinParsers } from "./builtins-DiCjLgsG.mjs";
 import { toValue } from "vue";
 //#region src/options.ts
@@ -57,9 +57,12 @@ function resolveParser(input = { name: "parseAsString" }) {
 }
 //#endregion
 //#region src/parser/utils.ts
+function normalizeRaw(raw) {
+	return (Array.isArray(raw) ? raw.find((v) => v != null) : raw) ?? null;
+}
 function parseValue(parser, raw) {
-	const value = Array.isArray(raw) ? raw.find((v) => v != null) : raw;
-	if (value == null) return parser.defaultValue !== void 0 ? unwrapDefault(parser.defaultValue) : null;
+	const value = normalizeRaw(raw);
+	if (value === null) return parser.defaultValue !== void 0 ? unwrapDefault(parser.defaultValue) : null;
 	const parsed = parser.parse(value);
 	if (parsed !== null) return parsed;
 	return parser.defaultValue !== void 0 ? unwrapDefault(parser.defaultValue) : null;
@@ -73,4 +76,4 @@ function serializeValue(parser, clearOnDefault, next) {
 	return serialized;
 }
 //#endregion
-export { toValueDeep as i, serializeValue as n, resolveParser as r, parseValue as t };
+export { toValueDeep as a, resolveParser as i, parseValue as n, serializeValue as r, normalizeRaw as t };

package/dist/vite/index.d.mts

@@ -1,8 +1,8 @@
 import { Plugin } from "vite";
 //#region src/vite/index.d.ts
-declare const PARSERS_ID = "virtual:usewagen/parsers";
-declare const RESOLVED_PARSERS_ID = "\0virtual:usewagen/parsers";
-interface WagenPluginOptions {
+export declare const PARSERS_ID = "virtual:usewagen/parsers";
+export declare const RESOLVED_PARSERS_ID = "\0virtual:usewagen/parsers";
+export interface WagenPluginOptions {
   /**
    * Directory or directories to scan for parser files.
    * @default 'src/parsers'
@@ -14,6 +14,6 @@ interface WagenPluginOptions {
    */
   dts?: string | false;
 }
-declare function usewagen(options?: WagenPluginOptions): Plugin;
+export declare function usewagen(options?: WagenPluginOptions): Plugin;
 //#endregion
-export { PARSERS_ID, RESOLVED_PARSERS_ID, WagenPluginOptions, usewagen as default, usewagen };
+export { usewagen as default };

package/dist/{wagen-C9_CPUdF.mjs → wagen-C2p8oQgu.mjs}

@@ -197,7 +197,8 @@ const WAGEN_KEY = Symbol.for("usewagen");
 const ROUTER_DEFAULTS = {
 	history: "replace",
 	source: "query",
-	clearOnDefault: true
+	clearOnDefault: true,
+	mode: "optimistic"
 };
 let activeWagen = null;
 function createStorage(options) {
@@ -228,7 +229,8 @@ function createStorage(options) {
 		},
 		get default() {
 			return options.default === "session" ? storage.session : storage.local;
-		}
+		},
+		mode: options.mode ?? "optimistic"
 	};
 	function destroy() {
 		for (const instance of created) instance.destroy();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "usewagen",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Reactive state for URL and storage in Vue.",
   "keywords": [
     "composables",
@@ -64,7 +64,7 @@
   "devEngines": {
     "packageManager": {
       "name": "pnpm",
-      "version": "11.24.0",
+      "version": "11.25.0",
       "onFail": "download"
     }
   },

package/dist/options-BKybciek.d.mts

@@ -1,7 +0,0 @@
-import { MaybeRefOrGetter } from "vue";
-//#region src/options.d.ts
-type MaybeRefsOrGetters<T> = { [K in keyof T]: MaybeRefOrGetter<T[K]>; };
-type ReactiveFields<T, TStatic extends keyof T = never> = MaybeRefsOrGetters<Omit<T, TStatic>> & Pick<T, TStatic>;
-type ReactiveOptions<T, TStatic extends keyof T = never> = MaybeRefOrGetter<ReactiveFields<T, TStatic>>;
-//#endregion
-export { ReactiveOptions as n, ReactiveFields as t };