formdata-io 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dougladmo
+
+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,277 @@
+# 🚀 FormData IO
+
+> TypeScript-first library for seamless FormData handling in frontend and backend.
+
+[![npm version](https://img.shields.io/npm/v/formdata-io.svg)](https://www.npmjs.com/package/formdata-io)
+[![Bundle size](https://img.shields.io/bundlephobia/minzip/formdata-io)](https://bundlephobia.com/package/formdata-io)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+
+## Why?
+
+Working with `multipart/form-data` in JavaScript is painful:
+
+- ❌ Manual `formData.append()` calls everywhere
+- ❌ Backend requires multer config, storage setup, and juggling `req.file` + `req.body`
+- ❌ Poor TypeScript support
+- ❌ Inconsistent APIs between frontend and backend
+
+**FormData IO solves this:**
+
+```typescript
+// Frontend: Write objects, not append calls
+const formData = payload({ name: "João", avatar: file });
+
+// Backend: Receive normalized payload, not scattered data
+app.post('/upload', parser(), (req, res) => {
+  const { name, avatar } = req.payload; // ✨ Type-safe!
+});
+```
+
+## Installation
+
+```bash
+npm install formdata-io
+```
+
+## Quick Start
+
+### Frontend (React, Vue, Vanilla JS)
+
+```typescript
+import { payload } from 'formdata-io/client';
+
+const formData = payload({
+  name: "João Silva",
+  age: 25,
+  avatar: fileInput.files[0],
+  tags: ["admin", "user"],
+  metadata: { source: "web" }
+});
+
+// Use with fetch
+fetch('/api/upload', {
+  method: 'POST',
+  body: formData
+});
+
+// Or with axios
+axios.post('/api/upload', formData);
+```
+
+### Backend (Express)
+
+```typescript
+import express from 'express';
+import { parser } from 'formdata-io/server';
+
+const app = express();
+
+app.post('/api/upload', parser(), (req, res) => {
+  const { name, age, avatar, tags, metadata } = req.payload;
+
+  console.log(name);     // "João Silva"
+  console.log(age);      // 25 (auto-parsed as number)
+  console.log(avatar);   // { buffer: Buffer, originalname: "...", ... }
+  console.log(tags);     // ["admin", "user"]
+  console.log(metadata); // { source: "web" } (auto-parsed JSON)
+
+  res.json({ success: true });
+});
+```
+
+## API Reference
+
+### Client API
+
+#### `payload(data, options?)`
+
+Converts a JavaScript object to FormData.
+
+**Parameters:**
+- `data: FormDataPayload` - Object to convert
+- `options?: PayloadOptions` - Configuration options
+
+**Returns:** `FormData`
+
+**Options:**
+```typescript
+{
+  indices: boolean;          // Add indices to array fields (default: false)
+  nullsAsUndefineds: boolean; // Skip null values (default: false)
+  booleansAsIntegers: boolean; // Convert true/false to 1/0 (default: true)
+}
+```
+
+**Examples:**
+
+```typescript
+// Basic usage
+const formData = payload({
+  name: "User",
+  file: document.querySelector('input[type="file"]').files[0]
+});
+
+// With arrays
+const formData = payload({
+  tags: ["admin", "user"] // → tags=admin&tags=user
+});
+
+// With indices
+const formData = payload(
+  { tags: ["admin", "user"] },
+  { indices: true } // → tags[0]=admin&tags[1]=user
+);
+
+// Nested objects (auto-serialized as JSON)
+const formData = payload({
+  metadata: { source: "web", version: 2 }
+  // → metadata='{"source":"web","version":2}'
+});
+
+// Date handling
+const formData = payload({
+  createdAt: new Date() // → createdAt='2024-01-01T00:00:00.000Z'
+});
+```
+
+### Server API
+
+#### `parser(options?)`
+
+Express middleware for parsing multipart/form-data.
+
+**Parameters:**
+- `options?: ParserOptions` - Configuration options
+
+**Returns:** Express middleware function
+
+**Options:**
+```typescript
+{
+  maxFileSize: number;      // Max file size in bytes (default: 10MB)
+  maxFiles: number;         // Max number of files (default: 10)
+  autoParseJSON: boolean;   // Auto-parse JSON strings (default: true)
+  autoParseNumbers: boolean; // Auto-convert numeric strings (default: true)
+  autoParseBooleans: boolean; // Auto-convert "true"/"false" (default: true)
+}
+```
+
+**Examples:**
+
+```typescript
+// Default options (10MB, 10 files)
+app.post('/upload', parser(), (req, res) => {
+  // req.payload contains all fields and files
+});
+
+// Custom file size limit
+app.post('/photos', parser({ maxFileSize: 50 * 1024 * 1024 }), (req, res) => {
+  // Allow up to 50MB files
+});
+
+// Disable auto-parsing
+app.post('/raw', parser({ autoParseJSON: false }), (req, res) => {
+  // All fields remain as strings
+});
+```
+
+#### `ParsedFile` Interface
+
+```typescript
+interface ParsedFile {
+  fieldname: string;    // Form field name
+  originalname: string; // Original filename
+  encoding: string;     // File encoding
+  mimetype: string;     // MIME type
+  size: number;         // File size in bytes
+  buffer: Buffer;       // File data
+}
+```
+
+## TypeScript Support
+
+Full TypeScript support with type inference:
+
+```typescript
+import type { ParsedFile } from 'formdata-io/server';
+
+app.post('/upload', parser(), (req, res) => {
+  const avatar = req.payload?.avatar as ParsedFile;
+
+  avatar.buffer;       // Buffer
+  avatar.originalname; // string
+  avatar.mimetype;     // string
+  avatar.size;         // number
+});
+```
+
+## Examples
+
+See the [examples](./examples) directory for complete working examples.
+
+**Run the example:**
+
+```bash
+# Terminal 1: Start the server
+npm run build
+node examples/basic/server.ts
+
+# Terminal 2: Open client.html in your browser
+open examples/basic/client.html
+```
+
+## Comparison with Alternatives
+
+| Feature | FormData IO | multer | busboy | object-to-formdata |
+|---------|-------------|--------|--------|-------------------|
+| Frontend + Backend | ✅ | ❌ | ❌ | ❌ |
+| TypeScript-first | ✅ | ⚠️ | ⚠️ | ❌ |
+| Zero config | ✅ | ❌ | ❌ | ✅ |
+| Auto-parsing | ✅ | ❌ | ❌ | N/A |
+| Bundle size | ~6KB | ~30KB | ~10KB | ~2KB |
+
+## How It Works
+
+### Client Side
+
+The `payload()` function converts JavaScript objects to FormData by:
+
+1. **File/Blob detection**: Directly appends File and Blob objects
+2. **Array handling**: Supports both flat (`tags=a&tags=b`) and indexed (`tags[0]=a`) formats
+3. **Object serialization**: Nested objects are JSON-serialized
+4. **Type conversion**: Booleans, numbers, dates converted to strings
+
+### Server Side
+
+The `parser()` middleware uses [busboy](https://github.com/mscdex/busboy) for stream-based parsing:
+
+1. **Stream processing**: Memory-efficient file handling
+2. **Size limits**: Enforced per-file and total limits
+3. **Auto-parsing**: Automatic type conversion (JSON, numbers, booleans)
+4. **Array normalization**: Multiple values with same key become arrays
+
+## Security
+
+**Built-in protections:**
+- ✅ File size limits (default: 10MB per file)
+- ✅ File count limits (default: 10 files max)
+- ✅ Stream-based processing (no memory exhaustion)
+- ✅ Safe JSON parsing (fallback to string on error)
+
+**Your responsibility:**
+- ⚠️ File type validation (check `mimetype` and magic bytes)
+- ⚠️ Filename sanitization (prevent path traversal)
+- ⚠️ Virus scanning (if accepting user files)
+- ⚠️ Storage security (S3 permissions, disk quotas)
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions welcome! Please open an issue or PR.
+
+## Credits
+
+Built with [busboy](https://github.com/mscdex/busboy) for multipart parsing.

package/dist/client/index.d.mts

@@ -0,0 +1,90 @@
+/**
+ * Supported value types for FormData conversion
+ */
+type FormDataValue = string | number | boolean | null | undefined | File | Blob | Date;
+/**
+ * Recursive type for objects that can be converted to FormData
+ *
+ * Supports nested objects and arrays, with automatic serialization
+ */
+type FormDataPayload = {
+    [key: string]: FormDataValue | FormDataValue[] | FormDataPayload | FormDataPayload[];
+};
+/**
+ * Configuration options for FormData conversion
+ */
+interface PayloadOptions {
+    /**
+     * Add numeric indices to array field names
+     *
+     * @default false
+     *
+     * @example
+     * ```typescript
+     * // indices: false → tags=a&tags=b
+     * // indices: true → tags[0]=a&tags[1]=b
+     * ```
+     */
+    indices?: boolean;
+    /**
+     * Skip null values instead of converting to empty strings
+     *
+     * @default false
+     *
+     * @example
+     * ```typescript
+     * // nullsAsUndefineds: false → optional=""
+     * // nullsAsUndefineds: true → optional field not sent
+     * ```
+     */
+    nullsAsUndefineds?: boolean;
+    /**
+     * Convert boolean values to 1/0 instead of true/false
+     *
+     * @default true
+     *
+     * @example
+     * ```typescript
+     * // booleansAsIntegers: true → active=1
+     * // booleansAsIntegers: false → active=true
+     * ```
+     */
+    booleansAsIntegers?: boolean;
+}
+
+/**
+ * Converts a JavaScript object to FormData
+ *
+ * @param data - Object to be converted
+ * @param options - Configuration options
+ * @returns FormData instance ready for submission
+ *
+ * @example
+ * ```typescript
+ * const formData = payload({
+ *   name: "João Silva",
+ *   age: 25,
+ *   avatar: fileInput.files[0],
+ *   tags: ["admin", "user"],
+ *   metadata: { source: "web" }
+ * });
+ *
+ * // Use with fetch
+ * fetch('/upload', { method: 'POST', body: formData });
+ *
+ * // Use with axios
+ * axios.post('/upload', formData);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom options
+ * const formData = payload(data, {
+ *   indices: true,           // tags[0]=admin&tags[1]=user
+ *   booleansAsIntegers: false // active=true instead of active=1
+ * });
+ * ```
+ */
+declare function payload(data: FormDataPayload, options?: Partial<PayloadOptions>): FormData;
+
+export { type FormDataPayload, type FormDataValue, type PayloadOptions, payload };

package/dist/client/index.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Supported value types for FormData conversion
+ */
+type FormDataValue = string | number | boolean | null | undefined | File | Blob | Date;
+/**
+ * Recursive type for objects that can be converted to FormData
+ *
+ * Supports nested objects and arrays, with automatic serialization
+ */
+type FormDataPayload = {
+    [key: string]: FormDataValue | FormDataValue[] | FormDataPayload | FormDataPayload[];
+};
+/**
+ * Configuration options for FormData conversion
+ */
+interface PayloadOptions {
+    /**
+     * Add numeric indices to array field names
+     *
+     * @default false
+     *
+     * @example
+     * ```typescript
+     * // indices: false → tags=a&tags=b
+     * // indices: true → tags[0]=a&tags[1]=b
+     * ```
+     */
+    indices?: boolean;
+    /**
+     * Skip null values instead of converting to empty strings
+     *
+     * @default false
+     *
+     * @example
+     * ```typescript
+     * // nullsAsUndefineds: false → optional=""
+     * // nullsAsUndefineds: true → optional field not sent
+     * ```
+     */
+    nullsAsUndefineds?: boolean;
+    /**
+     * Convert boolean values to 1/0 instead of true/false
+     *
+     * @default true
+     *
+     * @example
+     * ```typescript
+     * // booleansAsIntegers: true → active=1
+     * // booleansAsIntegers: false → active=true
+     * ```
+     */
+    booleansAsIntegers?: boolean;
+}
+
+/**
+ * Converts a JavaScript object to FormData
+ *
+ * @param data - Object to be converted
+ * @param options - Configuration options
+ * @returns FormData instance ready for submission
+ *
+ * @example
+ * ```typescript
+ * const formData = payload({
+ *   name: "João Silva",
+ *   age: 25,
+ *   avatar: fileInput.files[0],
+ *   tags: ["admin", "user"],
+ *   metadata: { source: "web" }
+ * });
+ *
+ * // Use with fetch
+ * fetch('/upload', { method: 'POST', body: formData });
+ *
+ * // Use with axios
+ * axios.post('/upload', formData);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom options
+ * const formData = payload(data, {
+ *   indices: true,           // tags[0]=admin&tags[1]=user
+ *   booleansAsIntegers: false // active=true instead of active=1
+ * });
+ * ```
+ */
+declare function payload(data: FormDataPayload, options?: Partial<PayloadOptions>): FormData;
+
+export { type FormDataPayload, type FormDataValue, type PayloadOptions, payload };

package/dist/client/index.js

@@ -0,0 +1,86 @@
+'use strict';
+
+// src/client/utils.ts
+function isFileOrBlob(value) {
+  if (typeof File !== "undefined" && value instanceof File) return true;
+  if (typeof Blob !== "undefined" && value instanceof Blob) return true;
+  return false;
+}
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null) return false;
+  if (isFileOrBlob(value)) return false;
+  if (value instanceof Date) return false;
+  if (Array.isArray(value)) return false;
+  return true;
+}
+function valueToString(value, options) {
+  if (value === null) {
+    return options.nullsAsUndefineds ? void 0 : "";
+  }
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value === "boolean") {
+    if (options.booleansAsIntegers) {
+      return value ? "1" : "0";
+    }
+    return value.toString();
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (typeof value === "number") {
+    return value.toString();
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  return void 0;
+}
+function buildFieldName(parentKey, key, options) {
+  if (typeof key === "number") {
+    return options.indices ? `${parentKey}[${key}]` : parentKey;
+  }
+  return parentKey ? `${parentKey}[${key}]` : key;
+}
+
+// src/client/payload.ts
+var DEFAULT_OPTIONS = {
+  indices: false,
+  nullsAsUndefineds: false,
+  booleansAsIntegers: true
+};
+function payload(data, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  const formData = new FormData();
+  function append(key, value) {
+    if (isFileOrBlob(value)) {
+      formData.append(key, value);
+      return;
+    }
+    if (Array.isArray(value)) {
+      value.forEach((item, index) => {
+        const fieldName = buildFieldName(key, index, opts);
+        append(fieldName, item);
+      });
+      return;
+    }
+    if (isPlainObject(value)) {
+      const jsonString = JSON.stringify(value);
+      formData.append(key, jsonString);
+      return;
+    }
+    const stringValue = valueToString(value, opts);
+    if (stringValue !== void 0) {
+      formData.append(key, stringValue);
+    }
+  }
+  Object.entries(data).forEach(([key, value]) => {
+    append(key, value);
+  });
+  return formData;
+}
+
+exports.payload = payload;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/client/utils.ts","../../src/client/payload.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { FormDataValue, FormDataPayload, PayloadOptions } from './types';\n\n/**\n * Checks if a value is a File or Blob object\n *\n * Handles environments where File/Blob may not be defined (e.g., JSDOM, SSR)\n *\n * @param value - Value to check\n * @returns True if value is File or Blob\n */\nexport function isFileOrBlob(value: unknown): value is File | Blob {\n  if (typeof File !== 'undefined' && value instanceof File) return true;\n  if (typeof Blob !== 'undefined' && value instanceof Blob) return true;\n  return false;\n}\n\n/**\n * Checks if a value is a plain object (not File, Blob, Date, Array, or null)\n *\n * Order matters: File/Blob checked before Date since File extends Blob\n *\n * @param value - Value to check\n * @returns True if value is a plain object\n */\nexport function isPlainObject(value: unknown): value is Record<string, unknown> {\n  if (typeof value !== 'object' || value === null) return false;\n  if (isFileOrBlob(value)) return false;\n  if (value instanceof Date) return false;\n  if (Array.isArray(value)) return false;\n  return true;\n}\n\n/**\n * Converts a primitive value to string according to options\n *\n * @param value - Value to convert\n * @param options - Conversion options\n * @returns String representation or undefined to skip\n */\nexport function valueToString(\n  value: FormDataValue,\n  options: PayloadOptions\n): string | undefined {\n  // null: '' or skip (based on nullsAsUndefineds)\n  if (value === null) {\n    return options.nullsAsUndefineds ? undefined : '';\n  }\n\n  // undefined: always skip\n  if (value === undefined) {\n    return undefined;\n  }\n\n  // boolean: '1'/'0' or 'true'/'false' (based on booleansAsIntegers)\n  if (typeof value === 'boolean') {\n    if (options.booleansAsIntegers) {\n      return value ? '1' : '0';\n    }\n    return value.toString();\n  }\n\n  // Date: ISO 8601 string\n  if (value instanceof Date) {\n    return value.toISOString();\n  }\n\n  // number: string representation (handles NaN, Infinity correctly)\n  if (typeof value === 'number') {\n    return value.toString();\n  }\n\n  // string: return as-is\n  if (typeof value === 'string') {\n    return value;\n  }\n\n  // Shouldn't reach here but return undefined for safety\n  return undefined;\n}\n\n/**\n * Builds field name with support for array/object notation\n *\n * @param parentKey - Parent field name\n * @param key - Current key (string or number for arrays)\n * @param options - Configuration options\n * @returns Formatted field name\n *\n * @example\n * ```typescript\n * buildFieldName('', 'name', opts) // 'name'\n * buildFieldName('user', 'email', opts) // 'user[email]'\n * buildFieldName('tags', 0, { indices: false }) // 'tags'\n * buildFieldName('tags', 0, { indices: true }) // 'tags[0]'\n * ```\n */\nexport function buildFieldName(\n  parentKey: string,\n  key: string | number,\n  options: PayloadOptions\n): string {\n  // Array index handling\n  if (typeof key === 'number') {\n    return options.indices ? `${parentKey}[${key}]` : parentKey;\n  }\n\n  // Object key handling\n  return parentKey ? `${parentKey}[${key}]` : key;\n}\n","import type { FormDataPayload, PayloadOptions } from './types';\nimport {\n  isFileOrBlob,\n  isPlainObject,\n  valueToString,\n  buildFieldName,\n} from './utils';\n\nconst DEFAULT_OPTIONS: PayloadOptions = {\n  indices: false,\n  nullsAsUndefineds: false,\n  booleansAsIntegers: true,\n};\n\n/**\n * Converts a JavaScript object to FormData\n *\n * @param data - Object to be converted\n * @param options - Configuration options\n * @returns FormData instance ready for submission\n *\n * @example\n * ```typescript\n * const formData = payload({\n *   name: \"João Silva\",\n *   age: 25,\n *   avatar: fileInput.files[0],\n *   tags: [\"admin\", \"user\"],\n *   metadata: { source: \"web\" }\n * });\n *\n * // Use with fetch\n * fetch('/upload', { method: 'POST', body: formData });\n *\n * // Use with axios\n * axios.post('/upload', formData);\n * ```\n *\n * @example\n * ```typescript\n * // With custom options\n * const formData = payload(data, {\n *   indices: true,           // tags[0]=admin&tags[1]=user\n *   booleansAsIntegers: false // active=true instead of active=1\n * });\n * ```\n */\nexport function payload(\n  data: FormDataPayload,\n  options: Partial<PayloadOptions> = {}\n): FormData {\n  const opts = { ...DEFAULT_OPTIONS, ...options };\n  const formData = new FormData();\n\n  /**\n   * Recursively append values to FormData\n   *\n   * @param key - Field name\n   * @param value - Value to append\n   */\n  function append(key: string, value: unknown): void {\n    // Case 1: File or Blob - direct append (terminal case)\n    if (isFileOrBlob(value)) {\n      formData.append(key, value);\n      return;\n    }\n\n    // Case 2: Array - recurse with optional indexing\n    if (Array.isArray(value)) {\n      value.forEach((item, index) => {\n        const fieldName = buildFieldName(key, index, opts);\n        append(fieldName, item);\n      });\n      return;\n    }\n\n    // Case 3: Plain object - serialize as JSON (terminal case)\n    if (isPlainObject(value)) {\n      const jsonString = JSON.stringify(value);\n      formData.append(key, jsonString);\n      return;\n    }\n\n    // Case 4: Primitives (string, number, boolean, null, undefined, Date)\n    const stringValue = valueToString(value as any, opts);\n    if (stringValue !== undefined) {\n      formData.append(key, stringValue);\n    }\n  }\n\n  // Iterate over root-level keys\n  Object.entries(data).forEach(([key, value]) => {\n    append(key, value);\n  });\n\n  return formData;\n}\n"]}

package/dist/client/index.mjs

@@ -0,0 +1,84 @@
+// src/client/utils.ts
+function isFileOrBlob(value) {
+  if (typeof File !== "undefined" && value instanceof File) return true;
+  if (typeof Blob !== "undefined" && value instanceof Blob) return true;
+  return false;
+}
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null) return false;
+  if (isFileOrBlob(value)) return false;
+  if (value instanceof Date) return false;
+  if (Array.isArray(value)) return false;
+  return true;
+}
+function valueToString(value, options) {
+  if (value === null) {
+    return options.nullsAsUndefineds ? void 0 : "";
+  }
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value === "boolean") {
+    if (options.booleansAsIntegers) {
+      return value ? "1" : "0";
+    }
+    return value.toString();
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (typeof value === "number") {
+    return value.toString();
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  return void 0;
+}
+function buildFieldName(parentKey, key, options) {
+  if (typeof key === "number") {
+    return options.indices ? `${parentKey}[${key}]` : parentKey;
+  }
+  return parentKey ? `${parentKey}[${key}]` : key;
+}
+
+// src/client/payload.ts
+var DEFAULT_OPTIONS = {
+  indices: false,
+  nullsAsUndefineds: false,
+  booleansAsIntegers: true
+};
+function payload(data, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  const formData = new FormData();
+  function append(key, value) {
+    if (isFileOrBlob(value)) {
+      formData.append(key, value);
+      return;
+    }
+    if (Array.isArray(value)) {
+      value.forEach((item, index) => {
+        const fieldName = buildFieldName(key, index, opts);
+        append(fieldName, item);
+      });
+      return;
+    }
+    if (isPlainObject(value)) {
+      const jsonString = JSON.stringify(value);
+      formData.append(key, jsonString);
+      return;
+    }
+    const stringValue = valueToString(value, opts);
+    if (stringValue !== void 0) {
+      formData.append(key, stringValue);
+    }
+  }
+  Object.entries(data).forEach(([key, value]) => {
+    append(key, value);
+  });
+  return formData;
+}
+
+export { payload };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/client/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/client/utils.ts","../../src/client/payload.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["import type { FormDataValue, FormDataPayload, PayloadOptions } from './types';\n\n/**\n * Checks if a value is a File or Blob object\n *\n * Handles environments where File/Blob may not be defined (e.g., JSDOM, SSR)\n *\n * @param value - Value to check\n * @returns True if value is File or Blob\n */\nexport function isFileOrBlob(value: unknown): value is File | Blob {\n  if (typeof File !== 'undefined' && value instanceof File) return true;\n  if (typeof Blob !== 'undefined' && value instanceof Blob) return true;\n  return false;\n}\n\n/**\n * Checks if a value is a plain object (not File, Blob, Date, Array, or null)\n *\n * Order matters: File/Blob checked before Date since File extends Blob\n *\n * @param value - Value to check\n * @returns True if value is a plain object\n */\nexport function isPlainObject(value: unknown): value is Record<string, unknown> {\n  if (typeof value !== 'object' || value === null) return false;\n  if (isFileOrBlob(value)) return false;\n  if (value instanceof Date) return false;\n  if (Array.isArray(value)) return false;\n  return true;\n}\n\n/**\n * Converts a primitive value to string according to options\n *\n * @param value - Value to convert\n * @param options - Conversion options\n * @returns String representation or undefined to skip\n */\nexport function valueToString(\n  value: FormDataValue,\n  options: PayloadOptions\n): string | undefined {\n  // null: '' or skip (based on nullsAsUndefineds)\n  if (value === null) {\n    return options.nullsAsUndefineds ? undefined : '';\n  }\n\n  // undefined: always skip\n  if (value === undefined) {\n    return undefined;\n  }\n\n  // boolean: '1'/'0' or 'true'/'false' (based on booleansAsIntegers)\n  if (typeof value === 'boolean') {\n    if (options.booleansAsIntegers) {\n      return value ? '1' : '0';\n    }\n    return value.toString();\n  }\n\n  // Date: ISO 8601 string\n  if (value instanceof Date) {\n    return value.toISOString();\n  }\n\n  // number: string representation (handles NaN, Infinity correctly)\n  if (typeof value === 'number') {\n    return value.toString();\n  }\n\n  // string: return as-is\n  if (typeof value === 'string') {\n    return value;\n  }\n\n  // Shouldn't reach here but return undefined for safety\n  return undefined;\n}\n\n/**\n * Builds field name with support for array/object notation\n *\n * @param parentKey - Parent field name\n * @param key - Current key (string or number for arrays)\n * @param options - Configuration options\n * @returns Formatted field name\n *\n * @example\n * ```typescript\n * buildFieldName('', 'name', opts) // 'name'\n * buildFieldName('user', 'email', opts) // 'user[email]'\n * buildFieldName('tags', 0, { indices: false }) // 'tags'\n * buildFieldName('tags', 0, { indices: true }) // 'tags[0]'\n * ```\n */\nexport function buildFieldName(\n  parentKey: string,\n  key: string | number,\n  options: PayloadOptions\n): string {\n  // Array index handling\n  if (typeof key === 'number') {\n    return options.indices ? `${parentKey}[${key}]` : parentKey;\n  }\n\n  // Object key handling\n  return parentKey ? `${parentKey}[${key}]` : key;\n}\n","import type { FormDataPayload, PayloadOptions } from './types';\nimport {\n  isFileOrBlob,\n  isPlainObject,\n  valueToString,\n  buildFieldName,\n} from './utils';\n\nconst DEFAULT_OPTIONS: PayloadOptions = {\n  indices: false,\n  nullsAsUndefineds: false,\n  booleansAsIntegers: true,\n};\n\n/**\n * Converts a JavaScript object to FormData\n *\n * @param data - Object to be converted\n * @param options - Configuration options\n * @returns FormData instance ready for submission\n *\n * @example\n * ```typescript\n * const formData = payload({\n *   name: \"João Silva\",\n *   age: 25,\n *   avatar: fileInput.files[0],\n *   tags: [\"admin\", \"user\"],\n *   metadata: { source: \"web\" }\n * });\n *\n * // Use with fetch\n * fetch('/upload', { method: 'POST', body: formData });\n *\n * // Use with axios\n * axios.post('/upload', formData);\n * ```\n *\n * @example\n * ```typescript\n * // With custom options\n * const formData = payload(data, {\n *   indices: true,           // tags[0]=admin&tags[1]=user\n *   booleansAsIntegers: false // active=true instead of active=1\n * });\n * ```\n */\nexport function payload(\n  data: FormDataPayload,\n  options: Partial<PayloadOptions> = {}\n): FormData {\n  const opts = { ...DEFAULT_OPTIONS, ...options };\n  const formData = new FormData();\n\n  /**\n   * Recursively append values to FormData\n   *\n   * @param key - Field name\n   * @param value - Value to append\n   */\n  function append(key: string, value: unknown): void {\n    // Case 1: File or Blob - direct append (terminal case)\n    if (isFileOrBlob(value)) {\n      formData.append(key, value);\n      return;\n    }\n\n    // Case 2: Array - recurse with optional indexing\n    if (Array.isArray(value)) {\n      value.forEach((item, index) => {\n        const fieldName = buildFieldName(key, index, opts);\n        append(fieldName, item);\n      });\n      return;\n    }\n\n    // Case 3: Plain object - serialize as JSON (terminal case)\n    if (isPlainObject(value)) {\n      const jsonString = JSON.stringify(value);\n      formData.append(key, jsonString);\n      return;\n    }\n\n    // Case 4: Primitives (string, number, boolean, null, undefined, Date)\n    const stringValue = valueToString(value as any, opts);\n    if (stringValue !== undefined) {\n      formData.append(key, stringValue);\n    }\n  }\n\n  // Iterate over root-level keys\n  Object.entries(data).forEach(([key, value]) => {\n    append(key, value);\n  });\n\n  return formData;\n}\n"]}