vue-context-storage 0.1.45 → 0.1.46

package/README.md

@@ -11,7 +11,7 @@ Vue 3 reactive state management — sync state with the URL query, localStorage,
 ![CI](https://github.com/lviobio/vue-context-storage/actions/workflows/ci.yml/badge.svg)
 ![Coverage](https://github.com/lviobio/vue-context-storage/actions/workflows/coverage.yml/badge.svg)
 [![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/)
+[![Live Demo](https://img.shields.io/badge/demo-live-brightgreen)](https://lviobio.github.io/vue-context-storage)
 
 Key features:
 
@@ -66,7 +66,6 @@ In Vue applications, reactive state often needs to live beyond a single componen
 - **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 key 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.
 
@@ -462,6 +461,93 @@ const customHandlers = [
 // <ContextStorage :handlers="customHandlers">
 ```
 
+### Comma-separated Arrays in the Query String
+
+By default, flat arrays are written as repeated query keys (`?ids=1&ids=2&ids=3`). Set `serialize: { arrayFormat: 'comma' }` to store them as a single comma-joined value instead:
+
+```typescript
+createQueryHandler({ serialize: { arrayFormat: 'comma' } })
+
+// { ids: [1, 2, 3] }  →  ?ids=1,2,3
+```
+
+Values that themselves contain the separator are safely backslash-escaped, so they survive the round-trip without breaking into extra elements:
+
+```typescript
+// { tags: ['Some value', 'with, comma', 'last'] }
+//   →  ?tags=Some value,with\,comma,last
+//   →  { tags: ['Some value', 'with,comma', 'last'] }   (escaped comma restored)
+```
+
+The option can be set on the factory (applies to every registered context) or per `useContextStorage('query', ...)` call (the per-call value wins). A custom separator is supported via `arraySeparator`:
+
+```typescript
+createQueryHandler({ serialize: { arrayFormat: 'comma', arraySeparator: '|' } })
+
+// { ids: [1, 2, 3] }  →  ?ids=1|2|3
+```
+
+Restoring a comma-joined array back into an array requires a `schema` or `transform` (a comma-joined string is indistinguishable from a plain string on the URL — the same requirement as any non-string query value):
+
+```typescript
+import { z } from 'zod'
+
+const data = reactive({ ids: [] as number[] })
+
+useContextStorage('query', data, {
+  schema: z.object({ ids: z.array(z.number()) }),
+  serialize: { arrayFormat: 'comma' },
+})
+// ?ids=1,2,3  →  { ids: [1, 2, 3] }  (split + coerced automatically)
+```
+
+With the manual `transform` approach, pass the matching `separator` to the array helpers:
+
+```typescript
+useContextStorage('query', data, {
+  transform: (deserialized) => ({
+    ids: transform.asNumberArray(deserialized.ids, { separator: ',' }),
+  }),
+  serialize: { arrayFormat: 'comma' },
+})
+```
+
+### Fully Custom Serializer
+
+When the built-in serializer options aren't enough, pass a `serializer` (a `serialize` / `deserialize` pair) to `createQueryHandler` to take **full control** of how state is encoded to and decoded from the URL — e.g. a `qs`-style format, base64, or JSON. This is a **factory-level** option.
+
+```typescript
+import { createQueryHandler, type QuerySerializer } from 'vue-context-storage'
+
+// Example: JSON-encode each registration's data under its key
+const jsonSerializer: QuerySerializer = {
+  serialize: (data, options) => ({ [options?.key ?? '_']: JSON.stringify(data) }),
+  deserialize: (query) => {
+    const out: Record<string, unknown> = {}
+    for (const key of Object.keys(query)) {
+      try {
+        out[key] = JSON.parse(query[key] as string)
+      } catch {
+        out[key] = query[key]
+      }
+    }
+    return out
+  },
+}
+
+// <ContextStorage :additional-handlers="[createQueryHandler({ serializer: jsonSerializer })]">
+//   useContextStorage('query', data, { key: 'f', schema: ... })
+//   →  ?f={"ids":[1,2,3],"q":"hello"}
+```
+
+**Contract** (`QuerySerializer`):
+
+- `serialize` and `deserialize` **must be mutual inverses**.
+- They must preserve the same per-`key` nesting the built-in pair uses: `deserialize(serialize(data, { key }))` reproduces `{ [key]: data }` (and `{ ...data }` when no `key` is given). The handler relies on this to extract each registration's subtree, diff against baselines, and drive `onlyChanges`.
+- `serialize` always receives the **fully resolved options** (`ResolvedSerializeOptions`): `key`, plus `arrayFormat` and `arraySeparator` (the factory-level and per-`useContextStorage` `serialize` options merged, with defaults applied). A custom serializer can honour them — e.g. respect `arrayFormat: 'comma'` — or own the encoding entirely and ignore them.
+- `deserialize` runs on the **whole** route query before per-registration extraction, so it does NOT receive options — fix the decoding format in the function (mirroring whatever `serialize` produced).
+- `deserialize` output still flows through `schema` / `transform` coercion, so return already-typed values (numbers, arrays — like the JSON example above) or URL-style strings the standard coercion understands.
+
 ## Use localStorage Handler in Components
 
 Persist reactive state to `localStorage`. Data is automatically synced across browser tabs.

package/dist/index.d.ts

@@ -220,8 +220,119 @@ declare function createCollectionManager(handlerFactories: ContextStorageHandler
 };
 type CollectionManager = ReturnType<typeof createCollectionManager>;
 //#endregion
+//#region src/handlers/query/helpers.d.ts
+/**
+ * Controls how flat (scalar) arrays are written to the URL query.
+ *
+ * - `'repeat'` (default): one query entry per value — `?ids=1&ids=2&ids=3`.
+ *   Round-trips natively because vue-router restores repeated keys as arrays.
+ * - `'comma'`: a single comma-joined value — `?ids=1,2,3`. Produces shorter,
+ *   more readable URLs, but the array-ness is lost on the URL (a comma-joined
+ *   string is indistinguishable from a plain string), so restoring an array
+ *   requires a `schema` or `transform` to know the field is an array.
+ */
+type QueryArrayFormat = 'repeat' | 'comma';
+interface QuerySerializeOptions {
+  /**
+   * How flat (scalar) arrays are written to the URL. Default: `'repeat'`.
+   */
+  arrayFormat?: QueryArrayFormat;
+  /**
+   * Separator used when `arrayFormat` is `'comma'`. Default: `','`.
+   */
+  arraySeparator?: string;
+}
+interface SerializeOptions extends QuerySerializeOptions {
+  /**
+   * Custom key prefix for serialized keys.
+   * @example
+   * - key: 'filters' => 'filters[field]'
+   * - key: 'search' => 'search[field]'
+   * - key: '' => 'field' (no prefix)
+   */
+  key?: string;
+}
+/**
+ * The serialize options after the handler has resolved them — the factory-level
+ * and per-register `serialize` options merged, with defaults applied
+ * (`arrayFormat: 'repeat'`, `arraySeparator: ','`). This is exactly what the
+ * query handler passes to {@link serializeParams} (and to a custom
+ * `serializer.serialize`), so `arrayFormat` and `arraySeparator` are always
+ * present — `key` is present only when the registration sets one.
+ */
+interface ResolvedSerializeOptions {
+  key?: string;
+  arrayFormat: QueryArrayFormat;
+  arraySeparator: 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' }
+ */
+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' }
+ */
+declare function deserializeParams(params: Record<string, any>): Record<string, unknown>;
+//#endregion
 //#region src/handlers/query/types.d.ts
 type QueryValue = LocationQueryValue | LocationQueryValue[];
+/**
+ * A fully custom serializer pair that replaces the built-in
+ * `serializeParams` / `deserializeParams` for the query handler.
+ *
+ * Set it on the handler factory (`createQueryHandler({ serializer })`) to take
+ * full control of how reactive state is encoded to / decoded from the URL query
+ * (e.g. a `qs`-style format, base64, JSON, or custom escaping).
+ *
+ * Contract:
+ * - `serialize` and `deserialize` MUST be mutual inverses.
+ * - They must preserve the same per-`key` nesting the standard pair uses, i.e.
+ *   `deserialize(serialize(data, { key }))` reproduces `{ [key]: data }` (and
+ *   `{ ...data }` when no `key` is given). The handler relies on this to extract
+ *   each registration's subtree, diff against baselines, and drive `onlyChanges`.
+ * - `serialize` receives the fully {@link ResolvedSerializeOptions resolved}
+ *   options — the factory-level and per-register `serialize` options merged with
+ *   defaults — so `key`, `arrayFormat` and `arraySeparator` are all available.
+ *   A custom implementation may honour the array options (e.g. respect
+ *   `arrayFormat: 'comma'`) or own the encoding entirely and ignore them.
+ * - `deserialize` runs on the whole route query before per-registration
+ *   extraction, so it does NOT receive options — the author fixes the decoding
+ *   format (and must mirror whatever `serialize` produced).
+ *
+ * `deserialize` output still flows through `schema` / `transform` coercion, so
+ * return already-typed values (numbers, arrays) or URL-style strings the
+ * standard coercion understands.
+ */
+interface QuerySerializer {
+  serialize: (params: Record<string, unknown>, options: ResolvedSerializeOptions) => LocationQuery;
+  deserialize: (query: Record<string, any>) => Record<string, any>;
+}
 type DeepTransformValuesToLocationQueryValue<T> = { [K in keyof T]?: T[K] extends object ? T[K] extends Array<any> ? QueryValue : DeepTransformValuesToLocationQueryValue<T[K]> : QueryValue };
 interface QueryHandlerSharedOptions {
   /**
@@ -290,6 +401,28 @@ interface QueryHandlerSharedOptions {
    * If transform option is not passed, ref will be merged with query only by keys that exists in ref.
    */
   mergeOnlyExistingKeysWithoutTransform?: boolean;
+  /**
+   * Options for the standard query serializer.
+   *
+   * Use this to store flat arrays as a single comma-joined value instead of
+   * repeated keys:
+   *
+   * @example
+   * ```ts
+   * createQueryHandler({ serialize: { arrayFormat: 'comma' } })
+   *
+   * // { ids: [1, 2, 3] } → ?ids=1,2,3   (instead of ?ids=1&ids=2&ids=3)
+   * ```
+   *
+   * Can be set on the handler factory (applies to every registered context) or
+   * per `useContextStorage('query', ...)` call (overrides the factory value).
+   *
+   * Restoring a comma-joined array back into an array requires a `schema` or a
+   * `transform` (the comma string is indistinguishable from a plain string on
+   * the URL). The built-in `schema` coercion and the `asArray` / `asNumberArray`
+   * transform helpers split on `arraySeparator` automatically.
+   */
+  serialize?: QuerySerializeOptions;
 }
 interface QueryHandlerBaseOptions extends QueryHandlerSharedOptions {
   /**
@@ -317,6 +450,27 @@ interface QueryHandlerBaseOptions extends QueryHandlerSharedOptions {
    * to have exclusive ownership of all query parameters.
    */
   preserveUnusedKeys?: boolean;
+  /**
+   * A fully custom serializer pair replacing the built-in `serializeParams` /
+   * `deserializeParams`. Factory-level only — owns the entire URL encoding.
+   *
+   * When set, the built-in `serialize` options (`arrayFormat` / `arraySeparator`)
+   * no longer apply. See {@link QuerySerializer} for the contract.
+   *
+   * @example
+   * ```ts
+   * import qs from 'qs'
+   *
+   * createQueryHandler({
+   *   serializer: {
+   *     serialize: (data, { key } = {}) =>
+   *       qs.parse(qs.stringify(key ? { [key]: data } : data, { encode: false })),
+   *     deserialize: (query) => query,
+   *   },
+   * })
+   * ```
+   */
+  serializer?: QuerySerializer;
 }
 interface RegisterQueryHandlerBaseOptions<T> extends QueryHandlerSharedOptions {
   /**
@@ -557,30 +711,36 @@ declare function asString(value: QueryValue | undefined, options: {
 declare function asNumberArray(value: QueryValue | undefined): number[];
 declare function asNumberArray(value: QueryValue | undefined, options: {
   nullable: true;
+  separator?: string;
 }): number[] | null;
 declare function asNumberArray(value: QueryValue | undefined, options: {
   nullable?: false;
+  separator?: string;
 }): number[];
 declare function asArray<T>(value: QueryValue | undefined): T[];
 declare function asArray<T>(value: QueryValue | undefined, options: {
   nullable: true;
   missable: true;
   transform?: (value: QueryValue) => T;
+  separator?: string;
 }): T[] | null | undefined;
 declare function asArray<T>(value: QueryValue | undefined, options: {
   nullable: true;
   missable?: false;
   transform?: (value: QueryValue) => T;
+  separator?: string;
 }): T[] | null;
 declare function asArray<T>(value: QueryValue | undefined, options: {
   nullable?: false;
   missable: true;
   transform?: (value: QueryValue) => T;
+  separator?: string;
 }): T[] | undefined;
 declare function asArray<T>(value: QueryValue | undefined, options: {
   nullable?: false;
   missable?: false;
   transform?: (value: QueryValue) => T;
+  separator?: string;
 }): T[];
 declare function asBoolean(value: QueryValue | undefined): boolean;
 declare function asBoolean(value: QueryValue | undefined, options: {
@@ -634,52 +794,6 @@ declare const transform: {
   asObjectArray: typeof asObjectArray;
 };
 //#endregion
-//#region src/handlers/query/helpers.d.ts
-interface SerializeOptions {
-  /**
-   * Custom key prefix for serialized keys.
-   * @example
-   * - key: 'filters' => 'filters[field]'
-   * - key: 'search' => 'search[field]'
-   * - key: '' => 'field' (no prefix)
-   */
-  key?: 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' }
- */
-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' }
- */
-declare function deserializeParams(params: Record<string, any>): Record<string, unknown>;
-//#endregion
 //#region src/injectionSymbols.d.ts
 declare const contextStorageCollectionInjectKey: InjectionKey<CollectionManager>;
 declare const contextStorageCollectionItemInjectKey: InjectionKey<CollectionManagerItem>;
@@ -691,4 +805,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 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 };
+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 QueryArrayFormat, type QueryHandlerBaseOptions, type QuerySerializeOptions, type QuerySerializer, type QueryValue, type RegisterBaseOptions, type RegisterWebStorageHandlerBaseOptions as RegisterLocalStorageHandlerBaseOptions, type ResolvedSerializeOptions, SCHEMA_SYMBOL, type SerializeOptions, 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,6 +1,5 @@
-import { computed, defineComponent, getCurrentInstance, h, inject, markRaw, onBeforeUnmount, onUnmounted, provide, toValue, watch } from "vue";
+import { computed, defineComponent, getCurrentInstance, h, inject, markRaw, onBeforeUnmount, onUnmounted, provide, toRaw, toValue, watch } from "vue";
 import { useRoute, useRouter } from "vue-router";
-import { cloneDeep, isEqual, merge, omit, pick } from "lodash";
 
 //#region src/symbols.ts
 const collection = /* @__PURE__ */ Symbol("context-storage-collection");
@@ -60,8 +59,39 @@ var ContextStorageActivator_default = ContextStorageActivator_vue_vue_type_scrip
 
 //#endregion
 //#region src/handlers/query/helpers.ts
+function escapeArrayValue(value, separator) {
+	if (!value.includes(separator) && !value.includes("\\")) return value;
+	return value.split("\\").join("\\\\").split(separator).join("\\" + separator);
+}
+function joinArrayValues(values, separator) {
+	return values.map((value) => escapeArrayValue(String(value), separator)).join(separator);
+}
+function splitArrayValue(value, separator) {
+	if (separator.length === 0) return [value];
+	if (!value.includes("\\")) return value.split(separator);
+	const result = [];
+	let current = "";
+	let i = 0;
+	while (i < value.length) {
+		if (value[i] === "\\" && i + 1 < value.length) {
+			current += value[i + 1];
+			i += 2;
+			continue;
+		}
+		if (value.startsWith(separator, i)) {
+			result.push(current);
+			current = "";
+			i += separator.length;
+			continue;
+		}
+		current += value[i];
+		i += 1;
+	}
+	result.push(current);
+	return result;
+}
 function serializeParams(params, options = {}) {
-	const { key: prefix = "" } = options;
+	const { key: prefix = "", arrayFormat = "repeat", arraySeparator = "," } = options;
 	const result = {};
 	Object.keys(params).forEach((key) => {
 		const value = params[key];
@@ -81,7 +111,8 @@ function serializeParams(params, options = {}) {
 				...options,
 				key: formattedKey
 			}));
-		} else result[formattedKey] = value.map(String);
+		} else if (arrayFormat === "comma") result[formattedKey] = joinArrayValues(value, arraySeparator);
+		else result[formattedKey] = value.map(String);
 		else Object.assign(result, serializeParams(value, {
 			...options,
 			key: formattedKey
@@ -112,6 +143,52 @@ function deserializeParams(params) {
 	}, {});
 }
 
+//#endregion
+//#region src/handlers/deep-utils.ts
+function isPlainObject(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+function isEqual(a, b) {
+	if (a === b) return true;
+	if (a !== a && b !== b) return true;
+	if (Array.isArray(a) || Array.isArray(b)) {
+		if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+		return a.every((item, i) => isEqual(item, b[i]));
+	}
+	if (isPlainObject(a) && isPlainObject(b)) {
+		const aKeys = Object.keys(a);
+		const bKeys = Object.keys(b);
+		if (aKeys.length !== bKeys.length) return false;
+		return aKeys.every((key) => Object.prototype.hasOwnProperty.call(b, key) && isEqual(a[key], b[key]));
+	}
+	return false;
+}
+function mergeDeep(target, ...sources) {
+	for (const source of sources) {
+		if (!source) continue;
+		for (const key of Object.keys(source)) {
+			const sourceValue = source[key];
+			if (sourceValue === void 0) continue;
+			const targetValue = target[key];
+			target[key] = isPlainObject(targetValue) && isPlainObject(sourceValue) ? mergeDeep({ ...targetValue }, sourceValue) : sourceValue;
+		}
+	}
+	return target;
+}
+function pick(obj, keys) {
+	const result = {};
+	for (const key of keys) if (key in obj) result[key] = obj[key];
+	return result;
+}
+function omit(obj, keys) {
+	const keySet = new Set(keys);
+	const result = {};
+	for (const key of Object.keys(obj)) if (!keySet.has(key)) result[key] = obj[key];
+	return result;
+}
+
 //#endregion
 //#region src/handlers/helpers.ts
 function syncReactive(target, source) {
@@ -185,7 +262,7 @@ function extractDefaultsFromSchema(schema) {
 			const { hasDefault: hasDefault2, value: objectDefault } = readZodFieldDefault(shape[key]);
 			const nested = extractDefaultsFromSchema(base);
 			let combined;
-			if (hasDefault2 && nested) combined = merge({}, objectDefault, nested);
+			if (hasDefault2 && nested) combined = mergeDeep({}, objectDefault, nested);
 			else if (hasDefault2) combined = objectDefault;
 			else combined = nested;
 			if (combined !== void 0) {
@@ -217,7 +294,7 @@ function coerceScalar(value, baseType) {
 	}
 	return value;
 }
-function coerceDataForSchema(data, schema) {
+function coerceDataForSchema(data, schema, arraySeparator) {
 	const shape = schema?.shape;
 	if (!shape || typeof shape !== "object") return data;
 	const result = { ...data };
@@ -232,16 +309,17 @@ function coerceDataForSchema(data, schema) {
 				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 if (arraySeparator !== void 0 && typeof value === "string") arr = splitArrayValue(value, arraySeparator);
 				else arr = [value];
 				const elementBase = unwrapZodField(base.element ?? base._zod?.def?.element);
 				const elementType = zodDefType(elementBase);
-				if (elementType === "object" && elementBase.shape) arr = arr.map((v) => v && typeof v === "object" && !Array.isArray(v) ? coerceDataForSchema(v, elementBase) : v);
+				if (elementType === "object" && elementBase.shape) arr = arr.map((v) => v && typeof v === "object" && !Array.isArray(v) ? coerceDataForSchema(v, elementBase, arraySeparator) : v);
 				else if (elementType === "number" || elementType === "boolean") arr = arr.map((v) => coerceScalar(v, elementType));
 				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);
+			if (nested && typeof nested === "object" && !Array.isArray(nested)) result[key] = coerceDataForSchema(nested, base, arraySeparator);
 		}
 	}
 	return result;
@@ -250,7 +328,7 @@ function applyTransform(input) {
 	const warnings = [];
 	let data = input.state;
 	if (input.schema) {
-		const coerced = coerceDataForSchema(merge({}, input.initialData, data), input.schema);
+		const coerced = coerceDataForSchema(mergeDeep({}, input.initialData, data), input.schema, input.arraySeparator);
 		const result = input.schema.safeParse(coerced);
 		if (result.success) data = result.data;
 		else {
@@ -339,11 +417,16 @@ function sortQueryByReference(query, ...references) {
 function buildQuery(input) {
 	const warnings = [];
 	const newQueryRaw = {};
+	const serialize = input.serialize ?? serializeParams;
 	const ownedKeys = /* @__PURE__ */ new Set();
 	input.items.forEach((item) => {
 		const { key, onlyChanges = input.onlyChanges } = item;
 		let preserveEmptyState = item.preserveEmptyState ?? input.preserveEmptyState;
-		const patch = serializeParams(item.data, { key });
+		const patch = serialize(item.data, {
+			key,
+			arrayFormat: item.arrayFormat ?? "repeat",
+			arraySeparator: item.arraySeparator ?? ","
+		});
 		Object.keys(patch).forEach((k) => ownedKeys.add(k));
 		Object.keys(item.initialQueryData).forEach((k) => ownedKeys.add(k));
 		if (onlyChanges) {
@@ -433,8 +516,21 @@ function createQueryHandler(baseOptions) {
 			preserveUnusedKeys: true,
 			preserveEmptyState: false,
 			onlyChanges: true,
+			serialize: {},
 			...baseOptions
 		};
+		const serialize = baseOptions?.serializer?.serialize ?? serializeParams;
+		const deserialize = baseOptions?.serializer?.deserialize ?? deserializeParams;
+		function resolveSerializeOptions(itemOptions) {
+			const merged = {
+				...options.serialize,
+				...itemOptions?.serialize
+			};
+			return {
+				arrayFormat: merged.arrayFormat ?? "repeat",
+				arraySeparator: merged.arraySeparator ?? ","
+			};
+		}
 		const stopAfterEach = router.afterEach(() => {
 			afterEachRoute();
 		});
@@ -508,7 +604,7 @@ function createQueryHandler(baseOptions) {
 			const { mergeOnlyExistingKeysWithoutTransform = options.mergeOnlyExistingKeysWithoutTransform } = item.options || {};
 			const itemState = toValue(item.data);
 			const result = computeSyncState({
-				deserializedState: deserializeParams(route.query),
+				deserializedState: deserialize(route.query),
 				initialData: item.initialData,
 				key,
 				emptyPlaceholder: options.emptyPlaceholder
@@ -516,16 +612,18 @@ function createQueryHandler(baseOptions) {
 			if (result.type === "none") return;
 			if (result.type === "reset") {
 				result.data;
-				syncReactive(itemState, cloneDeep(result.data));
+				syncReactive(itemState, structuredClone(result.data));
 				return;
 			}
 			const urlKeys = new Set(Object.keys(result.data));
+			const serializeOptions = resolveSerializeOptions(item.options);
 			const transformed = applyTransform({
 				state: result.data,
 				initialData: item.initialData,
 				schema: item.options?.schema,
 				transform: item.options?.transform,
-				mergeOnlyExistingKeysWithoutTransform
+				mergeOnlyExistingKeysWithoutTransform,
+				arraySeparator: serializeOptions.arrayFormat === "comma" ? serializeOptions.arraySeparator : void 0
 			});
 			transformed.warnings.forEach((w) => console.warn(w.message, ...w.args));
 			const finalData = { ...transformed.data };
@@ -550,11 +648,16 @@ function createQueryHandler(baseOptions) {
 				registerOptions.key;
 				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 serializeOptions = resolveSerializeOptions(registerOptions);
+			const serializeBaselineOptions = {
+				key: registerOptions.key,
+				...serializeOptions
+			};
+			const initialData = structuredClone(toRaw(resolvedData));
+			const initialQueryData = serialize(initialData, serializeBaselineOptions);
+			const additionalDefaultQueryData = registerOptions.additionalDefaultData ? serialize(registerOptions.additionalDefaultData, serializeBaselineOptions) : void 0;
 			const schemaMetaDefaults = registerOptions.schema ? extractAdditionalDefaultDataFromSchema(registerOptions.schema) : void 0;
-			const schemaMetaDefaultQueryData = schemaMetaDefaults ? serializeParams(schemaMetaDefaults, { key: registerOptions.key }) : void 0;
+			const schemaMetaDefaultQueryData = schemaMetaDefaults ? serialize(schemaMetaDefaults, serializeBaselineOptions) : void 0;
 			const schemaDefaults = registerOptions.schema ? extractDefaultsFromSchema(registerOptions.schema) : void 0;
 			const item = {
 				data,
@@ -562,7 +665,7 @@ function createQueryHandler(baseOptions) {
 				initialQueryData,
 				additionalDefaultQueryData,
 				schemaMetaDefaultQueryData,
-				schemaDefaultQueryData: schemaDefaults ? serializeParams(schemaDefaults, { key: registerOptions.key }) : void 0,
+				schemaDefaultQueryData: schemaDefaults ? serialize(schemaDefaults, serializeBaselineOptions) : void 0,
 				options: registerOptions,
 				watchHandle
 			};
@@ -591,30 +694,36 @@ function createQueryHandler(baseOptions) {
 				},
 				reset: () => {
 					registerOptions.key;
-					syncReactive(toValue(data), cloneDeep(initialData));
+					syncReactive(toValue(data), structuredClone(initialData));
 				},
 				wasChanged: computed(() => !isEqual(toValue(data), initialData))
 			};
 		}
 		function buildQueryFromRegistered() {
 			const result = buildQuery({
-				items: registered.map((item) => ({
-					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,
-					causer: item.options?.causer
-				})),
+				items: registered.map((item) => {
+					const serializeOptions = resolveSerializeOptions(item.options);
+					return {
+						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,
+						causer: item.options?.causer,
+						arrayFormat: serializeOptions.arrayFormat,
+						arraySeparator: serializeOptions.arraySeparator
+					};
+				}),
 				currentQuery,
 				routeQuery: route.query,
 				preserveUnusedKeys: options.preserveUnusedKeys,
 				preserveEmptyState: options.preserveEmptyState,
 				onlyChanges: options.onlyChanges,
-				emptyPlaceholder: options.emptyPlaceholder
+				emptyPlaceholder: options.emptyPlaceholder,
+				serialize
 			});
 			result.warnings.forEach((w) => console.warn(w));
 			return {
@@ -722,7 +831,7 @@ function createWebStorageHandlerInstance(config) {
 		const watchHandle = watch(data, () => syncRegisteredToStorage(), { deep: true });
 		const item = {
 			data,
-			initialData: cloneDeep(resolvedData),
+			initialData: structuredClone(toRaw(resolvedData)),
 			options,
 			watchHandle
 		};
@@ -737,7 +846,7 @@ function createWebStorageHandlerInstance(config) {
 				registeredDataObjects.delete(resolvedData);
 			},
 			reset: () => {
-				syncReactive(toValue(data), cloneDeep(item.initialData));
+				syncReactive(toValue(data), structuredClone(item.initialData));
 			},
 			wasChanged: computed(() => !isEqual(toValue(data), item.initialData))
 		};
@@ -1104,12 +1213,12 @@ function asString(value, options) {
 	return stringValue;
 }
 function asNumberArray(value, options) {
-	const { nullable = false } = options || {};
+	const { nullable = false, separator } = options || {};
 	if (value === null && nullable) return null;
 	if (value === void 0) return nullable ? null : [];
 	let arrayValue;
 	if (Array.isArray(value)) arrayValue = value;
-	else if (typeof value === "string") arrayValue = [value];
+	else if (typeof value === "string") arrayValue = separator !== void 0 ? splitArrayValue(value, separator) : [value];
 	else arrayValue = [];
 	return arrayValue.map((item) => {
 		if (item === null) return 0;
@@ -1118,12 +1227,13 @@ function asNumberArray(value, options) {
 	});
 }
 function asArray(value, options) {
-	const { nullable = false, missable = false, transform: transform2 } = options || {};
+	const { nullable = false, missable = false, transform: transform2, separator } = options || {};
 	if (value === null && nullable) return null;
 	if (value === void 0 && missable) return;
 	if (value === void 0) return nullable ? null : [];
 	let arrayValue;
 	if (Array.isArray(value)) arrayValue = value;
+	else if (separator !== void 0 && typeof value === "string") arrayValue = splitArrayValue(value, separator);
 	else arrayValue = [value];
 	if (transform2) return arrayValue.map((item) => transform2(item));
 	return arrayValue;

package/package.json

@@ -1,98 +1,94 @@
-{
-  "name": "vue-context-storage",
-  "type": "module",
-  "version": "0.1.45",
-  "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",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/lviobio/vue-context-storage.git"
-  },
-  "bugs": {
-    "url": "https://github.com/lviobio/vue-context-storage/issues"
-  },
-  "exports": {
-    ".": "./dist/index.js",
-    "./package.json": "./package.json"
-  },
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "build": "tsdown",
-    "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 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 --port 5173",
-    "play:e2e": "vite --port 5174 --config vite.e2e.config.ts",
-    "build:playground": "vite build",
-    "preview:playground": "vite preview --outDir playground/dist",
-    "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": {
-    "vue": "^3.0.0",
-    "vue-router": "^4.0.0 || ^5.0.0",
-    "zod": "^4.0.0"
-  },
-  "peerDependenciesMeta": {
-    "zod": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@playwright/test": "^1.60.0",
-    "@tailwindcss/vite": "^4.1.18",
-    "@types/lodash": "^4.17.21",
-    "@types/node": "^25.0.3",
-    "@vitejs/plugin-vue": "^6.0.3",
-    "@vitest/browser-playwright": "^4.0.16",
-    "@vitest/coverage-v8": "^4.0.16",
-    "@vue/eslint-config-typescript": "^14.6.0",
-    "@vue/test-utils": "^2.4.6",
-    "bumpp": "^10.3.2",
-    "dependency-cruiser": "^17.3.6",
-    "eslint": "^9.39.2",
-    "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-vue": "^10.6.2",
-    "happy-dom": "^20.1.0",
-    "highlight.js": "^11.11.1",
-    "jsdom": "^27.4.0",
-    "naive-ui": "^2.43.2",
-    "playwright": "^1.57.0",
-    "prettier": "^3.7.4",
-    "tailwindcss": "^4.1.18",
-    "tsdown": "^0.18.4",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.51.0",
-    "vite": "^7.3.0",
-    "vitest": "^4.0.16",
-    "vitest-browser-vue": "^2.0.1",
-    "vue": "^3.5.26",
-    "vue-tsc": "^3.2.1",
-    "zod": "^4.3.5"
-  },
-  "dependencies": {
-    "lodash": "^4.17.23"
-  }
-}
+{
+  "name": "vue-context-storage",
+  "type": "module",
+  "version": "0.1.46",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lviobio/vue-context-storage.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lviobio/vue-context-storage/issues"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "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 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 --port 5173",
+    "play:e2e": "vite --port 5174 --config vite.e2e.config.ts",
+    "build:playground": "vite build",
+    "preview:playground": "vite preview --outDir playground/dist",
+    "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": {
+    "vue": "^3.0.0",
+    "vue-router": "^4.0.0 || ^5.0.0",
+    "zod": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.60.0",
+    "@tailwindcss/vite": "^4.1.18",
+    "@types/node": "^25.0.3",
+    "@vitejs/plugin-vue": "^6.0.3",
+    "@vitest/browser-playwright": "^4.0.16",
+    "@vitest/coverage-v8": "^4.0.16",
+    "@vue/eslint-config-typescript": "^14.6.0",
+    "@vue/test-utils": "^2.4.6",
+    "bumpp": "^10.3.2",
+    "dependency-cruiser": "^17.3.6",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-vue": "^10.6.2",
+    "happy-dom": "^20.1.0",
+    "highlight.js": "^11.11.1",
+    "jsdom": "^27.4.0",
+    "naive-ui": "^2.43.2",
+    "playwright": "^1.57.0",
+    "prettier": "^3.7.4",
+    "tailwindcss": "^4.1.18",
+    "tsdown": "^0.18.4",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.51.0",
+    "vite": "^7.3.0",
+    "vitest": "^4.0.16",
+    "vitest-browser-vue": "^2.0.1",
+    "vue": "^3.5.26",
+    "vue-tsc": "^3.2.1",
+    "zod": "^4.3.5"
+  }
+}