multipasta

library0.2.7jsnpmunverified

multipasta is a cross-platform parser specifically designed for `multipart/form-data` payloads, commonly used for file uploads in web applications. It provides a stream-based API for handling incoming data, making it suitable for both Node.js environments (where it leverages Node's `Buffer` capabilities efficiently) and browser-like runtimes. The current stable version is 0.2.7, with frequent patch releases addressing bug fixes and minor improvements, as seen in recent changelogs. Minor version bumps (e.g., v0.2.0) introduce new features or behavior changes. Key differentiators include its cross-platform compatibility, TypeScript type definitions, and focus on efficient, stream-based parsing of multipart bodies.

http-networking web-framework

npm install multipasta

github ↗package ↗

INSTALL

IMPORT

SIG · MULTIPASTA

multipasta

http-networkingjavascriptv0.2.7

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

MultipartParser

✓ import { MultipartParser } from 'multipasta';

✗ const { MultipartParser } = require('multipasta');

Primarily designed for ESM. CommonJS `require` might work in some Node.js setups but ESM is recommended for full compatibility and type inference.

FileStream

✓ import { FileStream } from 'multipasta';

✗ import FileStream from 'multipasta';

FileStream is a named export, not a default export.

MultipartParserOptions

✓ import type { MultipartParserOptions } from 'multipasta';

✗ import { MultipartParserOptions } from 'multipasta';

When importing types in TypeScript, use `import type` for clarity and to ensure it's removed during transpilation if not needed at runtime.

Demonstrates parsing a multipart/form-data request body from a Node.js Readable stream, extracting both text fields and file content.

import { MultipartParser } from 'multipasta'; import { Readable } from 'stream'; const boundary = '----WebKitFormBoundary7MA4YWxkTrZu0gW'; const multipartBody = `--${boundary}\r\n` + 'Content-Disposition: form-data; name="text_field"\r\n\r\n' + 'Some text value\r\n' + `--${boundary}\r\n` + 'Content-Disposition: form-data; name="file_field"; filename="hello.txt"\r\n' + 'Content-Type: text/plain\r\n\r\n' + 'Hello, world!\nThis is a test file.\r\n' + `--${boundary}--\r\n`; const parser = new MultipartParser({ boundary: Buffer.from(boundary), }); const readableStream = Readable.from(multipartBody); readableStream.on('data', (chunk) => { parser.write(chunk); }); parser.on('field', (field) => { console.log(`Field: ${field.name.toString()} = ${field.value.toString()}`); }); parser.on('file', (file) => { console.log(`File received: Name=${file.name.toString()}, Filename=${file.filename?.toString() ?? 'N/A'}, Content-Type=${file.contentType?.toString() ?? 'N/A'}`); let fileContent = Buffer.alloc(0); file.on('data', (chunk) => { fileContent = Buffer.concat([fileContent, chunk]); }); file.on('end', () => { console.log(`File content for ${file.filename?.toString()}:\n${fileContent.toString()}`); }); }); parser.on('end', () => { console.log('Multipart parsing complete.'); }); readableStream.on('end', () => { parser.end(); }); readableStream.on('error', (err) => { console.error('Stream error:', err); }); parser.on('error', (err) => { console.error('Parser error:', err); });

Debug

Known issues

gotchaAs of v0.2.7, multipasta will no longer emit parts (fields or files) when an error occurs during parsing. This changes previous behavior where partial data might have been emitted before an error halted processing.

fix

Ensure robust error handling in your application logic. Any processing of emitted parts should consider that `error` events might occur after `field` or `file` events, and that subsequent parts will not be emitted.

affects: >=0.2.7

gotchaIn v0.2.6, error propagation within the Node.js parser was improved to correctly relay errors to file streams. This ensures that issues encountered while parsing file data are surfaced appropriately through the associated `FileStream` instance.

fix

Applications handling file uploads should attach error listeners to `file` objects (the `FileStream` instances) in addition to the main `MultipartParser` instance to catch stream-specific errors.

affects: >=0.2.6

gotchaVersion 0.2.0 introduced changes to handle duplicate header values more robustly. While not a breaking API change, this might alter how applications that rely on specific behavior for duplicate headers (e.g., only the first or last value being kept) process their data.

fix

Review how your application expects duplicate headers to be processed. Implement explicit logic to handle arrays of header values if needed, or ensure your `Content-Type` headers are unambiguous.

affects: >=0.2.0

Errors

Common errors & fixes

Error: Multipart boundary not found in Content-Type header.

The `Content-Type` header provided to the parser (or implicitly from the request) does not contain a `boundary` directive, or the boundary string passed to the parser options is incorrect.

fix

Ensure the `Content-Type` header (e.g., `multipart/form-data; boundary=xxxx`) is correctly extracted and the `boundary` option for `MultipartParser` is set to the correct `Buffer` representation of the boundary string.

TypeError: Cannot read properties of undefined (reading 'on')

This typically occurs when trying to attach an event listener to a `file` or `field` object that is `undefined` or not correctly returned/handled. It might happen if `file` or `field` events are not correctly wired up or if data is processed outside the event loop.

fix

Verify that `parser.on('file', (file) => { /* ... */ })` and `parser.on('field', (field) => { /* ... */ })` are correctly defined before data starts flowing into the parser, and that `file` and `field` objects are accessed within their respective event handlers.

Upgrade

Version history

0.2.7latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/tim-smart/multipasta ↗

packagehttps://www.npmjs.com/package/multipasta ↗