vue-context-storage 0.1.12 → 0.1.13

package/README.md

@@ -2,6 +2,14 @@
 
 Vue 3 context storage system with URL query synchronization support.
 
+[![npm downloads](https://img.shields.io/npm/dm/vue-context-storage.svg)](https://www.npmjs.com/package/vue-context-storage)
+[![TypeScript](https://badgen.net/badge/icon/TypeScript?icon=typescript&label)](https://www.typescriptlang.org/)
+[![Vue 3](https://img.shields.io/badge/vue-3.x-brightgreen.svg)](https://vuejs.org/)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/vue-context-storage)](https://bundlephobia.com/package/vue-context-storage)
+[![GitHub issues](https://img.shields.io/github/issues/lviobio/vue-context-storage)](https://github.com/lviobio/vue-context-storage/issues)
+[![GitHub License](https://img.shields.io/github/license/lviobio/vue-context-storage)](https://github.com/lviobio/vue-context-storage)
+[![Live Demo](https://img.shields.io/badge/demo-live-brightgreen)](https://lviobio.github.io/vue-context-storage/)
+
 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
@@ -9,6 +17,10 @@ A powerful state management solution for Vue 3 applications that provides:
 - **Type-safe** TypeScript support
 - **Tree-shakeable** and lightweight
 
+## Live Demo
+
+🚀 **[Try the interactive playground](https://lviobio.github.io/vue-context-storage)**
+
 ## Installation
 
 ```bash
@@ -43,7 +55,7 @@ app.use(VueContextStoragePlugin)
 app.mount('#app')
 ```
 
-Then use components without importing:
+Then use components without importing in your `App.vue`:
 
 ```vue
 <template>
@@ -55,7 +67,7 @@ Then use components without importing:
 
 ### Option 2: Manual Component Import
 
-Import components individually when needed:
+Import components individually when needed in your `App.vue`:
 
 ```vue
 <template>
@@ -84,7 +96,7 @@ interface Filters {
   page: number
 }
 
-const filters = ref<Filters>({
+const filters = reactive<Filters>({
   search: '',
   status: 'active',
   page: 1,
@@ -137,6 +149,39 @@ useContextStorageQueryHandler(state, {
 - `asArray(value, options)` - Convert to array
 - `asNumberArray(value, options)` - Convert to number array
 
+### Using Zod Schemas
+
+Alternatively, you can use [Zod](https://zod.dev/) schemas for automatic validation and type inference:
+
+```typescript
+import { z } from 'zod'
+import { useContextStorageQueryHandler } from 'vue-context-storage'
+
+// Define schema with automatic coercion
+const FiltersSchema = z.object({
+  search: z.string().default(''),
+  page: z.coerce.number().int().positive().default(1),
+  status: z.enum(['active', 'inactive']).default('active'),
+})
+
+const filters = ref(FiltersSchema.parse({}))
+
+// Use schema for automatic validation
+useContextStorageQueryHandler(filters, {
+  prefix: 'filters',
+  schema: FiltersSchema,
+})
+```
+
+**Benefits:**
+- Automatic type coercion (strings → numbers, etc.)
+- Runtime validation with detailed errors
+- Automatic TypeScript type inference
+- Less boilerplate code
+- Single source of truth for structure and validation
+
+See [ZOD_INTEGRATION.md](./ZOD_INTEGRATION.md) for detailed examples and comparison with manual transforms.
+
 ### Preserve Empty State
 
 Keep empty state in URL to prevent resetting on reload:
@@ -173,7 +218,7 @@ ContextStorageQueryHandler.configure({
 Registers reactive data for URL query synchronization.
 
 **Parameters:**
-- `data: Ref<T>` - Reactive reference to sync
+- `data: MaybeRefOrGetter<T>` - Reactive reference to sync
 - `options?: RegisterQueryHandlerOptions<T>`
   - `prefix?: string` - Query parameter prefix
   - `transform?: (deserialized, initial) => T` - Transform function
@@ -221,6 +266,18 @@ import type {
 } from 'vue-context-storage'
 ```
 
+When using Zod schemas, TypeScript will automatically infer types:
+
+```typescript
+const FiltersSchema = z.object({
+  search: z.string().default(''),
+  page: z.coerce.number().default(1),
+})
+
+type Filters = z.infer<typeof FiltersSchema>
+// Result: { search: string; page: number }
+```
+
 ## Examples
 
 ### Pagination with URL Sync
@@ -249,11 +306,51 @@ useContextStorageQueryHandler(pagination, {
 
 - `vue`: ^3.5.0
 - `vue-router`: ^4.0.0
+- `zod`: ^4.0.0 (optional - only if using schema validation)
 
 ## License
 
 MIT
 
+## Development
+
+### Running Playground Locally
+
+```bash
+# Development mode (hot reload)
+npm run play
+
+# Production preview
+npm run build:playground
+npm run preview:playground
+```
+
+### Building
+
+```bash
+# Build library
+npm run build
+
+# Build playground for deployment
+npm run build:playground
+```
+
+### Testing & Quality
+
+```bash
+# Run all checks
+npm run check
+
+# Type checking
+npm run ts:check
+
+# Linting
+npm run lint
+
+# Formatting
+npm run format
+```
+
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.

package/dist/index.d.ts

@@ -1,12 +1,12 @@
-import * as vue4 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: vue4.DefineComponent<{}, () => vue4.VNode<vue4.RendererNode, vue4.RendererElement, {
+declare const __VLS_export$3: vue9.DefineComponent<{}, () => vue9.VNode<vue9.RendererNode, vue9.RendererElement, {
   [key: string]: any;
-}>, {}, {}, {}, vue4.ComponentOptionsMixin, vue4.ComponentOptionsMixin, {}, string, vue4.PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, vue4.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,37 +26,37 @@ interface ContextStorageHandler {
 //#endregion
 //#region src/components/ContextStorageCollection.vue.d.ts
 declare const _default$2: typeof __VLS_export$2;
-declare const __VLS_export$2: vue4.DefineComponent<vue4.ExtractPropTypes<{
+declare const __VLS_export$2: vue9.DefineComponent<vue9.ExtractPropTypes<{
   handlers: {
     type: PropType<ContextStorageHandlerConstructor[]>;
     default: () => ContextStorageHandlerConstructor[];
   };
-}>, () => vue4.VNode<vue4.RendererNode, vue4.RendererElement, {
+}>, () => vue9.VNode<vue9.RendererNode, vue9.RendererElement, {
   [key: string]: any;
-}>[] | undefined, {}, {}, {}, vue4.ComponentOptionsMixin, vue4.ComponentOptionsMixin, {}, string, vue4.PublicProps, Readonly<vue4.ExtractPropTypes<{
+}>[] | undefined, {}, {}, {}, vue9.ComponentOptionsMixin, vue9.ComponentOptionsMixin, {}, string, vue9.PublicProps, Readonly<vue9.ExtractPropTypes<{
   handlers: {
     type: PropType<ContextStorageHandlerConstructor[]>;
     default: () => ContextStorageHandlerConstructor[];
   };
 }>> & Readonly<{}>, {
   handlers: ContextStorageHandlerConstructor[];
-}, {}, {}, {}, string, vue4.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: vue4.DefineComponent<vue4.ExtractPropTypes<{
+declare const __VLS_export$1: vue9.DefineComponent<vue9.ExtractPropTypes<{
   itemKey: {
     type: StringConstructor;
     required: true;
   };
-}>, () => vue4.VNode<vue4.RendererNode, vue4.RendererElement, {
+}>, () => vue9.VNode<vue9.RendererNode, vue9.RendererElement, {
   [key: string]: any;
-}>[] | undefined, {}, {}, {}, vue4.ComponentOptionsMixin, vue4.ComponentOptionsMixin, {}, string, vue4.PublicProps, Readonly<vue4.ExtractPropTypes<{
+}>[] | undefined, {}, {}, {}, vue9.ComponentOptionsMixin, vue9.ComponentOptionsMixin, {}, string, vue9.PublicProps, Readonly<vue9.ExtractPropTypes<{
   itemKey: {
     type: StringConstructor;
     required: true;
   };
-}>> & Readonly<{}>, {}, {}, {}, {}, string, vue4.ComponentProvideOptions, true, {}, any>;
+}>> & Readonly<{}>, {}, {}, {}, {}, string, vue9.ComponentProvideOptions, true, {}, any>;
 //#endregion
 //#region src/components/ContextStorage.vue.d.ts
 interface Props {
@@ -66,7 +66,7 @@ declare var __VLS_20: {};
 type __VLS_Slots = {} & {
   default?: (props: typeof __VLS_20) => any;
 };
-declare const __VLS_base: vue4.DefineComponent<Props, {}, {}, {}, {}, vue4.ComponentOptionsMixin, vue4.ComponentOptionsMixin, {}, string, vue4.PublicProps, Readonly<Props> & Readonly<{}>, {}, {}, {}, {}, string, vue4.ComponentProvideOptions, false, {}, any>;
+declare const __VLS_base: vue9.DefineComponent<Props, {}, {}, {}, {}, vue9.ComponentOptionsMixin, vue9.ComponentOptionsMixin, {}, string, vue9.PublicProps, Readonly<Props> & Readonly<{}>, {}, {}, {}, {}, string, vue9.ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;
 type __VLS_WithSlots<T, S> = T & {
@@ -169,7 +169,44 @@ interface RegisterQueryHandlerBaseOptions<T> extends QueryHandlerSharedOptions {
    * ```
    */
   prefix?: string;
+  /**
+   * Transform function to convert deserialized query parameters to the expected type.
+   *
+   * 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 extends ContextStorageHandler {

package/dist/index.js

@@ -229,7 +229,7 @@ var ContextStorageQueryHandler = class ContextStorageQueryHandler {
 				query: newQuery
 			});
 		} catch (e) {
-			console.error("[ContextStorage] Got error while routing", e);
+			console.error("[vue-context-storage] Got error while routing", e);
 		}
 		this.preventAfterEachRouteCallsWhileCallingRouter = false;
 	}
@@ -271,7 +271,14 @@ var ContextStorageQueryHandler = class ContextStorageQueryHandler {
 			}
 			if (deserializedKeys.length === 1 && deserialized[this.options.emptyPlaceholder] === null) delete deserialized[this.options.emptyPlaceholder];
 		}
-		if (item.options?.transform) deserialized = item.options.transform(deserialized, item.initialData);
+		if (item.options?.schema) {
+			console.log("[vue-context-storage] 248", deserialized);
+			const result = item.options.schema.safeParse(deserialized);
+			console.log("[vue-context-storage] 251", result);
+			if (result.success) deserialized = result.data;
+			else console.warn("[vue-context-storage] schema parse failed", result.error);
+			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 if (mergeOnlyExistingKeysWithoutTransform) deserialized = pick(deserialized, Object.keys(item.initialData));
 		if (isEqual(itemData, deserialized)) return;
 		merge(itemData, deserialized);
@@ -311,7 +318,7 @@ var ContextStorageQueryHandler = class ContextStorageQueryHandler {
 			const patch = serializeParams(toValue(item.data), { prefix });
 			const patchKeys = Object.keys(patch);
 			patchKeys.forEach((key) => {
-				if (newQueryRaw.hasOwnProperty(key)) console.warn(`[ContextStorage] Key ${key} is already present, overriding ` + (item.options?.causer || ""));
+				if (newQueryRaw.hasOwnProperty(key)) console.warn(`[vue-context-storage] Key ${key} is already present, overriding ` + (item.options?.causer || ""));
 			});
 			if (!patchKeys.length && preserveEmptyState) patch[prefix || this.options.emptyPlaceholder] = null;
 			Object.assign(newQueryRaw, patch);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vue-context-storage",
   "type": "module",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "Vue 3 context storage system with URL query synchronization support",
   "author": "",
   "license": "MIT",
@@ -37,13 +37,21 @@
     "lint:check": "eslint .",
     "dependency-cruiser:check": "depcruise --config .dependency-cruiser.cjs src",
     "play": "vite",
+    "build:playground": "vite build",
+    "preview:playground": "vite preview --outDir playground/dist",
     "test": "vitest",
     "release": "bumpp && npm publish",
     "prepublishOnly": "npm run check && npm run build"
   },
   "peerDependencies": {
     "vue": "^3.0.0",
-    "vue-router": "^4.0.0"
+    "vue-router": "^4.0.0",
+    "zod": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/lodash": "^4.17.21",
@@ -65,7 +73,8 @@
     "vitest": "^4.0.16",
     "vitest-browser-vue": "^2.0.1",
     "vue": "^3.5.26",
-    "vue-tsc": "^3.2.1"
+    "vue-tsc": "^3.2.1",
+    "zod": "^4.3.5"
   },
   "dependencies": {
     "lodash": "^4.17.21"