form-data-encoder

Encode FormData content into the multipart/form-data format

Usage

1. To start the encoding process, you need to create a new Encoder instance with the FormData you want to encode:

1import {Readable} from "stream"
2
3import {FormData, File} from "formdata-node"
4import {Encoder} from "form-data-encoder"
5
6import fetch from "node-fetch"
7
8const fd = new FormData()
9
10fd.set("greeting", "Hello, World!")
11fd.set("file", new File(["On Soviet Moon landscape see binoculars through YOU"], "file.txt"))
12
13const encoder = new Encoder(fd)
14
15const options = {
16  method: "post",
17
18  // Set request headers provided by the Encoder.
19  // The `headers` property has `Content-Type` and `Content-Length` headers.
20  headers: encoder.headers,
21
22  // Create a Readable stream from the Encoder.
23  // You can omit usage of `Readable.from` for HTTP clients whose support async iterables.
24  // The Encoder will yield FormData content portions encoded into the multipart/form-data format as node-fetch consumes the stream.
25  body: Readable.from(encoder.encode()) // or Readable.from(encoder)
26}
27
28const response = await fetch("https://httpbin.org/post", options)
29
30console.log(await response.json())

2. Encoder support different spec-compatible FormData implementations. Let's try it with formdata-polyfill:

1import {Readable} from "stream"
2
3import {Encoder} from "form-data-encoder"
4import {FormData, File} from "formdata-polyfill/esm-min.js"
5
6const fd = new FormData()
7
8fd.set("field", "Some value")
9fd.set("file", new File(["File content goes here"], "file.txt"))
10
11const encoder = new Encoder(fd)
12
13const options = {
14  method: "post",
15  headers: encoder.headers,
16  body: Readable.from(encoder)
17}
18
19await fetch("https://httpbin.org/post", options)

3. 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:

1import {Readable} from "stream"
2
3import {Encoder} from "form-data-encoder"
4
5import {FormData, File, Blob, fileFromPath} from "formdata-node"
6
7import fetch from "node-fetch"
8
9const fd = new FormData()
10
11fd.set("field", "Just a random string")
12fd.set("file", new File(["Using files is class amazing"], "file.txt"))
13fd.set("fileFromPath", await fileFromPath("path/to/a/file.txt"))
14
15const encoder = new Encoder(fd)
16
17const options = {
18  method: "post",
19
20  // To use this approach with fetch-blob@2 you probably gonna need to convert the encoder parts output to an array first:
21  // new Blob([...encoder], {type: encoder.connectType})
22  body: new Blob(encoder, {type: encoder.contentType})
23}
24
25const response = await fetch("https://httpbin.org/post", options)
26
27console.log(await response.json())

4. Here's FormData to Blob conversion with async-iterator approach:

1import {FormData} from "formdata-polyfill/esm-min.js"
2import {blobFrom} from "fetch-blob/from.js"
3import {Encoder} from "form-data-encoder"
4
5import Blob from "fetch-blob"
6import fetch from "node-fetch"
7
8async function toBlob(form) {
9  const encoder = new Encoder(form)
10  const chunks = []
11
12  for await (const chunk of encoder) {
13    chunks.push(chunk)
14  }
15
16  return new Blob(chunks, {type: encoder.contentType})
17}
18
19const fd = new FormData()
20
21fd.set("name", "John Doe")
22fd.set("avatar", await blobFrom("path/to/an/avatar.png"), "avatar.png")
23
24const options = {
25  method: "post",
26  body: await toBlob(fd)
27}
28
29await fetch("https://httpbin.org/post", options)

5. Another way to convert FormData parts to blob using form-data-encoder is making a Blob-ish class:

