@octetstream/object-to-form-data

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"

1. 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

1. 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"

1. 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"

1. 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

type NormalizeValue

Value normalizer.

Will 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.

Changelog

3.0.3

Patch Changes

• c150e64 Thanks @octet-stream! - Add example usage with File and Blob