FormData

Spec-compliant FormData implementation for Node.js

Requirements

For this module to work consider polyfilling: ReadableStream, and DOMException (if you use file-from-path utilities)

Highlights

1. Spec-compliant: implements every method of the FormData interface.
2. Supports Blobs and Files sourced from anywhere: you can use builtin fileFromPath and fileFromPathSync helpers to create a File from FS, or you can implement your BlobDataItem object to use a different source of data.
3. Written on TypeScript and ships with TS typings.
4. Isomorphic, but only re-exports native FormData object for browsers. If you need a polyfill for browsers, use formdata-polyfill
5. It's a ponyfill! Which means, no effect has been caused on globalThis or native FormData implementation.

Blob/File support

While formdata-node ships with its own File and Blob implementations, these might eventually be removed in favour of Node.js' Blob (introduced in v14.18) and File (when it will be introduced). In order to help you smoothen that transition period, our own Blob and File, as well as FormData itself, provides support Blob objects created by Node.js' implementation.

Installation

You can install this package with npm:

npm install formdata-node

Or yarn:

yarn add formdata-node

Or pnpm

pnpm add formdata-node

ESM/CJS support

This package is build for and bundled for both ESM and CommonJS, so you can use it in both environments.

Usage

1. Let's take a look at minimal example with got:

1import {FormData} from "formdata-node"
2
3// I assume Got >= 12.x is used for this example
4import got from "got"
5
6const form = new FormData()
7
8form.set("greeting", "Hello, World!")
9
10const data = await got.post("https://httpbin.org/post", {body: form}).json()
11
12console.log(data.form.greeting) // => Hello, World!

2. If your HTTP client does not support spec-compliant FormData, you can use form-data-encoder to encode entries:

1import {Readable} from "stream"
2
3import {FormDataEncoder} from "form-data-encoder"
4import {FormData} from "formdata-node"
5
6// Note that `node-fetch` >= 3.x have builtin support for spec-compliant FormData, sou you'll only need the `form-data-encoder` if you use `node-fetch` <= 2.x.
7import fetch from "node-fetch"
8
9const form = new FormData()
10
11form.set("field", "Some value")
12
13const encoder = new FormDataEncoder(form)
14
15const options = {
16  method: "post",
17  headers: encoder.headers,
18  body: Readable.from(encoder)
19}
20
21await fetch("https://httpbin.org/post", options)

3. Sending files over form-data:

1import {FormData, File} from "formdata-node" // You can use `File` from fetch-blob >= 3.x
2
3import fetch from "node-fetch"
4
5const form = new FormData()
6const file = new File(["My hovercraft is full of eels"], "file.txt")
7
8form.set("file", file)
9
10await fetch("https://httpbin.org/post", {method: "post", body: form})

4. Blobs as field's values allowed too:

1import {FormData, Blob} from "formdata-node" // You can use `Blob` from fetch-blob
2
3const form = new FormData()
4const blob = new Blob(["Some content"], {type: "text/plain"})
5
6form.set("blob", blob)
7
8// Will always be returned as `File`
9let file = form.get("blob")
10
11// The created file has "blob" as the name by default
12console.log(file.name) // -> blob
13
14// To change that, you need to set filename argument manually
15form.set("file", blob, "some-file.txt")
16
17file = form.get("file")
18
19console.log(file.name) // -> some-file.txt

5. You can use 3rd party Blob as FormData value, as vell as for BlobParts in out Blob implementation:

1import {FormData, Blob} from "formdata-node"
2import {Blob as FetchBlob} from "fetch-blob"
3
4const input = new FetchBlob(["a", "b", "c"])
5
6const blob = new Blob([input]) // Accepts 3rd party blobs as BlobParts
7
8await blob.text() // -> abc
9
10const form = new FormData()
11
12form.set("file", input)
13
14const file = form.get("file") // -> File
15
16await file.text() // -> abc

6. You can also use Node.js' Blob implementation in these scenarios:

1import {Blob as NodeBlob} from "node:buffer"
2
3import {FormData, Blob} from "formdata-node"
4
5const input = new NodeBlob(["a", "b", "c"])
6
7const blob = new Blob([input]) // Accepts Node.js' Blob implementation as BlobParts
8
9await blob.text() // -> abc
10
11const form = new FormData()
12
13form.set("file", input)
14
15const file = form.get("file") // -> File
16
17await file.text() // -> abc

7. You can also append files using fileFromPath or fileFromPathSync helpers. It does the same thing as fetch-blob/from, but returns a File instead of Blob:

1import {fileFromPath} from "formdata-node/file-from-path"
2import {FormData} from "formdata-node"
3
4import fetch from "node-fetch"
5
6const form = new FormData()
7
8form.set("file", await fileFromPath("/path/to/a/file"))
9
10await fetch("https://httpbin.org/post", {method: "post", body: form})

8. You can still use files sourced from any stream, but unlike in v2 you'll need some extra work to achieve that:

