pouch-js 0.0.11

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Emmanuel C.Alozie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,282 @@
+# pouch-js
+
+A schema-aware reactive FormData builder with Zod validation and full Blob/File support. Manage form state, validate data, and generate submission-ready FormData with a reactive proxy.
+
+## Features
+
+- ✅ **Framework Agnostic**: Works with any UI library or vanilla JS
+- ✅ **Automatic Schema Inference**: Derive Zod schemas from your data structures
+- ✅ **Manual Schema Validation**: Use custom Zod schemas for precise control
+- ✅ **Reactive Data Proxy**: Live updates with deep object reactivity
+- ✅ **Blob & File Support**: Perfect for file uploads and image handling
+- ✅ **TypeScript First**: Full type safety and intelligent inference
+- ✅ **FormData Generation**: Create fetch-ready FormData objects automatically
+
+## Installation
+
+Copy the `src/index.ts` into your project if you don't want to add additional dependencies to your project or
+
+```bash
+npm install pouch-js zod
+
+pnpm add pouch-js zod
+```
+
+Note: Zod is a peer dependency and must be installed separately.
+
+## Basic Usage
+
+```ts
+import { pack } from "pouch-js";
+
+// Create a form manager with automatic schema inference
+const { data, getFormData } = pack({
+  user: {
+    name: "Alice",
+    email: "alice@example.com",
+    age: 30,
+  },
+  preferences: {
+    newsletter: true,
+    tags: ["tech", "programming"],
+  },
+});
+
+// Update values reactively
+data.user.name = "Bob"; // Changes are tracked
+data.preferences.tags.push("javascript");
+
+// Generate FormData for submission
+const formData = getFormData();
+// formData contains: user[name]=Bob, user[email]=alice@example.com, etc.
+```
+
+## File Upload Example
+
+```ts
+import { pack } from "pouch-js";
+
+// Handle file inputs with full type safety
+document.getElementById("avatar").addEventListener("change", (e) => {
+  const file = e.target.files[0];
+
+  const { data, getFormData } = pack({
+    profile: {
+      name: "John Doe",
+      avatar: file, // File object handled properly
+      documents: [file], // Works in arrays too
+      metadata: {
+        uploadDate: new Date().toISOString(),
+      },
+    },
+  });
+
+  // Submit to server
+  fetch("/api/upload", {
+    method: "POST",
+    body: getFormData(), // Contains the file properly
+  });
+});
+```
+
+## Advanced Schema Validation
+
+```ts
+import { z } from "zod";
+import { pack } from "pouch-js";
+
+const userSchema = z.object({
+  name: z.string().min(2),
+  email: z.string().email(),
+  avatar: z.instanceof(Blob).optional(),
+  age: z.number().min(18),
+  tags: z.array(z.string()),
+});
+
+const { data, getFormData } = pack(
+  {
+    name: "Alice",
+    email: "alice@example.com",
+    age: 25,
+    tags: ["developer"],
+    avatar: someFile, // Optional blob
+  },
+  userSchema, // Custom schema override
+);
+```
+
+## API Reference
+
+### 1. `pack(initialData)`
+
+Creates a form manager with inferred schema.
+
+**Parameters:**
+
+- `initialData`: Object or array to use as initial state
+
+**Returns:**
+
+- `data`: Reactive proxy of the initial data
+- `getFormData()`: FormData: Function that returns current state as FormData
+
+### 2. `pack(initialData, schema)`
+
+Creates a form manager with custom Zod schema.
+
+**Parameters:**
+
+- `initialData`: Data matching the provided schema
+- `schema`: Zod schema for validation
+
+**Returns:**
+
+- `data`: Reactive proxy of validated data
+- `getFormData()`: FormData: Function that returns current state as FormData
+
+## Reactive Data Pattern
+
+The `data` object is a deep proxy that tracks changes:
+
+```ts
+import { pack } from "pouch-js";
+
+const { data, getFormData } = pack({
+  user: { name: "Alice", settings: { darkMode: true } },
+});
+
+// All changes are tracked
+data.user.name = "Bob"; // Simple property
+data.user.settings.darkMode = false; // Nested property
+data.user.settings.fontSize = 16; // New properties
+
+// getFormData() captures all current changes
+const formData = getFormData(); // Contains latest state
+```
+
+### FormData Output Format
+
+The generated FormData uses standard encoding:
+
+**Object properties:**
+
+```text
+user[name]=Alice
+user[email]=alice@example.com
+```
+
+**Array elements:**
+
+```text
+tags[0]=tech
+tags[1]=programming
+```
+
+**File uploads:**
+
+Handled as native `File`/`Blob` objects in FormData.
+
+## Type Utilities
+
+`DeepWritable<T>`
+
+Utility type to make deeply nested readonly types writable:
+
+```typescript
+import type { DeepWritable } from "pouch-js";
+
+type User = DeepWritable<typeof userSchema>;
+// Now all properties are mutable
+```
+
+## Error Handling
+
+The library throws Zod validation errors when provided data doesn't match the schema:
+
+```typescript
+import { pack } from "pouch-js";
+
+try {
+  const manager = pack(
+    { email: "invalid-email" },
+    z.object({ email: z.string().email() }),
+  );
+} catch (error) {
+  console.error("Validation failed:", error.errors);
+}
+```
+
+## Common Use Cases
+
+### 1. Form State Management
+
+```ts
+import { pack } from "pouch-js";
+
+const { data, getFormData } = pack(initialFormState);
+
+// Bind to input events
+input.addEventListener("change", (e) => {
+  data.user.name = e.target.value;
+});
+
+// Submit handler
+form.addEventListener("submit", async (e) => {
+  e.preventDefault();
+  await fetch("/submit", { body: getFormData() });
+});
+```
+
+### 2. File Upload Forms
+
+```ts
+import { pack } from "pouch-js";
+
+const { data, getFormData } = pack({
+  title: "",
+  description: "",
+  attachments: [], // Will hold files
+});
+
+// Add files to array
+fileInput.addEventListener("change", (e) => {
+  data.attachments.push(...e.target.files);
+});
+```
+
+### 3. Configuration Objects
+
+```ts
+import { pack } from "pouch-js";
+
+const { data, getFormData } = pack({
+  settings: {
+    theme: "dark",
+    notifications: true,
+    layout: { grid: true, spacing: 2 },
+  },
+});
+```
+
+## Limitations
+
+- **Root Types**: Only objects and arrays are supported as root values
+- **FormData Encoding**: Uses standard multipart/form-data encoding (not JSON)
+- **Circular References**: Not supported in the data structure
+- **Server Processing**: Requires server-side support for bracket notation (e.g., `user[name]`)
+
+## Browser Support
+
+Works in all modern browsers that support:
+
+- Proxy API (ES2015)
+- FormData API
+- Blob/File API
+
+## Contributing
+
+Found an issue? Want to add a feature? Please open an issue or PR on our GitHub repository.
+
+## License
+
+MIT License - feel free to use in your projects!

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+import { z, ZodTypeAny } from "zod";
+type Proxiable = object | any[];
+export type DeepWritable<T> = {
+    -readonly [K in keyof T]: T[K] extends object ? DeepWritable<T[K]> : T[K];
+};
+export declare function pack<T extends Proxiable>(initialData: T): {
+    data: T;
+    getFormData: () => FormData;
+};
+export declare function pack<T extends ZodTypeAny>(initialData: z.infer<T>, schema: T): {
+    data: z.infer<T>;
+    getFormData: () => FormData;
+};
+export {};

