What is form-data-encoder?
The form-data-encoder package is designed to encode FormData objects into a variety of formats suitable for HTTP transmission. It is particularly useful for preparing multipart/form-data payloads without relying on the browser's native FormData implementation, which can be beneficial in non-browser environments like Node.js.
What are form-data-encoder's main functionalities?
Encoding FormData for multipart/form-data
This feature allows you to encode a FormData object into a multipart/form-data format, which is suitable for HTTP requests. The code sample demonstrates how to create a FormData object, append fields and files, and then use the FormDataEncoder to encode the data and retrieve the necessary headers for an HTTP request.
const { FormDataEncoder } = require('form-data-encoder');
const { FormData, File } = require('formdata-node');
const formData = new FormData();
formData.append('field', 'value');
formData.append('file', new File(['content'], 'file.txt'));
const encoder = new FormDataEncoder(formData);
// You can now use encoder to get headers and read the encoded form data
const headers = encoder.headers;
const body = Readable.from(encoder);
Streaming encoded data
This feature is useful for streaming the encoded form data, which can be helpful when dealing with large files or when you want to send the data in chunks over a network. The code sample shows how to iterate over the encoder to handle each chunk of data.
const { FormDataEncoder } = require('form-data-encoder');
const { FormData } = require('formdata-node');
const formData = new FormData();
formData.append('field', 'value');
const encoder = new FormDataEncoder(formData);
// Stream the encoded form data
for await (const chunk of encoder) {
// Handle each chunk of data
}
Other packages similar to form-data-encoder
form-data
The form-data package is a Node.js module that allows you to create readable 'multipart/form-data' streams. It can be used to submit forms and file uploads to other web applications. It is similar to form-data-encoder but also provides the ability to append streams, buffers, and simple values to form data.
busboy
Busboy is a Node.js module for parsing incoming HTML form data. It handles multipart/form-data, which is primarily used for uploading files. While form-data-encoder is focused on encoding and preparing form data for transmission, busboy is designed to parse and handle form data received by a server.
multiparty
Multiparty is a Node.js module for parsing multipart/form-data requests, which are typically used for file uploads. Unlike form-data-encoder, which is for encoding form data, multiparty is used on the server side to process the uploaded data.
form-data-encoder
Encode FormData
content into the multipart/form-data
format

