@xof/formdata

A library to create readable multipart/form-data streams for Node.js. Easily build and submit forms, including file uploads, to web applications.

Features

• 📦 Create multipart/form-data streams
• 📁 Upload files from streams, buffers, or file paths
• 📄 Append text fields and custom headers
• 🌐 Compatible with Node.js HTTP clients
• ⚡ Lightweight with minimal dependencies

Installation

npm install @xof/formdata

or

yarn add @xof/formdata

or

pnpm add @xof/formdata

Basic Usage

const FormData = require("@xof/formdata");
const fs = require("fs");

const form = new FormData();

form.append("username", "john");
form.append("avatar", fs.createReadStream("./avatar.png"));

form.submit("https://example.com/upload", (err, res) => {
  if (err) throw err;

  console.log("Status:", res.statusCode);
});

Append Text

const FormData = require("@xof/formdata");

const form = new FormData();

form.append("name", "XOF");
form.append("email", "[email protected]");

Append Buffer

const FormData = require("@xof/formdata");

const form = new FormData();

const buffer = Buffer.from("Hello World");

form.append("file", buffer, {
  filename: "hello.txt",
  contentType: "text/plain"
});

Append File Stream

const FormData = require("@xof/formdata");
const fs = require("fs");

const form = new FormData();

form.append(
  "document",
  fs.createReadStream("./document.pdf")
);

Custom Headers

const headers = form.getHeaders();

console.log(headers);

Example output:

{
  "content-type": "multipart/form-data; boundary=--------------------------123456789"
}

Get Content Length

form.getLength((err, length) => {
  if (err) throw err;

  console.log(length);
});

HTTP Request Example

const http = require("http");
const fs = require("fs");
const FormData = require("@xof/formdata");

const form = new FormData();

form.append("file", fs.createReadStream("./image.jpg"));

const request = http.request({
  method: "POST",
  host: "example.com",
  path: "/upload",
  headers: form.getHeaders()
});

form.pipe(request);

API

new FormData()

Creates a new FormData instance.

form.append(name, value[, options])

Append a field or file.

| Parameter | Type | Description | |-----------|------|-------------| | name | String | Field name | | value | String | Buffer | Stream | Value to append | | options | Object | Optional metadata |

form.getHeaders()

Returns multipart request headers.

const headers = form.getHeaders();

form.getLength(callback)

Calculates total content length.

form.getLength((err, length) => {});

form.submit(url, callback)

Submits the form directly.

form.submit("https://example.com/upload", callback);

Browser Support

Browser entry:

lib/browser

Requirements

• Node.js >= 6

Dependencies

• asynckit
• combined-stream
• es-set-tostringtag
• hasown
• mime-types

Development

Install dependencies:

npm install

Run tests:

npm test

Run lint:

npm run lint

Generate changelog:

npm version patch

License

MIT © XOF ([email protected])