@brielov/formdata

@brielov/formdata is a TypeScript library designed to make working with FormData objects easy and reliable. It provides utilities to encode JavaScript objects into FormData for use in HTTP requests and decode FormData back into nested objects. This library handles nested objects, arrays, blobs, and various edge cases gracefully.

---

Features

• Encode objects to FormData: Convert deeply nested objects, arrays, numbers, booleans, and strings into FormData.
• Decode FormData to objects: Reconstruct the original object from a FormData instance with support for custom strategies for handling empty strings.
• TypeScript support: Leverages TypeScript's type system for safety and auto-completion.
• Handles complex structures: Supports nested objects and arrays in both encoding and decoding.

---

Installation

Install the library via npm or yarn:

deno add jsr:@brielov/formdata
npx jsr add @brielov/formdata
yarn dlx jsr add @brielov/formdata
pnpm dlx jsr add @brielov/formdata
bunx jsr add @brielov/formdata

---

Usage

1. Encoding Objects to FormData

Use the encode function to transform a JavaScript object into a FormData instance:

import { encode } from "@brielov/formdata";

const data = {
  name: "John Doe",
  age: 30,
  hobbies: ["reading", "cycling"],
  address: {
    street: "123 Main St",
    city: "Metropolis",
  },
};

const formData = encode(data);
console.log([...formData.entries()]);

Output:

[
  ["name", "John Doe"],
  ["age", "30"],
  ["hobbies[0]", "reading"],
  ["hobbies[1]", "cycling"],
  ["address[street]", "123 Main St"],
  ["address[city]", "Metropolis"]
]

---

2. Decoding FormData to Objects

Use the decode function to reconstruct an object from a FormData instance:

import { decode } from "@brielov/formdata";

const formData = new FormData();
formData.append("name", "John Doe");
formData.append("age", "30");
formData.append("hobbies[0]", "reading");
formData.append("hobbies[1]", "cycling");
formData.append("address[street]", "123 Main St");
formData.append("address[city]", "Metropolis");

const object = decode(formData);
console.log(object);

Output:

{
  "name": "John Doe",
  "age": "30",
  "hobbies": ["reading", "cycling"],
  "address": {
    "street": "123 Main St",
    "city": "Metropolis"
  }
}

---

3. Customizing Empty String Handling

The decode function allows you to define how empty strings are treated using the emptyString option:

• "preserve" (default): Keeps empty strings as they are.
• "set null": Converts empty strings to null.
• "set undefined": Ignores keys with empty string values.

import { decode } from "@brielov/formdata";

const formData = new FormData();
formData.append("empty", "");
formData.append("name", "John Doe");

// Decode with different strategies
console.log(decode(formData, { emptyString: "preserve" })); // { empty: "", name: "John Doe" }
console.log(decode(formData, { emptyString: "set null" })); // { empty: null, name: "John Doe" }
console.log(decode(formData, { emptyString: "set undefined" })); // { name: "John Doe" }

---

API Reference

encode<T>(data: T): FormData

Encodes an object into a FormData instance.

• Parameters:
  • data: The object to encode. All keys and values will be serialized.
• Returns: A FormData instance containing the serialized data.
• Throws: An error if data is not a plain object.

---

decode(formData: FormData, options?: { emptyString?: "set null" | "set undefined" | "preserve" }): DecodeObject

Decodes a FormData instance into a nested object.

• Parameters:
  • formData: The FormData instance to decode.
  • options (optional): Configuration for handling empty strings.
    • emptyString: Determines how empty string values are treated ("preserve", "set null", "set undefined").
• Returns: A nested object representing the decoded data.

---

Types

DecodeValue

Represents a single value decoded from FormData.

type DecodeValue = string | Blob | null | DecodeObject | DecodeArray;

DecodeObject

Represents a nested object structure.

interface DecodeObject {
  [key: string]: DecodeValue;
}

DecodeArray

Represents an array of DecodeValue.

type DecodeArray = DecodeValue[];

---

License

MIT