@exact-realty/multipart-parser

Multipart Message Parser

This is a library for parsing MIME multipart messages, such as those used in HTTP requests and email messages, written in TypeScript. It provides an easy-to-use async generator that returns the parsed headers and body of each part in a multipart message. Nested multipart messages are supported.

Features

• Parses multipart messages according to the specification
• Supports nested multipart messages
• Lightweight and fast
• Written in TypeScript, but can be used with plain JavaScript as well
• Well-tested

🚀 Installation

You can install the library using either npm or yarn:

npm install @exact-realty/multipart-parser

yarn add @exact-realty/multipart-parser

🎬 Usage

The library exports the function parseMultipartMessage, which returns an async generator that yields objects with the headers and body (as a Uint8Array) of each part in the multipart message.

📚 API

parseMultipartMessage(stream: ReadableStream, boundary: string): AsyncGenerator

This function takes a ReadableStream and a boundary string as arguments, and returns an asynchronous generator that yields objects with the following properties:

• headers: a Headers object containing the headers of the current part
• body: a Uint8Array containing the body of the current part, or null if the part is empty.
• parts: a nested iterator of the same structure for any parts within the current part, if the part's Content-Type header indicates that it is a multipart message.

boundaryRegex: RegExp

A regular expression that can be used to validate a boundary string.

boundaryMatchRegex: RegExp

A regular expression that can be used to extract a boundary string from a Content-Type header.

encodeMultipartMessage(boundary: string, msg: AsyncIterable<TDecodedMultipartMessage>): ReadableStream<ArrayBuffer>

This function takes a boundary string and an array of messages as arguments and returns a ReadableStream that can be read to obtain a multipart message.

TDecodedMultipartMessage is defined as an object with the following fields:

• headers: a Headers object containing the headers of the current part
• body (optional): The body of the current part, or null if the part is empty. It can be any of the following types: ArrayBuffer, Blob, ReadableStream or any typed array, such as Uint8Array.
• parts (optional): An async or sync iterable of one element or more of the same type (TDecodedMultipartMessage), for nested messages. If both body and parts are specified, body takes precedence.

Example

import { parseMultipartMessage } from '@exact-realty/multipart-message-parser';

const decoder = new TextDecoder();

const stream = ... // a ReadableStream containing the multipart message
const boundary = 'my-boundary'; // the boundary of the multipart message

for await (const part of parseMultipartMessage(stream, boundary)) {
  console.log(part.headers.get('content-type'));
  console.log(decoder.decode(part.body));
}

🤝 Contributing

We welcome contributions to this project! Feel free to submit a pull request or open an issue if you find a bug or have a feature request.

📄 License

This library is licensed under the ISC License, see LICENSE for more information.