Multipart.ts

A library for parsing and creating multipart data in Node.js and browsers, with built-in TypeScript support, zero dependencies, and no need for polyfills.

Documentation

Features

• Parse any kind of multipart/*, e.g. multipart/mixed, multipart/form-data, multipart/byteranges, etc.
• Create multipart messages with arbitrary parts
• Initialise a Multipart instance directly from FormData
• Serialise a Multipart instance into bytes (Uint8Array)
• Compatible with both Node.js and browsers, without requiring polyfills
• Zero dependencies — lightweight and efficient

Getting started

Install via NPM:

npm i multipart-ts

Import as native ESM:

import {Multipart} from "multipart-ts";

This library exclusively uses Uint8Array, which ensures it works seamlessly in both Node.js and browsers.

In Node.js, Buffer can be used interchangeably with Uint8Array in most cases, as it inherits from it.

In the browser, use TextEncoder and TextDecoder to convert between strings and Uint8Array.

Example

node:http

This Node.js example sets up a simple HTTP server that parses multipart messages from POST requests and responds with an example multipart message to GET requests.

import http from "node:http";
import {Component, Multipart} from "multipart-ts";

http.createServer(async (req, res) => {
    // Parse multipart request body
    if (req.method === "POST" && req.headers["content-type"]) {
        // Get the request body
        const body: Uint8Array[] = [];
        for await (const chunk of req)
            body.push(chunk);

        // Create a Blob to hold the Content-Type header (which includes the boundary) and the body
        const blob = new Blob(body, {type: req.headers["content-type"]});
        // Parse multipart from the blob
        const multipart = await Multipart.blob(blob);
        console.log(multipart);

        res.end("Parsed!");
    }
    // Return a multipart response
    else if (req.method === "GET") {
        const multipart = new Multipart(
            [
                new Component({
                    "X-Foo": "Bar Baz",
                    "Content-Type": "text/plain"
                }, Buffer.from("Hello world!")),

                // You can add nested multipart components
                new Multipart([
                    new Component({"Content-Type": "application/json"}, Buffer.from(JSON.stringify({foo: "bar"}))),
                    new Component({}, [0x66, 0x6f, 0x6f, 0x20, 0x62, 0x61, 0x72])
                ])
            ],
            "your-custom-boundary", // or omit to generate a random one
            "multipart/mixed"
        );
        // use the content-type header generated by the multipart
        res.setHeader("Content-Type", multipart.headers.get("Content-Type")!);
        // send the multipart body bytes
        res.end(multipart.body);
    }
    else res.end();
}).listen(3000);

Browser

A minimal example demonstrating the creation, serialisation, and parsing of a simple multipart message. This can also be done the same way in Node.js.

import {Multipart, Component} from "multipart-ts";

// Create
const multipart = new Multipart(
    [new Component({"Content-Type": "text/plain"}, new TextEncoder().encode("Hello world!"))],
    "your-custom-boundary", // or omit to generate a random one
    "multipart/mixed"
);

// Serialise
const data: Uint8Array = multipart.bytes();

// Parse
const parsed: Multipart = Multipart.parse(data);

console.log(new TextDecoder().decode(parsed.parts[0].body)); // Hello world!

Licence

Copyright © 2024–2025 Zefir Kirilov.

This project is licensed under the GNU Lesser General Public License v3.0 (LGPL-3.0). A copy of the licence text is included in the repository.