Requirements
- Node.js v18.0.0 or higher;
- Runtime should support
TextEncoder
, TextDecoder
, WeakMap
, WeakSet
and async generator functions;
- For TypeScript users: tsc v4.3 or higher.
Installation
You can install this package using npm:
npm install form-data-encoder
Or yarn:
yarn add form-data-encoder
Or pnpm:
pnpm add form-data-encoder
Usage
- To start the encoding process, you need to create a new Encoder instance with the FormData you want to encode:
import {Readable} from "stream"
import {FormData, File} from "formdata-node"
import {FormDataEncoder} from "form-data-encoder"
import fetch from "node-fetch"
const form = new FormData()
form.set("greeting", "Hello, World!")
form.set("file", new File(["On Soviet Moon landscape see binoculars through YOU"], "file.txt"))
const encoder = new FormDataEncoder(form)
const options = {
method: "post",
headers: encoder.headers,
body: Readable.from(encoder.encode())
}
const response = await fetch("https://httpbin.org/post", options)
console.log(await response.json())
- Encoder support different spec-compatible FormData implementations. Let's try it with
formdata-polyfill
:
import {Readable} from "stream"
import {FormDataEncoder} from "form-data-encoder"
import {FormData} from "formdata-polyfill/esm-min.js"
import {File} from "fetch-blob"
const form = new FormData()
form.set("field", "Some value")
form.set("file", new File(["File content goes here"], "file.txt"))
const encoder = new FormDataEncoder(form)
const options = {
method: "post",
headers: encoder.headers,
body: Readable.from(encoder)
}
await fetch("https://httpbin.org/post", options)
- Because the Encoder is iterable (it has both Symbol.asyncIterator and Symbol.iterator methods), you can use it with different targets. Let's say you want to convert FormData content into
Blob
, for that you can write a function like this:
import {Readable} from "stream"
import {FormDataEncoder} from "form-data-encoder"
import {FormData, File, Blob} from "formdata-node"
import {fileFromPath} from "formdata-node/file-from-path"
import fetch from "node-fetch"
const form = new FormData()
form.set("field", "Just a random string")
form.set("file", new File(["Using files is class amazing"], "file.txt"))
form.set("fileFromPath", await fileFromPath("path/to/a/file.txt"))
const encoder = new FormDataEncoder(form)
const options = {
method: "post",
body: new Blob(encoder, {type: encoder.contentType})
}
const response = await fetch("https://httpbin.org/post", options)
console.log(await response.json())
- Here's FormData to Blob conversion with async-iterator approach:
import {FormData} from "formdata-polyfill/esm-min.js"
import {FormDataEncoder} from "form-data-encoder"
import {blobFrom} from "fetch-blob/from.js"
import Blob from "fetch-blob"
import fetch from "node-fetch"
async function toBlob(form) {
const encoder = new Encoder(form)
const chunks = []
for await (const chunk of encoder) {
chunks.push(chunk)
}
return new Blob(chunks, {type: encoder.contentType})
}
const form = new FormData()
form.set("name", "John Doe")
form.set("avatar", await blobFrom("path/to/an/avatar.png"), "avatar.png")
const options = {
method: "post",
body: await toBlob(form)
}
await fetch("https://httpbin.org/post", options)
- Another way to convert FormData parts to blob using
form-data-encoder
is making a Blob-ish class:
import {Readable} from "stream"
import {FormDataEncoder} from "form-data-encoder"
import {FormData} from "formdata-polyfill/esm-min.js"
import {blobFrom} from "fetch-blob/from.js"
import Blob from "fetch-blob"
import fetch from "node-fetch"
class BlobDataItem {
constructor(encoder) {
this.#encoder = encoder
this.#size = encoder.headers["Content-Length"]
this.#type = encoder.headers["Content-Type"]
}
get type() {
return this.#type
}
get size() {
return this.#size
}
stream() {
return Readable.from(this.#encoder)
}
get [Symbol.toStringTag]() {
return "Blob"
}
}
const form = new FormData()
form.set("name", "John Doe")
form.set("avatar", await blobFrom("path/to/an/avatar.png"), "avatar.png")
const encoder = new FormDataEncoder(form)
const blob = new BlobDataItem(encoder)
const options = {
method: "post",
body: blob
}
await fetch("https://httpbin.org/post", options)
- In this example we will pull FormData content into the ReadableStream:
import {ReadableStream} from "web-streams-polyfill/ponyfill/es2018"
import {FormDataEncoder} from "form-data-encoder"
import {FormData} from "formdata-node"
import fetch from "node-fetch"
function toReadableStream(encoder) {
const iterator = encoder.encode()
return new ReadableStream({
async pull(controller) {
const {value, done} = await iterator.next()
if (done) {
return controller.close()
}
controller.enqueue(value)
}
})
}
const form = new FormData()
form.set("field", "My hovercraft is full of eels")
const encoder = new FormDataEncoder(form)
const options = {
method: "post",
headers: encoder.headers,
body: toReadableStream(encoder)
}
await fetch("https://httpbin.org/post", options)
- Speaking of async iterables - if HTTP client supports them, you can use encoder like this:
import {FormDataEncoder} from "form-data-encoder"
import {FormData} from "formdata-node"
import fetch from "node-fetch"
const form = new FormData()
form.set("field", "My hovercraft is full of eels")
const encoder = new FormDataEncoder(form)
const options = {
method: "post",
headers: encoder.headers,
body: encoder
}
await fetch("https://httpbin.org/post", options)
- ...And for those client whose supporting form-data-encoder out of the box, the usage will be much, much more simpler:
import {FormData} from "formdata-node"
import fetch from "node-fetch"
const form = new FormData()
form.set("field", "My hovercraft is full of eels")
const options = {
method: "post",
body: form
}
await fetch("https://httpbin.org/post", options)
API
class FormDataEncoder
constructor(form[, boundary, options]) -> {FormDataEncoder}
- {FormDataLike} form - FormData object to encode. This object must be a spec-compatible FormData implementation.
- {string} [boundary] - An optional boundary string that will be used by the encoder. If there's no boundary string is present, FormDataEncoder will generate it automatically.
- {object} [options] - FormDataEncoder options.
- {boolean} [options.enableAdditionalHeaders = false] - When enabled, the encoder will emit additional per part headers, such as
Content-Length
. Please note that the web clients do not include these, so when enabled this option might cause an error if multipart/form-data
does not consider additional headers.
Creates a multipart/form-data
encoder.
Instance properties
boundary -> {string}
Returns boundary string.
contentType -> {string}
Returns Content-Type header.
contentLength -> {string}
Return Content-Length header.
Returns headers object with Content-Type and Content-Length header.
Instance methods
values() -> {Generator<Uint8Array | FileLike, void, undefined>}
Creates an iterator allowing to go through form-data parts (with metadata).
This method will not read the files and will not split values big into smaller chunks.
encode() -> {AsyncGenerator<Uint8Array, void, undefined>}
Creates an async iterator allowing to perform the encoding by portions.
This method reads through files and splits big values into smaller pieces (65536 bytes per each).
[Symbol.iterator]() -> {Generator<Uint8Array | FileLike, void, undefined>}
An alias for Encoder#values()
method.
[Symbol.asyncIterator]() -> {AsyncGenerator<Uint8Array, void, undefined>}
An alias for Encoder#encode()
method.
isFile(value) -> {boolean}
Check if a value is File-ish object.
- {unknown} value - a value to test
isFormData(value) -> {boolean}
Check if a value is FormData-ish object.
- {unknown} value - a value to test