vue-context-storage 0.1.22 → 0.1.23

package/dist/index.d.ts

@@ -1,12 +1,12 @@
-import * as vue0 from "vue";
+import * as vue9 from "vue";
 import { InjectionKey, MaybeRefOrGetter, Plugin, PropType, UnwrapNestedRefs, WatchHandle } from "vue";
 import { LocationQuery, LocationQueryValue } from "vue-router";
 
 //#region src/components/ContextStorageActivator.vue.d.ts
 declare const _default$1: typeof __VLS_export$3;
-declare const __VLS_export$3: vue0.DefineComponent<{}, () => vue0.VNode<vue0.RendererNode, vue0.RendererElement, {
+declare const __VLS_export$3: vue9.DefineComponent<{}, () => vue9.VNode<vue9.RendererNode, vue9.RendererElement, {
   [key: string]: any;
-}>, {}, {}, {}, vue0.ComponentOptionsMixin, vue0.ComponentOptionsMixin, {}, string, vue0.PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, vue0.ComponentProvideOptions, true, {}, any>;
+}>, {}, {}, {}, vue9.ComponentOptionsMixin, vue9.ComponentOptionsMixin, {}, string, vue9.PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, vue9.ComponentProvideOptions, true, {}, any>;
 //#endregion
 //#region src/handlers.d.ts
 interface ContextStorageHandlerConstructor {
@@ -26,55 +26,55 @@ interface ContextStorageHandler {
 //#endregion
 //#region src/components/ContextStorageCollection.vue.d.ts
 declare const _default$2: typeof __VLS_export$2;
-declare const __VLS_export$2: vue0.DefineComponent<vue0.ExtractPropTypes<{
+declare const __VLS_export$2: vue9.DefineComponent<vue9.ExtractPropTypes<{
   handlers: {
     type: PropType<ContextStorageHandlerConstructor[]>;
     default: () => ContextStorageHandlerConstructor[];
   };
-}>, () => vue0.VNode<vue0.RendererNode, vue0.RendererElement, {
+}>, () => vue9.VNode<vue9.RendererNode, vue9.RendererElement, {
   [key: string]: any;
-}>[] | undefined, {}, {}, {}, vue0.ComponentOptionsMixin, vue0.ComponentOptionsMixin, {}, string, vue0.PublicProps, Readonly<vue0.ExtractPropTypes<{
+}>[] | undefined, {}, {}, {}, vue9.ComponentOptionsMixin, vue9.ComponentOptionsMixin, {}, string, vue9.PublicProps, Readonly<vue9.ExtractPropTypes<{
   handlers: {
     type: PropType<ContextStorageHandlerConstructor[]>;
     default: () => ContextStorageHandlerConstructor[];
   };
 }>> & Readonly<{}>, {
   handlers: ContextStorageHandlerConstructor[];
-}, {}, {}, {}, string, vue0.ComponentProvideOptions, true, {}, any>;
+}, {}, {}, {}, string, vue9.ComponentProvideOptions, true, {}, any>;
 //#endregion
 //#region src/components/ContextStorageProvider.vue.d.ts
 declare const _default$3: typeof __VLS_export$1;
-declare const __VLS_export$1: vue0.DefineComponent<vue0.ExtractPropTypes<{
+declare const __VLS_export$1: vue9.DefineComponent<vue9.ExtractPropTypes<{
   itemKey: {
     type: StringConstructor;
     required: true;
   };
-}>, () => vue0.VNode<vue0.RendererNode, vue0.RendererElement, {
+}>, () => vue9.VNode<vue9.RendererNode, vue9.RendererElement, {
   [key: string]: any;
-}>[] | undefined, {}, {}, {}, vue0.ComponentOptionsMixin, vue0.ComponentOptionsMixin, {}, string, vue0.PublicProps, Readonly<vue0.ExtractPropTypes<{
+}>[] | undefined, {}, {}, {}, vue9.ComponentOptionsMixin, vue9.ComponentOptionsMixin, {}, string, vue9.PublicProps, Readonly<vue9.ExtractPropTypes<{
   itemKey: {
     type: StringConstructor;
     required: true;
   };
-}>> & Readonly<{}>, {}, {}, {}, {}, string, vue0.ComponentProvideOptions, true, {}, any>;
+}>> & Readonly<{}>, {}, {}, {}, {}, string, vue9.ComponentProvideOptions, true, {}, any>;
 //#endregion
 //#region src/components/ContextStorage.vue.d.ts
 declare const _default: typeof __VLS_export;
-declare const __VLS_export: vue0.DefineComponent<vue0.ExtractPropTypes<{
+declare const __VLS_export: vue9.DefineComponent<vue9.ExtractPropTypes<{
   handlers: {
     type: PropType<ContextStorageHandlerConstructor[]>;
     default: () => ContextStorageHandlerConstructor[];
   };
-}>, () => vue0.VNode<vue0.RendererNode, vue0.RendererElement, {
+}>, () => vue9.VNode<vue9.RendererNode, vue9.RendererElement, {
   [key: string]: any;
-}>[] | undefined, {}, {}, {}, vue0.ComponentOptionsMixin, vue0.ComponentOptionsMixin, {}, string, vue0.PublicProps, Readonly<vue0.ExtractPropTypes<{
+}>[] | undefined, {}, {}, {}, vue9.ComponentOptionsMixin, vue9.ComponentOptionsMixin, {}, string, vue9.PublicProps, Readonly<vue9.ExtractPropTypes<{
   handlers: {
     type: PropType<ContextStorageHandlerConstructor[]>;
     default: () => ContextStorageHandlerConstructor[];
   };
 }>> & Readonly<{}>, {
   handlers: ContextStorageHandlerConstructor[];
-}, {}, {}, {}, string, vue0.ComponentProvideOptions, true, {}, any>;
+}, {}, {}, {}, string, vue9.ComponentProvideOptions, true, {}, any>;
 //#endregion
 //#region src/plugin.d.ts
 declare const VueContextStoragePlugin: Plugin;
@@ -105,23 +105,6 @@ declare class CollectionManager {
   setActive(activeItem: CollectionManagerItem): void;
 }
 //#endregion
-//#region src/composables/useContextStorageActivator.d.ts
-declare function useContextStorageActivator(): {
-  activate: () => void;
-};
-//#endregion
-//#region src/composables/useContextStorageCollection.d.ts
-declare function useContextStorageCollection(handlers?: ContextStorageHandlerConstructor[]): CollectionManager;
-//#endregion
-//#region src/composables/useContextStorageProvider.d.ts
-declare function useContextStorageProvider(key: string): void;
-//#endregion
-//#region src/symbols.d.ts
-declare const collection: unique symbol;
-declare const collectionItem: unique symbol;
-declare const handlers: unique symbol;
-declare const contextStorageQueryHandler: unique symbol;
-//#endregion
 //#region src/handlers/query/types.d.ts
 type QueryValue = LocationQueryValue | LocationQueryValue[];
 type DeepTransformValuesToLocationQueryValue<T> = { [K in keyof T]?: T[K] extends object ? T[K] extends Array<any> ? QueryValue : DeepTransformValuesToLocationQueryValue<T[K]> : QueryValue };
@@ -257,6 +240,149 @@ interface ContextStorageQueryRegisteredItem<T extends Record<string, unknown>> {
   watchHandle: WatchHandle;
 }
 //#endregion
+//#region src/handlers/web-storage-base/types.d.ts
+interface WebStorageHandlerBaseOptions {
+  /**
+   * Default: true for localStorage, false for sessionStorage
+   *
+   * If enabled - storage events will be listened to for cross-tab synchronization.
+   * Only works with localStorage (sessionStorage is per-tab).
+   */
+  listenToStorageEvents?: boolean;
+}
+interface RegisterWebStorageHandlerBaseOptions<T> {
+  /**
+   * Storage key for this data.
+   */
+  key?: string;
+  /**
+   * Optional prefix for nested data within the storage key.
+   * When provided, data will be stored under this prefix within the main storage object.
+   */
+  prefix?: string;
+  /**
+   * Transform function to convert deserialized storage data to the expected type.
+   *
+   * Note: If `schema` is provided, it takes priority over `transform`.
+   */
+  transform?: (deserialized: Record<string, unknown>, initialData: T) => UnwrapNestedRefs<T>;
+  /**
+   * Zod schema for automatic validation and type coercion.
+   *
+   * When provided, the schema will be used to parse and validate storage data.
+   * This option takes priority over the `transform` option.
+   *
+   * @example
+   * ```typescript
+   * import { z } from 'zod'
+   *
+   * const SettingsSchema = z.object({
+   *   theme: z.enum(['light', 'dark']).default('light'),
+   *   fontSize: z.number().int().positive().default(14),
+   * })
+   *
+   * useContextStorageLocalStorage(settings, {
+   *   key: 'app-settings',
+   *   schema: SettingsSchema,
+   * })
+   * ```
+   */
+  schema?: {
+    safeParse: (data: unknown) => {
+      success: true;
+      data: T;
+    } | {
+      success: false;
+      error: any;
+    };
+    parse: (data: unknown) => T;
+  };
+  /**
+   * Custom serializer function. Defaults to JSON.stringify.
+   */
+  serializer?: (data: T) => string;
+  /**
+   * Custom deserializer function. Defaults to JSON.parse.
+   */
+  deserializer?: (str: string) => unknown;
+}
+interface RegisterWebStorageHandlerOptions<T> extends RegisterBaseOptions, RegisterWebStorageHandlerBaseOptions<T> {}
+interface IContextStorageWebStorageHandler extends ContextStorageHandler {
+  register: <T extends Record<string, unknown>>(data: MaybeRefOrGetter<T>, options: RegisterWebStorageHandlerOptions<T>) => () => void;
+}
+interface ContextStorageWebStorageRegisteredItem<T extends Record<string, unknown>> {
+  data: MaybeRefOrGetter<T>;
+  initialData: T;
+  options: RegisterWebStorageHandlerOptions<T>;
+  watchHandle: WatchHandle;
+}
+//#endregion
+//#region src/handlers/web-storage-base/index.d.ts
+declare abstract class ContextStorageWebStorageHandler implements IContextStorageWebStorageHandler {
+  protected enabled: boolean;
+  protected registered: ContextStorageWebStorageRegisteredItem<any>[];
+  protected initialState?: Record<string, unknown>;
+  protected hasAnyRegistered: boolean;
+  protected preventSyncToStorage: boolean;
+  protected abstract readonly storage: Storage;
+  protected abstract readonly injectionKey: InjectionKey<ContextStorageWebStorageHandler>;
+  protected readonly options: Required<WebStorageHandlerBaseOptions>;
+  private storageEventHandler;
+  constructor(defaultOptions: Required<WebStorageHandlerBaseOptions>);
+  protected initializeStorageListener(): void;
+  protected handleStorageEvent(event: StorageEvent): void;
+  getInjectionKey(): InjectionKey<ContextStorageWebStorageHandler>;
+  setInitialState(state: Record<string, unknown> | undefined): void;
+  setEnabled(state: boolean, initial: boolean): void;
+  syncRegisteredToStorage(): void;
+  syncStorageToRegisteredItem<T extends Record<string, unknown>>(item: ContextStorageWebStorageRegisteredItem<T>): void;
+  syncStorageToRegistered(): void;
+  register<T extends Record<string, unknown>>(data: MaybeRefOrGetter<T>, options: RegisterWebStorageHandlerOptions<T>): () => void;
+}
+/**
+ * Options for the web storage composable with required key
+ */
+type UseWebStorageOptions<T> = RegisterWebStorageHandlerBaseOptions<T> & Required<Pick<RegisterWebStorageHandlerBaseOptions<T>, 'key'>>;
+//#endregion
+//#region src/registry.d.ts
+/**
+ * Augmentable interface mapping handler names to their options types.
+ *
+ * Users can extend this via module declaration:
+ * ```typescript
+ * declare module 'vue-context-storage' {
+ *   interface ContextStorageHandlerMap {
+ *     myHandler: MyHandlerOptions
+ *   }
+ * }
+ * ```
+ */
+interface ContextStorageHandlerMap {
+  query: RegisterQueryHandlerBaseOptions<any>;
+  localStorage: UseWebStorageOptions<any>;
+  sessionStorage: UseWebStorageOptions<any>;
+}
+declare function defineContextStorageHandler(name: string, injectionKey: InjectionKey<ContextStorageHandler>): void;
+declare function resolveHandlerInjectionKey(type: string): InjectionKey<ContextStorageHandler> | undefined;
+//#endregion
+//#region src/composables/useContextStorage.d.ts
+declare function useContextStorage<K$1 extends keyof ContextStorageHandlerMap, T extends Record<string, unknown>>(type: K$1, data: MaybeRefOrGetter<T>, options: ContextStorageHandlerMap[K$1]): void;
+declare function useContextStorage<T extends Record<string, unknown>>(type: InjectionKey<ContextStorageHandler>, data: MaybeRefOrGetter<T>, options?: Record<string, unknown>): void;
+//#endregion
+//#region src/composables/useContextStorageActivator.d.ts
+declare function useContextStorageActivator(): {
+  activate: () => void;
+};
+//#endregion
+//#region src/composables/useContextStorageCollection.d.ts
+declare function useContextStorageCollection(handlers?: ContextStorageHandlerConstructor[]): CollectionManager;
+//#endregion
+//#region src/composables/useContextStorageProvider.d.ts
+declare function useContextStorageProvider(key: string): void;
+//#endregion
+//#region src/symbols.d.ts
+declare const contextStorageQueryHandler: unique symbol;
+//#endregion
 //#region src/handlers/query/index.d.ts
 declare function useContextStorageQueryHandler<T extends Record<string, unknown>>(data: MaybeRefOrGetter<T>, options?: RegisterQueryHandlerBaseOptions<T>): void;
 declare class ContextStorageQueryHandler implements IContextStorageQueryHandler {
@@ -285,6 +411,26 @@ declare class ContextStorageQueryHandler implements IContextStorageQueryHandler
   register<T extends Record<string, unknown>>(data: MaybeRefOrGetter<T>, options: RegisterQueryHandlerOptions<T>): () => void;
 }
 //#endregion
+//#region src/handlers/local-storage/index.d.ts
+declare class ContextStorageLocalStorageHandler extends ContextStorageWebStorageHandler {
+  protected readonly storage: Storage;
+  protected readonly injectionKey: InjectionKey<ContextStorageLocalStorageHandler>;
+  static customHandlerOptions: WebStorageHandlerBaseOptions;
+  constructor();
+  static configure(options: WebStorageHandlerBaseOptions): ContextStorageHandlerConstructor;
+}
+declare const useContextStorageLocalStorage: <T extends Record<string, unknown>>(data: vue9.MaybeRefOrGetter<T>, options: UseWebStorageOptions<T>) => void;
+//#endregion
+//#region src/handlers/session-storage/index.d.ts
+declare class ContextStorageSessionStorageHandler extends ContextStorageWebStorageHandler {
+  protected readonly storage: Storage;
+  protected readonly injectionKey: InjectionKey<ContextStorageSessionStorageHandler>;
+  static customHandlerOptions: WebStorageHandlerBaseOptions;
+  constructor();
+  static configure(options: WebStorageHandlerBaseOptions): ContextStorageHandlerConstructor;
+}
+declare const useContextStorageSessionStorage: <T extends Record<string, unknown>>(data: vue9.MaybeRefOrGetter<T>, options: UseWebStorageOptions<T>) => void;
+//#endregion
 //#region src/handlers/query/transform-helpers.d.ts
 declare function asNumber(value: QueryValue | number | undefined): number;
 declare function asNumber(value: QueryValue | number | undefined, options: {
@@ -460,8 +606,10 @@ declare const contextStorageCollectionInjectKey: InjectionKey<CollectionManager>
 declare const contextStorageCollectionItemInjectKey: InjectionKey<CollectionManagerItem>;
 declare const contextStorageHandlersInjectKey: InjectionKey<CollectionManagerItem['handlers']>;
 declare const contextStorageQueryHandlerInjectKey: InjectionKey<InstanceType<typeof ContextStorageQueryHandler>>;
+declare const contextStorageLocalStorageHandlerInjectKey: InjectionKey<InstanceType<typeof ContextStorageLocalStorageHandler>>;
+declare const contextStorageSessionStorageHandlerInjectKey: InjectionKey<InstanceType<typeof ContextStorageSessionStorageHandler>>;
 //#endregion
 //#region src/constants.d.ts
 declare const defaultHandlers: ContextStorageHandlerConstructor[];
 //#endregion
-export { CollectionManager, type CollectionManagerItem, _default as ContextStorage, _default$1 as ContextStorageActivator, _default$2 as ContextStorageCollection, type ContextStorageHandler, type ContextStorageHandlerConstructor, _default$3 as ContextStorageProvider, ContextStorageQueryHandler, type IContextStorageQueryHandler, type QueryValue, type RegisterBaseOptions, VueContextStoragePlugin, asArray, asBoolean, asNumber, asNumberArray, asString, collection, collectionItem, contextStorageCollectionInjectKey, contextStorageCollectionItemInjectKey, contextStorageHandlersInjectKey, contextStorageQueryHandler, contextStorageQueryHandlerInjectKey, defaultHandlers, deserializeParams as deserializeQueryParams, handlers, serializeParams as serializeQueryParams, transform, useContextStorageActivator, useContextStorageCollection, useContextStorageProvider, useContextStorageQueryHandler };
+export { CollectionManager, type CollectionManagerItem, _default as ContextStorage, _default$1 as ContextStorageActivator, _default$2 as ContextStorageCollection, type ContextStorageHandler, type ContextStorageHandlerConstructor, type ContextStorageHandlerMap, ContextStorageLocalStorageHandler, _default$3 as ContextStorageProvider, ContextStorageQueryHandler, ContextStorageSessionStorageHandler, type IContextStorageWebStorageHandler as IContextStorageLocalStorageHandler, type IContextStorageWebStorageHandler as IContextStorageSessionStorageHandler, type IContextStorageQueryHandler, type WebStorageHandlerBaseOptions as LocalStorageHandlerBaseOptions, type WebStorageHandlerBaseOptions as SessionStorageHandlerBaseOptions, type QueryValue, type RegisterBaseOptions, type RegisterWebStorageHandlerBaseOptions as RegisterLocalStorageHandlerBaseOptions, type RegisterWebStorageHandlerBaseOptions as RegisterSessionStorageHandlerBaseOptions, VueContextStoragePlugin, asArray, asBoolean, asNumber, asNumberArray, asString, contextStorageCollectionInjectKey, contextStorageCollectionItemInjectKey, contextStorageHandlersInjectKey, contextStorageLocalStorageHandlerInjectKey, contextStorageQueryHandlerInjectKey, contextStorageSessionStorageHandlerInjectKey, defaultHandlers, defineContextStorageHandler, deserializeParams as deserializeQueryParams, resolveHandlerInjectionKey, serializeParams as serializeQueryParams, transform, useContextStorage, useContextStorageActivator, useContextStorageCollection, useContextStorageLocalStorage, useContextStorageProvider, useContextStorageQueryHandler, useContextStorageSessionStorage };

package/dist/index.js

@@ -59,6 +59,200 @@ var CollectionManager = class {
 	}
 };
 
+//#endregion
+//#region src/symbols.ts
+const collection = Symbol("context-storage-collection");
+const collectionItem = Symbol("context-storage-collection-item");
+const handlers = Symbol("context-storage-handlers");
+const contextStorageQueryHandler = Symbol("context-storage-query-handler");
+const contextStorageLocalStorageHandler = Symbol("context-storage-local-storage-handler");
+const contextStorageSessionStorageHandler = Symbol("context-storage-session-storage-handler");
+
+//#endregion
+//#region src/handlers/web-storage-base/index.ts
+var ContextStorageWebStorageHandler = class {
+	enabled = false;
+	registered = [];
+	initialState;
+	hasAnyRegistered = false;
+	preventSyncToStorage = false;
+	options;
+	storageEventHandler = null;
+	constructor(defaultOptions) {
+		this.options = { ...defaultOptions };
+	}
+	initializeStorageListener() {
+		if (this.options.listenToStorageEvents && typeof window !== "undefined") {
+			this.storageEventHandler = (event) => {
+				this.handleStorageEvent(event);
+			};
+			window.addEventListener("storage", this.storageEventHandler);
+			onBeforeUnmount(() => {
+				if (this.storageEventHandler) {
+					window.removeEventListener("storage", this.storageEventHandler);
+					this.storageEventHandler = null;
+				}
+			});
+		}
+	}
+	handleStorageEvent(event) {
+		if (!this.enabled) return;
+		this.registered.forEach((item) => {
+			if (event.key === item.options.key) this.syncStorageToRegisteredItem(item);
+		});
+	}
+	getInjectionKey() {
+		return this.injectionKey;
+	}
+	setInitialState(state) {
+		this.initialState = state;
+	}
+	setEnabled(state, initial) {
+		const prevState = this.enabled;
+		this.enabled = state;
+		if (this.hasAnyRegistered) {
+			if (initial) this.syncStorageToRegistered();
+			if (state && !prevState || !initial) this.syncRegisteredToStorage();
+		}
+	}
+	syncRegisteredToStorage() {
+		if (!this.enabled) return;
+		if (this.preventSyncToStorage) return;
+		const byKey = /* @__PURE__ */ new Map();
+		this.registered.forEach((item) => {
+			const key = item.options.key;
+			if (!byKey.has(key)) byKey.set(key, []);
+			byKey.get(key).push(item);
+		});
+		byKey.forEach((items, key) => {
+			let storageData = {};
+			try {
+				const existing = this.storage.getItem(key);
+				if (existing) storageData = JSON.parse(existing);
+			} catch {}
+			items.forEach((item) => {
+				const { prefix, serializer } = item.options;
+				const data = toValue(item.data);
+				if (prefix) storageData[prefix] = data;
+				else storageData = {
+					...storageData,
+					...data
+				};
+				if (serializer && !prefix) {
+					try {
+						this.storage.setItem(key, serializer(data));
+					} catch (e) {
+						console.error("[vue-context-storage] Error writing to storage", e);
+					}
+					return;
+				}
+			});
+			try {
+				this.storage.setItem(key, JSON.stringify(storageData));
+			} catch (e) {
+				console.error("[vue-context-storage] Error writing to storage", e);
+			}
+		});
+	}
+	syncStorageToRegisteredItem(item) {
+		const { key, prefix, deserializer } = item.options;
+		let stored = null;
+		try {
+			stored = this.storage.getItem(key);
+		} catch {
+			return;
+		}
+		if (stored === null) return;
+		let deserialized;
+		try {
+			if (deserializer) deserialized = deserializer(stored);
+			else deserialized = JSON.parse(stored);
+		} catch {
+			console.warn("[vue-context-storage] Failed to parse storage data for key:", key);
+			return;
+		}
+		if (typeof prefix === "string" && prefix.length > 0) deserialized = deserialized[prefix] || {};
+		if (deserialized === void 0 || deserialized === null) return;
+		const itemData = toValue(item.data);
+		if (item.options?.schema) {
+			const result = item.options.schema.safeParse(deserialized);
+			if (result.success) deserialized = result.data;
+			else {
+				console.warn("[vue-context-storage] schema parse failed", result.error);
+				merge(itemData, item.initialData);
+				return;
+			}
+			if (item.options?.transform) console.warn("[vue-context-storage] transform is not supported with schema");
+		} else if (item.options?.transform) deserialized = item.options.transform(deserialized, item.initialData);
+		else deserialized = pick(deserialized, Object.keys(item.initialData));
+		if (isEqual(itemData, deserialized)) return;
+		merge(itemData, deserialized);
+	}
+	syncStorageToRegistered() {
+		this.registered.forEach((item) => this.syncStorageToRegisteredItem(item));
+	}
+	register(data, options) {
+		if (!options.key) throw new Error("[vue-context-storage] Storage handler requires a key option");
+		this.hasAnyRegistered = true;
+		const watchHandle = watch(data, () => this.syncRegisteredToStorage(), { deep: true });
+		const item = {
+			data,
+			initialData: cloneDeep(toValue(data)),
+			options,
+			watchHandle
+		};
+		this.registered.push(item);
+		const syncCallback = () => {
+			this.syncStorageToRegisteredItem(item);
+			this.syncRegisteredToStorage();
+		};
+		queueMicrotask(syncCallback);
+		return () => {
+			watchHandle();
+			this.registered.splice(this.registered.indexOf(item), 1);
+		};
+	}
+};
+function createWebStorageComposable(injectionKey, handlerName) {
+	return function useContextStorageWebStorage(data, options) {
+		const handler = inject(injectionKey);
+		if (!handler) throw new Error(`[vue-context-storage] ${handlerName} is not provided`);
+		const uid = getCurrentInstance()?.uid || 0;
+		const causer = (/* @__PURE__ */ new Error()).stack?.split("\n")[2]?.trimStart() || "unknown";
+		const stop = handler.register(data, {
+			causer,
+			uid,
+			...options
+		});
+		onBeforeUnmount(() => {
+			stop();
+		});
+	};
+}
+
+//#endregion
+//#region src/handlers/local-storage/index.ts
+var ContextStorageLocalStorageHandler = class ContextStorageLocalStorageHandler extends ContextStorageWebStorageHandler {
+	storage;
+	injectionKey;
+	static customHandlerOptions = {};
+	constructor() {
+		const defaultOptions = {
+			listenToStorageEvents: true,
+			...ContextStorageLocalStorageHandler.customHandlerOptions
+		};
+		super(defaultOptions);
+		this.storage = localStorage;
+		this.injectionKey = contextStorageLocalStorageHandler;
+		this.initializeStorageListener();
+	}
+	static configure(options) {
+		ContextStorageLocalStorageHandler.customHandlerOptions = options;
+		return ContextStorageLocalStorageHandler;
+	}
+};
+const useContextStorageLocalStorage = createWebStorageComposable(contextStorageLocalStorageHandler, "ContextStorageLocalStorageHandler");
+
 //#endregion
 //#region src/handlers/query/helpers.ts
 /**
@@ -133,13 +327,6 @@ function deserializeParams(params) {
 	}, {});
 }
 
-//#endregion
-//#region src/symbols.ts
-const collection = Symbol("context-storage-collection");
-const collectionItem = Symbol("context-storage-collection-item");
-const handlers = Symbol("context-storage-handlers");
-const contextStorageQueryHandler = Symbol("context-storage-query-handler");
-
 //#endregion
 //#region src/handlers/query/index.ts
 function useContextStorageQueryHandler(data, options) {
@@ -352,12 +539,37 @@ var ContextStorageQueryHandler = class ContextStorageQueryHandler {
 	}
 };
 
+//#endregion
+//#region src/handlers/session-storage/index.ts
+var ContextStorageSessionStorageHandler = class ContextStorageSessionStorageHandler extends ContextStorageWebStorageHandler {
+	storage;
+	injectionKey;
+	static customHandlerOptions = {};
+	constructor() {
+		const defaultOptions = {
+			listenToStorageEvents: false,
+			...ContextStorageSessionStorageHandler.customHandlerOptions
+		};
+		super(defaultOptions);
+		this.storage = sessionStorage;
+		this.injectionKey = contextStorageSessionStorageHandler;
+		this.initializeStorageListener();
+	}
+	static configure(options) {
+		ContextStorageSessionStorageHandler.customHandlerOptions = options;
+		return ContextStorageSessionStorageHandler;
+	}
+};
+const useContextStorageSessionStorage = createWebStorageComposable(contextStorageSessionStorageHandler, "ContextStorageSessionStorageHandler");
+
 //#endregion
 //#region src/injectionSymbols.ts
 const contextStorageCollectionInjectKey = collection;
 const contextStorageCollectionItemInjectKey = collectionItem;
 const contextStorageHandlersInjectKey = handlers;
 const contextStorageQueryHandlerInjectKey = contextStorageQueryHandler;
+const contextStorageLocalStorageHandlerInjectKey = contextStorageLocalStorageHandler;
+const contextStorageSessionStorageHandlerInjectKey = contextStorageSessionStorageHandler;
 
 //#endregion
 //#region src/composables/useContextStorageActivator.ts
@@ -380,7 +592,11 @@ var ContextStorageActivator_default = ContextStorageActivator_vue_vue_type_scrip
 
 //#endregion
 //#region src/constants.ts
-const defaultHandlers = [ContextStorageQueryHandler];
+const defaultHandlers = [
+	ContextStorageQueryHandler,
+	ContextStorageLocalStorageHandler,
+	ContextStorageSessionStorageHandler
+];
 
 //#endregion
 //#region src/composables/useContextStorageCollection.ts
@@ -468,8 +684,7 @@ var ContextStorage_vue_vue_type_script_lang_default = defineComponent({
 		const initItem = () => {
 			item.handlers.forEach((handler) => {
 				const state = initialNavigatorState.get(handler.constructor);
-				if (!state) return;
-				handler.setInitialState?.(state);
+				if (state) handler.setInitialState?.(state);
 				handler.setEnabled?.(true, true);
 			});
 		};
@@ -496,6 +711,42 @@ const VueContextStoragePlugin = { install(app) {
 	app.component("ContextStorage", ContextStorage_default);
 } };
 
+//#endregion
+//#region src/registry.ts
+const handlerRegistry = /* @__PURE__ */ new Map();
+function defineContextStorageHandler(name, injectionKey) {
+	handlerRegistry.set(name, injectionKey);
+}
+function resolveHandlerInjectionKey(type) {
+	return handlerRegistry.get(type);
+}
+defineContextStorageHandler("query", contextStorageQueryHandlerInjectKey);
+defineContextStorageHandler("localStorage", contextStorageLocalStorageHandlerInjectKey);
+defineContextStorageHandler("sessionStorage", contextStorageSessionStorageHandlerInjectKey);
+
+//#endregion
+//#region src/composables/useContextStorage.ts
+function useContextStorage(type, data, options) {
+	let injectionKey;
+	if (typeof type === "string") {
+		const resolved = resolveHandlerInjectionKey(type);
+		if (!resolved) throw new Error(`[vue-context-storage] Unknown handler type: "${type}". Use defineContextStorageHandler() to register it.`);
+		injectionKey = resolved;
+	} else injectionKey = type;
+	const handler = inject(injectionKey);
+	if (!handler) throw new Error(`[vue-context-storage] Handler not provided for type: "${String(type)}"`);
+	const uid = getCurrentInstance()?.uid || 0;
+	const causer = (/* @__PURE__ */ new Error()).stack?.split("\n")[2]?.trimStart() || "unknown";
+	const stop = handler.register(data, {
+		causer,
+		uid,
+		...options
+	});
+	onBeforeUnmount(() => {
+		stop();
+	});
+}
+
 //#endregion
 //#region src/handlers/query/transform-helpers.ts
 function asNumber(value, options) {
@@ -559,4 +810,4 @@ const transform = {
 };
 
 //#endregion
-export { CollectionManager, ContextStorage_default as ContextStorage, ContextStorageActivator_default as ContextStorageActivator, ContextStorageCollection_default as ContextStorageCollection, ContextStorageProvider_default as ContextStorageProvider, ContextStorageQueryHandler, VueContextStoragePlugin, asArray, asBoolean, asNumber, asNumberArray, asString, collection, collectionItem, contextStorageCollectionInjectKey, contextStorageCollectionItemInjectKey, contextStorageHandlersInjectKey, contextStorageQueryHandler, contextStorageQueryHandlerInjectKey, defaultHandlers, deserializeParams as deserializeQueryParams, handlers, serializeParams as serializeQueryParams, transform, useContextStorageActivator, useContextStorageCollection, useContextStorageProvider, useContextStorageQueryHandler };
+export { CollectionManager, ContextStorage_default as ContextStorage, ContextStorageActivator_default as ContextStorageActivator, ContextStorageCollection_default as ContextStorageCollection, ContextStorageLocalStorageHandler, ContextStorageProvider_default as ContextStorageProvider, ContextStorageQueryHandler, ContextStorageSessionStorageHandler, VueContextStoragePlugin, asArray, asBoolean, asNumber, asNumberArray, asString, contextStorageCollectionInjectKey, contextStorageCollectionItemInjectKey, contextStorageHandlersInjectKey, contextStorageLocalStorageHandlerInjectKey, contextStorageQueryHandlerInjectKey, contextStorageSessionStorageHandlerInjectKey, defaultHandlers, defineContextStorageHandler, deserializeParams as deserializeQueryParams, resolveHandlerInjectionKey, serializeParams as serializeQueryParams, transform, useContextStorage, useContextStorageActivator, useContextStorageCollection, useContextStorageLocalStorage, useContextStorageProvider, useContextStorageQueryHandler, useContextStorageSessionStorage };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vue-context-storage",
   "type": "module",
-  "version": "0.1.22",
+  "version": "0.1.23",
   "description": "Vue 3 context storage system with URL query synchronization support",
   "author": "",
   "license": "MIT",
@@ -68,6 +68,7 @@
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-vue": "^10.6.2",
     "happy-dom": "^20.1.0",
+    "highlight.js": "^11.11.1",
     "jsdom": "^27.4.0",
     "naive-ui": "^2.43.2",
     "playwright": "^1.57.0",