1import {Readable} from "stream"
2
3import {FormData} from "formdata-polyfill/esm-min.js"
4import {blobFrom} from "fetch-blob/from.js"
5import {Encoder} from "form-data-encoder"
6
7import Blob from "fetch-blob"
8import fetch from "node-fetch"
9
10class BlobDataItem {
11  constructor(encoder) {
12    this.#encoder = encoder
13    this.#size = encoder.headers["Content-Length"]
14    this.#type = encoder.headers["Content-Type"]
15  }
16
17  get type() {
18    return this.#type
19  }
20
21  get size() {
22    return this.#size
23  }
24
25  stream() {
26    return Readable.from(this.#encoder)
27  }
28
29  get [Symbol.toStringTag]() {
30    return "Blob"
31  }
32}
33
34const fd = new FormData()
35
36fd.set("name", "John Doe")
37fd.set("avatar", await blobFrom("path/to/an/avatar.png"), "avatar.png")
38
39const encoder = new Encoder(fd)
40
41// Note that node-fetch@2 performs more strictness tests for Blob objects, so you may need to do extra steps before you set up request body (like, maybe you'll need to instaniate a Blob with BlobDataItem as one of its blobPart)
42const blob = new BlobDataItem(enocoder) // or new Blob([new BlobDataItem(enocoder)], {type: encoder.contentType})
43
44const options = {
45  method: "post",
46  body: blob
47}
48
49await fetch("https://httpbin.org/post", options)

6. In this example we will pull FormData content into the ReadableStream:

1 // This module is only necessary when you targeting Node.js or need web streams that implement Symbol.asyncIterator
2import {ReadableStream} from "web-streams-polyfill/ponyfill/es2018"
3
4import {Encoder} from "form-data-encoder"
5import {FormData} from "formdata-node"
6
7import fetch from "node-fetch"
8
9const toReadableStream = iterator => new ReadableStream({
10  async pull(controller) {
11    const {value, done} = await iterator.next()
12
13    if (done) {
14      return controller.close()
15    }
16
17    controller.enqueue(value)
18  }
19})
20
21const fd = new FormData()
22
23fd.set("field", "My hovercraft is full of eels")
24
25const encoder = new Encoder(fd)
26
27const options = {
28  method: "post",
29  headers: encoder.headers,
30  body: toReadableStream(encoder.encode())
31}
32
33// Note that this example requires `fetch` to support Symbol.asyncIterator, which node-fetch lacks of (but will support eventually)
34await fetch("https://httpbin.org/post", options)

7. Speaking of async iterables - if HTTP client supports them, you can use encoder like this:

1import {Encoder} from "form-data-encoder"
2import {FormData} from "formdata-node"
3
4import fetch from "node-fetch"
5
6const fd = new FormData()
7
8fd.set("field", "My hovercraft is full of eels")
9
10const encoder = new Encoder(fd)
11
12const options = {
13  method: "post",
14  headers: encoder.headers,
15  body: encoder
16}
17
18await fetch("https://httpbin.org/post", options)

8. ...And for those client whose supporting form-data-encoder out of the box, the usage will be much, much more simpler:

1import {FormData} from "formdata-node" // Or any other spec-compatible implementation
2
3import fetch from "node-fetch"
4
5const fd = new FormData()
6
7fd.set("field", "My hovercraft is full of eels")
8
9const options = {
10  method: "post",
11  body: fd
12}
13
14// Note that node-fetch does NOT support form-data-encoder
15await fetch("https://httpbin.org/post", options)

Installation

You can install this package using npm:

1npm install form-data-encoder

Or yarn:

1yarn add form-data-encoder

Or pnpm:

1pnpm add form-data-encoder

API

class Encoder

constructor(form[, boundary]) -> {Encoder}

• {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, Encoder will generate it automatically.

Creates a multipart/form-data encoder.

Instance properties

boundary -> {string}

Returns boundary string

contentType -> {string}

Returns Content-Type header for multipart/form-data

headers -> {object}

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.

encode() -> {AsyncGenerator<Uint8Array, void, undefined>}

Creates an async iterator allowing to perform the encoding by portions. This method will also read files.

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

isFileLike(value) -> {boolean}

Check if a value is File-ish object.

• {unknown} value - a value to test

isFormDataLike(value) -> {boolean}

Check if a value is FormData-ish object.

• {unknown} value - a value to test