1import {Readable} from "stream"
2
3import {FormData} from "formdata-node"
4
5class BlobFromStream {
6  #stream
7
8  constructor(stream, size) {
9    this.#stream = stream
10    this.size = size
11  }
12
13  stream() {
14    return this.#stream
15  }
16
17  get [Symbol.toStringTag]() {
18    return "Blob"
19  }
20}
21
22const content = Buffer.from("Stream content")
23
24const stream = new Readable({
25  read() {
26    this.push(content)
27    this.push(null)
28  }
29})
30
31const form = new FormData()
32
33form.set("stream", new BlobFromStream(stream, content.length), "file.txt")
34
35await fetch("https://httpbin.org/post", {method: "post", body: form})

9. Note that if you don't know the length of that stream, you'll also need to handle form-data encoding manually or use form-data-encoder package. This is necessary to control which headers will be sent with your HTTP request:

1import {Readable} from "stream"
2
3import {Encoder} from "form-data-encoder"
4import {FormData} from "formdata-node"
5
6const form = new FormData()
7
8// You can use file-shaped or blob-shaped objects as FormData value instead of creating separate class
9form.set("stream", {
10  type: "text/plain",
11  name: "file.txt",
12  [Symbol.toStringTag]: "File",
13  stream() {
14    return getStreamFromSomewhere()
15  }
16})
17
18const encoder = new Encoder(form)
19
20const options = {
21  method: "post",
22  headers: {
23    "content-type": encoder.contentType
24  },
25  body: Readable.from(encoder)
26}
27
28await fetch("https://httpbin.org/post", {method: "post", body: form})

Comparison

	formdata-node	formdata-polyfill	undici FormData	form-data
.append()	✔️	✔️	✔️	✔️1
.set()	✔️	✔️	✔️	❌
.get()	✔️	✔️	✔️	❌
.getAll()	✔️	✔️	✔️	❌
.forEach()	✔️	✔️	✔️	❌
.keys()	✔️	✔️	✔️	❌
.values()	✔️	✔️	✔️	❌
.entries()	✔️	✔️	✔️	❌
Symbol.iterator	✔️	✔️	✔️	❌
ESM	✔️	✔️	✔️2	✔️2
Blob	✔️3	✔️4	✔️3	❌
Browser polyfill	❌	✔️	✔️	❌
Builtin encoder	❌	✔️	✔️5	✔️

¹ Does not support Blob and File in entry value, but allows streams and Buffer (which is not spec-compliant, however).

² Can be imported in ESM, because Node.js support for CJS modules in ESM context, but it does not have ESM entry point.

³ Have builtin implementations of Blob and/or File, allows native Blob and File as entry value.

⁴ Support Blob and File via fetch-blob package, allows native Blob and File as entry value.

⁵ Have multipart/form-data encoder as part of their fetch implementation.

✔️ - For FormData methods, indicates that the method is present and spec-compliant. For features, shows its presence.

❌ - Indicates that method or feature is not implemented.

API

class FormData

constructor() -> {FormData}

Creates a new FormData instance.

Instance methods

set(name, value[, filename]) -> {void}

Set a new value for an existing key inside FormData, or add the new field if it does not already exist.

• {string} name – The name of the field whose data is contained in value.
• {unknown} value – The field's value. This can be Blob or File. If none of these are specified the value is converted to a string.
• {string} [filename = undefined] – The filename reported to the server, when a Blob or File is passed as the second parameter. The default filename for Blob objects is "blob". The default filename for File objects is the file's filename.

append(name, value[, filename]) -> {void}

Appends a new value onto an existing key inside a FormData object, or adds the key if it does not already exist.

The difference between set() and append() is that if the specified key already exists, set() will overwrite all existing values with the new one, whereas append() will append the new value onto the end of the existing set of values.

• {string} name – The name of the field whose data is contained in value.
• {unknown} value – The field's value. This can be Blob or File. If none of these are specified the value is converted to a string.
• {string} [filename = undefined] – The filename reported to the server, when a Blob or File is passed as the second parameter. The default filename for Blob objects is "blob". The default filename for File objects is the file's filename.

get(name) -> {FormDataValue}

Returns the first value associated with a given key from within a FormData object. If you expect multiple values and want all of them, use the getAll() method instead.

• {string} name – A name of the value you want to retrieve.

getAll(name) -> {Array<FormDataValue>}

Returns all the values associated with a given key from within a FormData object.

• {string} name – A name of the value you want to retrieve.

has(name) -> {boolean}

Returns a boolean stating whether a FormData object contains a certain key.

• {string} – A string representing the name of the key you want to test for.

delete(name) -> {void}

Deletes a key and its value(s) from a FormData object.

• {string} name – The name of the key you want to delete.

forEach(callback[, thisArg]) -> {void}

Executes a given callback for each field of the FormData instance

• {function} callback – Function to execute for each element, taking three arguments:
  • {FormDataValue} value – A value(s) of the current field.
  • {string} name – Name of the current field.
  • {FormData} form – The FormData instance that forEach is being applied to