package/dist/index.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pack = pack;
+const zod_1 = require("zod");
+const isProxiable = (v) => typeof v === "object" && v !== null;
+const isBlobLike = (v) => v instanceof Blob || v instanceof File;
+const isProxiableNotBlob = (v) => isProxiable(v) && !isBlobLike(v);
+function inferValueSchema(value) {
+    if (isProxiableNotBlob(value))
+        return inferSchema(value);
+    if (isBlobLike(value))
+        return zod_1.z.instanceof(Blob);
+    if (typeof value === "string")
+        return zod_1.z.string();
+    if (typeof value === "number")
+        return zod_1.z.number();
+    if (typeof value === "boolean")
+        return zod_1.z.boolean();
+    if (value === null)
+        return zod_1.z.null();
+    if (value === undefined)
+        return zod_1.z.undefined();
+    return zod_1.z.unknown();
+}
+function inferSchema(data) {
+    if (Array.isArray(data)) {
+        const types = data.map(inferValueSchema);
+        return zod_1.z.array(types.length > 0
+            ? zod_1.z.union(types)
+            : zod_1.z.unknown());
+    }
+    if (isProxiableNotBlob(data)) {
+        const shape = Object.fromEntries(Object.keys(data).map((k) => [k, inferValueSchema(data[k])]));
+        return zod_1.z.object(shape);
+    }
+    return (isBlobLike(data)
+        ? zod_1.z.instanceof(Blob)
+        : zod_1.z.unknown());
+}
+const handler = {
+    set(target, property, value) {
+        Reflect.set(target, property, isProxiableNotBlob(value) ? createDeepProxy(value, handler) : value);
+        return true;
+    },
+};
+function createDeepProxy(target, handler) {
+    for (const key of Object.keys(target)) {
+        const value = target[key];
+        if (isProxiableNotBlob(value)) {
+            target[key] = createDeepProxy(value, handler);
+        }
+    }
+    return new Proxy(target, handler);
+}
+function appendToFormData(formData, data, key = "") {
+    if (Array.isArray(data)) {
+        data.forEach((value, i) => appendToFormData(formData, value, key ? `${key}[${i}]` : `${i}`));
+    }
+    else if (isProxiableNotBlob(data)) {
+        for (const [k, value] of Object.entries(data)) {
+            appendToFormData(formData, value, key ? `${key}[${k}]` : k);
+        }
+    }
+    else if (key) {
+        formData.append(key, isBlobLike(data) ? data : String(data));
+    }
+}
+function pack(initialData, schema) {
+    if (!isProxiable(initialData)) {
+        throw new Error("createFormDataManager only supports object and array root types");
+    }
+    const data = createDeepProxy(structuredClone((schema ?? inferSchema(initialData)).parse(initialData)), handler);
+    return {
+        data,
+        getFormData: () => {
+            const formData = new FormData();
+            appendToFormData(formData, data);
+            return formData;
+        },
+    };
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "pouch-js",
+  "version": "0.0.11",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "package.json",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "npx tsc -w",
+    "build": "npx tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "formdata",
+    "zod",
+    "validation",
+    "typescript",
+    "forms",
+    "file-upload",
+    "blob",
+    "proxy",
+    "reactive",
+    "schema",
+    "form-validation"
+  ],
+  "license": "MIT",
+  "description": "A schema-aware reactive FormData builder with Zod validation and full Blob/File support",
+  "peerDependencies": {
+    "zod": "^3.0.0"
+  },
+  "repository": {
+    "url": "https://github.com/techwithmanuel/frmz"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3",
+    "zod": "^3.24.4"
+  }
+}