vue-context-storage 0.1.24 → 0.1.26

package/README.md

@@ -21,7 +21,7 @@ A powerful state management solution for Vue 3 applications that provides:
 - **Multiple storage contexts** with activation management
 - **Type-safe** TypeScript support
 - **Tree-shakeable** and lightweight
-
+- 
 ## Live Demo
 
 🚀 **[Try the interactive playground](https://lviobio.github.io/vue-context-storage)**
@@ -40,9 +40,22 @@ npm install vue-context-storage
 - ✅ **sessionStorage Handler** - Session-scoped state that survives page refreshes
 - ✅ **Multiple Contexts** - Support multiple independent storage contexts
 - ✅ **TypeScript** - Full type safety and IntelliSense support
-- ✅ **Flexible** - Works with vue-router 4+
+- ✅ **Flexible** - Works with vue-router 4+ or 5+
 - ✅ **Transform Helpers** - Built-in utilities for type conversion
 
+## Motivation
+
+In Vue applications, reactive state often needs to live beyond a single component. Filters, pagination, sorting, and user preferences must survive page reloads, be shareable via URL, or persist across sessions. Solving this typically means writing the same boilerplate over and over: manually reading and writing query parameters with vue-router, serializing objects to localStorage, handling type coercion from URL strings, and keeping everything in sync.
+
+`vue-context-storage` eliminates that repetitive work. You declare your reactive state once, point it at a storage target, and the library handles the rest:
+
+- **URL query parameters** stay in sync with your data automatically -- users can bookmark or share a page and get the exact same state back.
+- **localStorage and sessionStorage** are kept up to date without manual `getItem`/`setItem` calls, including cross-tab synchronization.
+- **Type safety** is preserved end-to-end: URL strings are coerced back to numbers, booleans, and arrays via transform helpers or Zod schemas.
+- **Multiple independent contexts** (e.g. two data tables on the same page) are supported out of the box through the prefix pattern, so query parameters never collide.
+
+The goal is a single, declarative API -- `useContextStorage('query', data, options)` -- that replaces scattered watchers, router guards, and storage listeners with one composable call per piece of state.
+
 ## Basic Usage
 
 ### Option 1: Manual Component Import (Recommended)
@@ -590,8 +603,8 @@ useContextStorageQueryHandler(pagination, {
 
 ## Peer Dependencies
 
-- `vue`: ^3.5.0
-- `vue-router`: ^4.0.0
+- `vue`: ^3.0.0
+- `vue-router`: ^4.0.0 || ^5.0.0
 - `zod`: ^4.0.0 (optional - only if using schema validation)
 
 ## License

package/dist/index.d.ts

@@ -1,80 +1,121 @@
-import * as vue9 from "vue";
-import { InjectionKey, MaybeRefOrGetter, Plugin, PropType, UnwrapNestedRefs, WatchHandle } from "vue";
+import * as vue19 from "vue";
+import { ComputedRef, 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: vue9.DefineComponent<{}, () => vue9.VNode<vue9.RendererNode, vue9.RendererElement, {
+declare const __VLS_export$3: vue19.DefineComponent<{}, () => vue19.VNode<vue19.RendererNode, vue19.RendererElement, {
   [key: string]: any;
-}>, {}, {}, {}, vue9.ComponentOptionsMixin, vue9.ComponentOptionsMixin, {}, string, vue9.PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, vue9.ComponentProvideOptions, true, {}, any>;
+}>, {}, {}, {}, vue19.ComponentOptionsMixin, vue19.ComponentOptionsMixin, {}, string, vue19.PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, vue19.ComponentProvideOptions, true, {}, any>;
+//#endregion
+//#region src/handlers/types.d.ts
+interface HandlerSchema<T> {
+  safeParse: (data: unknown) => {
+    success: true;
+    data: T;
+  } | {
+    success: false;
+    error: any;
+  };
+  parse: (data: unknown) => T;
+}
 //#endregion
 //#region src/handlers.d.ts
-interface ContextStorageHandlerConstructor<T = any> {
-  new (): ContextStorageHandler<T>;
+interface ContextStorageHandlerConstructor<T extends Record<string, unknown> = {}, O extends RegisterOptions<T> = RegisterOptions<T>> {
+  new (): ContextStorageHandler<T, O>;
   getInitialStateResolver?: () => () => Record<string, unknown>;
 }
-interface RegisterBaseOptions {
-  causer: string;
-  uid: number;
+interface RegisterBaseOptions<T> {
+  causer?: string;
+  uid?: number;
+  /**
+   * Zod schema for automatic validation and type coercion.
+   *
+   * When provided, the schema will be used to parse and validate query parameters.
+   * This option takes priority over the `transform` option.
+   *
+   * @example
+   * ```ts
+   * import { z } from 'zod'
+   *
+   * const FiltersSchema = z.object({
+   *   search: z.string().default(''),
+   *   page: z.coerce.number().int().positive().default(1),
+   *   status: z.enum(['active', 'inactive']).default('active'),
+   * })
+   *
+   * useContextStorageQueryHandler(filters, {
+   *   prefix: 'filters',
+   *   schema: FiltersSchema,
+   * })
+   * ```
+   */
+  schema?: HandlerSchema<T>;
+}
+type RegisterOptions<T> = Required<Pick<RegisterBaseOptions<T>, 'causer' | 'uid'>> & Omit<RegisterBaseOptions<T>, 'causer' | 'uid'>;
+interface RegisterResult {
+  stop: () => void;
+  reset: () => void;
+  wasChanged: ComputedRef<boolean>;
 }
-interface ContextStorageHandler<T> {
-  register: (data: MaybeRefOrGetter<T>, options: RegisterBaseOptions) => () => void;
+interface ContextStorageHandler<T, O> {
+  register: (data: MaybeRefOrGetter<T>, options: O) => RegisterResult;
   setInitialState?: (state: Record<string, unknown>) => void;
   setEnabled?: (enabled: boolean, initial: boolean) => void;
-  getInjectionKey(): InjectionKey<ContextStorageHandler<T>>;
+  getInjectionKey(): InjectionKey<ContextStorageHandler<T, O>>;
 }
 //#endregion
 //#region src/components/ContextStorageCollection.vue.d.ts
 declare const _default$2: typeof __VLS_export$2;
-declare const __VLS_export$2: vue9.DefineComponent<vue9.ExtractPropTypes<{
+declare const __VLS_export$2: vue19.DefineComponent<vue19.ExtractPropTypes<{
   handlers: {
     type: PropType<ContextStorageHandlerConstructor[]>;
-    default: () => ContextStorageHandlerConstructor<any>[];
+    default: () => ContextStorageHandlerConstructor<{}, RegisterOptions<{}>>[];
   };
-}>, () => vue9.VNode<vue9.RendererNode, vue9.RendererElement, {
+}>, () => vue19.VNode<vue19.RendererNode, vue19.RendererElement, {
   [key: string]: any;
-}>[] | undefined, {}, {}, {}, vue9.ComponentOptionsMixin, vue9.ComponentOptionsMixin, {}, string, vue9.PublicProps, Readonly<vue9.ExtractPropTypes<{
+}>[] | undefined, {}, {}, {}, vue19.ComponentOptionsMixin, vue19.ComponentOptionsMixin, {}, string, vue19.PublicProps, Readonly<vue19.ExtractPropTypes<{
   handlers: {
     type: PropType<ContextStorageHandlerConstructor[]>;
-    default: () => ContextStorageHandlerConstructor<any>[];
+    default: () => ContextStorageHandlerConstructor<{}, RegisterOptions<{}>>[];
   };
 }>> & Readonly<{}>, {
-  handlers: ContextStorageHandlerConstructor<any>[];
-}, {}, {}, {}, string, vue9.ComponentProvideOptions, true, {}, any>;
+  handlers: ContextStorageHandlerConstructor<{}, RegisterOptions<{}>>[];
+}, {}, {}, {}, string, vue19.ComponentProvideOptions, true, {}, any>;
 //#endregion
 //#region src/components/ContextStorageProvider.vue.d.ts
 declare const _default$3: typeof __VLS_export$1;
-declare const __VLS_export$1: vue9.DefineComponent<vue9.ExtractPropTypes<{
+declare const __VLS_export$1: vue19.DefineComponent<vue19.ExtractPropTypes<{
   itemKey: {
     type: StringConstructor;
     required: true;
   };
-}>, () => vue9.VNode<vue9.RendererNode, vue9.RendererElement, {
+}>, () => vue19.VNode<vue19.RendererNode, vue19.RendererElement, {
   [key: string]: any;
-}>[] | undefined, {}, {}, {}, vue9.ComponentOptionsMixin, vue9.ComponentOptionsMixin, {}, string, vue9.PublicProps, Readonly<vue9.ExtractPropTypes<{
+}>[] | undefined, {}, {}, {}, vue19.ComponentOptionsMixin, vue19.ComponentOptionsMixin, {}, string, vue19.PublicProps, Readonly<vue19.ExtractPropTypes<{
   itemKey: {
     type: StringConstructor;
     required: true;
   };
-}>> & Readonly<{}>, {}, {}, {}, {}, string, vue9.ComponentProvideOptions, true, {}, any>;
+}>> & Readonly<{}>, {}, {}, {}, {}, string, vue19.ComponentProvideOptions, true, {}, any>;
 //#endregion
 //#region src/components/ContextStorage.vue.d.ts
 declare const _default: typeof __VLS_export;
-declare const __VLS_export: vue9.DefineComponent<vue9.ExtractPropTypes<{
+declare const __VLS_export: vue19.DefineComponent<vue19.ExtractPropTypes<{
   handlers: {
     type: PropType<ContextStorageHandlerConstructor[]>;
-    default: () => ContextStorageHandlerConstructor<any>[];
+    default: () => ContextStorageHandlerConstructor<{}, RegisterOptions<{}>>[];
   };
-}>, () => vue9.VNode<vue9.RendererNode, vue9.RendererElement, {
+}>, () => vue19.VNode<vue19.RendererNode, vue19.RendererElement, {
   [key: string]: any;
-}>[] | undefined, {}, {}, {}, vue9.ComponentOptionsMixin, vue9.ComponentOptionsMixin, {}, string, vue9.PublicProps, Readonly<vue9.ExtractPropTypes<{
+}>[] | undefined, {}, {}, {}, vue19.ComponentOptionsMixin, vue19.ComponentOptionsMixin, {}, string, vue19.PublicProps, Readonly<vue19.ExtractPropTypes<{
   handlers: {
     type: PropType<ContextStorageHandlerConstructor[]>;
-    default: () => ContextStorageHandlerConstructor<any>[];
+    default: () => ContextStorageHandlerConstructor<{}, RegisterOptions<{}>>[];
   };
 }>> & Readonly<{}>, {
-  handlers: ContextStorageHandlerConstructor<any>[];
-}, {}, {}, {}, string, vue9.ComponentProvideOptions, true, {}, any>;
+  handlers: ContextStorageHandlerConstructor<{}, RegisterOptions<{}>>[];
+}, {}, {}, {}, string, vue19.ComponentProvideOptions, true, {}, any>;
 //#endregion
 //#region src/plugin.d.ts
 declare const VueContextStoragePlugin: Plugin;
@@ -82,7 +123,7 @@ declare const VueContextStoragePlugin: Plugin;
 //#region src/collection.d.ts
 type CollectionManagerItem = {
   key: string;
-  handlers: ContextStorageHandler<any>[];
+  handlers: ContextStorageHandler<any, RegisterOptions<any>>[];
 };
 interface ItemOptions {
   key: string;
@@ -109,6 +150,25 @@ declare class CollectionManager {
 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 };
 interface QueryHandlerSharedOptions {
+  /**
+   * Default: false
+   *
+   * If enabled - only values that differ from the initial state will be written to URL.
+   * This keeps URLs clean by omitting default values.
+   *
+   * @example
+   * ```
+   * Options: { onlyChanges: true }
+   *
+   * Initial state: { page: 1, search: '', with_trashed: false }
+   * Current state: { page: 1, search: 'test', with_trashed: true }
+   *
+   * URL will be: ?search=test&with_trashed=1
+   *
+   * The page parameter is omitted because it equals the initial value.
+   * ```
+   */
+  onlyChanges?: boolean;
   /**
    * Default: false
    *
@@ -196,46 +256,12 @@ interface RegisterQueryHandlerBaseOptions<T> extends QueryHandlerSharedOptions {
    * Note: If `schema` is provided, it takes priority over `transform`.
    */
   transform?: (deserialized: DeepTransformValuesToLocationQueryValue<UnwrapNestedRefs<T>>, initialData: T) => UnwrapNestedRefs<T>;
-  /**
-   * Zod schema for automatic validation and type coercion.
-   *
-   * When provided, the schema will be used to parse and validate query parameters.
-   * This option takes priority over the `transform` option.
-   *
-   * @example
-   * ```typescript
-   * import { z } from 'zod'
-   *
-   * const FiltersSchema = z.object({
-   *   search: z.string().default(''),
-   *   page: z.coerce.number().int().positive().default(1),
-   *   status: z.enum(['active', 'inactive']).default('active'),
-   * })
-   *
-   * useContextStorageQueryHandler(filters, {
-   *   prefix: 'filters',
-   *   schema: FiltersSchema,
-   * })
-   * ```
-   */
-  schema?: {
-    safeParse: (data: unknown) => {
-      success: true;
-      data: T;
-    } | {
-      success: false;
-      error: any;
-    };
-    parse: (data: unknown) => T;
-  };
-}
-interface RegisterQueryHandlerOptions<T> extends RegisterBaseOptions, RegisterQueryHandlerBaseOptions<T> {}
-interface IContextStorageQueryHandler<T extends Record<string, unknown>> extends ContextStorageHandler<T> {
-  register: <T extends Record<string, unknown>>(data: MaybeRefOrGetter<T>, options: RegisterQueryHandlerOptions<T>) => () => void;
 }
+interface RegisterQueryHandlerOptions<T> extends RegisterBaseOptions<T>, RegisterQueryHandlerBaseOptions<T> {}
 interface ContextStorageQueryRegisteredItem<T extends Record<string, unknown>> {
   data: MaybeRefOrGetter<T>;
   initialData: T;
+  initialQueryData: LocationQuery;
   options: RegisterQueryHandlerOptions<T>;
   watchHandle: WatchHandle;
 }
@@ -251,9 +277,6 @@ interface WebStorageHandlerBaseOptions {
   listenToStorageEvents?: boolean;
 }
 interface RegisterWebStorageHandlerBaseOptions<T> {
-  /**
-   * Storage key for this data.
-   */
   key?: string;
   /**
    * Optional prefix for nested data within the storage key.
@@ -266,37 +289,6 @@ interface RegisterWebStorageHandlerBaseOptions<T> {
    * 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.
    */
@@ -306,10 +298,7 @@ interface RegisterWebStorageHandlerBaseOptions<T> {
    */
   deserializer?: (str: string) => unknown;
 }
-interface RegisterWebStorageHandlerOptions<T> extends RegisterBaseOptions, RegisterWebStorageHandlerBaseOptions<T> {}
-interface IContextStorageWebStorageHandler<T extends Record<string, unknown>> extends ContextStorageHandler<T> {
-  register: <T extends Record<string, unknown>>(data: MaybeRefOrGetter<T>, options: RegisterWebStorageHandlerOptions<T>) => () => void;
-}
+interface RegisterWebStorageHandlerOptions<T> extends RegisterBaseOptions<T>, RegisterWebStorageHandlerBaseOptions<T> {}
 interface ContextStorageWebStorageRegisteredItem<T extends Record<string, unknown>> {
   data: MaybeRefOrGetter<T>;
   initialData: T;
@@ -317,33 +306,6 @@ interface ContextStorageWebStorageRegisteredItem<T extends Record<string, unknow
   watchHandle: WatchHandle;
 }
 //#endregion
-//#region src/handlers/web-storage-base/index.d.ts
-declare abstract class ContextStorageWebStorageHandler<T extends Record<string, unknown>> implements IContextStorageWebStorageHandler<T> {
-  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<T>>;
-  protected readonly options: Required<WebStorageHandlerBaseOptions>;
-  private storageEventHandler;
-  constructor(defaultOptions: Required<WebStorageHandlerBaseOptions>);
-  protected initializeStorageListener(): void;
-  protected handleStorageEvent(event: StorageEvent): void;
-  getInjectionKey(): InjectionKey<ContextStorageWebStorageHandler<T>>;
-  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.
@@ -358,15 +320,23 @@ type UseWebStorageOptions<T> = RegisterWebStorageHandlerBaseOptions<T> & Require
  * ```
  */
 interface ContextStorageHandlerMap<T> {
-  query: RegisterQueryHandlerBaseOptions<T>;
-  localStorage: UseWebStorageOptions<T>;
-  sessionStorage: UseWebStorageOptions<T>;
+  query: RegisterQueryHandlerOptions<T>;
+  localStorage: RegisterWebStorageHandlerOptions<T>;
+  sessionStorage: RegisterWebStorageHandlerOptions<T>;
 }
-declare function defineContextStorageHandler<T>(name: string, injectionKey: InjectionKey<ContextStorageHandler<T>>): void;
-declare function resolveHandlerInjectionKey<K$1 extends keyof ContextStorageHandlerMap<T>, T>(type: K$1): InjectionKey<ContextStorageHandler<T>> | undefined;
+declare function defineContextStorageHandler<T, O extends object>(name: string, injectionKey: InjectionKey<ContextStorageHandler<T, O>>): void;
+declare function resolveHandlerInjectionKey<K$1 extends keyof ContextStorageHandlerMap<T>, T>(type: K$1): InjectionKey<ContextStorageHandler<T, ContextStorageHandlerMap<T>[K$1]>> | undefined;
+//#endregion
+//#region src/composables/types.d.ts
+type UseContextStorageResult<T> = {
+  data: MaybeRefOrGetter<T>;
+  stop: () => void;
+  reset: () => void;
+  wasChanged: ComputedRef<boolean>;
+};
 //#endregion
 //#region src/composables/useContextStorage.d.ts
-declare function useContextStorage<K$1 extends keyof ContextStorageHandlerMap<T>, T>(type: K$1, data: MaybeRefOrGetter<T>, options: ContextStorageHandlerMap<T>[K$1]): void;
+declare function useContextStorage<K$1 extends keyof ContextStorageHandlerMap<T>, T>(type: K$1, data: MaybeRefOrGetter<T>, options: ContextStorageHandlerMap<T>[K$1]): UseContextStorageResult<T>;
 //#endregion
 //#region src/composables/useContextStorageActivator.d.ts
 declare function useContextStorageActivator(): {
@@ -383,11 +353,12 @@ declare function useContextStorageProvider(key: string): void;
 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<T extends Record<string, unknown>> implements IContextStorageQueryHandler<T> {
+declare function useContextStorageQueryHandler<T extends Record<string, unknown>>(data: MaybeRefOrGetter<T>, options?: RegisterQueryHandlerOptions<T>): UseContextStorageResult<T>;
+declare class ContextStorageQueryHandler<T extends Record<string, unknown>> implements ContextStorageHandler<T, RegisterQueryHandlerOptions<T>> {
   #private;
   private enabled;
   private registered;
+  private registeredDataObjects;
   private currentQuery;
   private readonly route;
   private router;
@@ -395,6 +366,8 @@ declare class ContextStorageQueryHandler<T extends Record<string, unknown>> impl
   private hasAnyRegistered;
   private preventSyncRegisteredToQueryByAfterEachRoute;
   private preventAfterEachRouteCallsWhileCallingRouter;
+  private syncToQueryScheduled;
+  private registeredVersion;
   static customQueryHandlerOptions: QueryHandlerBaseOptions;
   private readonly options;
   static configure<T extends Record<string, unknown>>(options: QueryHandlerBaseOptions): ContextStorageHandlerConstructor<T>;
@@ -404,31 +377,67 @@ declare class ContextStorageQueryHandler<T extends Record<string, unknown>> impl
   static getInitialStateResolver(): () => LocationQuery;
   setEnabled(state: boolean, initial: boolean): void;
   syncRegisteredToQuery(): Promise<void>;
+  private scheduleSyncToQuery;
   afterEachRoute(): void;
-  syncInitialStateToRegisteredItem<T extends Record<string, unknown>>(item: ContextStorageQueryRegisteredItem<T>): void;
   syncInitialStateToRegistered(): void;
-  register<T extends Record<string, unknown>>(data: MaybeRefOrGetter<T>, options: RegisterQueryHandlerOptions<T>): () => void;
+  syncInitialStateToRegisteredItem<T extends Record<string, unknown>>(item: ContextStorageQueryRegisteredItem<T>): void;
+  register<T extends Record<string, unknown>>(data: MaybeRefOrGetter<T>, options: RegisterQueryHandlerOptions<T>): {
+    stop: () => void;
+    reset: () => void;
+    wasChanged: vue19.ComputedRef<boolean>;
+  };
+}
+//#endregion
+//#region src/handlers/web-storage-base/index.d.ts
+declare abstract class ContextStorageWebStorageHandler<T extends Record<string, unknown>> implements ContextStorageHandler<T, RegisterWebStorageHandlerOptions<T>> {
+  protected enabled: boolean;
+  protected registered: ContextStorageWebStorageRegisteredItem<any>[];
+  private registeredDataObjects;
+  protected initialState?: Record<string, unknown>;
+  protected hasAnyRegistered: boolean;
+  protected preventSyncToStorage: boolean;
+  protected abstract readonly storage: Storage;
+  protected abstract readonly injectionKey: InjectionKey<ContextStorageWebStorageHandler<T>>;
+  protected abstract readonly handlerName: string;
+  protected readonly options: Required<WebStorageHandlerBaseOptions>;
+  private storageEventHandler;
+  protected constructor(defaultOptions: Required<WebStorageHandlerBaseOptions>);
+  protected initializeStorageListener(): void;
+  protected handleStorageEvent(event: StorageEvent): void;
+  getInjectionKey(): InjectionKey<ContextStorageWebStorageHandler<T>>;
+  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>): {
+    stop: () => void;
+    reset: () => void;
+    wasChanged: vue19.ComputedRef<boolean>;
+  };
 }
 //#endregion
 //#region src/handlers/local-storage/index.d.ts
 declare class ContextStorageLocalStorageHandler<T extends Record<string, unknown>> extends ContextStorageWebStorageHandler<T> {
   protected readonly storage: Storage;
   protected readonly injectionKey: InjectionKey<ContextStorageLocalStorageHandler<T>>;
+  protected readonly handlerName = "localStorage";
   static customHandlerOptions: WebStorageHandlerBaseOptions;
   constructor();
   static configure<T extends Record<string, unknown>>(options: WebStorageHandlerBaseOptions): ContextStorageHandlerConstructor<T>;
 }
-declare const useContextStorageLocalStorage: <T extends Record<string, unknown>>(data: vue9.MaybeRefOrGetter<T>, options: UseWebStorageOptions<T>) => void;
+declare const useContextStorageLocalStorage: (data: vue19.MaybeRefOrGetter<Record<string, unknown>>, options: RegisterWebStorageHandlerOptions<Record<string, unknown>>) => UseContextStorageResult<Record<string, unknown>>;
 //#endregion
 //#region src/handlers/session-storage/index.d.ts
 declare class ContextStorageSessionStorageHandler<T extends Record<string, unknown>> extends ContextStorageWebStorageHandler<T> {
   protected readonly storage: Storage;
   protected readonly injectionKey: InjectionKey<ContextStorageSessionStorageHandler<T>>;
+  protected readonly handlerName = "sessionStorage";
   static customHandlerOptions: WebStorageHandlerBaseOptions;
   constructor();
   static configure<T extends Record<string, unknown>>(options: WebStorageHandlerBaseOptions): ContextStorageHandlerConstructor<T>;
 }
-declare const useContextStorageSessionStorage: <T extends Record<string, unknown>>(data: vue9.MaybeRefOrGetter<T>, options: UseWebStorageOptions<T>) => void;
+declare const useContextStorageSessionStorage: (data: vue19.MaybeRefOrGetter<Record<string, unknown>>, options: RegisterWebStorageHandlerOptions<Record<string, unknown>>) => UseContextStorageResult<Record<string, unknown>>;
 //#endregion
 //#region src/handlers/query/transform-helpers.d.ts
 declare function asNumber(value: QueryValue | number | undefined): number;
@@ -598,7 +607,7 @@ declare function serializeParams(params: Record<string, unknown>, options?: Seri
  * deserializeParams({ 'filters[status]': 'active', search: 'test' })
  * // => { filters: {status: 'active'}, search: 'test' }
  */
-declare function deserializeParams(params: Record<string, any>): Record<string, any>;
+declare function deserializeParams(params: Record<string, any>): Record<string, unknown>;
 //#endregion
 //#region src/injectionSymbols.d.ts
 declare const contextStorageCollectionInjectKey: InjectionKey<CollectionManager>;
@@ -611,4 +620,4 @@ declare const contextStorageSessionStorageHandlerInjectKey: InjectionKey<Instanc
 //#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, 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 };
+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 WebStorageHandlerBaseOptions as LocalStorageHandlerBaseOptions, type QueryValue, type RegisterBaseOptions, type RegisterWebStorageHandlerBaseOptions as RegisterLocalStorageHandlerBaseOptions, 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 };