formdata-node

Patch Changes

• 32fa6da Thanks @octet-stream! - Remove changeset config from distro

Major Changes

• 324a9a5 Thanks @octet-stream! - Drop node-domexception in favour of Node.js' builtins. Consider polyfilling DOMException if you want to run this package in older environment

• 324a9a5 Thanks @octet-stream! - Bring back CJS support via tsup. You can now import package in both ES and CJS modules

• 324a9a5 Thanks @octet-stream! - Drop web-streams-polyfill in favour of Node.js' builtins. Consider polyfilling ReadableStream if you want to run this package in older environment

• 47a3ff8 Thanks @octet-stream! - Add ReadableStream w/o Symbol.asyncIterator support in Blob

• 0f68880 Thanks @octet-stream! - Add typings tests to make sure FormData, Blob and File compatible with globally available BodyInit type

• 47a3ff8 Thanks @octet-stream! - Drop Node.js 16. Now minimal required version is 18.0.0

Update

• Update package.json for bundler module resolution (#63)

---

All changes: https://github.com/octet-stream/form-data/compare/v5.0.0...v5.0.1

Breaking

• Removed CommonJS support. This package is native ESM from now on;
• Drop Node.js v12 support. Minimal version is 14.17;
• Remove entries argument from FormData constructor.

Update

• Port fixes from fetch-blob for FileFromPath.slice() method;
• Improved types compatibility with addition of File.webkitRelatedPath property (See v4.4.0 release for more info);
• Improve normalization for File values in FormData.{append,set}() methods (See v4.4.0 release for more info);
• Fix instanceof checks for File (See v4.4.0 release for more info);
• Update web-streams-polyfill to 4.0.0-beta.3 (#59).

---

https://github.com/octet-stream/form-data/compare/v4.3.3...v5.0.0

Update

• Bump web-streams-polyfill to 4.0.0-beta.3 (#59)

---

All changes: https://github.com/octet-stream/form-data/compare/v4.4.0...v4.4.1

Update

• Backport File.webkitRelativePath property for better types compatibility with native FormData

• Backport improvements for instanceof checks on File object: It now will recognize File-ish objects and Files as File instance, but not Blob or Blob-ish objects:

  Old behaviour:

  import {Blob, File} from "formdata-node"
  
  const file = new File(["File content"], "file.txt")
  const blob = new Blob()
  
  file instanceof Blob // -> true
  file instanceof File // -> true
  
  blob instanceof Blob // -> true
  blob instanceof File // -> true
  
  const fileLike = {
    [Symbol.toStringTag]: "File",
    name: "file.txt",
    stream() { }
  }
  
  const blobLike = {
    [Symbol.toStringTag]: "Blob",
    stream() { }
  }
  
  fileLike instanceof Blob // -> true
  fileLike instanceof File // -> true
  
  blobLike instanceof Blob // -> true
  blobLike instanceof File // -> true
  

  New behaviour:

  import {Blob, File} from "formdata-node"
  
  const file = new File(["File content"], "file.txt")
  const blob = new Blob()
  
  file instanceof Blob // -> true
  file instanceof File // -> true
  
  blob instanceof Blob // -> true
  blob instanceof File // -> false
  
  const fileLike = {
    [Symbol.toStringTag]: "File",
    name: "file.txt",
    stream() { }
  }
  
  const blobLike = {
    [Symbol.toStringTag]: "Blob",
    stream() { }
  }
  
  fileLike instanceof Blob // -> true
  fileLike instanceof File // -> true
  
  blobLike instanceof Blob // -> true
  blobLike instanceof File // -> false
  

• Backport File values normalization for better alignment with the spec. FormData instances will store Files added via .set() and .append() methods as is.

  Old behaviour:

  import {FormData, File} from "formdata-node"
  
  const file = new File(["File content"], "file.txt")
  const form = new FormData()
  
  form.set("file", file) // will create a new File, then store that new object
  form.get("file") === file // -> false
  
  form.set("file", file, "renamed-file.txt") // will also create a new File (with the new name), then store that new object
  form.get("file") === file // -> false
  

  New behaviour:

  import {FormData, File} from "formdata-node"
  
  const file = new File(["File content"], "file.txt")
  const form = new FormData()
  
  form.set("file", file) // will store this File instance as is
  form.get("file") === file // -> true
  
  form.set("file", file, "renamed-file.txt") // will create a new File (with the new name), then store that new object
  form.get("file") === file // -> false
  

---

All changes: https://github.com/octet-stream/form-data/compare/v4.3.3...v4.4.0

Update

• Remove duplicate row from comparison table (#53)

---

All changes: v4.3.2...v4.3.3

Update

• Fix the way how the package exposes typings for the upcoming TypeScript version. Thanks to @jaydenseric for this fix. More information here: #48;
• Improve documentation for fileFromPath and fileFromPathSync functions.

---

All changes: v4.3.1...v4.3.2

Update

• Fix typings to allow File constructor to take Iterable<unknown> as fileBits argument;
• Improvements for in-code documentation.

---

All changes: https://github.com/octet-stream/form-data/compare/v4.3.0...v4.3.1

Update

• Support custom FormData implementations in instanceof test via Symbol.hasInstance method;
• Expose package.json using exports field (#46);
• Deprecate entries argument in FormData constructor, because it is not spec-compliant.

---

All changes: https://github.com/octet-stream/form-data/compare/v4.2.4...v4.3.0

Update

• Improve type casting for lastModified option in File constructor;
• Add Comparison section to readme.md;

---

All changes: https://github.com/octet-stream/form-data/compare/v4.2.3...v4.2.4

Update

• Minor improvements for Blob.stream() method;
• Documentation improvements;
• Mark package as side effect free.

---

All changes: https://github.com/octet-stream/form-data/compare/v4.2.2...v4.2.3

Update

• Deprecate FileOptions interface in favour of FilePropertyBag;
• Documentation improvements;

---

All changes: https://github.com/octet-stream/form-data/compare/v4.2.1...v4.2.2

Update

• Update typings for FileLike interface and improve documentation.

---

All changes: https://github.com/octet-stream/form-data/compare/v4.2.0...v4.2.1

Update

• Replace entry point in module field in package.json, so it will now point to browser entry point. This should fix the issue with Rollup module resolution. See: #44

---

All changes: https://github.com/octet-stream/form-data/compare/v4.1.0...v4.2.0

Add

• Port Blob from fetch-blob@3 and replace fetch-blob@2 package with our own implementation. Note that formdata-node will switch back to use fetch-blob once we drop CommonJS. Our Blob implementation should be compatible with fetch-blob, so you can use either of them in FormData values. In terms of usage nothing is changed - you can import Blob as from formdata-node package:

import {FormData, Blob} from "formdata-node" // This will now import our own Blob implementation instead of `node-fetch@2`

const form = new FormData()

form.set("file", new Blob(["Some ", "content"]))

• This release also introduces a new dependency: web-streams-polyfill, so the overall installation size will increase by ≈393KB.

---

All changes: https://github.com/octet-stream/form-data/compare/v4.0.1...v4.1.0

Update

• Improvements for File class spec-compliancy: Make sure File.name and File.lastModified properties read-only in runtime;
• Cast name argument in File constructor to string;
• Improve lastModified option normalization in File constructor to mimic browsers implementation behaviour: When lastModified option is NaN it is interpreted as 0 in browsers;
• Improve filename argument normalization for FormData.set() and FormData.append() methods.

---

All changes: https://github.com/octet-stream/form-data/compare/v4.0.0...v4.0.1

Remove

• [BREAKING] Remove builtin multipart/form-data encoder and all related methods. You need check if your HTTP client supports spec-compliant FormData in Node.js and if it don't, then you can suggest them to implement multipart/form-data encoding or use form-data-encoder package;
• [BREAKING] Remove support for Buffer and ReadStream (the one you might create with fs.createReadStream), you can use Blob, fileFromPath and fileFromPathSync to replace them. Other async data sources are still supported - see documentation for more information;
• Remove polyfill entry points;
• Remove unused helpers and reduce overall size of the project.

Update

• [BREAKING] Set minimal required Node.js version to 12.20;
• [BREAKING] Separate fileFromPath functions from main entry point:

- import {fileFromPath, fileFromPathSync} from "formdata-node"
+ import {fileFromPath, fileFromPathSync} from "formdata-node/file-from-path"

This subpath is NOT available in browsers!

• [BREAKING] Expose isFile from file-from-path subpath;

- import {isFileLike} from "formdata-node"
+ import {isFile} from "formdata-node/file-from-path"

• [BREAKING] Rename FormDataFieldValue type to FormDataEntryValue (TypeScript specific);
• Fix message for the error thrown when filename argument passed with non-File value to set() or append();
• Improved documentation.

---

Closes #42 All changes: https://github.com/octet-stream/form-data/compare/v3.7.0...v4.0.0

Update

• Improve browser.ts;
• Return both Content-Type and Content-Length headers from FormData#headers getter;
• Updated deprecation warnings;
• Deprecate options argument in set and append methods;
• Deprecate FormData#boundary property;

---

All changes: https://github.com/octet-stream/form-data/compare/v3.6.4...v3.7.0

Update

• Update form-data-encoder to 1.4.3 version to improve spec compliance;

---

All changes: https://github.com/octet-stream/form-data/compare/v3.6.3...v3.6.4

Update

• Update form-data-encoder to latest version;
• Reduce package size by removing comments for JS output (but keep comments for .d.ts output).

---

All changes: https://github.com/octet-stream/form-data/compare/v3.6.2...v3.6.3

Update

• Fix path in browser field in package.json

---

All changes: https://github.com/octet-stream/form-data/compare/v3.6.1...v3.6.2

Update

• Rewrite browser.js module with TypeScript and introduce CJS and ESM versions of it;
• Update exports field in main package.json to expose compiled versions browser.js.

---

All changes: https://github.com/octet-stream/form-data/compare/v3.6.0...v3.6.1

Add

• [EXPERIMENTAL] Introduce browser field in package.json (see #39 PR by @char0n). Node.js user will not be affected by this change.

Update

• Replace domexpeption with node-domexception which is using DOMException class from Node.js
• Replace internal form-data encoding implementation with form-data-encoder package. Note that the encoding will be removed in v4, so you'll need a client that support spec-compatible FormData or form-data-encoder to handle the encoding.

Remove

• [BREAKING] Remove options.lastModified from fileFromPath and fileFromPathSync since it may have introduce DOMException error to be thrown.
• Remove mime-types package to reduce the size of formdata-node and make fileFromPath and fileFromPathSync behaviour more compatible with File class;

---

All changes: https://github.com/octet-stream/form-data/compare/v3.5.4...v3.6.0

Update

• Various improvements TS typings:
  • Updated blobParts argument in file constructor to expect an array of unknown parts, because fetch-blob can perform automatic conversions if necessary;
  • FileLike interface will expect type field to be presented, because every File and Blob has such field;
• Simplify getFilename helper;
• Update dependencies;

---

All changes: https://github.com/octet-stream/form-data/compare/v3.5.3...v3.5.4

Update

• Fix for FormData#stream initialization (#36)

---

All changes: https://github.com/octet-stream/form-data/compare/v3.5.2...v3.5.3

Add

• Expose isFileLike helper for public usage

Update

• Update fetch-blob to 2.1.2 version since it has a fix for checks with nullish values (null instanceof Blob)
• Improvements for documentation
• Use dynamic error message in File constructor.

---

All changes: https://github.com/octet-stream/form-data/compare/v3.5.1...v3.5.2

Update

• Fix for .append() method behaviour: It should always append entries

---

All changes: https://github.com/octet-stream/form-data/compare/v3.5.0...v3.5.1

This release is mostly about deprecation of an old spec-incompatible features of this package on its way to the next major release.

Update

• Documentation improvements
• Fixes for typings
• Update polyfill.mjs and polyfill.js so they will not affect globalThis when File, Blob or FormData presented.

Deprecate

• Every serialisation method and property: FormData#stream, FormData#headers, FormData#getComputedLength() and FormData#[Symbol.asyncIterator]() will be removed in 4.x version, use formdata-node with HTTP clients that support spec-compatible form-data or use form-data-encoder to perform the serialisation manually

This is how serialisation would look like, when using form-data-encoder:

import {Readable} from "stream"

import fetch from "node-fetch"

import {FormData, fileFromPath} from "formdata-node"
+ import {Encoder} from "form-data-encoder"

const fd = new FormData()

fd.set("name", "John Doe")
fd.set("avatar", await fileFromPath("/path/to/an/avatar.png"))

- const options = {
-   method: "post",
-   headers: fd.headers,
-   body: Readable.from(fd)
- }

+ const encoder = new Encoder(fd)
+
+ const options = {
+   method: "post",
+   headers: encoder.headers // Note that this property has both `Content-Type` and `Content-Length` headers in it, unlike FormData#headers which only has `Content-Type` header
+   body: Readable.from(encoder)
+ }

await fetch("https://httpbin.org/post", options)

You don't have to worry about the form-data serialisation if your HTTP client support spec-compatible form-data, but this may help you otherwise

• Due to compatibility reasons, the Buffer and ReadStream in entry's value will be removed in 4.x version. So they're deprecated too. To append files to the formdata-node instances, use File, Blob, fileFromPath() or fileFromPathSync:

This is how you'll append files from Buffer:

- import {FormData, Blob} from "formdata-node"
+ import {FormData, Blob, fileFromPathSync} from "formdata-node"

const fd = new FormData()

- fd.set("blob", Buffer.from("Some data in buffer"))

+ // Note that you don't have to convert a string into buffer first to use it in Blobs. The source of Buffer may vary depending on the context. This one is here just for an example.
+ const buffer = Buffer.from("Some data in buffer")
+ fd.set("blob", new Blob([buffer], {type: "text/plain"}))

Appending files using fileFromPath:

- import {createReadStream} from "fs"
- import {FormData} from "formdata-node"
+ import {FormData, fileFromPath} from "formdata-node"

const fd = new FormData()

- fd.set("file", createReadStream("/path/to/a/file"))
+ fd.set("file", await fileFromPath("/path/to/a/file")) // Or use `fileFromPathSync` if you need synchronous version

• The third upcoming change is deprecation of CommonJS support in this package. You may still use it (as all deprecated features mentioned above), but CJS version of this package will not be included starting from 4.x.

---

All changes: https://github.com/octet-stream/form-data/compare/v3.4.0...v3.5.0

Update

• Compatibility improvements for File: It should now throw TypeError when called with less than 2 arguments
• Compatibility improvements for form-data encoder: Content-Type will now be set to application/octet-stream if File object does not have the value for type property

Add

• Re-export Blob class from fetch-blob package to allow to use it right from the formdata-node

---

All changes: https://github.com/octet-stream/form-data/compare/v3.3.2...v3.4.0

Update

• Revert Buffer to File conversion changes.
• Update readme.md

---

All changes: https://github.com/octet-stream/form-data/compare/v3.3.1...v3.3.2

Update

• Fix for TypeScript typings in FileLike interface

---

All changes: https://github.com/octet-stream/form-data/compare/v3.3.0...3.3.1

Add

• Introduce fileFromPath an async version of fileFromPathSync: Creates a File referencing the one on a disk by given path.

Update

• FormData#getComputedLength() became synchronous. No need to use await with this method anymore. This change was made because FormData converts ReadStream to a File instance, so this method will use File#size value to get the size instead of using fsPromises.stat on ReadStream#path.

---

All changes: https://github.com/octet-stream/form-data/compare/v3.2.0...v3.3.0

Update

• Fix returning type of the FormData#delete() method (that was probably a regression): now it returns undefined instead of boolean which was the result of the internal Map#delete() call.
• Documentation improvements
• Deprecate FormData#stream property and ReadStream in a field's value. Propose Readable.from(formData) and fileFromPathSync as the new alternatives.
• Overall improvements for form-data encoder and helpers.

---

All changes: https://github.com/octet-stream/form-data/compare/v3.1.1...v3.2.0

Update

• Improvements for form-data encoder.

---

All changes: https://github.com/octet-stream/form-data/compare/v3.1.0...v3.1.1

Update

• Improve options normalisation for File and Blob values.
• Simplify the way FormData stored field's values internally
• Improvements for FormData encoder
• docs: Remove misleading comments about ReadableStream and Readable support.

---

All changes: https://github.com/octet-stream/form-data/compare/v3.0.0...v3.1.0

Breaking

1. Drop Node v10 support. Since its end-of-life is near, I set Node v12 as minimal required version ahead of time.
2. The project has been rewritten from the ground up on TypeScript. So, the overall experience for TypeScript users have to be improved.
3. Default import has been removed, since formdata-node exposes few more classes and helpers: FormData, File and fileFromPathSync. Also, for TypeScript users there are few types available now. In brief:

import FormData from "formdata-node" // < 3.x version

import {FormData, File, fileFromPathSync} from "formdata-node" // >= 3.x version

1. Removed support for ReadableStream and Readable as field's value. Since the browser-side FormData doesn't allow to use streams as values, I also decided to remove them from formdata-node. But you are still able to use ReadStream as value – they will automatically converted to File, there's no more option.size parameter in FormData#{append,set}() too.

Add

• The package will have both CommonJS and ESM entry points. Node.js should pick up the one you need depending on your environment, but feel free to open an issue is something is broken.

Update

• Documentation improvements and fixes

---

All changes: https://github.com/octet-stream/form-data/compare/v2.5.0...v3.0.0

Update

• Fix filename priorities for Blob and File objects (#28)
• Improve TS typings

---

All changes: https://github.com/octet-stream/form-data/compare/v2.4.0...v2.5.0

Update

• Fix returning value of the FormData#get() method for non-existent fields: it now returns null instead of undefined just like the browser implementations do.

---

All changes: https://github.com/octet-stream/form-data/compare/v2.3.0...v2.4.0

Remove

• Removed Babel from the project. All modules as been rewritten as CJS. The @babel/runtime package is no more included.

---

All changes: https://github.com/octet-stream/form-data/compare/v2.2.2...v2.3.0

Update

• Coerce field names to string. (https://github.com/octet-stream/form-data/pull/23)

---

All changes: https://github.com/octet-stream/form-data/compare/v2.2.1...v2.2.2

Update

• Fix for Blob filename retrieving (#20)

---

All changes: https://github.com/octet-stream/form-data/compare/v2.2.0...v2.2.1

Update

• Bump minimal required Node.js version to 10.17
• Improved fields data consumption for FormData#stream
• Fix for FormData#getComputedLength() to match browsers behaviour: now it will return the length of the boundary when FormData has no fields

Remove

• Replace nanoid with crypto.randomBytes in boundary generator

---

All changes: https://github.com/octet-stream/form-data/compare/v2.1.4...v2.2.0

Update

• Fix for nanoid import that causes error in Catsby.js

---

All changes: https://github.com/octet-stream/form-data/compare/v2.1.3...v2.1.4

Update

• Fix builtin modules imports

---

All changes: https://github.com/octet-stream/form-data/compare/v2.1.2...v2.1.3

Update

• Improve TypeScript typings

---

All changes: https://github.com/octet-stream/form-data/compare/v2.1.1...v2.1.2

Update

• Fix default name for a Blob field (https://github.com/octet-stream/form-data/issues/13)

import FormData from "formdata-node"
import Blob from "fetch-blob"

const fd = new FormData()
const blob = new Blob(["Where's your motivation?"], {type: "text/plain"})

fd.set("file", blob)

fd.get("file").name // "blob"

---

All changes: https://github.com/octet-stream/form-data/compare/v2.1.0...v2.1.1

Update

• Improve form-data encoding algorithm to make it more spec-compliant
• Improve documentation

---

All changes: https://github.com/octet-stream/form-data/compare/v2.0.1...v2.1.0

Update

• Fix arguments passing in constructor allowing to set the options arguments for form-data fields given to constructor

import {createReadStream, statSync} from "fs"

import FormData from "formdata-node"

const fd = new FormData([
  {
    name: "file",
    value: createReadStream("/path/to/file"),

    // Here you can set field's options
    options: {
      size: statSync("/path/to/file").size
    }
  }
])

Remove

• @octetstream/invariant is not necessary for this package anymore so I did removed it from dependencies

---

All changes: https://github.com/octet-stream/form-data/compare/v2.0.0...v2.0.1

Remove

• Drop Node.js 8 support. The minimal supported version is now 10.

Add

• FormData#{set,append}() now takes an optional 4th (or 3rd) argument – options:

  type Options = {
    size?: number,
    type?: string,
    lastModified?: number,
    filename?: string
  }
  

  This argument is used to put additional information for stream values. Streams will be considered as a File-ish objects when this option is set. If given value is Buffer, Blob-ish or File-ish object, its own properties will be used to get the size.

Update

• FormData now stores Buffer and Blob-ish objects like a File-ish. So, when you use the FormData#{get,getAll}() methods or iterate through FormData values you will get File-ish object instead of Blob, File, Buffer and streams:

  import fs from "fs"
  
  import FormData from "formdata-node"
  import Blob from "fetch-blob"
  
  const fd = new FormData()
  
  fd.set("buffer", Buffer.from("I beat Twilight Sparkle and all I got was this lousy t-shirt"))
  fd.get("buffer") // -> File
  
  fd.set("blob", new Blob(["I beat Twilight Sparkle and all I got was this lousy t-shirt"], {type: "text/plain"}))
  fd.get("blob") // -> File
  
  // The "size" option required for stream values if you want them to be set as a File
  fd.set("readStream", fs.createReadStream("/path/to/some/file.txt"))
  fd.get("readStream") // -> ReadStream
  
  fd.set("readStream", fs.createReadStream("/path/to/some/file.txt"), {
    size: fs.statSync("/path/to/some/file.txt").size
  })
  
  fd.get("readStream") // -> File
  

• Fix a typo in default content-type value https://github.com/octet-stream/form-data/commit/51e01a7175f5b558f47ea84574728d69c31d6d90;

• Fix for a field content-type header #8 (https://github.com/octet-stream/form-data/commit/dfd5ad1ceaa212067e946ae76e2c8c5c217c0afd);

• Improve error messaging and arguments checking for FormData#{set,append}() methods.

---

All changes: https://github.com/octet-stream/form-data/compare/v1.8.1...v2.0.0

Update:

• Fix a typo for default content type

---

All changes: https://github.com/octet-stream/form-data/compare/v1.8.0...v1.8.1

Add

• Allow to use FormData as a polyfill. Just improve module like so:

  import "formdata-node/polyfill"
  
  console.log(FormData) // => [Function: FormData]
  console.log(global.FormData) // => [Function: FormData]
  console.log(globalThis.FormData) // => [Function: FormData]
  

• Blob, File and ReadableStream -like objects as a field value:

  import FormData from "formdata-node"
  import fetch from "node-fetch"
  import Blob from "fetch-blob" // Or any other compatible Blob implementation
  
  const fd = new FormData()
  const blob = new Blob(["My hovercraft is full of eels"], {type: "text/plain"})
  
  fd.set("someFiled", blob)
  
  fd.get("someField") // => Blob
  
  // Now we send it
  fetch("https://httpbin/post", {
    method: "post",
    body: fd.stream,
    headers: fd.headers
  })
    .then(response => response.json())
    .then(console.log)
  

Update

• Bump dependencies.

---

All changes: https://github.com/octet-stream/form-data/compare/v1.7.0...v1.8.0

Add

• Typings to use for TypeScript and some tests for them
• Node 12 in CI config

Update

• Bump dependencies
• Improve docs

All changes: https://github.com/octet-stream/form-data/compare/63620dbb3b1b6528591b57c08bfb1013a8414c69...202b39a41995fe2e2df6e07a98d53b67be0f5c94