2k-form-data-to-object

2k-form-data-to-object

A lightweight TypeScript utility library for seamlessly converting between FormData and nested JavaScript objects. Perfect for handling complex form submissions with hierarchical data structures.

Features

✨ Bidirectional Conversion

• Transform FormData to nested objects
• Convert nested objects back to FormData
• Maintain data integrity through round-trip conversions

🎯 Smart Type Handling

• Automatic type inference for strings, numbers, and booleans
• Preserve File and Blob objects during conversion
• Support for Date serialization (ISO 8601)
• Handle null and undefined values intelligently

🏗️ Nested Structure Support

• Deep object nesting with dot notation (user.address.street)
• Array indexing support (items.0.name, items.1.name)
• Mixed nested objects and arrays

✅ Fully Tested

• Comprehensive Jest test suite
• Edge case coverage
• Type-safe with TypeScript

Installation

npm install 2k-form-data-to-object

or

yarn add 2k-form-data-to-object

Quick Start

FormData → Object

import { transformFormDataToObject } from "2k-form-data-to-object";

const formData = new FormData();
formData.append("name", "John");
formData.append("age", "30");
formData.append("active", "on");
formData.append("user.email", "john@example.com");
formData.append("user.address.city", "New York");

const result = transformFormDataToObject(formData);
// Result:
// {
//   name: "John",
//   age: 30,
//   active: true,
//   user: {
//     email: "john@example.com",
//     address: {
//       city: "New York"
//     }
//   }
// }

Object → FormData

import { transformObjectToFormData } from "2k-form-data-to-object";

const data = {
  name: "John",
  age: 30,
  active: true,
  profile: {
    email: "john@example.com",
    avatar: fileObject, // File or Blob
  },
  tags: ["javascript", "typescript"],
};

const formData = transformObjectToFormData(data);
// FormData entries:
// name: "John"
// age: "30"
// active: "true"
// profile.email: "john@example.com"
// profile.avatar: File
// tags.0: "javascript"
// tags.1: "typescript"

API Reference

transformFormDataToObject(formData: FormData): UnknownObject

Converts FormData to a nested JavaScript object with automatic type coercion.

Parameters

• formData (FormData): The FormData object to transform

Returns

• (UnknownObject): A nested object with intelligently typed values

Type Conversion Rules

Dot Notation Examples

• user.name → { user: { name: "..." } }
• items.0.id → { items: [{ id: "..." }] }
• config.nested.deep.value → deeply nested objects

---

transformObjectToFormData(object: Record<string, FormDataValue>): FormData

Converts a nested JavaScript object to FormData with proper serialization.

Parameters

• object (Record<string, FormDataValue>): The object to transform

Returns

• (FormData): A FormData object ready for submission

Supported Types

type FormDataValue =
  | string
  | number
  | boolean
  | bigint
  | Date
  | File
  | Blob
  | null
  | undefined
  | FormDataValue[]
  | { [key: string]: FormDataValue };

Serialization Rules

---

Usage Examples

Complex Nested Form

const form = new FormData();
form.append("user.profile.firstName", "Jane");
form.append("user.profile.lastName", "Doe");
form.append("user.contacts.0", "jane@example.com");
form.append("user.contacts.1", "jane.doe@work.com");
form.append("user.active", "true");
form.append("user.age", "28");

const result = transformFormDataToObject(form);
// {
//   user: {
//     profile: {
//       firstName: "Jane",
//       lastName: "Doe"
//     },
//     contacts: ["jane@example.com", "jane.doe@work.com"],
//     active: true,
//     age: 28
//   }
// }

File Handling

const formData = new FormData();
const file = new File(["content"], "document.pdf");

formData.append("document", file);
formData.append("metadata.title", "My Document");

const result = transformFormDataToObject(formData);
// {
//   document: File,
//   metadata: {
//     title: "My Document"
//   }
// }

Date Serialization

const data = {
  createdAt: new Date("2024-01-15"),
  updatedAt: new Date("2024-01-20"),
  name: "Project",
};

const formData = transformObjectToFormData(data);
// FormData contains:
// createdAt: "2024-01-15T00:00:00.000Z"
// updatedAt: "2024-01-20T00:00:00.000Z"
// name: "Project"

Array Handling

// Object to FormData
const data = {
  items: [
    { id: 1, name: "Item 1" },
    { id: 2, name: "Item 2" },
  ],
};

const formData = transformObjectToFormData(data);
// FormData entries:
// items.0.id: "1"
// items.0.name: "Item 1"
// items.1.id: "2"
// items.1.name: "Item 2"

---

Testing

The library includes a comprehensive Jest test suite covering:

• ✅ Basic type conversions
• ✅ Nested object transformations
• ✅ Array handling and indexing
• ✅ File and Blob preservation
• ✅ Date serialization
• ✅ Edge cases (null, undefined, empty values)
• ✅ Round-trip conversions (object → FormData → object)

Run tests with:

npm test

---

TypeScript Support

Full TypeScript support with strict type safety:

import {
  transformFormDataToObject,
  transformObjectToFormData,
} from "@2_k/2k-form-data-to-object";

// Type-safe usage
const data: Record<string, FormDataValue> = {
  name: "John",
  age: 30,
  avatar: fileObject,
};

const formData = transformObjectToFormData(data);
const result = transformFormDataToObject(formData);

---

Use Cases

• 📝 Form Submission: Convert HTML form data to structured objects
• 🔄 API Integration: Prepare nested data for multipart form requests
• 📤 File Uploads: Handle file uploads with additional metadata
• 🗂️ Data Validation: Work with typed objects before form submission
• 🔁 Data Serialization: Round-trip conversion for data persistence

---

Performance

Optimized for typical form sizes with:

• Minimal memory overhead
• Single-pass processing
• Efficient recursion handling
• No external dependencies

---

💛 Donate via Orange Money (Madagascar)

Send your donation directly to:

my Orange Money 📱 +261 37 65 442 50

Or Mvola 📱 +261 34 68 814 74

Or Airtel Money 📱 +261 33 36 613 20

Any amount is deeply appreciated! 🤝

License

MIT

Changelog

v1.0.0

• Initial release
• FormData ↔ Object conversion
• Type inference for primitives
• Nested object and array support
• File/Blob preservation
• Date serialization