vue-context-storage 0.1.43 → 0.1.44

package/README.md

@@ -154,7 +154,7 @@ useContextStorage('sessionStorage', filters, {
 useContextStorage('query', filters, {
   key: 'filters',
   schema: z.object({
-    page: z.coerce.number().default(1),
+    page: z.number().default(1),
     search: z.string().default(''),
     status: z.string().default('active'),
   }),
@@ -267,7 +267,7 @@ import { useContextStorage } 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),
+  page: z.number().int().positive().default(1),
   status: z.enum(['active', 'inactive']).default('active'),
 })
 
@@ -329,7 +329,7 @@ import { z } from 'zod'
 
 const ItemSchema = z.object({
   product: z.string().default(''),
-  quantity: z.coerce.number().default(0),
+  quantity: z.number().default(0),
 })
 
 const DataSchema = z.object({
@@ -379,7 +379,7 @@ When using Zod schemas, you can also specify `additionalDefaultData` per-field v
 
 ```typescript
 const Schema = z.object({
-  page: z.coerce.number().default(1).meta({ additionalDefaultData: 3 }),
+  page: z.number().default(1).meta({ additionalDefaultData: 3 }),
   search: z.string().default(''),
 })
 
@@ -405,7 +405,7 @@ Nested objects work the same way. Following the documented best practice of decl
 const Schema = z.object({
   filters: z
     .object({
-      page: z.coerce.number(),
+      page: z.number(),
       sort: z.string(),
     })
     .default({ page: 1, sort: 'asc' }),
@@ -759,7 +759,7 @@ npm install zod
 
 ### 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:
+When a `schema` is provided, the library automatically coerces URL query parameter values to match the expected Zod types before validation. This handles the common URL serialization quirks below.
 
 #### Array Coercion
 
@@ -770,7 +770,7 @@ The library introspects the Zod schema before validation and wraps non-array val
 ```typescript
 const Schema = z.object({
   tags: z.string().array().default([]),
-  ids: z.coerce.number().array().default([]),
+  ids: z.number().array().default([]),
   statuses: z.enum(['active', 'inactive']).array().default([]),
   filters: z
     .object({
@@ -790,7 +790,7 @@ Arrays of objects are also handled automatically. They deserialize from indexed
 ```typescript
 const ItemSchema = z.object({
   product: z.string().default(''),
-  quantity: z.coerce.number().default(0),
+  quantity: z.number().default(0),
 })
 
 const Schema = z.object({
@@ -803,7 +803,7 @@ const Schema = z.object({
 
 #### 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:
+The query handler serializes booleans as `'1'`/`'0'` strings in URL parameters (e.g. `?active=1`). Standard `z.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:
 
 ```typescript
 const Schema = z.object({
@@ -815,6 +815,26 @@ const Schema = z.object({
 // ?active=0  → { active: false, enabled: true }
 ```
 
+#### Number Coercion
+
+URL query parameters are always strings (`?page=5` → `'5'`), so plain `z.number()` would reject them with `"expected number, received string"`. The library automatically converts numeric strings to numbers wherever the schema expects a number — including inside nested objects and `z.array(z.number())`. **`z` is not required** — plain `z.number()` works out of the box:
+
+```typescript
+const Schema = z.object({
+  page: z.number().default(1),
+  score: z.number().nullable(),
+  ids: z.array(z.number()).default([]),
+})
+
+// ?page=5            → { page: 5, ... }
+// ?score=42          → { score: 42, ... }
+// ?ids=1&ids=2       → { ids: [1, 2], ... }
+```
+
+Coercion is conservative: a non-numeric string (`?page=abc`) or an empty value is **not** forced to a number (`Number('')` would be `0`). Instead the schema validation fails and the field falls back to its initial data, so missing/garbage input never silently becomes `0`. `null` is preserved for `.nullable()` fields.
+
+> `z.number()` still works and remains useful when you want Zod's own coercion semantics (e.g. coercing booleans or accepting empty strings as `0`).
+
 ### `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.
@@ -825,7 +845,7 @@ import { createEmptyZodObject } from 'vue-context-storage'
 
 const FiltersSchema = z.object({
   search: z.string().default(''),
-  page: z.coerce.number().default(1),
+  page: z.number().default(1),
   active: z.boolean().default(false),
   score: z.number().nullable(),
 })
@@ -876,7 +896,7 @@ When using Zod schemas, TypeScript will automatically infer types:
 ```typescript
 const FiltersSchema = z.object({
   search: z.string().default(''),
-  page: z.coerce.number().default(1),
+  page: z.number().default(1),
 })
 
 type Filters = z.infer<typeof FiltersSchema>

package/dist/index.d.ts

@@ -40,7 +40,7 @@ interface RegisterBaseOptions<T> {
    *
    * const FiltersSchema = z.object({
    *   search: z.string().default(''),
-   *   page: z.coerce.number().int().positive().default(1),
+   *   page: z.number().int().positive().default(1),
    *   status: z.enum(['active', 'inactive']).default('active'),
    * })
    *
@@ -366,10 +366,12 @@ interface RegisterQueryHandlerOptions<T> extends RegisterBaseOptions<T>, Registe
 //#region src/handlers/web-storage-base/types.d.ts
 interface WebStorageHandlerBaseOptions {
   /**
-   * Default: true for localStorage, false for sessionStorage
+   * Default: true
    *
-   * If enabled - storage events will be listened to for cross-tab synchronization.
-   * Only works with localStorage (sessionStorage is per-tab).
+   * If enabled - storage events will be listened to so external changes are synced
+   * back into the reactive data. For localStorage this covers other tabs; for
+   * sessionStorage it covers other contexts of the same session (iframes,
+   * `window.open` windows) and manual edits via DevTools.
    */
   listenToStorageEvents?: boolean;
 }

package/dist/index.js

@@ -202,6 +202,21 @@ function extractDefaultsFromSchema(schema) {
 	}
 	return result;
 }
+function coerceScalar(value, baseType) {
+	if (baseType === "boolean") {
+		if (value === "1") return true;
+		if (value === "0") return false;
+		return value;
+	}
+	if (baseType === "number") {
+		if (typeof value === "string" && value.trim() !== "") {
+			const n = Number(value);
+			if (!Number.isNaN(n)) return n;
+		}
+		return value;
+	}
+	return value;
+}
 function coerceDataForSchema(data, schema) {
 	const shape = schema?.shape;
 	if (!shape || typeof shape !== "object") return data;
@@ -210,11 +225,8 @@ function coerceDataForSchema(data, schema) {
 		if (!(key in result)) continue;
 		const base = unwrapZodField(shape[key]);
 		const baseType = zodDefType(base);
-		if (baseType === "boolean") {
-			const value = result[key];
-			if (value === "1") result[key] = true;
-			else if (value === "0") result[key] = false;
-		} else if (baseType === "array") {
+		if (baseType === "boolean" || baseType === "number") result[key] = coerceScalar(result[key], baseType);
+		else if (baseType === "array") {
 			const value = result[key];
 			if (value !== void 0 && value !== null) {
 				let arr;
@@ -222,7 +234,9 @@ function coerceDataForSchema(data, schema) {
 				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);
+				const elementType = zodDefType(elementBase);
+				if (elementType === "object" && elementBase.shape) arr = arr.map((v) => v && typeof v === "object" && !Array.isArray(v) ? coerceDataForSchema(v, elementBase) : v);
+				else if (elementType === "number" || elementType === "boolean") arr = arr.map((v) => coerceScalar(v, elementType));
 				result[key] = arr;
 			}
 		} else if (baseType === "object" && base.shape) {
@@ -635,6 +649,7 @@ function createWebStorageHandlerInstance(config) {
 	}
 	function handleStorageEvent(event) {
 		if (!enabled) return;
+		if (event.storageArea && event.storageArea !== config.storage) return;
 		registered.forEach((item) => {
 			if (event.key === item.options.key) syncStorageToRegisteredItem(item);
 		});
@@ -757,7 +772,7 @@ function createSessionStorageHandler(customOptions) {
 		injectionKey: contextStorageSessionStorageHandler,
 		handlerName: "sessionStorage",
 		options: {
-			listenToStorageEvents: false,
+			listenToStorageEvents: true,
 			...customOptions
 		}
 	});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vue-context-storage",
   "type": "module",
-  "version": "0.1.43",
+  "version": "0.1.44",
   "description": "Vue 3 reactive state management — sync state with the URL query, localStorage, and sessionStorage",
   "author": "",
   "license": "MIT",