vue-context-storage 0.1.41 → 0.1.43

package/README.md

@@ -1,6 +1,6 @@
 # vue-context-storage
 
-Vue 3 context storage system with URL query, localStorage, and sessionStorage synchronization support.
+Vue 3 reactive state management — sync state with the URL query, localStorage, and sessionStorage through a single type-safe composable.
 
 [![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/)
@@ -13,15 +13,29 @@ Vue 3 context storage system with URL query, localStorage, and sessionStorage sy
 [![codecov](https://codecov.io/gh/lviobio/vue-context-storage/branch/main/graph/badge.svg)](https://codecov.io/gh/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:
+Key features:
 
-- **Context-based storage** using Vue's provide/inject API
-- **Automatic URL query synchronization** for preserving state across page reloads
-- **localStorage & sessionStorage handlers** for persistent and session-scoped state
-- **Multiple storage contexts** with activation management
-- **Type-safe** TypeScript support
+- **Automatic URL query sync** — painless type coercion (numbers, booleans, arrays) and nested objects
+- **localStorage & sessionStorage** for persistent and session-scoped state — same API as the query handler
+- **Context prefixing** to avoid key collisions when the same key is reused across instances
+- **Type-safe** with optional Zod schema validation
 - **Tree-shakeable** and lightweight
 
+```ts
+const filters = reactive({ search: '', page: 1 })
+
+// reactive state ⇄ URL query — kept in sync automatically, both directions
+useContextStorage('query', filters) // URL: /products?search=shoes&page=2
+useContextStorage('query', filters, { key: 'filters' }) // URL: /products?filters[search]=shoes&filters[page]=2
+// zod schema support with type coercion, 'page' will be converted to number
+useContextStorage('query', filters, { schema: z.object({ search: z.string(), page: z.number() }) }) // URL: /products?filters[search]=shoes&filters[page]=2
+// transform function support with type coercion, 'page' will be converted to number
+useContextStorage('query', filters, {
+  transform: (value) => ({ search: value.search, page: Number(value.page) }),
+}) // URL: /products?filters[search]=shoes&filters[page]=2
+// And a lot of other features... (onlyChanges option; createEmptyZodObject helper for zod schemas; additional default values; passing 'key' via ContextStoragePrefix wrapper)
+```
+
 ## Live Demo
 
 🚀 **[Try the interactive playground](https://lviobio.github.io/vue-context-storage)**
@@ -147,12 +161,14 @@ useContextStorage('query', filters, {
 })
 
 // Option 2: Transform function
+import { transform } from 'vue-context-storage'
+
 useContextStorage('query', filters, {
   key: 'filters',
   transform: (deserialized, initial) => ({
-    page: asNumber(deserialized.page, { fallback: initial.page }),
-    search: asString(deserialized.search, { fallback: initial.search }),
-    status: asString(deserialized.status, { fallback: initial.status }),
+    page: transform.asNumber(deserialized.page, { fallback: initial.page }),
+    search: transform.asString(deserialized.search, { fallback: initial.search }),
+    status: transform.asString(deserialized.status, { fallback: initial.status }),
   }),
 })
 ```
@@ -280,7 +296,7 @@ The query handler supports arrays of objects. They are serialized as indexed que
 ?items[0][product]=Apple&items[0][quantity]=5&items[1][product]=Banana&items[1][quantity]=10
 ```
 
-After deserialization, URL parameters produce indexed objects (`{ '0': {...}, '1': {...} }`) rather than arrays. Use `transform.asObjectArray` or the Zod helper `zObjectArray` to convert them back.
+After deserialization, URL parameters produce indexed objects (`{ '0': {...}, '1': {...} }`) rather than arrays. With a Zod schema, plain `z.array(...)` works out of the box — the library converts indexed objects back to sorted arrays automatically. With the manual approach, use `transform.asObjectArray`.
 
 **With transform helpers:**
 
@@ -310,7 +326,6 @@ useContextStorage('query', data, {
 
 ```typescript
 import { z } from 'zod'
-import { zObjectArray } from 'vue-context-storage/zod'
 
 const ItemSchema = z.object({
   product: z.string().default(''),
@@ -319,13 +334,13 @@ const ItemSchema = z.object({
 
 const DataSchema = z.object({
   title: z.string().default(''),
-  items: zObjectArray(ItemSchema),
+  items: z.array(ItemSchema),
 })
 
 useContextStorage('query', data, { schema: DataSchema })
 ```
 
-See [Zod Helpers](#zod-helpers-vue-context-storagezod) for more details.
+See [Automatic Type Coercion](#automatic-type-coercion) for details on how indexed objects are converted.
 
 ### Preserve Empty State
 
@@ -360,6 +375,55 @@ useContextStorage('query', data, {
 // page=2         → appears in query as ?filters[page]=2
 ```
 
+When using Zod schemas, you can also specify `additionalDefaultData` per-field via `.meta()` instead of (or in addition to) the option:
+
+```typescript
+const Schema = z.object({
+  page: z.coerce.number().default(1).meta({ additionalDefaultData: 3 }),
+  search: z.string().default(''),
+})
+
+const data = reactive({ page: undefined as number | undefined, search: '' })
+
+useContextStorage('query', data, {
+  key: 'filters',
+  schema: Schema,
+})
+
+// page=1 → not in query (matches default from schema)
+// page=2 → appears in query as ?filters[page]=2
+// page=3 → not in query (matches additionalDefaultData from schema meta)
+```
+
+A field's schema `.default(...)` value is itself treated as a default baseline: a value equal to it is omitted from the URL, exactly like the initial snapshot and `additionalDefaultData`. So both the `.default()` value and any `.meta({ additionalDefaultData })` value are excluded, while every other value appears in the query.
+
+Each source of defaults is an **independent baseline** — the initial snapshot, the option-level `additionalDefaultData`, the schema `.meta({ additionalDefaultData })`, and the schema `.default()`. A value is omitted from the URL if it matches **any** of them, so they never overwrite each other (e.g. a field can have a `.default()` of `1`, a meta value of `5`, and an option value of `3`, and all three are excluded).
+
+Nested objects work the same way. Following the documented best practice of declaring `.default()` at the object level, a value matching the nested default is omitted too:
+
+```typescript
+const Schema = z.object({
+  filters: z
+    .object({
+      page: z.coerce.number(),
+      sort: z.string(),
+    })
+    .default({ page: 1, sort: 'asc' }),
+})
+
+const data = reactive({
+  filters: { page: undefined as number | undefined, sort: undefined as string | undefined },
+})
+
+useContextStorage('query', data, { key: 'q', schema: Schema })
+
+// filters = { page: 1, sort: 'asc' }  → not in query (matches the nested default)
+// filters = { page: 2, sort: 'asc' }  → ?q[filters][page]=2 (sort matches default, omitted)
+// filters = { page: 2, sort: 'desc' } → ?q[filters][page]=2&q[filters][sort]=desc
+```
+
+Field-level defaults inside a nested object take priority over the object-level default and fill in any fields the object-level default omits.
+
 ### Configure Query Handler
 
 Customize behavior by passing options to the factory:
@@ -685,33 +749,14 @@ transform.asNumber(value, {
 })
 ```
 
-## Zod Helpers (`vue-context-storage/zod`)
+## Zod Helpers
 
-The library provides a separate entry point with Zod-specific helpers. Since `zod` is an optional peer dependency, these helpers are isolated in `vue-context-storage/zod` to avoid importing Zod in the main bundle.
+Zod-specific helpers are exported from the main entry point. `zod` remains an optional peer dependency — the helpers are implemented via duck-typed schema introspection, so the main bundle never imports Zod at runtime.
 
 ```bash
 npm install zod
 ```
 
-### `zObjectArray(itemSchema)`
-
-Creates a Zod schema for arrays of objects serialized as indexed query parameters. Wraps `z.record()` + `.transform()` to convert indexed objects back to sorted arrays.
-
-```typescript
-import { z } from 'zod'
-import { zObjectArray } from 'vue-context-storage/zod'
-
-const ItemSchema = z.object({
-  product: z.string().default(''),
-  quantity: z.coerce.number().default(0),
-})
-
-const DataSchema = z.object({
-  title: z.string().default(''),
-  items: zObjectArray(ItemSchema),
-})
-```
-
 ### Automatic Type Coercion
 
 When a `schema` is provided, the library automatically coerces URL query parameter values to match the expected Zod types before validation. This handles two common URL serialization quirks:
@@ -740,6 +785,22 @@ const Schema = z.object({
 // (no tags param)    → { tags: [], ... }
 ```
 
+Arrays of objects are also handled automatically. They deserialize from indexed query parameters (`?items[0][product]=Apple`) into indexed objects (`{ '0': { product: 'Apple' } }`), and the library converts them back to arrays sorted by numeric key wherever the schema expects `.array()` — coercion is applied recursively inside array elements as well:
+
+```typescript
+const ItemSchema = z.object({
+  product: z.string().default(''),
+  quantity: z.coerce.number().default(0),
+})
+
+const Schema = z.object({
+  items: z.array(ItemSchema),
+})
+
+// ?items[0][product]=Apple&items[0][quantity]=5
+// → { items: [{ product: 'Apple', quantity: 5 }] }
+```
+
 #### Boolean Coercion
 
 The query handler serializes booleans as `'1'`/`'0'` strings in URL parameters (e.g. `?active=1`). Standard `z.coerce.boolean()` cannot be used because `Boolean('0')` is `true` in JavaScript. The library automatically converts `'1'` → `true` and `'0'` → `false` when the schema expects a boolean field. **No special helpers are needed** — plain `z.boolean()` works out of the box:
@@ -754,13 +815,13 @@ const Schema = z.object({
 // ?active=0  → { active: false, enabled: true }
 ```
 
-### `createSchemaObject(schema, options?)`
+### `createEmptyZodObject(schema, options?)`
 
 Creates a plain object with empty/default values based on a Zod schema. Useful for initializing reactive data from a schema definition.
 
 ```typescript
 import { z } from 'zod'
-import { createSchemaObject } from 'vue-context-storage/zod'
+import { createEmptyZodObject } from 'vue-context-storage'
 
 const FiltersSchema = z.object({
   search: z.string().default(''),
@@ -769,7 +830,7 @@ const FiltersSchema = z.object({
   score: z.number().nullable(),
 })
 
-const filters = reactive(createSchemaObject(FiltersSchema))
+const filters = reactive(createEmptyZodObject(FiltersSchema))
 // Result: { search: '', page: 1, active: false, score: null }
 ```
 
@@ -779,24 +840,24 @@ const filters = reactive(createSchemaObject(FiltersSchema))
 - `withSchema` (default: `false`) — When `true`, attaches the schema to the result object via `SCHEMA_SYMBOL` (wrapped with `markRaw`). Nested objects also receive their respective schemas.
 
 ```typescript
-import { createSchemaObject, SCHEMA_SYMBOL } from 'vue-context-storage/zod'
+import { createEmptyZodObject, SCHEMA_SYMBOL } from 'vue-context-storage'
 
-const data = createSchemaObject(FiltersSchema, { withSchema: true })
+const data = createEmptyZodObject(FiltersSchema, { withSchema: true })
 data[SCHEMA_SYMBOL] // → FiltersSchema
 ```
 
 **Type-based defaults** (when `useDefaults: false` or no `.default()` is set):
 
-| Zod type      | Default value                                |
-| ------------- | -------------------------------------------- |
-| `z.string()`  | `''`                                         |
-| `z.number()`  | `0` (respects `.min()` / `.positive()`)      |
-| `z.boolean()` | `false`                                      |
-| `z.array()`   | `[]`                                         |
-| `z.object()`  | Recursively created via `createSchemaObject` |
-| `z.date()`    | `null`                                       |
-| `.nullable()` | `null`                                       |
-| `.optional()` | `undefined`                                  |
+| Zod type      | Default value                                  |
+| ------------- | ---------------------------------------------- |
+| `z.string()`  | `''`                                           |
+| `z.number()`  | `0` (respects `.min()` / `.positive()`)        |
+| `z.boolean()` | `false`                                        |
+| `z.array()`   | `[]`                                           |
+| `z.object()`  | Recursively created via `createEmptyZodObject` |
+| `z.date()`    | `null`                                         |
+| `.nullable()` | `null`                                         |
+| `.optional()` | `undefined`                                    |
 
 ## TypeScript Support
 

package/dist/index.d.ts

@@ -1,12 +1,13 @@
-import * as vue9 from "vue";
+import * as vue0 from "vue";
 import { ComputedRef, InjectionKey, MaybeRefOrGetter, Plugin, PropType, UnwrapNestedRefs } from "vue";
 import { LocationQuery, LocationQueryValue } from "vue-router";
+import { ZodObject, ZodRawShape, z } from "zod";
 
 //#region src/components/ContextStorageActivator.vue.d.ts
 declare const _default$1: typeof __VLS_export$4;
-declare const __VLS_export$4: vue9.DefineComponent<{}, () => vue9.VNode<vue9.RendererNode, vue9.RendererElement, {
+declare const __VLS_export$4: vue0.DefineComponent<{}, () => vue0.VNode<vue0.RendererNode, vue0.RendererElement, {
   [key: string]: any;
-}>, {}, {}, {}, vue9.ComponentOptionsMixin, vue9.ComponentOptionsMixin, {}, string, vue9.PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, vue9.ComponentProvideOptions, true, {}, any>;
+}>, {}, {}, {}, vue0.ComponentOptionsMixin, vue0.ComponentOptionsMixin, {}, string, vue0.PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, vue0.ComponentProvideOptions, true, {}, any>;
 //#endregion
 //#region src/handlers/types.d.ts
 interface HandlerSchema<T> {
@@ -65,7 +66,7 @@ interface ContextStorageHandler<T, O> {
 //#endregion
 //#region src/components/ContextStorageCollection.vue.d.ts
 declare const _default$2: typeof __VLS_export$3;
-declare const __VLS_export$3: vue9.DefineComponent<vue9.ExtractPropTypes<{
+declare const __VLS_export$3: vue0.DefineComponent<vue0.ExtractPropTypes<{
   handlers: {
     type: PropType<ContextStorageHandlerFactory[]>;
     default: () => ContextStorageHandlerFactory<{}, RegisterOptions<{}>>[];
@@ -81,9 +82,9 @@ declare const __VLS_export$3: vue9.DefineComponent<vue9.ExtractPropTypes<{
     type: PropType<ContextStorageHandlerFactory[]>;
     default: undefined;
   };
-}>, () => vue9.VNode<vue9.RendererNode, vue9.RendererElement, {
+}>, () => vue0.VNode<vue0.RendererNode, vue0.RendererElement, {
   [key: string]: any;
-}>[] | undefined, {}, {}, {}, vue9.ComponentOptionsMixin, vue9.ComponentOptionsMixin, {}, string, vue9.PublicProps, Readonly<vue9.ExtractPropTypes<{
+}>[] | undefined, {}, {}, {}, vue0.ComponentOptionsMixin, vue0.ComponentOptionsMixin, {}, string, vue0.PublicProps, Readonly<vue0.ExtractPropTypes<{
   handlers: {
     type: PropType<ContextStorageHandlerFactory[]>;
     default: () => ContextStorageHandlerFactory<{}, RegisterOptions<{}>>[];
@@ -102,27 +103,27 @@ declare const __VLS_export$3: vue9.DefineComponent<vue9.ExtractPropTypes<{
 }>> & Readonly<{}>, {
   handlers: ContextStorageHandlerFactory<{}, RegisterOptions<{}>>[];
   additionalHandlers: ContextStorageHandlerFactory<{}, RegisterOptions<{}>>[];
-}, {}, {}, {}, string, vue9.ComponentProvideOptions, true, {}, any>;
+}, {}, {}, {}, string, vue0.ComponentProvideOptions, true, {}, any>;
 //#endregion
 //#region src/components/ContextStorageProvider.vue.d.ts
 declare const _default$4: typeof __VLS_export$2;
-declare const __VLS_export$2: vue9.DefineComponent<vue9.ExtractPropTypes<{
+declare const __VLS_export$2: vue0.DefineComponent<vue0.ExtractPropTypes<{
   itemKey: {
     type: StringConstructor;
     required: true;
   };
-}>, () => vue9.VNode<vue9.RendererNode, vue9.RendererElement, {
+}>, () => vue0.VNode<vue0.RendererNode, vue0.RendererElement, {
   [key: string]: any;
-}>[] | undefined, {}, {}, {}, vue9.ComponentOptionsMixin, vue9.ComponentOptionsMixin, {}, string, vue9.PublicProps, Readonly<vue9.ExtractPropTypes<{
+}>[] | undefined, {}, {}, {}, vue0.ComponentOptionsMixin, vue0.ComponentOptionsMixin, {}, string, vue0.PublicProps, Readonly<vue0.ExtractPropTypes<{
   itemKey: {
     type: StringConstructor;
     required: true;
   };
-}>> & Readonly<{}>, {}, {}, {}, {}, string, vue9.ComponentProvideOptions, true, {}, any>;
+}>> & Readonly<{}>, {}, {}, {}, {}, string, vue0.ComponentProvideOptions, true, {}, any>;
 //#endregion
 //#region src/components/ContextStorage.vue.d.ts
 declare const _default: typeof __VLS_export$1;
-declare const __VLS_export$1: vue9.DefineComponent<vue9.ExtractPropTypes<{
+declare const __VLS_export$1: vue0.DefineComponent<vue0.ExtractPropTypes<{
   handlers: {
     type: PropType<ContextStorageHandlerFactory[]>;
     default: () => ContextStorageHandlerFactory<{}, RegisterOptions<{}>>[];
@@ -138,9 +139,9 @@ declare const __VLS_export$1: vue9.DefineComponent<vue9.ExtractPropTypes<{
     type: PropType<ContextStorageHandlerFactory[]>;
     default: undefined;
   };
-}>, () => vue9.VNode<vue9.RendererNode, vue9.RendererElement, {
+}>, () => vue0.VNode<vue0.RendererNode, vue0.RendererElement, {
   [key: string]: any;
-}>[] | undefined, {}, {}, {}, vue9.ComponentOptionsMixin, vue9.ComponentOptionsMixin, {}, string, vue9.PublicProps, Readonly<vue9.ExtractPropTypes<{
+}>[] | undefined, {}, {}, {}, vue0.ComponentOptionsMixin, vue0.ComponentOptionsMixin, {}, string, vue0.PublicProps, Readonly<vue0.ExtractPropTypes<{
   handlers: {
     type: PropType<ContextStorageHandlerFactory[]>;
     default: () => ContextStorageHandlerFactory<{}, RegisterOptions<{}>>[];
@@ -159,7 +160,7 @@ declare const __VLS_export$1: vue9.DefineComponent<vue9.ExtractPropTypes<{
 }>> & Readonly<{}>, {
   handlers: ContextStorageHandlerFactory<{}, RegisterOptions<{}>>[];
   additionalHandlers: ContextStorageHandlerFactory<{}, RegisterOptions<{}>>[];
-}, {}, {}, {}, string, vue9.ComponentProvideOptions, true, {}, any>;
+}, {}, {}, {}, string, vue0.ComponentProvideOptions, true, {}, any>;
 //#endregion
 //#region src/prefix.d.ts
 /**
@@ -181,19 +182,19 @@ declare const contextStoragePrefixSegmentsInjectKey: InjectionKey<MaybeRefOrGett
 //#endregion
 //#region src/components/ContextStoragePrefix.vue.d.ts
 declare const _default$3: typeof __VLS_export;
-declare const __VLS_export: vue9.DefineComponent<vue9.ExtractPropTypes<{
+declare const __VLS_export: vue0.DefineComponent<vue0.ExtractPropTypes<{
   name: {
     type: PropType<ContextStoragePrefixSegment>;
     required: true;
   };
-}>, () => vue9.VNode<vue9.RendererNode, vue9.RendererElement, {
+}>, () => vue0.VNode<vue0.RendererNode, vue0.RendererElement, {
   [key: string]: any;
-}>, {}, {}, {}, vue9.ComponentOptionsMixin, vue9.ComponentOptionsMixin, {}, string, vue9.PublicProps, Readonly<vue9.ExtractPropTypes<{
+}>, {}, {}, {}, vue0.ComponentOptionsMixin, vue0.ComponentOptionsMixin, {}, string, vue0.PublicProps, Readonly<vue0.ExtractPropTypes<{
   name: {
     type: PropType<ContextStoragePrefixSegment>;
     required: true;
   };
-}>> & Readonly<{}>, {}, {}, {}, {}, string, vue9.ComponentProvideOptions, true, {}, any>;
+}>> & Readonly<{}>, {}, {}, {}, {}, string, vue0.ComponentProvideOptions, true, {}, any>;
 //#endregion
 //#region src/plugin.d.ts
 declare const VueContextStoragePlugin: Plugin;
@@ -456,6 +457,34 @@ declare function createLocalStorageHandler(customOptions?: WebStorageHandlerBase
 //#region src/handlers/session-storage/index.d.ts
 declare function createSessionStorageHandler(customOptions?: WebStorageHandlerBaseOptions): ContextStorageHandlerFactory;
 //#endregion
+//#region src/zod.d.ts
+declare const SCHEMA_SYMBOL: unique symbol;
+/**
+ * This type is "Maybe", but always has a schema attached to it.
+ * It's used to avoid any type errors with transformations.
+ */
+type MaybeWithSchema<T extends ZodRawShape> = z.infer<ZodObject<T>> & {
+  [SCHEMA_SYMBOL]?: ZodObject<T>;
+};
+/**
+ * Creates an object with empty values based on a Zod schema.
+ * Useful for initializing forms.
+ *
+ * When `withSchema` is `true`, attaches the schema to the result via `SCHEMA_SYMBOL`
+ * (wrapped with `markRaw` to prevent Vue reactivity on the schema instance).
+ *
+ * Implemented via duck-typed introspection (`_zod.def.type`) — `zod` is only
+ * imported as types, so the main bundle never depends on it at runtime.
+ */
+declare function createEmptyZodObject<T extends ZodRawShape>(schema: ZodObject<T>, options: {
+  useDefaults?: boolean;
+  withSchema: true;
+}): MaybeWithSchema<T>;
+declare function createEmptyZodObject<T extends ZodRawShape>(schema: ZodObject<T>, options?: {
+  useDefaults?: boolean;
+  withSchema?: false;
+}): z.infer<ZodObject<T>>;
+//#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: {
@@ -660,4 +689,4 @@ declare const contextStorageSessionStorageHandlerInjectKey: InjectionKey<Context
 //#region src/constants.d.ts
 declare const defaultHandlers: ContextStorageHandlerFactory[];
 //#endregion
-export { type CollectionManager, type CollectionManagerItem, _default as ContextStorage, _default$1 as ContextStorageActivator, _default$2 as ContextStorageCollection, type ContextStorageHandler, type ContextStorageHandlerFactory, type ContextStorageHandlerMap, _default$3 as ContextStoragePrefix, type ContextStoragePrefixSegment, _default$4 as ContextStorageProvider, type WebStorageHandlerBaseOptions as LocalStorageHandlerBaseOptions, type QueryValue, type RegisterBaseOptions, type RegisterWebStorageHandlerBaseOptions as RegisterLocalStorageHandlerBaseOptions, VueContextStoragePlugin, asArray, asBoolean, asNumber, asNumberArray, asObjectArray, asString, contextStorageCollectionInjectKey, contextStorageCollectionItemInjectKey, contextStorageHandlersInjectKey, contextStorageLocalStorageHandlerInjectKey, contextStoragePrefixSegmentsInjectKey, contextStorageQueryHandlerInjectKey, contextStorageSessionStorageHandlerInjectKey, createCollectionManager, createLocalStorageHandler, createQueryHandler, createSessionStorageHandler, defaultHandlers, defineContextStorageHandler, deserializeParams as deserializeQueryParams, resolveHandlerInjectionKey, serializeParams as serializeQueryParams, transform, useContextStorage, useContextStorageActivator, useContextStorageCollection, useContextStorageProvider };
+export { type CollectionManager, type CollectionManagerItem, _default as ContextStorage, _default$1 as ContextStorageActivator, _default$2 as ContextStorageCollection, type ContextStorageHandler, type ContextStorageHandlerFactory, type ContextStorageHandlerMap, _default$3 as ContextStoragePrefix, type ContextStoragePrefixSegment, _default$4 as ContextStorageProvider, type WebStorageHandlerBaseOptions as LocalStorageHandlerBaseOptions, type MaybeWithSchema, type QueryValue, type RegisterBaseOptions, type RegisterWebStorageHandlerBaseOptions as RegisterLocalStorageHandlerBaseOptions, SCHEMA_SYMBOL, VueContextStoragePlugin, asArray, asBoolean, asNumber, asNumberArray, asObjectArray, asString, contextStorageCollectionInjectKey, contextStorageCollectionItemInjectKey, contextStorageHandlersInjectKey, contextStorageLocalStorageHandlerInjectKey, contextStoragePrefixSegmentsInjectKey, contextStorageQueryHandlerInjectKey, contextStorageSessionStorageHandlerInjectKey, createCollectionManager, createEmptyZodObject, createLocalStorageHandler, createQueryHandler, createSessionStorageHandler, defaultHandlers, defineContextStorageHandler, deserializeParams as deserializeQueryParams, resolveHandlerInjectionKey, serializeParams as serializeQueryParams, transform, useContextStorage, useContextStorageActivator, useContextStorageCollection, useContextStorageProvider };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { computed, defineComponent, getCurrentInstance, h, inject, onBeforeUnmount, onUnmounted, provide, toValue, watch } from "vue";
+import { computed, defineComponent, getCurrentInstance, h, inject, markRaw, onBeforeUnmount, onUnmounted, provide, toValue, watch } from "vue";
 import { useRoute, useRouter } from "vue-router";
 import { cloneDeep, isEqual, merge, omit, pick } from "lodash";
 
@@ -130,6 +130,78 @@ function unwrapZodField(field) {
 	}
 	return t;
 }
+function readZodFieldMeta(field) {
+	let t = field;
+	while (true) {
+		const m = typeof t?.meta === "function" ? t.meta() : void 0;
+		if (m !== void 0) return m;
+		const type = zodDefType(t);
+		if (type === "default" || type === "optional" || type === "nullable") t = t.unwrap();
+		else break;
+	}
+}
+function extractAdditionalDefaultDataFromSchema(schema) {
+	const shape = schema?.shape;
+	if (!shape || typeof shape !== "object") return void 0;
+	let result;
+	for (const key of Object.keys(shape)) {
+		const meta = readZodFieldMeta(shape[key]);
+		if (meta && "additionalDefaultData" in meta) {
+			if (!result) result = {};
+			result[key] = meta.additionalDefaultData;
+		} else {
+			const base = unwrapZodField(shape[key]);
+			if (zodDefType(base) === "object" && base.shape) {
+				const nested = extractAdditionalDefaultDataFromSchema(base);
+				if (nested) {
+					if (!result) result = {};
+					result[key] = nested;
+				}
+			}
+		}
+	}
+	return result;
+}
+function readZodFieldDefault(field) {
+	let t = field;
+	while (true) {
+		const type = zodDefType(t);
+		if (type === "default") return {
+			hasDefault: true,
+			value: t._zod.def.defaultValue
+		};
+		if (type === "optional" || type === "nullable") t = t.unwrap();
+		else break;
+	}
+	return { hasDefault: false };
+}
+function extractDefaultsFromSchema(schema) {
+	const shape = schema?.shape;
+	if (!shape || typeof shape !== "object") return void 0;
+	let result;
+	for (const key of Object.keys(shape)) {
+		const base = unwrapZodField(shape[key]);
+		if (zodDefType(base) === "object" && base.shape) {
+			const { hasDefault: hasDefault2, value: objectDefault } = readZodFieldDefault(shape[key]);
+			const nested = extractDefaultsFromSchema(base);
+			let combined;
+			if (hasDefault2 && nested) combined = merge({}, objectDefault, nested);
+			else if (hasDefault2) combined = objectDefault;
+			else combined = nested;
+			if (combined !== void 0) {
+				if (!result) result = {};
+				result[key] = combined;
+			}
+			continue;
+		}
+		const { hasDefault, value } = readZodFieldDefault(shape[key]);
+		if (hasDefault) {
+			if (!result) result = {};
+			result[key] = value;
+		}
+	}
+	return result;
+}
 function coerceDataForSchema(data, schema) {
 	const shape = schema?.shape;
 	if (!shape || typeof shape !== "object") return data;
@@ -144,7 +216,15 @@ function coerceDataForSchema(data, schema) {
 			else if (value === "0") result[key] = false;
 		} else if (baseType === "array") {
 			const value = result[key];
-			if (value !== void 0 && value !== null && !Array.isArray(value)) result[key] = [value];
+			if (value !== void 0 && value !== null) {
+				let arr;
+				if (Array.isArray(value)) arr = value;
+				else if (typeof value === "object") arr = Object.entries(value).sort(([a], [b]) => Number(a) - Number(b)).map(([, v]) => v);
+				else arr = [value];
+				const elementBase = unwrapZodField(base.element ?? base._zod?.def?.element);
+				if (zodDefType(elementBase) === "object" && elementBase.shape) arr = arr.map((v) => v && typeof v === "object" && !Array.isArray(v) ? coerceDataForSchema(v, elementBase) : v);
+				result[key] = arr;
+			}
 		} else if (baseType === "object" && base.shape) {
 			const nested = result[key];
 			if (nested && typeof nested === "object" && !Array.isArray(nested)) result[key] = coerceDataForSchema(nested, base);
@@ -258,7 +338,7 @@ function buildQuery(input) {
 				warnings.push("[vue-context-storage] preserveEmptyState is not supported with onlyChanges");
 			}
 			Object.keys(patch).forEach((key2) => {
-				if (isEqual(patch[key2], item.initialQueryData[key2]) || item.additionalDefaultQueryData && isEqual(patch[key2], item.additionalDefaultQueryData[key2])) delete patch[key2];
+				if (isEqual(patch[key2], item.initialQueryData[key2]) || item.additionalDefaultQueryData && isEqual(patch[key2], item.additionalDefaultQueryData[key2]) || item.schemaMetaDefaultQueryData && isEqual(patch[key2], item.schemaMetaDefaultQueryData[key2]) || item.schemaDefaultQueryData && isEqual(patch[key2], item.schemaDefaultQueryData[key2])) delete patch[key2];
 			});
 		}
 		const patchKeys = Object.keys(patch);
@@ -457,11 +537,18 @@ function createQueryHandler(baseOptions) {
 				scheduleSyncToQuery();
 			}, { deep: true });
 			const initialData = cloneDeep(resolvedData);
+			const initialQueryData = serializeParams(initialData, { key: registerOptions.key });
+			const additionalDefaultQueryData = registerOptions.additionalDefaultData ? serializeParams(registerOptions.additionalDefaultData, { key: registerOptions.key }) : void 0;
+			const schemaMetaDefaults = registerOptions.schema ? extractAdditionalDefaultDataFromSchema(registerOptions.schema) : void 0;
+			const schemaMetaDefaultQueryData = schemaMetaDefaults ? serializeParams(schemaMetaDefaults, { key: registerOptions.key }) : void 0;
+			const schemaDefaults = registerOptions.schema ? extractDefaultsFromSchema(registerOptions.schema) : void 0;
 			const item = {
 				data,
 				initialData,
-				initialQueryData: serializeParams(initialData, { key: registerOptions.key }),
-				additionalDefaultQueryData: registerOptions.additionalDefaultData ? serializeParams(registerOptions.additionalDefaultData, { key: registerOptions.key }) : void 0,
+				initialQueryData,
+				additionalDefaultQueryData,
+				schemaMetaDefaultQueryData,
+				schemaDefaultQueryData: schemaDefaults ? serializeParams(schemaDefaults, { key: registerOptions.key }) : void 0,
 				options: registerOptions,
 				watchHandle
 			};
@@ -501,6 +588,8 @@ function createQueryHandler(baseOptions) {
 					data: toValue(item.data),
 					initialQueryData: item.initialQueryData,
 					additionalDefaultQueryData: item.additionalDefaultQueryData,
+					schemaMetaDefaultQueryData: item.schemaMetaDefaultQueryData,
+					schemaDefaultQueryData: item.schemaDefaultQueryData,
 					key: item.options?.key,
 					onlyChanges: item.options?.onlyChanges,
 					preserveEmptyState: item.options?.preserveEmptyState,
@@ -929,6 +1018,59 @@ function useContextStorage(type, data, options) {
 	return buildContextStorageHandler(handler, data, options);
 }
 
+//#endregion
+//#region src/zod.ts
+const SCHEMA_SYMBOL = /* @__PURE__ */ Symbol("schema");
+function createEmptyZodObject(schema, options) {
+	const shape = schema.shape;
+	const result = {};
+	const { useDefaults = true } = options || {};
+	for (const key in shape) {
+		const field = shape[key];
+		let hasDefault = false;
+		let isNullable = false;
+		let isOptional = false;
+		let base = field;
+		while (true) {
+			const type = zodDefType(base);
+			if (type === "default") hasDefault = true;
+			else if (type === "nullable") isNullable = true;
+			else if (type === "optional") isOptional = true;
+			else break;
+			base = base.unwrap();
+		}
+		if (useDefaults && hasDefault) {
+			result[key] = field.parse(void 0);
+			continue;
+		}
+		if (isNullable) {
+			result[key] = null;
+			continue;
+		}
+		if (isOptional) {
+			result[key] = void 0;
+			continue;
+		}
+		const baseType = zodDefType(base);
+		if (baseType === "string") result[key] = "";
+		else if (baseType === "number") {
+			const minValue = base.minValue;
+			let defaultValue = minValue !== null && minValue !== void 0 && isFinite(minValue) ? minValue : 0;
+			if (!base.safeParse(defaultValue).success) defaultValue += 1;
+			result[key] = defaultValue;
+		} else if (baseType === "boolean") result[key] = false;
+		else if (baseType === "array") result[key] = [];
+		else if (baseType === "object" && base.shape) result[key] = createEmptyZodObject(base, {
+			useDefaults: options?.useDefaults,
+			withSchema: options?.withSchema
+		});
+		else if (baseType === "date") result[key] = null;
+		else result[key] = void 0;
+	}
+	if (options?.withSchema) result[SCHEMA_SYMBOL] = markRaw(schema);
+	return result;
+}
+
 //#endregion
 //#region src/handlers/query/transform-helpers.ts
 function asNumber(value, options) {
@@ -1006,4 +1148,4 @@ const transform = {
 };
 
 //#endregion
-export { ContextStorage_default as ContextStorage, ContextStorageActivator_default as ContextStorageActivator, ContextStorageCollection_default as ContextStorageCollection, ContextStoragePrefix_default as ContextStoragePrefix, ContextStorageProvider_default as ContextStorageProvider, VueContextStoragePlugin, asArray, asBoolean, asNumber, asNumberArray, asObjectArray, asString, contextStorageCollectionInjectKey, contextStorageCollectionItemInjectKey, contextStorageHandlersInjectKey, contextStorageLocalStorageHandlerInjectKey, contextStoragePrefixSegmentsInjectKey, contextStorageQueryHandlerInjectKey, contextStorageSessionStorageHandlerInjectKey, createCollectionManager, createLocalStorageHandler, createQueryHandler, createSessionStorageHandler, defaultHandlers, defineContextStorageHandler, deserializeParams as deserializeQueryParams, resolveHandlerInjectionKey, serializeParams as serializeQueryParams, transform, useContextStorage, useContextStorageActivator, useContextStorageCollection, useContextStorageProvider };
+export { ContextStorage_default as ContextStorage, ContextStorageActivator_default as ContextStorageActivator, ContextStorageCollection_default as ContextStorageCollection, ContextStoragePrefix_default as ContextStoragePrefix, ContextStorageProvider_default as ContextStorageProvider, SCHEMA_SYMBOL, VueContextStoragePlugin, asArray, asBoolean, asNumber, asNumberArray, asObjectArray, asString, contextStorageCollectionInjectKey, contextStorageCollectionItemInjectKey, contextStorageHandlersInjectKey, contextStorageLocalStorageHandlerInjectKey, contextStoragePrefixSegmentsInjectKey, contextStorageQueryHandlerInjectKey, contextStorageSessionStorageHandlerInjectKey, createCollectionManager, createEmptyZodObject, createLocalStorageHandler, createQueryHandler, createSessionStorageHandler, defaultHandlers, defineContextStorageHandler, deserializeParams as deserializeQueryParams, resolveHandlerInjectionKey, serializeParams as serializeQueryParams, transform, useContextStorage, useContextStorageActivator, useContextStorageCollection, useContextStorageProvider };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "vue-context-storage",
   "type": "module",
-  "version": "0.1.41",
-  "description": "Vue 3 context storage system with URL query synchronization support",
+  "version": "0.1.43",
+  "description": "Vue 3 reactive state management — sync state with the URL query, localStorage, and sessionStorage",
   "author": "",
   "license": "MIT",
   "homepage": "https://github.com/lviobio/vue-context-storage#readme",
@@ -15,7 +15,6 @@
   },
   "exports": {
     ".": "./dist/index.js",
-    "./zod": "./dist/zod.js",
     "./package.json": "./package.json"
   },
   "main": "./dist/index.js",
@@ -32,16 +31,23 @@
     "dev": "tsdown --watch",
     "check": "npm run ts:check && npm run lint:check && npm run format:check && npm run dependency-cruiser:check",
     "ts:check": "vue-tsc --noEmit",
-    "format": "prettier --write src/ playground/src",
-    "format:check": "prettier --check src/ playground/src",
+    "format": "prettier --write src/ playground/src playground-e2e/src",
+    "format:check": "prettier --check src/ playground/src playground-e2e/src",
     "lint": "eslint . --fix",
     "lint:check": "eslint .",
     "dependency-cruiser:check": "depcruise --config .dependency-cruiser.cjs src playground/src",
-    "play": "vite",
+    "play": "vite --port 5173",
+    "play:e2e": "vite --port 5174 --config vite.e2e.config.ts",
     "build:playground": "vite build",
     "preview:playground": "vite preview --outDir playground/dist",
-    "test": "vitest run",
-    "release": "bumpp && npm publish",
+    "test": "npm run test:unit && npm run test:e2e",
+    "test:unit": "vitest run",
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui",
+    "test:e2e:headed": "playwright test --headed",
+    "test:e2e:debug": "playwright test --debug",
+    "test:e2e:report": "playwright show-report",
+    "release": "npm run check && npm run test && bumpp && npm publish",
     "prepublishOnly": "npm run check && npm run test && npm run build"
   },
   "peerDependencies": {
@@ -55,6 +61,7 @@
     }
   },
   "devDependencies": {
+    "@playwright/test": "^1.60.0",
     "@tailwindcss/vite": "^4.1.18",
     "@types/lodash": "^4.17.21",
     "@types/node": "^25.0.3",

package/dist/zod.d.ts

@@ -1,59 +0,0 @@
-import { ZodObject, ZodRawShape, z } from "zod";
-
-//#region src/zod.d.ts
-declare const SCHEMA_SYMBOL: unique symbol;
-/**
- * This type is "Maybe", but always has a schema attached to it.
- * It's used to avoid any type errors with transformations.
- */
-type MaybeWithSchema<T extends ZodRawShape> = z.infer<ZodObject<T>> & {
-  [SCHEMA_SYMBOL]?: ZodObject<T>;
-};
-/**
- * Creates a Zod schema for arrays of objects serialized as indexed query parameters.
- *
- * URL query parameters serialize arrays of objects as indexed keys:
- * `items[0][product]=Apple&items[0][quantity]=5&items[1][product]=Banana&items[1][quantity]=10`
- *
- * After deserialization, these become indexed objects:
- * `{ '0': { product: 'Apple', quantity: '5' }, '1': { product: 'Banana', quantity: '10' } }`
- *
- * This helper wraps `z.record()` + `.transform()` to convert them back to a typed array,
- * so you don't have to write the boilerplate yourself.
- *
- * @example
- * ```ts
- * import { z } from 'zod'
- * import { zObjectArray } from 'vue-context-storage/zod'
- *
- * const ItemSchema = z.object({
- *   product: z.string().default(''),
- *   quantity: z.coerce.number().default(0),
- * })
- *
- * const DataSchema = z.object({
- *   title: z.string().default(''),
- *   items: zObjectArray(ItemSchema),
- * })
- *
- * useContextStorage('query', data, { schema: DataSchema })
- * ```
- */
-declare function zObjectArray<T extends z.ZodTypeAny>(itemSchema: T): z.ZodPipe<z.ZodDefault<z.ZodRecord<z.ZodString, T>>, z.ZodTransform<z.core.output<T>[], Record<string, z.core.output<T>>>>;
-/**
- * Creates an object with empty values based on a Zod schema.
- * Useful for initializing forms.
- *
- * When `withSchema` is `true`, attaches the schema to the result via `SCHEMA_SYMBOL`
- * (wrapped with `markRaw` to prevent Vue reactivity on the schema instance).
- */
-declare function createEmptyObject<T extends ZodRawShape>(schema: ZodObject<T>, options: {
-  useDefaults?: boolean;
-  withSchema: true;
-}): MaybeWithSchema<T>;
-declare function createEmptyObject<T extends ZodRawShape>(schema: ZodObject<T>, options?: {
-  useDefaults?: boolean;
-  withSchema?: false;
-}): z.infer<ZodObject<T>>;
-//#endregion
-export { MaybeWithSchema, SCHEMA_SYMBOL, createEmptyObject, zObjectArray };

package/dist/zod.js

@@ -1,68 +0,0 @@
-import { markRaw } from "vue";
-import { z } from "zod";
-
-//#region src/zod.ts
-const SCHEMA_SYMBOL = /* @__PURE__ */ Symbol("schema");
-function zObjectArray(itemSchema) {
-	return z.record(z.string(), itemSchema).default({}).transform((record) => Object.entries(record).sort(([a], [b]) => Number(a) - Number(b)).map(([, v]) => v));
-}
-function createEmptyObject(schema, options) {
-	const shape = schema.shape;
-	const result = {};
-	const { useDefaults = true } = options || {};
-	for (const key in shape) {
-		const field = shape[key];
-		if (useDefaults) {
-			let hasDefault = false;
-			let currentType = field;
-			while (currentType instanceof z.ZodOptional || currentType instanceof z.ZodNullable || currentType instanceof z.ZodDefault) {
-				if (currentType instanceof z.ZodDefault) {
-					hasDefault = true;
-					break;
-				}
-				currentType = currentType.unwrap();
-			}
-			if (hasDefault) {
-				result[key] = field.parse(void 0);
-				continue;
-			}
-		}
-		let isNullable = false;
-		let isOptional = false;
-		let checkType = field;
-		while (checkType instanceof z.ZodOptional || checkType instanceof z.ZodNullable || checkType instanceof z.ZodDefault) {
-			if (checkType instanceof z.ZodNullable) isNullable = true;
-			if (checkType instanceof z.ZodOptional) isOptional = true;
-			checkType = checkType.unwrap();
-		}
-		if (isNullable) {
-			result[key] = null;
-			continue;
-		}
-		if (isOptional) {
-			result[key] = void 0;
-			continue;
-		}
-		let baseType = field;
-		while (baseType instanceof z.ZodOptional || baseType instanceof z.ZodNullable || baseType instanceof z.ZodDefault) baseType = baseType.unwrap();
-		if (baseType instanceof z.ZodString) result[key] = "";
-		else if (baseType instanceof z.ZodNumber) {
-			let defaultValue = baseType.minValue !== null && baseType.minValue !== void 0 && isFinite(baseType.minValue) ? baseType.minValue : 0;
-			if (!baseType.safeParse(defaultValue).success) defaultValue += 1;
-			result[key] = defaultValue;
-		} else if (baseType instanceof z.ZodBoolean) result[key] = false;
-		else if (baseType instanceof z.ZodArray) result[key] = [];
-		else if (baseType instanceof z.ZodObject) result[key] = createEmptyObject(baseType, {
-			useDefaults: options?.useDefaults,
-			withSchema: options?.withSchema
-		});
-		else if (baseType instanceof z.ZodDate) result[key] = null;
-		else if (field instanceof z.ZodOptional || field instanceof z.ZodNullable) result[key] = void 0;
-		else result[key] = void 0;
-	}
-	if (options?.withSchema) result[SCHEMA_SYMBOL] = markRaw(schema);
-	return result;
-}
-
-//#endregion
-export { SCHEMA_SYMBOL, createEmptyObject, zObjectArray };