• {unknown} [thisArg = null] – Value to use as this context when executing the given callback

keys() -> {Generator<string>}

Returns an iterator allowing to go through all keys contained in this FormData object. Each key is a string.

values() -> {Generator<FormDataValue>}

Returns an iterator allowing to go through all values contained in this object FormData object. Each value is a FormDataValue.

entries() -> {Generator<[string, FormDataValue]>}

Returns an iterator allowing to go through key/value pairs contained in this FormData object. The key of each pair is a string; the value is a FormDataValue.

[Symbol.iterator]() -> {Generator<[string, FormDataValue]>}

An alias for FormData#entries()

class Blob

The Blob object represents a blob, which is a file-like object of immutable, raw data; they can be read as text or binary data, or converted into a ReadableStream so its methods can be used for processing the data.

constructor(blobParts[, options]) -> {Blob}

Creates a new Blob instance. The Blob constructor accepts following arguments:

• {(ArrayBufferLike | ArrayBufferView | File | Blob | string)[]} blobParts – An Array strings, or ArrayBuffer, ArrayBufferView, Blob objects, or a mix of any of such objects, that will be put inside the Blob;
• {object} [options = {}] - An options object containing optional attributes for the file. Available options are as follows;
• {string} [options.type = ""] - Returns the media type (MIME) of the blob represented by a Blob object.

Instance properties

type -> {string}

Returns the MIME type of the Blob or File.

size -> {number}

Returns the size of the Blob or File in bytes.

Instance methods

slice([start, end, contentType]) -> {Blob}

Creates and returns a new Blob object which contains data from a subset of the blob on which it's called.

• {number} [start = 0] An index into the Blob indicating the first byte to include in the new Blob. If you specify a negative value, it's treated as an offset from the end of the Blob toward the beginning. For example, -10 would be the 10th from last byte in the Blob. The default value is 0. If you specify a value for start that is larger than the size of the source Blob, the returned Blob has size 0 and contains no data.

• {number} [end = blob.size] An index into the Blob indicating the first byte that will not be included in the new Blob (i.e. the byte exactly at this index is not included). If you specify a negative value, it's treated as an offset from the end of the Blob toward the beginning. For example, -10 would be the 10th from last byte in the Blob. The default value is size.

• {string} [contentType = ""] The content type to assign to the new Blob; this will be the value of its type property. The default value is an empty string.

stream() -> {ReadableStream<Uint8Array>}

Returns a ReadableStream which upon reading returns the data contained within the Blob.

arrayBuffer() -> {Promise<ArrayBuffer>}

Returns a Promise that resolves with the contents of the blob as binary data contained in an ArrayBuffer.

text() -> {Promise<string>}

Returns a Promise that resolves with a string containing the contents of the blob, interpreted as UTF-8.

class File extends Blob

The File class provides information about files. The File class inherits Blob.

constructor(fileBits, filename[, options]) -> {File}

Creates a new File instance. The File constructor accepts following arguments:

• {(ArrayBufferLike | ArrayBufferView | File | Blob | string)[]} fileBits – An Array strings, or ArrayBuffer, ArrayBufferView, Blob objects, or a mix of any of such objects, that will be put inside the File;
• {string} filename – Representing the file name.
• {object} [options = {}] - An options object containing optional attributes for the file. Available options are as follows;
• {number} [options.lastModified = Date.now()] – provides the last modified date of the file as the number of milliseconds since the Unix epoch (January 1, 1970 at midnight). Files without a known last modified date return the current date;
• {string} [options.type = ""] - Returns the media type (MIME) of the file represented by a File object.

fileFromPath(path[, filename, options]) -> {Promise<File>}

Available from formdata-node/file-from-path subpath.

Creates a File referencing the one on a disk by given path.

• {string} path - Path to a file
• {string} [filename] - Optional name of the file. Will be passed as the second argument in File constructor. If not presented, the name will be taken from the file's path.
• {object} [options = {}] - Additional File options, except for lastModified.
• {string} [options.type = ""] - Returns the media type (MIME) of the file represented by a File object.

fileFromPathSync(path[, filename, options]) -> {File}

Available from formdata-node/file-from-path subpath.

Creates a File referencing the one on a disk by given path. Synchronous version of the fileFromPath.

• {string} path - Path to a file
• {string} [filename] - Optional name of the file. Will be passed as the second argument in File constructor. If not presented, the name will be taken from the file's path.
• {object} [options = {}] - Additional File options, except for lastModified.
• {string} [options.type = ""] - Returns the media type (MIME) of the file represented by a File object.

isFile(value) -> {boolean}

Available from formdata-node/file-from-path subpath.

Checks if given value is a File, Blob or file-look-a-like object.

• {unknown} value - A value to test

Related links

• FormData documentation on MDN
• File documentation on MDN
• Blob documentation on MDN
• FormDataValue documentation on MDN.
• 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 on 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.
• @octetstream/object-to-form-data converts JavaScript object to FormData.