vue-context-storage 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,262 @@
+# vue-context-storage
+
+Vue 3 context storage system with URL query synchronization support.
+
+A powerful state management solution for Vue 3 applications that provides:
+- **Context-based storage** using Vue's provide/inject API
+- **Automatic URL query synchronization** for preserving state across page reloads
+- **Multiple storage contexts** with activation management
+- **Type-safe** TypeScript support
+- **Tree-shakeable** and lightweight
+
+## Installation
+
+```bash
+npm install vue-context-storage
+```
+
+## Features
+
+- ✅ **Vue 3 Composition API** - Built with modern Vue patterns
+- ✅ **URL Query Sync** - Automatically sync state with URL parameters
+- ✅ **Multiple Contexts** - Support multiple independent storage contexts
+- ✅ **TypeScript** - Full type safety and IntelliSense support
+- ✅ **Flexible** - Works with vue-router 4+
+- ✅ **Transform Helpers** - Built-in utilities for type conversion
+
+## Basic Usage
+
+### Option 1: Using Vue Plugin (Recommended)
+
+Register the plugin in your main app file:
+
+```typescript
+import { createApp } from 'vue'
+import { VueContextStoragePlugin } from 'vue-context-storage/plugin'
+import App from './App.vue'
+
+const app = createApp(App)
+
+// Register components globally
+app.use(VueContextStoragePlugin)
+
+app.mount('#app')
+```
+
+Then use components without importing:
+
+```vue
+<template>
+  <ContextStorageRoot>
+    <router-view />
+  </ContextStorageRoot>
+</template>
+```
+
+### Option 2: Manual Component Import
+
+Import components individually when needed:
+
+```vue
+<template>
+  <ContextStorageRoot>
+    <router-view />
+  </ContextStorageRoot>
+</template>
+
+<script setup lang="ts">
+import { ContextStorageRoot } from 'vue-context-storage/components'
+</script>
+```
+
+## Use Query Handler in Components
+
+Sync reactive state with URL query parameters:
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { useContextStorageQueryHandler } from 'vue-context-storage'
+
+interface Filters {
+  search: string
+  status: string
+  page: number
+}
+
+const filters = ref<Filters>({
+  search: '',
+  status: 'active',
+  page: 1
+})
+
+// Automatically syncs filters with URL query
+useContextStorageQueryHandler(filters, {
+  prefix: 'filters' // URL will be: ?filters[search]=...&filters[status]=...
+})
+</script>
+```
+
+## Advanced Usage
+
+### Using Transform Helpers
+
+Convert URL query string values to proper types:
+
+```typescript
+import { ref } from 'vue'
+import { useContextStorageQueryHandler, asNumber, asString } from 'vue-context-storage'
+
+interface TableState {
+  page: number
+  search: string
+  perPage: number
+}
+
+const state = ref<TableState>({
+  page: 1,
+  search: '',
+  perPage: 25
+})
+
+useContextStorageQueryHandler(state, {
+  prefix: 'table',
+  transform: (deserialized, initial) => ({
+    page: asNumber(deserialized.page, { fallback: 1 }),
+    search: asString(deserialized.search, { fallback: '' }),
+    perPage: asNumber(deserialized.perPage, { fallback: 25 })
+  })
+})
+```
+
+### Available Transform Helpers
+
+- `asNumber(value, options)` - Convert to number
+- `asString(value, options)` - Convert to string
+- `asBoolean(value, options)` - Convert to boolean
+- `asArray(value, options)` - Convert to array
+- `asNumberArray(value, options)` - Convert to number array
+
+### Preserve Empty State
+
+Keep empty state in URL to prevent resetting on reload:
+
+```typescript
+useContextStorageQueryHandler(filters, {
+  prefix: 'filters',
+  preserveEmptyState: true
+  // Empty filters will show as: ?filters
+  // Without this option, empty filters would clear the URL completely
+})
+```
+
+### Configure Query Handler
+
+Customize global behavior:
+
+```typescript
+import { ContextStorageQueryHandler } from 'vue-context-storage'
+
+const CustomQueryHandler = ContextStorageQueryHandler.configure({
+  mode: 'push', // 'replace' (default) or 'push' for history
+  preserveUnusedKeys: true, // Keep other query params
+  preserveEmptyState: false
+})
+
+// Use in ContextStorageRoot
+<ContextStorageRoot :handlers="[CustomQueryHandler]">
+```
+
+## API Reference
+
+### Composables
+
+#### `useContextStorageQueryHandler<T>(data, options)`
+
+Registers reactive data for URL query synchronization.
+
+**Parameters:**
+- `data: Ref<T>` - Reactive reference to sync
+- `options?: RegisterQueryHandlerOptions<T>`
+  - `prefix?: string` - Query parameter prefix
+  - `transform?: (deserialized, initial) => T` - Transform function
+  - `preserveEmptyState?: boolean` - Keep empty state in URL
+  - `mergeOnlyExistingKeysWithoutTransform?: boolean` - Only merge existing keys (default: true)
+
+### Classes
+
+#### `ContextStorageQueryHandler`
+
+Main handler for URL query synchronization.
+
+**Static Methods:**
+- `configure(options): ContextStorageHandlerConstructor` - Configure global options
+- `getInitialStateResolver(): () => LocationQuery` - Get initial state resolver
+
+**Methods:**
+- `register<T>(data, options): () => void` - Register data for sync
+- `setEnabled(state, initial): void` - Enable/disable handler
+- `setInitialState(state): void` - Set initial state
+
+### Transform Helpers
+
+All transform helpers support nullable and missable options:
+
+```typescript
+asNumber(value, {
+  fallback: 0,      // Default value
+  nullable: false,  // Allow null return
+  missable: false   // Allow undefined return
+})
+```
+
+## TypeScript Support
+
+Full TypeScript support with type inference:
+
+```typescript
+import type {
+  ContextStorageHandler,
+  ContextStorageHandlerConstructor,
+  IContextStorageQueryHandler,
+  QueryValue,
+  SerializeOptions
+} from 'vue-context-storage'
+```
+
+## Examples
+
+### Pagination with URL Sync
+
+```typescript
+import { ref } from 'vue'
+import { useContextStorageQueryHandler, asNumber } from 'vue-context-storage'
+
+const pagination = ref({
+  page: 1,
+  perPage: 25,
+  total: 0
+})
+
+useContextStorageQueryHandler(pagination, {
+  prefix: 'page',
+  transform: (data, initial) => ({
+    page: asNumber(data.page, { fallback: 1 }),
+    perPage: asNumber(data.perPage, { fallback: 25 }),
+    total: initial.total // Don't sync total from URL
+  })
+})
+```
+
+## Peer Dependencies
+
+- `vue`: ^3.5.0
+- `vue-router`: ^4.0.0
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

package/dist/collection.d.cts

@@ -0,0 +1,22 @@
+import { ContextStorageHandler, ContextStorageHandlerConstructor } from './handlers';
+export type ContextStorageCollectionItem = {
+    key: string;
+    handlers: ContextStorageHandler[];
+};
+interface ItemOptions {
+    key: string;
+}
+export declare class ContextStorageCollection {
+    private handlerConstructors;
+    active?: ContextStorageCollectionItem;
+    private collection;
+    private onActiveChangeCallbacks;
+    constructor(handlerConstructors: ContextStorageHandlerConstructor[]);
+    onActiveChange(callback: (item: ContextStorageCollectionItem) => void): void;
+    first(): ContextStorageCollectionItem | undefined;
+    findItemByKey(key: string): ContextStorageCollectionItem | undefined;
+    add(options: ItemOptions): ContextStorageCollectionItem;
+    remove(removeItem: ContextStorageCollectionItem): void;
+    setActive(activeItem: ContextStorageCollectionItem): void;
+}
+export {};

package/dist/collection.d.ts

@@ -0,0 +1,22 @@
+import { ContextStorageHandler, ContextStorageHandlerConstructor } from './handlers';
+export type ContextStorageCollectionItem = {
+    key: string;
+    handlers: ContextStorageHandler[];
+};
+interface ItemOptions {
+    key: string;
+}
+export declare class ContextStorageCollection {
+    private handlerConstructors;
+    active?: ContextStorageCollectionItem;
+    private collection;
+    private onActiveChangeCallbacks;
+    constructor(handlerConstructors: ContextStorageHandlerConstructor[]);
+    onActiveChange(callback: (item: ContextStorageCollectionItem) => void): void;
+    first(): ContextStorageCollectionItem | undefined;
+    findItemByKey(key: string): ContextStorageCollectionItem | undefined;
+    add(options: ItemOptions): ContextStorageCollectionItem;
+    remove(removeItem: ContextStorageCollectionItem): void;
+    setActive(activeItem: ContextStorageCollectionItem): void;
+}
+export {};

package/dist/handlers/query/helpers.d.cts

@@ -0,0 +1,45 @@
+import { LocationQuery } from 'vue-router';
+export interface SerializeOptions {
+    /**
+     * Custom prefix for serialized keys.
+     * @example
+     * - prefix: 'filters' => 'filters[key]'
+     * - prefix: 'search' => 'search[key]'
+     * - prefix: '' => 'key' (no prefix)
+     */
+    prefix?: string;
+}
+/**
+ * Serializes filter parameters into a URL-friendly format.
+ *
+ * @param params - Raw parameters object to serialize
+ * @param options - Serialization options
+ * @returns Serialized parameters with prefixed keys
+ *
+ * @example
+ * // With default prefix 'filters'
+ * serializeFiltersParams({ status: 'active', tags: ['a', 'b'] })
+ * // => { 'filters[status]': 'active', 'filters[tags]': 'a,b' }
+ *
+ * @example
+ * // With custom prefix
+ * serializeFiltersParams({ name: 'John', all: true }, { prefix: 'search' })
+ * // => { 'search[name]': 'John', 'search[all]': '1' }
+ *
+ * @example
+ * // Without prefix
+ * serializeFiltersParams({ page: 1, all: false }, { prefix: '' })
+ * // => { 'page': '1', 'all': '0' }
+ */
+export declare function serializeParams(params: Record<string, unknown>, options?: SerializeOptions): LocationQuery;
+/**
+ * Deserializes query parameters from a URL-friendly format back to an object.
+ *
+ * @param params - Serialized parameters object
+ * @returns Deserialized parameters object
+ *
+ * @example
+ * deserializeParams({ 'filters[status]': 'active', search: 'test' })
+ * // => { filters: {status: 'active'}, search: 'test' }
+ */
+export declare function deserializeParams(params: Record<string, any>): Record<string, any>;

package/dist/handlers/query/helpers.d.ts

@@ -0,0 +1,45 @@
+import { LocationQuery } from 'vue-router';
+export interface SerializeOptions {
+    /**
+     * Custom prefix for serialized keys.
+     * @example
+     * - prefix: 'filters' => 'filters[key]'
+     * - prefix: 'search' => 'search[key]'
+     * - prefix: '' => 'key' (no prefix)
+     */
+    prefix?: string;
+}
+/**
+ * Serializes filter parameters into a URL-friendly format.
+ *
+ * @param params - Raw parameters object to serialize
+ * @param options - Serialization options
+ * @returns Serialized parameters with prefixed keys
+ *
+ * @example
+ * // With default prefix 'filters'
+ * serializeFiltersParams({ status: 'active', tags: ['a', 'b'] })
+ * // => { 'filters[status]': 'active', 'filters[tags]': 'a,b' }
+ *
+ * @example
+ * // With custom prefix
+ * serializeFiltersParams({ name: 'John', all: true }, { prefix: 'search' })
+ * // => { 'search[name]': 'John', 'search[all]': '1' }
+ *
+ * @example
+ * // Without prefix
+ * serializeFiltersParams({ page: 1, all: false }, { prefix: '' })
+ * // => { 'page': '1', 'all': '0' }
+ */
+export declare function serializeParams(params: Record<string, unknown>, options?: SerializeOptions): LocationQuery;
+/**
+ * Deserializes query parameters from a URL-friendly format back to an object.
+ *
+ * @param params - Serialized parameters object
+ * @returns Deserialized parameters object
+ *
+ * @example
+ * deserializeParams({ 'filters[status]': 'active', search: 'test' })
+ * // => { filters: {status: 'active'}, search: 'test' }
+ */
+export declare function deserializeParams(params: Record<string, any>): Record<string, any>;

package/dist/handlers/query/index.d.cts

@@ -0,0 +1,31 @@
+import { ContextStorageHandlerConstructor } from '../../handlers.ts';
+import { contextStorageQueryHandler } from '../../symbols.ts';
+import { MaybeRefOrGetter } from 'vue';
+import { LocationQuery } from 'vue-router';
+import { ContextStorageQueryRegisteredItem, IContextStorageQueryHandler, QueryHandlerBaseOptions, RegisterQueryHandlerBaseOptions, RegisterQueryHandlerOptions } from './types.ts';
+export declare function useContextStorageQueryHandler<T extends Record<string, unknown>>(data: MaybeRefOrGetter<T>, options?: RegisterQueryHandlerBaseOptions<T>): void;
+export declare class ContextStorageQueryHandler implements IContextStorageQueryHandler {
+    #private;
+    private enabled;
+    private registered;
+    private currentQuery;
+    private readonly route;
+    private router;
+    private initialState?;
+    private hasAnyRegistered;
+    private preventSyncRegisteredToQueryByAfterEachRoute;
+    private preventAfterEachRouteCallsWhileCallingRouter;
+    static customQueryHandlerOptions: QueryHandlerBaseOptions;
+    private readonly options;
+    static configure(options: QueryHandlerBaseOptions): ContextStorageHandlerConstructor;
+    constructor();
+    getInjectionKey(): typeof contextStorageQueryHandler;
+    setInitialState(state: Record<string, unknown> | undefined): void;
+    static getInitialStateResolver(): () => LocationQuery;
+    setEnabled(state: boolean, initial: boolean): void;
+    syncRegisteredToQuery(): Promise<void>;
+    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;
+}

package/dist/handlers/query/index.d.ts

@@ -0,0 +1,31 @@
+import { ContextStorageHandlerConstructor } from '../../handlers.ts';
+import { contextStorageQueryHandler } from '../../symbols.ts';
+import { MaybeRefOrGetter } from 'vue';
+import { LocationQuery } from 'vue-router';
+import { ContextStorageQueryRegisteredItem, IContextStorageQueryHandler, QueryHandlerBaseOptions, RegisterQueryHandlerBaseOptions, RegisterQueryHandlerOptions } from './types.ts';
+export declare function useContextStorageQueryHandler<T extends Record<string, unknown>>(data: MaybeRefOrGetter<T>, options?: RegisterQueryHandlerBaseOptions<T>): void;
+export declare class ContextStorageQueryHandler implements IContextStorageQueryHandler {
+    #private;
+    private enabled;
+    private registered;
+    private currentQuery;
+    private readonly route;
+    private router;
+    private initialState?;
+    private hasAnyRegistered;
+    private preventSyncRegisteredToQueryByAfterEachRoute;
+    private preventAfterEachRouteCallsWhileCallingRouter;
+    static customQueryHandlerOptions: QueryHandlerBaseOptions;
+    private readonly options;
+    static configure(options: QueryHandlerBaseOptions): ContextStorageHandlerConstructor;
+    constructor();
+    getInjectionKey(): typeof contextStorageQueryHandler;
+    setInitialState(state: Record<string, unknown> | undefined): void;
+    static getInitialStateResolver(): () => LocationQuery;
+    setEnabled(state: boolean, initial: boolean): void;
+    syncRegisteredToQuery(): Promise<void>;
+    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;
+}

package/dist/handlers/query/transform-helpers.d.cts

@@ -0,0 +1,123 @@
+import { QueryValue } from './types.ts';
+export declare function asNumber(value: QueryValue | number | undefined): number;
+export declare function asNumber(value: QueryValue | number | undefined, options: {
+    nullable: true;
+    missable: true;
+    fallbackValue?: number;
+}): number | null | undefined;
+export declare function asNumber(value: QueryValue | number | undefined, options: {
+    nullable: true;
+    missable?: false;
+    fallbackValue?: number;
+}): number | null;
+export declare function asNumber(value: QueryValue | number | undefined, options: {
+    nullable?: false;
+    missable: true;
+    fallbackValue?: number;
+}): number | undefined;
+export declare function asNumber(value: QueryValue | number | undefined, options: {
+    nullable?: false;
+    missable?: false;
+    fallbackValue?: number;
+}): number;
+export declare function asString(value: QueryValue | undefined): string;
+export declare function asString<T extends readonly string[]>(value: QueryValue | undefined, options: {
+    nullable: true;
+    missable: true;
+    fallbackValue?: T[number];
+    allowedValues: T;
+}): T[number] | null | undefined;
+export declare function asString<T extends readonly string[]>(value: QueryValue | undefined, options: {
+    nullable: true;
+    missable?: false;
+    fallbackValue?: T[number];
+    allowedValues: T;
+}): T[number] | null;
+export declare function asString<T extends readonly string[]>(value: QueryValue | undefined, options: {
+    nullable?: false;
+    missable: true;
+    fallbackValue?: T[number];
+    allowedValues: T;
+}): T[number] | undefined;
+export declare function asString<T extends readonly string[]>(value: QueryValue | undefined, options: {
+    nullable?: false;
+    missable?: false;
+    fallbackValue?: T[number];
+    allowedValues: T;
+}): T[number];
+export declare function asString(value: QueryValue | undefined, options: {
+    nullable: true;
+    missable: true;
+    fallbackValue?: string;
+}): string | null | undefined;
+export declare function asString(value: QueryValue | undefined, options: {
+    nullable: true;
+    missable?: false;
+    fallbackValue?: string;
+}): string | null;
+export declare function asString(value: QueryValue | undefined, options: {
+    nullable?: false;
+    missable: true;
+    fallbackValue?: string;
+}): string | undefined;
+export declare function asString(value: QueryValue | undefined, options: {
+    nullable?: false;
+    missable?: false;
+    fallbackValue?: string;
+}): string;
+export declare function asNumberArray(value: QueryValue | undefined): number[];
+export declare function asNumberArray(value: QueryValue | undefined, options: {
+    nullable: true;
+}): number[] | null;
+export declare function asNumberArray(value: QueryValue | undefined, options: {
+    nullable?: false;
+}): number[];
+export declare function asArray<T>(value: QueryValue | undefined): T[];
+export declare function asArray<T>(value: QueryValue | undefined, options: {
+    nullable: true;
+    missable: true;
+    transform?: (value: QueryValue) => T;
+}): T[] | null | undefined;
+export declare function asArray<T>(value: QueryValue | undefined, options: {
+    nullable: true;
+    missable?: false;
+    transform?: (value: QueryValue) => T;
+}): T[] | null;
+export declare function asArray<T>(value: QueryValue | undefined, options: {
+    nullable?: false;
+    missable: true;
+    transform?: (value: QueryValue) => T;
+}): T[] | undefined;
+export declare function asArray<T>(value: QueryValue | undefined, options: {
+    nullable?: false;
+    missable?: false;
+    transform?: (value: QueryValue) => T;
+}): T[];
+export declare function asBoolean(value: QueryValue | undefined): boolean;
+export declare function asBoolean(value: QueryValue | undefined, options: {
+    nullable: true;
+    missable: true;
+    fallbackValue?: boolean;
+}): boolean | null | undefined;
+export declare function asBoolean(value: QueryValue | undefined, options: {
+    nullable: true;
+    missable?: false;
+    fallbackValue?: boolean;
+}): boolean | null;
+export declare function asBoolean(value: QueryValue | undefined, options: {
+    nullable?: false;
+    missable: true;
+    fallbackValue?: boolean;
+}): boolean | undefined;
+export declare function asBoolean(value: QueryValue | undefined, options: {
+    nullable?: false;
+    missable?: false;
+    fallbackValue?: boolean;
+}): boolean;
+export declare const transform: {
+    asString: typeof asString;
+    asNumber: typeof asNumber;
+    asArray: typeof asArray;
+    asNumberArray: typeof asNumberArray;
+    asBoolean: typeof asBoolean;
+};