object-to-form-data

Serialize objects, arrays and collections into FormData.

Installation

pnpm:

pnpm add @octetstream/object-to-form-data

npm:

npm i @octetstream/object-to-form-data

CJS/ESM support

This module supports both CommonJS and ES Modules.

Usage

1. To use this package, just import objectToFormData and pass input data as the first argument:

import {objectToFormData} from "@octetstream/object-to-form-data"

const user = {
  name: "The Octocat",
  login: "octocat",
  url: "https://github.com/octocat",
  repositories: {
    nodes: [
      {
        name: "Hello-World",
        description: "My first repository on GitHub!",
        url: "https://github.com/octocat/Hello-World"
      }
    ]
  }
}

// You will receive a FormData instance with all fields of given object
const form = objectToFormData(user)

const options = {
  method: "post",
  body: form
}

const response = await fetch("https://httpbin.org/post", options)

The user object from this example will be serailized into FormData with following structure (pseudo code):

name = "The Octocat"
login = "octocat"
url = "https://github.com/octocat"
repositories[nodes][0][name] = "Hello-World"
repositories[nodes][0][description] = "My first repository on GitHub!"
repositories[nodes][0][url] = "https://github.com/octocat/Hello-World"

2. By default the bracked notation is applied, but use can pass dot as notation option like this:

import {objectToFormData} from "@octetstream/object-to-form-data"

const person = {
  name: "Nick K.",
  url: "https://github.com/octet-stream",
  skills: ["TypeScript", "JavaScript", "React", "Next.js", "Vue", "Nuxt", "Qwik", "Docker"]
}

const form = objectToFormData(person, {
  notation: "dot" // This will enable dot notation for serialization
})

Returned form object has following structure:

name = "Nick K."
url = "https://github.com/octet-stream"
skills.0 = TypeScript
skills.1 = JavaScript
skills.2 = React
skills.3 = Next.js
skills.4 = Vue
skills.5 = Nuxt
skills.6 = Qwik
skills.7 = Docker

3. You can also pass collections as the input:

import {objectToFormData} from "@octetstream/object-to-form-data"

const developers = [
  {
    name: "John Doe",
    skills: ["JavaScript", "TypeScript", "React", "Qwik"],
    isHireable: true
  },
  {
    name: "Max Doe",
    skills: ["Python", "Django", "Flask", "MySQL", "Pony ORM"],
    isHireable: false
  }
]

const form = objectToFormData(developers)

This results in following form structure:

[0][name] = "John Doe"
[0][skills][0] = "JavaScript"
[0][skills][1] = "TypeScript"
[0][skills][2] = "React"
[0][skills][3] = "Qwik"
[1][name] = "Max Doe"
[1][skills][0] = "Python"
[1][skills][1] = "Django"
[1][skills][2] = "Flask"
[1][skills][3] = "MySQL"
[1][skills][4] = "Pony ORM"

4. Flat arrays supported too:

import {objectToFormData} from "@octetstream/object-to-form-data"

const fruits = ["orange", "pineapple", "nectarine", "pear", "pomegranate"]

const form = objectToFormData(fruits)

Result:

[0] = "orange"
[1] = "pineapple"
[2] = "nectarine"
[3] = "pear"
[4] = "pomegranate"

5. Serializing files and blobs:

import {objectToFormData} from "@octetstream/object-to-form-data"

const input = [
  {
    caption: "Text file created with File object",
    file: new File(["My hovercraft if full of eels"], "test.txt", {type: "text/plain"}),
  },
  {
    caption: "Text data created with Blob object",
    file: new Blob(["On Soviet Moon landscape see binoculars through you"], {type: "text/plain"}),
  }
]

const form = objectToFormData(input)

Result:

[0][caption] = "Text file created with File object"
[0][file] = File [type: "text/plain", name: "test.txt", content: "My hovercraft if full of eels"]
[1][caption] = "Text data created with Blob object"
[1][file] = File [type: "text/plain", name: "blob", content: "On Soviet Moon landscape see binoculars through you"]

API

objectToFormData(input[, options]): FormData

Serializes objects, arrays and collections into FormData.

Nested objects will be flattened using either dot or bracket notation.

This function takes following arguments:

| Name | Type | Required | Default | Description | |---------|:---------------------------------------------------------------:|:---------:|:-----------:|----------------------------------| | input | unknown[] \| Record<sting \| number, unknown> | true | – | An object to transform | | options | ObjectToFormDataOptions | false | undefined | Additional serialization options |

Returns FormData instance.

interface ObjectToFormDataOptions

Serialization options

| Name | Type | Required | Default | Description | |----------------|:----------------------------------------:|:--------:|:---------------------:|---------------------------------------------------------------------------------------------------------------| | strict | boolean | false | false | Indicates whether or not to omit every false values. Applied enabled. Does not affect boolean array values | | FormData | FormData | false | globalThis.FormData | Custom spec-compliant FormData implementation | | notation | "dot" \| "bracket" | false | "bracket" | Type of the nested fields notation. Can be either "dot" or "bracket" | | normalizeValue | NormalizeValue | false | undefined | Value normalizer. This function will be called on each scalar value, before it's added to FormData instance |

interface NormalizeValue

Value normalizer.

A function to be called on each scalar value, before it's added to FormData instance. It must return either Blob or string

This function will be called with the following arguments:

| Name | Type | Description | |---------|:-------------------------:|-------------------------------------| | value | unknown | Current entry value | | name | string | The name of the entry | | path | Array<string \| number> | Entry's path within original object |

This function must return either Blob or string. Any unsupported type will be converted to string by FormData.

Related links

• FormData documentation on MDN
• File documentation on MDN
• Blob documentation on MDN
• FormDataValue documentation on MDN.
• formdata-node Spec-compliant FormData implementation for Node.js.
• formdata-polyfill HTML5 FormData for Browsers & NodeJS.
• node-fetch a light-weight module that brings the Fetch API to Node.js
• fetch-blob a Blob implementation for Node.js, originally from node-fetch.
• form-data-encoder spec-compliant multipart/form-data encoder implementation.
• then-busboy a promise-based wrapper around Busboy. Process multipart/form-data content and returns it as a single object. Will be helpful to handle your data on the server-side applications.