vue-context-storage 0.1.39 → 0.1.41

package/README.md

@@ -712,56 +712,46 @@ const DataSchema = z.object({
 })
 ```
 
-### `zUrlBoolean(defaultValue?)`
+### Automatic Type Coercion
 
-Creates a Zod schema for booleans serialized as URL query parameters. Standard `z.coerce.boolean()` cannot be used because `Boolean('0')` is `true` in JavaScript. This helper correctly handles `'1'`, `'true'`, `'0'`, `'false'`, and native booleans.
+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:
 
-```typescript
-import { z } from 'zod'
-import { zUrlBoolean } from 'vue-context-storage/zod'
-
-const Schema = z.object({
-  active: zUrlBoolean(), // defaults to false
-  enabled: zUrlBoolean(true), // defaults to true
-})
-```
+#### Array Coercion
 
-### `zNumberArray()`
+A URL with multiple values (`?ids=1&ids=2`) produces an array `['1', '2']`, but a single value (`?ids=1`) produces just `'1'`. Without correction, `z.string().array()` would reject the single-value case with `"expected array, received string"`.
 
-Creates a Zod schema for arrays of numbers serialized as URL query parameters. Handles the common issue where a single query value (`?ids=1`) is deserialized as a string `'1'` instead of an array `['1']`, which would cause `z.coerce.number().array()` to fail with `"expected array, received string"`.
-
-This helper normalizes the input by accepting both a single value and an array, coercing each element to a number.
+The library introspects the Zod schema before validation and wraps non-array values into single-element arrays wherever the schema expects `.array()`. This works recursively for nested objects. **No special helpers are needed** — plain `.array()` schemas work out of the box:
 
 ```typescript
-import { z } from 'zod'
-import { zNumberArray } from 'vue-context-storage/zod'
-
 const Schema = z.object({
-  users_ids: zNumberArray(),
+  tags: z.string().array().default([]),
+  ids: z.coerce.number().array().default([]),
+  statuses: z.enum(['active', 'inactive']).array().default([]),
+  filters: z
+    .object({
+      categories: z.string().array().default([]),
+    })
+    .default({ categories: [] }),
 })
 
-// All of these work:
-Schema.parse({ users_ids: ['1', '2'] }) // → { users_ids: [1, 2] }
-Schema.parse({ users_ids: '1' }) // → { users_ids: [1] }
-Schema.parse({}) // → { users_ids: [] }
+// All of these work automatically:
+// ?tags=vue          → { tags: ['vue'], ... }
+// ?tags=vue&tags=ts  → { tags: ['vue', 'ts'], ... }
+// (no tags param)    → { tags: [], ... }
 ```
 
-### `zStringArray()`
+#### Boolean Coercion
 
-Creates a Zod schema for arrays of strings serialized as URL query parameters. Same problem as `zNumberArray()` — a single query value (`?tags=vue`) is deserialized as a string `'vue'` instead of an array `['vue']`, which would cause `z.string().array()` to fail.
+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:
 
 ```typescript
-import { z } from 'zod'
-import { zStringArray } from 'vue-context-storage/zod'
-
 const Schema = z.object({
-  tags: zStringArray(),
+  active: z.boolean().default(false),
+  enabled: z.boolean().default(true),
 })
 
-// All of these work:
-Schema.parse({ tags: ['vue', 'react'] }) // → { tags: ['vue', 'react'] }
-Schema.parse({ tags: 'vue' }) // → { tags: ['vue'] }
-Schema.parse({}) // → { tags: [] }
+// ?active=1  → { active: true, enabled: true }
+// ?active=0  → { active: false, enabled: true }
 ```
 
 ### `createSchemaObject(schema, options?)`

package/dist/index.js

@@ -118,12 +118,46 @@ function syncReactive(target, source) {
 	for (const key of Object.keys(target)) if (!(key in source)) delete target[key];
 	Object.assign(target, source);
 }
+function zodDefType(field) {
+	return field?._zod?.def?.type;
+}
+function unwrapZodField(field) {
+	let t = field;
+	while (true) {
+		const type = zodDefType(t);
+		if (type === "default" || type === "optional" || type === "nullable") t = t.unwrap();
+		else break;
+	}
+	return t;
+}
+function coerceDataForSchema(data, schema) {
+	const shape = schema?.shape;
+	if (!shape || typeof shape !== "object") return data;
+	const result = { ...data };
+	for (const key of Object.keys(shape)) {
+		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") {
+			const value = result[key];
+			if (value !== void 0 && value !== null && !Array.isArray(value)) result[key] = [value];
+		} else if (baseType === "object" && base.shape) {
+			const nested = result[key];
+			if (nested && typeof nested === "object" && !Array.isArray(nested)) result[key] = coerceDataForSchema(nested, base);
+		}
+	}
+	return result;
+}
 function applyTransform(input) {
 	const warnings = [];
 	let data = input.state;
 	if (input.schema) {
-		const merged = merge({}, input.initialData, data);
-		const result = input.schema.safeParse(merged);
+		const coerced = coerceDataForSchema(merge({}, input.initialData, data), input.schema);
+		const result = input.schema.safeParse(coerced);
 		if (result.success) data = result.data;
 		else {
 			warnings.push({

package/dist/zod.d.ts

@@ -40,86 +40,6 @@ type MaybeWithSchema<T extends ZodRawShape> = z.infer<ZodObject<T>> & {
  * ```
  */
 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 a Zod schema for booleans serialized as URL query parameters.
