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", "[email protected]");
formData.append("user.address.city", "New York");

const result = transformFormDataToObject(formData);
// Result:
// {
//   name: "John",
//   age: 30,
//   active: true,
//   user: {
//     email: "[email protected]",
//     address: {
//       city: "New York"
//     }
//   }
// }

Object → FormData

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

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

const formData = transformObjectToFormData(data);
// FormData entries:
// name: "John"
// age: "30"
// active: "true"
// profile.email: "[email protected]"
// 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

| Input | Output | Example | | ------------------ | ------- | ------------------------ | | "true"/"false" | boolean | "true"→true | | "on"/"off" | boolean | "on"→true | | Numeric string | number | "42"→42 | | File object | File | File→File(unchanged) | | Regular string | string | "hello"→"hello" |

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

| Input Type | Serialized As | Notes | | ------------------ | --------------- | --------------------------- | | File/Blob | Raw value | Preserved as-is | | Date | ISO 8601 string | UsestoISOString() | | null/undefined | Omitted | Not included in FormData | | Array | Indexed keys | [a, b]→0: a, 1: b | | Object | Nested keys | {x: y}→x: y | | Primitives | String | true→"true",42→"42" |

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", "[email protected]");
form.append("user.contacts.1", "[email protected]");
form.append("user.active", "true");
form.append("user.age", "28");

const result = transformFormDataToObject(form);
// {
//   user: {
//     profile: {
//       firstName: "Jane",
//       lastName: "Doe"
//     },
//     contacts: ["[email protected]", "[email protected]"],
//     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