https://github.com/apeleghq/ts-multipart-parser

TypeScript streaming parser for MIME multipart messages
https://github.com/apeleghq/ts-multipart-parser

encoder encoder-decoder javascript mime mime-parser multipart parser typescript

Last synced: about 1 month ago
JSON representation

TypeScript streaming parser for MIME multipart messages

• Host: GitHub
• URL: https://github.com/apeleghq/ts-multipart-parser
• Owner: ApelegHQ
• License: isc
• Created: 2023-04-14T22:12:14.000Z (about 2 years ago)
• Default Branch: master
• Last Pushed: 2025-03-24T04:16:17.000Z (3 months ago)
• Last Synced: 2025-05-08T02:51:49.746Z (about 1 month ago)
• Topics: encoder, encoder-decoder, javascript, mime, mime-parser, multipart, parser, typescript
• Language: TypeScript
• Homepage:
• Size: 251 KB
• Stars: 8
• Watchers: 2
• Forks: 1
• Open Issues: 2
• Metadata Files:
  • Readme: README.md
  • License: LICENSE
  • Security: SECURITY

Awesome Lists containing this project

README

        
# Multipart Message Parser

 [![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=Exact-Realty_ts-multipart-parser&metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=Exact-Realty_ts-multipart-parser)

 [![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=Exact-Realty_ts-multipart-parser&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=Exact-Realty_ts-multipart-parser)

 [![Bugs](https://sonarcloud.io/api/project_badges/measure?project=Exact-Realty_ts-multipart-parser&metric=bugs)](https://sonarcloud.io/summary/new_code?id=Exact-Realty_ts-multipart-parser)

 [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=Exact-Realty_ts-multipart-parser&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=Exact-Realty_ts-multipart-parser)

 [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=Exact-Realty_ts-multipart-parser&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=Exact-Realty_ts-multipart-parser)

 ![NPM Downloads](https://img.shields.io/npm/dw/@apeleghq/multipart-parser?style=flat-square)

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](https://www.ietf.org/rfc/rfc2046.html#section-5.1)

  * 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`:

```sh

npm install @apeleghq/multipart-parser

```

```sh

yarn add @apeleghq/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): ReadableStream`

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

```js

import { parseMultipartMessage } from '@apeleghq/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.