- *
- * URL query parameters serialize booleans as `'1'`/`'0'` strings.
- * `z.coerce.boolean()` cannot be used because `Boolean('0')` is `true` in JavaScript.
- *
- * This helper correctly handles `'1'`, `'true'`, `'0'`, `'false'`, and native booleans.
- *
- * @param defaultValue - The default value when the field is missing (defaults to `false`)
- *
- * @example
- * ```ts
- * import { z } from 'zod'
- * import { zUrlBoolean } from 'vue-context-storage/zod'
- *
- * const Schema = z.object({
- *   active: zUrlBoolean(),        // defaults to false
- *   enabled: zUrlBoolean(true),   // defaults to true
- * })
- * ```
- */
-declare function zUrlBoolean(defaultValue?: boolean): z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>, z.ZodTransform<boolean, string | boolean>>>;
-/**
- * Creates a Zod schema for arrays of numbers serialized as URL query parameters.
- *
- * URL query parameters serialize arrays as repeated keys:
- * `?users_ids=1&users_ids=2` → `['1', '2']` (array of strings)
- *
- * But when only one value is present:
- * `?users_ids=1` → `'1'` (just a string, not an array)
- *
- * `z.coerce.number().array()` would fail with "expected array, received string"
- * for the single-value case. This helper normalizes the input by wrapping
- * a single value into an array before coercing each element to a number.
- *
- * @example
- * ```ts
- * import { z } from 'zod'
- * import { zNumberArray } from 'vue-context-storage/zod'
- *
- * const Schema = z.object({
- *   users_ids: zNumberArray(),
- * })
- *
- * // All of these work:
- * Schema.parse({ users_ids: ['1', '2'] })  // → { users_ids: [1, 2] }
- * Schema.parse({ users_ids: '1' })          // → { users_ids: [1] }
- * Schema.parse({})                           // → { users_ids: [] }
- * ```
- */
-declare function zNumberArray(): z.ZodDefault<z.ZodUnion<readonly [z.ZodArray<z.ZodCoercedNumber<unknown>>, z.ZodPipe<z.ZodCoercedNumber<unknown>, z.ZodTransform<number[], number>>]>>;
-/**
- * Creates a Zod schema for arrays of strings serialized as URL query parameters.
- *
- * URL query parameters serialize arrays as repeated keys:
- * `?tags=vue&tags=react` → `['vue', 'react']` (array of strings)
- *
- * But when only one value is present:
- * `?tags=vue` → `'vue'` (just a string, not an array)
- *
- * `z.string().array()` would fail with "expected array, received string"
- * for the single-value case. This helper normalizes the input by wrapping
- * a single value into an array.
- *
- * @example
- * ```ts
- * import { z } from 'zod'
- * import { zStringArray } from 'vue-context-storage/zod'
- *
- * const Schema = z.object({
- *   tags: zStringArray(),
- * })
- *
- * // All of these work:
- * Schema.parse({ tags: ['vue', 'react'] })  // → { tags: ['vue', 'react'] }
- * Schema.parse({ tags: 'vue' })              // → { tags: ['vue'] }
- * Schema.parse({})                            // → { tags: [] }
- * ```
- */
-declare function zStringArray(): z.ZodDefault<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodPipe<z.ZodString, z.ZodTransform<string[], string>>]>>;
 /**
  * Creates an object with empty values based on a Zod schema.
  * Useful for initializing forms.
@@ -136,4 +56,4 @@ declare function createEmptyObject<T extends ZodRawShape>(schema: ZodObject<T>,
   withSchema?: false;
 }): z.infer<ZodObject<T>>;
 //#endregion
-export { MaybeWithSchema, SCHEMA_SYMBOL, createEmptyObject, zNumberArray, zObjectArray, zStringArray, zUrlBoolean };
+export { MaybeWithSchema, SCHEMA_SYMBOL, createEmptyObject, zObjectArray };

package/dist/zod.js

@@ -6,18 +6,6 @@ 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 zUrlBoolean(defaultValue = false) {
-	return z.union([z.boolean(), z.string()]).transform((val) => {
-		if (typeof val === "boolean") return val;
-		return val === "1" || val === "true";
-	}).default(defaultValue);
-}
-function zNumberArray() {
-	return z.union([z.coerce.number().array(), z.coerce.number().transform((v) => [v])]).default([]);
-}
-function zStringArray() {
-	return z.union([z.string().array(), z.string().transform((v) => [v])]).default([]);
-}
 function createEmptyObject(schema, options) {
 	const shape = schema.shape;
 	const result = {};
@@ -77,4 +65,4 @@ function createEmptyObject(schema, options) {
 }
 
 //#endregion
-export { SCHEMA_SYMBOL, createEmptyObject, zNumberArray, zObjectArray, zStringArray, zUrlBoolean };
+export { SCHEMA_SYMBOL, createEmptyObject, zObjectArray };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vue-context-storage",
   "type": "module",
-  "version": "0.1.39",
+  "version": "0.1.41",
   "description": "Vue 3 context storage system with URL query synchronization support",
   "author": "",
   "license": "MIT",