A fast, efficient parser for multipart streams in any JavaScript environment
npm install @mjackson/multipart-parsermultipart-parser is a fast, streaming multipart parser that works in any JavaScript environment, from serverless functions to traditional servers. Whether you're handling file uploads, parsing email attachments, or working with multipart API responses, multipart-parser has you covered.
- Universal JavaScript - One library that works everywhere: Node.js, Bun, Deno, Cloudflare Workers, and browsers
- Blazing Fast - Consistently outperforms popular alternatives like busboy in benchmarks
- Zero Dependencies - Lightweight and secure with no external dependencies
- Memory Efficient - Streaming architecture that yields files as they are found in the stream
- Type Safe - Written in TypeScript with comprehensive type definitions
- Standards Based - Built on the web standard Streams API for maximum compatibility
- Production Ready - Battle-tested error handling with specific error types for common scenarios
- Parse file uploads (multipart/form-data) with automatic field and file detection
- Support for all multipart/* content types (mixed, alternative, related, etc.)
- Convenient MultipartPart API with arrayBuffer, bytes, text, size, and metadata access
- Built-in file size limiting to prevent abuse
- First-class Node.js support with native http.IncomingMessage compatibility
- Examples for every major runtime
Install from npm:
``sh`
npm install @mjackson/multipart-parser
Or install from JSR:
`sh`
deno add @mjackson/multipart-parser
The most common use case for multipart-parser is handling file uploads when you're building a web server. For this case, the parseMultipartRequest function is your friend. It automatically validates the request is multipart/form-data, extracts the multipart boundary from the Content-Type header, parses all fields and files in the request.body stream, and gives each one to you as a MultipartPart object with a rich API for accessing its metadata and content.
`ts
import { MultipartParseError, parseMultipartRequest } from '@mjackson/multipart-parser';
async function handleRequest(request: Request): void {
try {
for await (let part of parseMultipartRequest(request)) {
if (part.isFile) {
// Access file data in multiple formats
let buffer = part.arrayBuffer; // ArrayBuffer
console.log(File received: ${part.filename} (${buffer.byteLength} bytes));Content type: ${part.mediaType}
console.log();Field name: ${part.name}
console.log();
// Save to disk, upload to cloud storage, etc.
await saveFile(part.filename, part.bytes);
} else {
let text = part.text; // string
console.log(Field received: ${part.name} = ${JSON.stringify(text)});`
}
}
} catch (error) {
if (error instanceof MultipartParseError) {
console.error('Failed to parse multipart request:', error.message);
} else {
console.error('An unexpected error occurred:', error);
}
}
}
A common use case when handling file uploads is limiting the size of uploaded files to prevent malicious users from sending very large files that may overload your server's memory and/or storage capacity. You can set a file upload size limit using the maxFileSize option, and return a 413 "Payload Too Large" response when you receive a request that exceeds the limit.
`ts
import {
MultipartParseError,
MaxFileSizeExceededError,
parseMultipartRequest,
} from '@mjackson/multipart-parser/node';
const oneMb = Math.pow(2, 20);
const maxFileSize = 10 * oneMb;
async function handleRequest(request: Request): Promise
try {
for await (let part of parseMultipartRequest(request, { maxFileSize })) {
// ...
}
} catch (error) {
if (error instanceof MaxFileSizeExceededError) {
return new Response('File size limit exceeded', { status: 413 });
} else if (error instanceof MultipartParseError) {
return new Response('Failed to parse multipart request', { status: 400 });
} else {
console.error(error);
return new Response('Internal Server Error', { status: 500 });
}
}
}
`
The main module (import from "@mjackson/multipart-parser") assumes you're working with the fetch API (Request, ReadableStream, etc). Support for these interfaces was added to Node.js by the undici project in version 16.5.0.
If however you're building a server for Node.js that relies on node-specific APIs like http.IncomingMessage, stream.Readable, and buffer.Buffer (ala Express or http.createServer), multipart-parser ships with an additional module that works directly with these APIs.
`ts
import * as http from 'node:http';
import { MultipartParseError, parseMultipartRequest } from '@mjackson/multipart-parser/node';
let server = http.createServer(async (req, res) => {
try {
for await (let part of parseMultipartRequest(req)) {
// ...
}
} catch (error) {
if (error instanceof MultipartParseError) {
console.error('Failed to parse multipart request:', error.message);
} else {
console.error('An unexpected error occurred:', error);
}
}
});
server.listen(8080);
`
If you're working directly with multipart boundaries and buffers/streams of multipart data that are not necessarily part of a request, multipart-parser provides a low-level parseMultipart() API that you can use directly:
`ts
import { parseMultipart } from '@mjackson/multipart-parser';
let message = new Uint8Array(/ ... /);
let boundary = '----WebKitFormBoundary56eac3x';
for (let part of parseMultipart(message, { boundary })) {
// ...
}
`
In addition, the parseMultipartStream function provides an async generator interface for multipart data in a ReadableStream:
`ts
import { parseMultipartStream } from '@mjackson/multipart-parser';
let message = new ReadableStream(/ ... /);
let boundary = '----WebKitFormBoundary56eac3x';
for await (let part of parseMultipartStream(message, { boundary })) {
// ...
}
`
The examples directory contains a few working examples of how you can use this library:
- examples/bun - using multipart-parser in Bun
- examples/cf-workers - using multipart-parser in a Cloudflare Worker and storing file uploads in R2
- examples/deno - using multipart-parser in Deno
- examples/node - using multipart-parser in Node.js
multipart-parser is designed to be as efficient as possible, operating on streams of data and rarely buffering in common usage. This design yields exceptional performance when handling multipart payloads of any size. In benchmarks, multipart-parser is as fast or faster than busboy.
The results of running the benchmarks on my laptop:
`
> @mjackson/multipart-parser@0.6.1 bench:node /Users/michael/Projects/multipart-parser
> node --import tsimp/import ./bench/runner.ts
Platform: Darwin (23.5.0)
CPU: Apple M1 Pro
Date: 8/18/2024, 4:18:39 PM
Node.js v22.1.0
āāāāāāāāāāāāāāāāāāāā¬āāāāāāāāāāāāāāāāāāā¬āāāāāāāāāāāāāāāāāāā¬āāāāāāāāāāāāāāāāāāā¬āāāāāāāāāāāāāāāāāāāā
ā (index) ā 1 small file ā 1 large file ā 100 small files ā 5 large files ā
āāāāāāāāāāāāāāāāāāāā¼āāāāāāāāāāāāāāāāāāā¼āāāāāāāāāāāāāāāāāāā¼āāāāāāāāāāāāāāāāāāā¼āāāāāāāāāāāāāāāāāāāā¤
ā multipart-parser ā '0.01 ms Ā± 0.03' ā '1.06 ms Ā± 0.04' ā '0.10 ms Ā± 0.03' ā '10.60 ms Ā± 0.22' ā
ā multipasta ā '0.01 ms Ā± 0.03' ā '1.06 ms Ā± 0.03' ā '0.15 ms Ā± 0.02' ā '10.70 ms Ā± 2.70' ā
ā busboy ā '0.03 ms Ā± 0.09' ā '3.01 ms Ā± 0.08' ā '0.22 ms Ā± 0.03' ā '29.91 ms Ā± 0.91' ā
ā @fastify/busboy ā '0.03 ms Ā± 0.07' ā '1.20 ms Ā± 0.08' ā '0.39 ms Ā± 0.07' ā '11.86 ms Ā± 0.17' ā
āāāāāāāāāāāāāāāāāāāā“āāāāāāāāāāāāāāāāāāā“āāāāāāāāāāāāāāāāāāā“āāāāāāāāāāāāāāāāāāā“āāāāāāāāāāāāāāāāāāāā
> @mjackson/multipart-parser@0.6.1 bench:bun /Users/michael/Projects/multipart-parser
> bun run ./bench/runner.ts
Platform: Darwin (23.5.0)
CPU: Apple M1 Pro
Date: 8/18/2024, 4:20:58 PM
Bun 1.1.21
āāāāāāāāāāāāāāāāāāāā¬āāāāāāāāāāāāāāāāā¬āāāāāāāāāāāāāāāāā¬āāāāāāāāāāāāāāāāāā¬āāāāāāāāāāāāāāāāāā
ā ā 1 small file ā 1 large file ā 100 small files ā 5 large files ā
āāāāāāāāāāāāāāāāāāāā¼āāāāāāāāāāāāāāāāā¼āāāāāāāāāāāāāāāāā¼āāāāāāāāāāāāāāāāāā¼āāāāāāāāāāāāāāāāāā¤
ā multipart-parser ā 0.01 ms Ā± 0.04 ā 0.91 ms Ā± 0.09 ā 0.11 ms Ā± 0.05 ā 8.23 ms Ā± 0.18 ā
ā multipasta ā 0.01 ms Ā± 0.03 ā 0.87 ms Ā± 0.08 ā 0.22 ms Ā± 0.15 ā 8.09 ms Ā± 0.15 ā
ā busboy ā 0.03 ms Ā± 0.07 ā 3.59 ms Ā± 0.13 ā 0.36 ms Ā± 0.17 ā 35.26 ms Ā± 0.39 ā
ā @fastify/busboy ā 0.04 ms Ā± 0.11 ā 7.23 ms Ā± 0.15 ā 0.63 ms Ā± 0.15 ā 71.86 ms Ā± 0.53 ā
āāāāāāāāāāāāāāāāāāāā“āāāāāāāāāāāāāāāāā“āāāāāāāāāāāāāāāāā“āāāāāāāāāāāāāāāāāā“āāāāāāāāāāāāāāāāāā
> @mjackson/multipart-parser@0.6.1 bench:deno /Users/michael/Projects/multipart-parser
> deno --unstable-byonm --unstable-sloppy-imports run --allow-sys ./bench/runner.ts
Platform: Darwin (23.5.0)
CPU: Apple M1 Pro
Date: 8/18/2024, 4:24:16 PM
Deno 1.45.5
āāāāāāāāāāāāāāāāāāāā¬āāāāāāāāāāāāāāāāāāā¬āāāāāāāāāāāāāāāāāāāā¬āāāāāāāāāāāāāāāāāāā¬āāāāāāāāāāāāāāāāāāāāā
ā (idx) ā 1 small file ā 1 large file ā 100 small files ā 5 large files ā
āāāāāāāāāāāāāāāāāāāā¼āāāāāāāāāāāāāāāāāāā¼āāāāāāāāāāāāāāāāāāāā¼āāāāāāāāāāāāāāāāāāā¼āāāāāāāāāāāāāāāāāāāāā¤
ā multipart-parser ā "0.01 ms Ā± 0.15" ā "1.00 ms Ā± 1.00" ā "0.08 ms Ā± 0.39" ā "10.08 ms Ā± 0.41" ā
ā multipasta ā "0.01 ms Ā± 0.14" ā "1.02 ms Ā± 1.00" ā "0.17 ms Ā± 0.56" ā "14.59 ms Ā± 0.92" ā
ā busboy ā "0.04 ms Ā± 0.28" ā "3.04 ms Ā± 1.00" ā "0.30 ms Ā± 0.71" ā "29.86 ms Ā± 0.83" ā
ā @fastify/busboy ā "0.05 ms Ā± 0.31" ā "12.36 ms Ā± 0.78" ā "0.78 ms Ā± 0.98" ā "123.54 ms Ā± 5.04" ā
āāāāāāāāāāāāāāāāāāāā“āāāāāāāāāāāāāāāāāāā“āāāāāāāāāāāāāāāāāāāā“āāāāāāāāāāāāāāāāāāā“āāāāāāāāāāāāāāāāāāāāā
`
- form-data-parser - Uses multipart-parser internally to parse multipart requests and generate FileUploads for storageheaders
- - Used internally to parse HTTP headers and get metadata (filename, content type) for each MultipartPart`
Thanks to Jacob Ebey who gave me several code reviews on this project prior to publishing.
See LICENSE