Serialize objects, arrays and collections into FormData.
npm install @octetstream/object-to-form-dataSerialize objects, arrays and collections into FormData.


pnpm:
``sh`
pnpm add @octetstream/object-to-form-data
npm:
`sh`
npm i @octetstream/object-to-form-data
This module supports both CommonJS and ES Modules.
1. To use this package, just import objectToFormData and pass input data as the first argument:
`ts
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:
`ts
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:
`ts
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:
`ts
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:
`ts
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"]
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 | true | – | An object to transform |ObjectToFormDataOptions
| options | | false | undefined | Additional serialization options |
Returns FormData instance.
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 |"dot" \| "bracket"
| notation | | 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 |
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 |string
| name | | The name of the entry |Array
| path | | Entry's path within original object |
This function must return either Blob or string. Any unsupported type will be converted to string by FormData.
- 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.jsfetch-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.