@maroonedsoftware/multipart 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Marooned Software
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,247 @@
+# @maroonedsoftware/multipart
+
+A robust multipart form-data and multipart/related parser for Node.js HTTP servers. Built on top of [@fastify/busboy](https://github.com/fastify/busboy) with a promise-based API and sensible defaults.
+
+## Installation
+
+```bash
+pnpm add @maroonedsoftware/multipart
+```
+
+## Features
+
+- **Promise-based API** – Clean async/await interface for parsing multipart requests
+- **Configurable limits** – Protect against resource exhaustion with file size, count, and field limits
+- **Stream-based file handling** – Process files efficiently without loading entire files into memory
+- **Type-safe** – Full TypeScript support with comprehensive type definitions
+- **Automatic cleanup** – Properly removes event listeners to prevent memory leaks
+
+## Quick Start
+
+```typescript
+import { createServer, IncomingMessage, ServerResponse } from 'node:http';
+import { createWriteStream } from 'node:fs';
+import { pipeline } from 'node:stream/promises';
+import { MultipartBody, isMultipartFieldData } from '@maroonedsoftware/multipart';
+
+const server = createServer(async (req: IncomingMessage, res: ServerResponse) => {
+  if (req.method === 'POST' && req.headers['content-type']?.includes('multipart/form-data')) {
+    const multipart = new MultipartBody(req);
+
+    const fields = await multipart.parse(async (fieldname, stream, filename) => {
+      // Save uploaded file to disk
+      await pipeline(stream, createWriteStream(`./uploads/${filename}`));
+    });
+
+    // Access form fields
+    const description = fields.get('description');
+    if (description && isMultipartFieldData(description)) {
+      console.log('Description:', description.value);
+    }
+
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ success: true }));
+  }
+});
+
+server.listen(3000);
+```
+
+## API Reference
+
+### `MultipartBody`
+
+The main class for parsing multipart/form-data requests.
+
+#### Constructor
+
+```typescript
+new MultipartBody(req: IncomingMessage, limits?: MultipartLimits)
+```
+
+| Parameter | Type              | Description                         |
+| --------- | ----------------- | ----------------------------------- |
+| `req`     | `IncomingMessage` | The incoming HTTP request           |
+| `limits`  | `MultipartLimits` | Optional default limits for parsing |
+
+**Default limits:**
+
+- `files`: 1
+- `fileSize`: 20 MB
+
+#### `parse(fileHandler, limits?)`
+
+Parses the multipart request body.
+
+```typescript
+parse(
+  fileHandler: FileHandler,
+  limits?: MultipartLimits
+): Promise<Map<string, MultipartData | MultipartData[]>>
+```
+
+| Parameter     | Type              | Description                           |
+| ------------- | ----------------- | ------------------------------------- |
+| `fileHandler` | `FileHandler`     | Callback invoked for each file upload |
+| `limits`      | `MultipartLimits` | Optional per-request limit overrides  |
+
+**Returns:** A `Map` where keys are field names and values are either a single `MultipartData` object or an array if multiple values were submitted.
+
+### `FileHandler`
+
+Callback type for handling file uploads:
+
+```typescript
+type FileHandler = (fieldname: string, stream: Readable, filename: string, encoding: string, mimeType: string) => Promise<void>;
+```
+
+### `MultipartLimits`
+
+Configuration options for limiting request sizes:
+
+| Option          | Type     | Default  | Description                      |
+| --------------- | -------- | -------- | -------------------------------- |
+| `fieldNameSize` | `number` | 100      | Max field name size in bytes     |
+| `fieldSize`     | `number` | 1 MB     | Max field value size in bytes    |
+| `fields`        | `number` | Infinity | Max number of non-file fields    |
+| `fileSize`      | `number` | Infinity | Max file size in bytes           |
+| `files`         | `number` | Infinity | Max number of file fields        |
+| `parts`         | `number` | Infinity | Max total parts (fields + files) |
+| `headerPairs`   | `number` | 2000     | Max header key-value pairs       |
+| `headerSize`    | `number` | 81920    | Max header part size in bytes    |
+
+### Type Guards
+
+#### `isMultipartFieldData(data)`
+
+Type guard to check if parsed data is a form field.
+
+```typescript
+if (isMultipartFieldData(data)) {
+  console.log(data.value); // TypeScript knows this is FieldData
+}
+```
+
+#### `isMultipartFileData(data)`
+
+Type guard to check if parsed data is a file.
+
+```typescript
+if (isMultipartFileData(data)) {
+  data.stream.pipe(destination); // TypeScript knows this is FileData
+}
+```
+
+### Data Types
+
+#### `FieldData`
+
+```typescript
+type FieldData = {
+  value: string;
+  nameTruncated: boolean;
+  valueTruncated: boolean;
+  encoding: string;
+  mimeType: string;
+};
+```
+
+#### `FileData`
+
+```typescript
+type FileData = {
+  stream: Readable;
+  filename: string;
+  encoding: string;
+  mimeType: string;
+};
+```
+
+## Advanced Usage
+
+### Custom File Size Limits
+
+```typescript
+// Set default limits in constructor
+const multipart = new MultipartBody(req, {
+  files: 5,
+  fileSize: 50 * 1024 * 1024, // 50 MB
+});
+
+// Override per-request
+const fields = await multipart.parse(fileHandler, {
+  fileSize: 100 * 1024 * 1024, // 100 MB for this request only
+});
+```
+
+### Handling Multiple Files
+
+```typescript
+const multipart = new MultipartBody(req, { files: 10 });
+
+const uploadedFiles: string[] = [];
+
+const fields = await multipart.parse(async (fieldname, stream, filename) => {
+  const path = `./uploads/${Date.now()}-${filename}`;
+  await pipeline(stream, createWriteStream(path));
+  uploadedFiles.push(path);
+});
+
+console.log('Uploaded files:', uploadedFiles);
+```
+
+### Error Handling
+
+The parser throws HTTP 413 errors when limits are exceeded:
+
+```typescript
+import { MultipartBody } from '@maroonedsoftware/multipart';
+
+try {
+  const fields = await multipart.parse(fileHandler);
+} catch (error) {
+  if (error.statusCode === 413) {
+    // Handle limit exceeded
+    console.error('Upload too large:', error.internalDetails?.reason);
+  }
+  throw error;
+}
+```
+
+## Example
+
+```typescript
+type ParsedMultipartBody = {
+  fields: Map<string, MultipartData>;
+  file: {
+    filename: string;
+    stream: Readable;
+    encoding: string;
+    mimeType: string;
+  };
+};
+
+export class Service {
+  private async parseMultipartBody(multipartReq: MultipartBody) {
+    let file: ParsedMultipartBody['file'] | undefined;
+    const fields = await multipartReq.parse(async (fieldname, stream, fileFieldName, encoding, mimeType) => {
+      if (fieldname === 'file') {
+        file = { stream, filename: fileFieldName, encoding, mimeType };
+      }
+    });
+    return { fields, file } as ParsedMultipartBody;
+  }
+
+  async handle(body: MultipartBody): Promise<void> {
+    const parsedBody = await this.parseMultipartBody(body);
+    filename = parsedBody.file?.filename ?? 'missing name';
+    content = parsedBody.file?.stream;
+
+    // use content
+  }
+}
+```
+
+## License
+
+MIT

package/dist/busboy.wrapper.d.ts

@@ -0,0 +1,107 @@
+import { IncomingMessage } from 'node:http';
+import { Busboy } from '@fastify/busboy';
+import { FileHandler, MultipartData, MultipartLimits } from './types.js';
+/**
+ * A wrapper around the Busboy multipart parser that provides a promise-based API
+ * for parsing multipart/form-data requests.
+ *
+ * This class handles both file and field parsing, automatically managing the lifecycle
+ * of streams and cleanup of resources. It enforces configurable limits on file sizes,
+ * field counts, and other parameters to prevent resource exhaustion.
+ *
+ * @extends Busboy
+ *
+ * @example
+ * ```typescript
+ * import { IncomingMessage } from 'node:http';
+ * import { BusboyWrapper } from './busboy.wrapper.js';
+ *
+ * async function handleUpload(req: IncomingMessage) {
+ *   const parser = new BusboyWrapper(req, { fileSize: 10 * 1024 * 1024 });
+ *
+ *   const fields = await parser.parse(async (fieldname, stream, filename) => {
+ *     // Handle file upload
+ *     await pipeline(stream, fs.createWriteStream(`./uploads/${filename}`));
+ *   });
+ *
+ *   // Access parsed fields
+ *   const name = fields.get('name');
+ * }
+ * ```
+ */
+export declare class BusboyWrapper extends Busboy {
+    /** The incoming HTTP request being parsed */
+    private readonly req;
+    /** Map storing parsed fields and files keyed by field name */
+    private readonly fields;
+    /** Optional handler for processing file uploads */
+    private fileHandler?;
+    /** A null stream used to drain file streams when errors occur */
+    private readonly nullStream;
+    /**
+     * Creates a new BusboyWrapper instance.
+     *
+     * @param req - The incoming HTTP request containing multipart data
+     * @param limits - Optional limits configuration for parsing
+     */
+    constructor(req: IncomingMessage, limits?: MultipartLimits);
+    /**
+     * Parses the multipart request body.
+     *
+     * @param fileHandler - A callback function to handle file uploads as they are received
+     * @returns A promise that resolves to a Map of field names to their parsed data.
+     *          If multiple values exist for a field name, they are stored as an array.
+     *
+     * @throws {HttpError} 413 error if parts, files, or fields limits are exceeded
+     *
+     * @example
+     * ```typescript
+     * const fields = await parser.parse(async (fieldname, stream, filename) => {
+     *   const chunks: Buffer[] = [];
+     *   for await (const chunk of stream) {
+     *     chunks.push(chunk);
+     *   }
+     *   await fs.writeFile(`./uploads/${filename}`, Buffer.concat(chunks));
+     * });
+     * ```
+     */
+    parse(fileHandler: FileHandler): Promise<Map<string, MultipartData | MultipartData[]>>;
+    /**
+     * Stores parsed data in the fields map, handling multiple values for the same field.
+     *
+     * @param name - The field name
+     * @param data - The parsed field or file data
+     */
+    private setData;
+    /**
+     * Handler for parsed form fields.
+     */
+    private onField;
+    /**
+     * Handler for parsed file uploads.
+     */
+    private onFile;
+    private resolve;
+    private reject;
+    /**
+     * Handler called when parsing completes or an error occurs.
+     */
+    private onEnd;
+    /**
+     * Handler for when the parts limit is exceeded.
+     */
+    private onPartsLimit;
+    /**
+     * Handler for when the files limit is exceeded.
+     */
+    private onFilesLimit;
+    /**
+     * Handler for when the fields limit is exceeded.
+     */
+    private onFieldsLimit;
+    /**
+     * Cleans up event listeners to prevent memory leaks.
+     */
+    private cleanup;
+}
+//# sourceMappingURL=busboy.wrapper.d.ts.map

package/dist/busboy.wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"busboy.wrapper.d.ts","sourceRoot":"","sources":["../src/busboy.wrapper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAmC,MAAM,iBAAiB,CAAC;AAG1E,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,aAAc,SAAQ,MAAM;IACvC,6CAA6C;IAC7C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAkB;IAEtC,8DAA8D;IAC9D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsD;IAE7E,mDAAmD;IACnD,OAAO,CAAC,WAAW,CAAC,CAAc;IAElC,iEAAiE;IACjE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAIxB;IAEH;;;;;OAKG;gBACS,GAAG,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,eAAe;IAe1D;;;;;;;;;;;;;;;;;;;OAmBG;IACH,KAAK,CAAC,WAAW,EAAE,WAAW;IAS9B;;;;;OAKG;IACH,OAAO,CAAC,OAAO;IAWf;;OAEG;IACH,OAAO,CAAC,OAAO;IAUf;;OAEG;IACH,OAAO,CAAC,MAAM;IAcd,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,MAAM;IAEd;;OAEG;IACH,OAAO,CAAC,KAAK;IASb;;OAEG;IACH,OAAO,CAAC,YAAY;IAOpB;;OAEG;IACH,OAAO,CAAC,YAAY;IAOpB;;OAEG;IACH,OAAO,CAAC,aAAa;IAOrB;;OAEG;IACH,OAAO,CAAC,OAAO;CAUhB"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './multipart.body.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,243 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/types.ts
+var isMultipartFieldData = /* @__PURE__ */ __name((data) => {
+  return "value" in data;
+}, "isMultipartFieldData");
+var isMultipartFileData = /* @__PURE__ */ __name((data) => {
+  return "stream" in data;
+}, "isMultipartFileData");
+
+// src/busboy.wrapper.ts
+import { Busboy } from "@fastify/busboy";
+import { Writable } from "stream";
+import { httpError } from "@maroonedsoftware/errors";
+var BusboyWrapper = class extends Busboy {
+  static {
+    __name(this, "BusboyWrapper");
+  }
+  /** The incoming HTTP request being parsed */
+  req;
+  /** Map storing parsed fields and files keyed by field name */
+  fields = /* @__PURE__ */ new Map();
+  /** Optional handler for processing file uploads */
+  fileHandler;
+  /** A null stream used to drain file streams when errors occur */
+  nullStream = new Writable({
+    write(_chunk, _encding, callback) {
+      setImmediate(callback);
+    }
+  });
+  /**
+  * Creates a new BusboyWrapper instance.
+  *
+  * @param req - The incoming HTTP request containing multipart data
+  * @param limits - Optional limits configuration for parsing
+  */
+  constructor(req, limits) {
+    super({
+      headers: req.headers,
+      limits
+    });
+    this.req = req;
+    this.req.on("close", () => this.cleanup);
+    this.on("field", this.onField).on("file", this.onFile).on("finish", this.onEnd).on("error", this.onEnd).on("partsLimit", this.onPartsLimit).on("filesLimit", this.onFilesLimit).on("fieldsLimit", this.onFieldsLimit);
+  }
+  /**
+  * Parses the multipart request body.
+  *
+  * @param fileHandler - A callback function to handle file uploads as they are received
+  * @returns A promise that resolves to a Map of field names to their parsed data.
+  *          If multiple values exist for a field name, they are stored as an array.
+  *
+  * @throws {HttpError} 413 error if parts, files, or fields limits are exceeded
+  *
+  * @example
+  * ```typescript
+  * const fields = await parser.parse(async (fieldname, stream, filename) => {
+  *   const chunks: Buffer[] = [];
+  *   for await (const chunk of stream) {
+  *     chunks.push(chunk);
+  *   }
+  *   await fs.writeFile(`./uploads/${filename}`, Buffer.concat(chunks));
+  * });
+  * ```
+  */
+  parse(fileHandler) {
+    return new Promise((resolve, reject) => {
+      this.fileHandler = fileHandler;
+      this.resolve = resolve;
+      this.reject = reject;
+      this.req.pipe(this);
+    });
+  }
+  /**
+  * Stores parsed data in the fields map, handling multiple values for the same field.
+  *
+  * @param name - The field name
+  * @param data - The parsed field or file data
+  */
+  setData(name, data) {
+    const prev = this.fields.get(name);
+    if (prev == null) {
+      this.fields.set(name, data);
+    } else if (Array.isArray(prev)) {
+      prev.push(data);
+    } else {
+      this.fields.set(name, [
+        prev,
+        data
+      ]);
+    }
+  }
+  /**
+  * Handler for parsed form fields.
+  */
+  onField(name, value, nameTruncated, valueTruncated, encoding, mimeType) {
+    this.setData(name, {
+      value,
+      nameTruncated,
+      valueTruncated,
+      encoding,
+      mimeType
+    });
+  }
+  /**
+  * Handler for parsed file uploads.
+  */
+  onFile(fieldname, stream, filename, encoding, mimeType) {
+    this.setData(fieldname, {
+      stream,
+      filename,
+      encoding,
+      mimeType
+    });
+    if (this.fileHandler) {
+      this.fileHandler(fieldname, stream, filename, encoding, mimeType).then(() => {
+        this.onEnd();
+      }).catch((reason) => {
+        stream.pipe(this.nullStream);
+        this.onEnd(reason);
+      });
+    }
+  }
+  resolve(_) {
+  }
+  reject(_) {
+  }
+  /**
+  * Handler called when parsing completes or an error occurs.
+  */
+  onEnd(err) {
+    this.cleanup();
+    if (err) {
+      this.reject(err);
+    } else {
+      this.resolve(this.fields);
+    }
+  }
+  /**
+  * Handler for when the parts limit is exceeded.
+  */
+  onPartsLimit() {
+    const err = httpError(413).withInternalDetails({
+      reason: "Reached parts limit"
+    });
+    this.onEnd(err);
+  }
+  /**
+  * Handler for when the files limit is exceeded.
+  */
+  onFilesLimit() {
+    const err = httpError(413).withInternalDetails({
+      reason: "Reached files limit"
+    });
+    this.onEnd(err);
+  }
+  /**
+  * Handler for when the fields limit is exceeded.
+  */
+  onFieldsLimit() {
+    const err = httpError(413).withInternalDetails({
+      reason: "Reached fields limit"
+    });
+    this.onEnd(err);
+  }
+  /**
+  * Cleans up event listeners to prevent memory leaks.
+  */
+  cleanup() {
+    this.req.removeListener("close", this.cleanup);
+    this.removeListener("field", this.onField);
+    this.removeListener("file", this.onFile);
+    this.removeListener("error", this.onEnd);
+    this.removeListener("partsLimit", this.onPartsLimit);
+    this.removeListener("filesLimit", this.onFilesLimit);
+    this.removeListener("fieldsLimit", this.onFieldsLimit);
+    this.removeListener("finish", this.onEnd);
+  }
+};
+
+// src/multipart.body.ts
+var MAX_FILE_SIZE = 20 * 1024 * 1024;
+var MultipartBody = class {
+  static {
+    __name(this, "MultipartBody");
+  }
+  req;
+  _limits;
+  /**
+  * Creates a new MultipartBody instance.
+  *
+  * @param req - The incoming HTTP request containing multipart data
+  * @param _limits - Default limits applied to all parse operations.
+  *                  Defaults to 1 file maximum and 20MB file size limit.
+  */
+  constructor(req, _limits = {
+    files: 1,
+    fileSize: MAX_FILE_SIZE
+  }) {
+    this.req = req;
+    this._limits = _limits;
+  }
+  /**
+  * Parses the multipart request body and processes any file uploads.
+  *
+  * @param fileHandler - A callback function invoked for each file in the request.
+  *                      The callback receives the field name, file stream, filename,
+  *                      encoding, and MIME type. It should return a promise that
+  *                      resolves when the file has been fully processed.
+  * @param limits - Optional per-request limits that override the instance defaults.
+  *                 These are merged with the default limits (per-request takes precedence).
+  * @returns A promise that resolves to a Map containing all parsed fields and files.
+  *          Field names are keys, and values are either a single MultipartData object
+  *          or an array if multiple values were submitted for the same field name.
+  *
+  * @throws {HttpError} 413 error if configured limits are exceeded
+  *
+  * @example
+  * ```typescript
+  * // Parse with custom file size limit for this request
+  * const fields = await multipart.parse(
+  *   async (fieldname, stream, filename) => {
+  *     await saveFile(stream, filename);
+  *   },
+  *   { fileSize: 50 * 1024 * 1024 } // 50MB for this request
+  * );
+  * ```
+  */
+  parse(fileHandler, limits) {
+    const busboy = new BusboyWrapper(this.req, {
+      ...this._limits,
+      ...limits
+    });
+    return busboy.parse(fileHandler);
+  }
+};
+export {
+  MultipartBody,
+  isMultipartFieldData,
+  isMultipartFileData
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts","../src/busboy.wrapper.ts","../src/multipart.body.ts"],"sourcesContent":["import { Readable } from 'node:stream';\n\n/**\n * Callback function for handling file uploads during multipart parsing.\n *\n * @param fieldname - The name of the form field\n * @param stream - A readable stream containing the file data\n * @param filename - The original filename from the upload\n * @param encoding - The encoding of the file (e.g., '7bit', 'binary')\n * @param mimeType - The MIME type of the file (e.g., 'image/png')\n * @returns A promise that resolves when the file has been fully processed\n *\n * @example\n * ```typescript\n * const handler: FileHandler = async (fieldname, stream, filename, encoding, mimeType) => {\n *   const writeStream = fs.createWriteStream(`./uploads/${filename}`);\n *   await pipeline(stream, writeStream);\n * };\n * ```\n */\nexport type FileHandler = (fieldname: string, stream: Readable, filename: string, encoding: string, mimeType: string) => Promise<void>;\n\n/**\n * Represents parsed form field data from a multipart request.\n */\nexport type FieldData = {\n  /** The string value of the field */\n  value: string;\n  /** Whether the field name was truncated due to limits */\n  nameTruncated: boolean;\n  /** Whether the field value was truncated due to limits */\n  valueTruncated: boolean;\n  /** The encoding of the field value */\n  encoding: string;\n  /** The MIME type of the field */\n  mimeType: string;\n};\n\n/**\n * Represents parsed file data from a multipart request.\n */\nexport type FileData = {\n  /** A readable stream containing the file data */\n  stream: Readable;\n  /** The original filename from the upload */\n  filename: string;\n  /** The encoding of the file */\n  encoding: string;\n  /** The MIME type of the file */\n  mimeType: string;\n};\n\n/**\n * Union type representing either field data or file data from a multipart request.\n */\nexport type MultipartData = FieldData | FileData;\n\n/**\n * Type guard to check if the multipart data is field data.\n *\n * @param data - The multipart data to check\n * @returns True if the data is field data, false otherwise\n *\n * @example\n * ```typescript\n * if (isMultipartFieldData(data)) {\n *   console.log(data.value); // TypeScript knows this is FieldData\n * }\n * ```\n */\nexport const isMultipartFieldData = (data: MultipartData): data is FieldData => {\n  return 'value' in data;\n};\n\n/**\n * Type guard to check if the multipart data is file data.\n *\n * @param data - The multipart data to check\n * @returns True if the data is file data, false otherwise\n *\n * @example\n * ```typescript\n * if (isMultipartFileData(data)) {\n *   data.stream.pipe(destination); // TypeScript knows this is FileData\n * }\n * ```\n */\nexport const isMultipartFileData = (data: MultipartData): data is FileData => {\n  return 'stream' in data;\n};\n\n/**\n * Configuration options for limiting multipart request sizes.\n * Used to prevent resource exhaustion from malicious or oversized uploads.\n *\n * @see https://github.com/fastify/busboy/blob/main/lib/main.d.ts#L104\n */\nexport interface MultipartLimits {\n  /**\n   * Maximum field name size in bytes.\n   * @default 100\n   */\n  fieldNameSize?: number | undefined;\n  /**\n   * Maximum field value size in bytes.\n   * @default 1048576 (1MB)\n   */\n  fieldSize?: number | undefined;\n  /**\n   * Maximum number of non-file fields.\n   * @default Infinity\n   */\n  fields?: number | undefined;\n  /**\n   * Maximum file size in bytes for multipart forms.\n   * @default Infinity\n   */\n  fileSize?: number | undefined;\n  /**\n   * Maximum number of file fields for multipart forms.\n   * @default Infinity\n   */\n  files?: number | undefined;\n  /**\n   * Maximum number of parts (fields + files) for multipart forms.\n   * @default Infinity\n   */\n  parts?: number | undefined;\n  /**\n   * Maximum number of header key-value pairs to parse for multipart forms.\n   * @default 2000\n   */\n  headerPairs?: number | undefined;\n  /**\n   * Maximum size of a header part in bytes for multipart forms.\n   * @default 81920\n   */\n  headerSize?: number | undefined;\n}\n","import { IncomingMessage } from 'node:http';\nimport { Busboy, BusboyFileStream, BusboyHeaders } from '@fastify/busboy';\nimport { Writable } from 'node:stream';\nimport { httpError } from '@maroonedsoftware/errors';\nimport { FileHandler, MultipartData, MultipartLimits } from './types.js';\n\n/**\n * A wrapper around the Busboy multipart parser that provides a promise-based API\n * for parsing multipart/form-data requests.\n *\n * This class handles both file and field parsing, automatically managing the lifecycle\n * of streams and cleanup of resources. It enforces configurable limits on file sizes,\n * field counts, and other parameters to prevent resource exhaustion.\n *\n * @extends Busboy\n *\n * @example\n * ```typescript\n * import { IncomingMessage } from 'node:http';\n * import { BusboyWrapper } from './busboy.wrapper.js';\n *\n * async function handleUpload(req: IncomingMessage) {\n *   const parser = new BusboyWrapper(req, { fileSize: 10 * 1024 * 1024 });\n *\n *   const fields = await parser.parse(async (fieldname, stream, filename) => {\n *     // Handle file upload\n *     await pipeline(stream, fs.createWriteStream(`./uploads/${filename}`));\n *   });\n *\n *   // Access parsed fields\n *   const name = fields.get('name');\n * }\n * ```\n */\nexport class BusboyWrapper extends Busboy {\n  /** The incoming HTTP request being parsed */\n  private readonly req: IncomingMessage;\n\n  /** Map storing parsed fields and files keyed by field name */\n  private readonly fields = new Map<string, MultipartData | MultipartData[]>();\n\n  /** Optional handler for processing file uploads */\n  private fileHandler?: FileHandler;\n\n  /** A null stream used to drain file streams when errors occur */\n  private readonly nullStream = new Writable({\n    write(_chunk, _encding, callback) {\n      setImmediate(callback);\n    },\n  });\n\n  /**\n   * Creates a new BusboyWrapper instance.\n   *\n   * @param req - The incoming HTTP request containing multipart data\n   * @param limits - Optional limits configuration for parsing\n   */\n  constructor(req: IncomingMessage, limits?: MultipartLimits) {\n    super({ headers: req.headers as BusboyHeaders, limits });\n\n    this.req = req;\n    this.req.on('close', () => this.cleanup);\n\n    this.on('field', this.onField)\n      .on('file', this.onFile)\n      .on('finish', this.onEnd)\n      .on('error', this.onEnd)\n      .on('partsLimit', this.onPartsLimit)\n      .on('filesLimit', this.onFilesLimit)\n      .on('fieldsLimit', this.onFieldsLimit);\n  }\n\n  /**\n   * Parses the multipart request body.\n   *\n   * @param fileHandler - A callback function to handle file uploads as they are received\n   * @returns A promise that resolves to a Map of field names to their parsed data.\n   *          If multiple values exist for a field name, they are stored as an array.\n   *\n   * @throws {HttpError} 413 error if parts, files, or fields limits are exceeded\n   *\n   * @example\n   * ```typescript\n   * const fields = await parser.parse(async (fieldname, stream, filename) => {\n   *   const chunks: Buffer[] = [];\n   *   for await (const chunk of stream) {\n   *     chunks.push(chunk);\n   *   }\n   *   await fs.writeFile(`./uploads/${filename}`, Buffer.concat(chunks));\n   * });\n   * ```\n   */\n  parse(fileHandler: FileHandler) {\n    return new Promise<Map<string, MultipartData | MultipartData[]>>((resolve, reject) => {\n      this.fileHandler = fileHandler;\n      this.resolve = resolve;\n      this.reject = reject;\n      this.req.pipe(this);\n    });\n  }\n\n  /**\n   * Stores parsed data in the fields map, handling multiple values for the same field.\n   *\n   * @param name - The field name\n   * @param data - The parsed field or file data\n   */\n  private setData(name: string, data: MultipartData) {\n    const prev = this.fields.get(name);\n    if (prev == null) {\n      this.fields.set(name, data);\n    } else if (Array.isArray(prev)) {\n      prev.push(data);\n    } else {\n      this.fields.set(name, [prev, data]);\n    }\n  }\n\n  /**\n   * Handler for parsed form fields.\n   */\n  private onField(name: string, value: string, nameTruncated: boolean, valueTruncated: boolean, encoding: string, mimeType: string) {\n    this.setData(name, {\n      value,\n      nameTruncated,\n      valueTruncated,\n      encoding,\n      mimeType,\n    });\n  }\n\n  /**\n   * Handler for parsed file uploads.\n   */\n  private onFile(fieldname: string, stream: BusboyFileStream, filename: string, encoding: string, mimeType: string) {\n    this.setData(fieldname, { stream, filename, encoding, mimeType });\n    if (this.fileHandler) {\n      this.fileHandler(fieldname, stream, filename, encoding, mimeType)\n        .then(() => {\n          this.onEnd();\n        })\n        .catch(reason => {\n          stream.pipe(this.nullStream);\n          this.onEnd(reason);\n        });\n    }\n  }\n\n  private resolve(_: Map<string, MultipartData | MultipartData[]>) {}\n  private reject(_?: Error) {}\n\n  /**\n   * Handler called when parsing completes or an error occurs.\n   */\n  private onEnd(err?: Error) {\n    this.cleanup();\n    if (err) {\n      this.reject(err);\n    } else {\n      this.resolve(this.fields);\n    }\n  }\n\n  /**\n   * Handler for when the parts limit is exceeded.\n   */\n  private onPartsLimit() {\n    const err = httpError(413).withInternalDetails({\n      reason: 'Reached parts limit',\n    });\n    this.onEnd(err);\n  }\n\n  /**\n   * Handler for when the files limit is exceeded.\n   */\n  private onFilesLimit() {\n    const err = httpError(413).withInternalDetails({\n      reason: 'Reached files limit',\n    });\n    this.onEnd(err);\n  }\n\n  /**\n   * Handler for when the fields limit is exceeded.\n   */\n  private onFieldsLimit() {\n    const err = httpError(413).withInternalDetails({\n      reason: 'Reached fields limit',\n    });\n    this.onEnd(err);\n  }\n\n  /**\n   * Cleans up event listeners to prevent memory leaks.\n   */\n  private cleanup() {\n    this.req.removeListener('close', this.cleanup);\n    this.removeListener('field', this.onField);\n    this.removeListener('file', this.onFile);\n    this.removeListener('error', this.onEnd);\n    this.removeListener('partsLimit', this.onPartsLimit);\n    this.removeListener('filesLimit', this.onFilesLimit);\n    this.removeListener('fieldsLimit', this.onFieldsLimit);\n    this.removeListener('finish', this.onEnd);\n  }\n}\n","import { IncomingMessage } from 'node:http';\nimport { BusboyWrapper } from './busboy.wrapper.js';\nimport { FileHandler, MultipartData } from './types.js';\nimport { MultipartLimits } from './types.js';\n\n/** Default maximum file size: 20 MB */\nconst MAX_FILE_SIZE = 20 * 1024 * 1024;\n\n/**\n * High-level API for parsing multipart/form-data request bodies.\n *\n * This class provides a simple interface for handling file uploads and form fields\n * from HTTP requests. It wraps the lower-level BusboyWrapper with sensible defaults\n * and allows per-request limit overrides.\n *\n * @example\n * ```typescript\n * import { IncomingMessage } from 'node:http';\n * import { MultipartBody } from '@maroonedsoftware/multipart';\n *\n * async function handleRequest(req: IncomingMessage) {\n *   const multipart = new MultipartBody(req);\n *\n *   const fields = await multipart.parse(async (fieldname, stream, filename) => {\n *     // Save the file\n *     await pipeline(stream, fs.createWriteStream(`./uploads/${filename}`));\n *   });\n *\n *   // Access form fields\n *   const description = fields.get('description');\n * }\n * ```\n */\nexport class MultipartBody {\n  /**\n   * Creates a new MultipartBody instance.\n   *\n   * @param req - The incoming HTTP request containing multipart data\n   * @param _limits - Default limits applied to all parse operations.\n   *                  Defaults to 1 file maximum and 20MB file size limit.\n   */\n  constructor(\n    private readonly req: IncomingMessage,\n    private readonly _limits: MultipartLimits = {\n      files: 1,\n      fileSize: MAX_FILE_SIZE,\n    },\n  ) {}\n\n  /**\n   * Parses the multipart request body and processes any file uploads.\n   *\n   * @param fileHandler - A callback function invoked for each file in the request.\n   *                      The callback receives the field name, file stream, filename,\n   *                      encoding, and MIME type. It should return a promise that\n   *                      resolves when the file has been fully processed.\n   * @param limits - Optional per-request limits that override the instance defaults.\n   *                 These are merged with the default limits (per-request takes precedence).\n   * @returns A promise that resolves to a Map containing all parsed fields and files.\n   *          Field names are keys, and values are either a single MultipartData object\n   *          or an array if multiple values were submitted for the same field name.\n   *\n   * @throws {HttpError} 413 error if configured limits are exceeded\n   *\n   * @example\n   * ```typescript\n   * // Parse with custom file size limit for this request\n   * const fields = await multipart.parse(\n   *   async (fieldname, stream, filename) => {\n   *     await saveFile(stream, filename);\n   *   },\n   *   { fileSize: 50 * 1024 * 1024 } // 50MB for this request\n   * );\n   * ```\n   */\n  parse(fileHandler: FileHandler, limits?: MultipartLimits): Promise<Map<string, MultipartData | MultipartData[]>> {\n    const busboy = new BusboyWrapper(this.req, { ...this._limits, ...limits });\n\n    return busboy.parse(fileHandler);\n  }\n}\n"],"mappings":"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","names":["isMultipartFieldData","data","isMultipartFileData","Busboy","Writable","httpError","BusboyWrapper","Busboy","req","fields","Map","fileHandler","nullStream","Writable","write","_chunk","_encding","callback","setImmediate","limits","headers","on","cleanup","onField","onFile","onEnd","onPartsLimit","onFilesLimit","onFieldsLimit","parse","Promise","resolve","reject","pipe","setData","name","data","prev","get","set","Array","isArray","push","value","nameTruncated","valueTruncated","encoding","mimeType","fieldname","stream","filename","then","catch","reason","_","err","httpError","withInternalDetails","removeListener","MAX_FILE_SIZE","MultipartBody","req","_limits","files","fileSize","parse","fileHandler","limits","busboy","BusboyWrapper"]}

package/dist/multipart.body.d.ts

@@ -0,0 +1,68 @@
+import { IncomingMessage } from 'node:http';
+import { FileHandler, MultipartData } from './types.js';
+import { MultipartLimits } from './types.js';
+/**
+ * High-level API for parsing multipart/form-data request bodies.
+ *
+ * This class provides a simple interface for handling file uploads and form fields
+ * from HTTP requests. It wraps the lower-level BusboyWrapper with sensible defaults
+ * and allows per-request limit overrides.
+ *
+ * @example
+ * ```typescript
+ * import { IncomingMessage } from 'node:http';
+ * import { MultipartBody } from '@maroonedsoftware/multipart';
+ *
+ * async function handleRequest(req: IncomingMessage) {
+ *   const multipart = new MultipartBody(req);
+ *
+ *   const fields = await multipart.parse(async (fieldname, stream, filename) => {
+ *     // Save the file
+ *     await pipeline(stream, fs.createWriteStream(`./uploads/${filename}`));
+ *   });
+ *
+ *   // Access form fields
+ *   const description = fields.get('description');
+ * }
+ * ```
+ */
+export declare class MultipartBody {
+    private readonly req;
+    private readonly _limits;
+    /**
+     * Creates a new MultipartBody instance.
+     *
+     * @param req - The incoming HTTP request containing multipart data
+     * @param _limits - Default limits applied to all parse operations.
+     *                  Defaults to 1 file maximum and 20MB file size limit.
+     */
+    constructor(req: IncomingMessage, _limits?: MultipartLimits);
+    /**
+     * Parses the multipart request body and processes any file uploads.
+     *
+     * @param fileHandler - A callback function invoked for each file in the request.
+     *                      The callback receives the field name, file stream, filename,
+     *                      encoding, and MIME type. It should return a promise that
+     *                      resolves when the file has been fully processed.
+     * @param limits - Optional per-request limits that override the instance defaults.
+     *                 These are merged with the default limits (per-request takes precedence).
+     * @returns A promise that resolves to a Map containing all parsed fields and files.
+     *          Field names are keys, and values are either a single MultipartData object
+     *          or an array if multiple values were submitted for the same field name.
+     *
+     * @throws {HttpError} 413 error if configured limits are exceeded
+     *
+     * @example
+     * ```typescript
+     * // Parse with custom file size limit for this request
+     * const fields = await multipart.parse(
+     *   async (fieldname, stream, filename) => {
+     *     await saveFile(stream, filename);
+     *   },
+     *   { fileSize: 50 * 1024 * 1024 } // 50MB for this request
+     * );
+     * ```
+     */
+    parse(fileHandler: FileHandler, limits?: MultipartLimits): Promise<Map<string, MultipartData | MultipartData[]>>;
+}
+//# sourceMappingURL=multipart.body.d.ts.map

package/dist/multipart.body.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multipart.body.d.ts","sourceRoot":"","sources":["../src/multipart.body.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAK7C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,aAAa;IAStB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAT1B;;;;;;OAMG;gBAEgB,GAAG,EAAE,eAAe,EACpB,OAAO,GAAE,eAGzB;IAGH;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,KAAK,CAAC,WAAW,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa,EAAE,CAAC,CAAC;CAKjH"}

package/dist/multipart.related.parser.d.ts

@@ -0,0 +1,120 @@
+import { IncomingMessage } from 'node:http';
+import { FileHandler, MultipartData } from './types.js';
+import { Readable, Writable } from 'node:stream';
+/**
+ * Extended Readable stream interface for multipart/related file parts.
+ *
+ * Provides additional metadata about the stream state including whether
+ * the stream was truncated due to size limits and the total bytes read.
+ */
+export interface MultipartRelatedFileStream extends Readable {
+    /** Whether the file stream was truncated due to size limits */
+    truncated: boolean;
+    /** The number of bytes that have been read from the stream so far */
+    bytesRead: number;
+}
+/**
+ * Parser for multipart/related content type requests.
+ *
+ * The multipart/related content type is used when multiple related parts
+ * need to be processed together, such as email messages with inline attachments
+ * or SOAP messages with MIME attachments.
+ *
+ * This parser extends Writable to act as a stream destination for the incoming
+ * request body, parsing parts as they arrive and invoking handlers for files.
+ *
+ * @extends Writable
+ *
+ * @example
+ * ```typescript
+ * import { IncomingMessage } from 'node:http';
+ * import { MultipartRelatedParser } from './multipart.related.parser.js';
+ *
+ * async function handleRelatedContent(req: IncomingMessage) {
+ *   const parser = new MultipartRelatedParser(req);
+ *
+ *   const parts = await parser.parse(async (fieldname, stream, filename) => {
+ *     // Process each related part
+ *     const content = await streamToBuffer(stream);
+ *     console.log(`Received ${filename}: ${content.length} bytes`);
+ *   });
+ * }
+ * ```
+ */
+export declare class MultipartRelatedParser extends Writable {
+    private readonly req;
+    /** Map storing parsed fields and files keyed by field name */
+    private readonly fields;
+    /** Optional handler for processing file uploads */
+    private fileHandler?;
+    /** A null stream used to drain file streams when errors occur */
+    private readonly nullStream;
+    /**
+     * Creates a new MultipartRelatedParser instance.
+     *
+     * @param req - The incoming HTTP request containing multipart/related data
+     */
+    constructor(req: IncomingMessage);
+    /**
+     * Parses the multipart/related request body.
+     *
+     * @param fileHandler - A callback function to handle file parts as they are received.
+     *                      Each file part triggers the handler with the field name, stream,
+     *                      filename, encoding, and MIME type.
+     * @returns A promise that resolves to a Map of field names to their parsed data.
+     *          If multiple values exist for a field name, they are stored as an array.
+     *
+     * @throws {HttpError} 413 error if parts, files, or fields limits are exceeded
+     *
+     * @example
+     * ```typescript
+     * const parts = await parser.parse(async (fieldname, stream, filename) => {
+     *   const chunks: Buffer[] = [];
+     *   for await (const chunk of stream) {
+     *     chunks.push(chunk);
+     *   }
+     *   // Process the complete content
+     *   processContent(Buffer.concat(chunks));
+     * });
+     * ```
+     */
+    parse(fileHandler: FileHandler): Promise<Map<string, MultipartData | MultipartData[]>>;
+    /**
+     * Stores parsed data in the fields map, handling multiple values for the same field.
+     *
+     * @param name - The field name
+     * @param data - The parsed field or file data
+     */
+    private setData;
+    /**
+     * Handler for parsed form fields.
+     */
+    private onField;
+    /**
+     * Handler for parsed file uploads.
+     */
+    private onFile;
+    private resolve;
+    private reject;
+    /**
+     * Handler called when parsing completes or an error occurs.
+     */
+    private onEnd;
+    /**
+     * Handler for when the parts limit is exceeded.
+     */
+    private onPartsLimit;
+    /**
+     * Handler for when the files limit is exceeded.
+     */
+    private onFilesLimit;
+    /**
+     * Handler for when the fields limit is exceeded.
+     */
+    private onFieldsLimit;
+    /**
+     * Cleans up event listeners to prevent memory leaks.
+     */
+    private cleanup;
+}
+//# sourceMappingURL=multipart.related.parser.d.ts.map

package/dist/multipart.related.parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multipart.related.parser.d.ts","sourceRoot":"","sources":["../src/multipart.related.parser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAGjD;;;;;GAKG;AACH,MAAM,WAAW,0BAA2B,SAAQ,QAAQ;IAC1D,+DAA+D;IAC/D,SAAS,EAAE,OAAO,CAAC;IACnB,qEAAqE;IACrE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,sBAAuB,SAAQ,QAAQ;IAmBtC,OAAO,CAAC,QAAQ,CAAC,GAAG;IAlBhC,8DAA8D;IAC9D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsD;IAE7E,mDAAmD;IACnD,OAAO,CAAC,WAAW,CAAC,CAAc;IAElC,iEAAiE;IACjE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAIxB;IAEH;;;;OAIG;gBAC0B,GAAG,EAAE,eAAe;IAIjD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,KAAK,CAAC,WAAW,EAAE,WAAW;IAS9B;;;;;OAKG;IACH,OAAO,CAAC,OAAO;IAWf;;OAEG;IACH,OAAO,CAAC,OAAO;IAUf;;OAEG;IACH,OAAO,CAAC,MAAM;IAcd,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,MAAM;IAEd;;OAEG;IACH,OAAO,CAAC,KAAK;IASb;;OAEG;IACH,OAAO,CAAC,YAAY;IAOpB;;OAEG;IACH,OAAO,CAAC,YAAY;IAOpB;;OAEG;IACH,OAAO,CAAC,aAAa;IAOrB;;OAEG;IACH,OAAO,CAAC,OAAO;CAUhB"}

package/dist/types.d.ts

@@ -0,0 +1,129 @@
+import { Readable } from 'node:stream';
+/**
+ * Callback function for handling file uploads during multipart parsing.
+ *
+ * @param fieldname - The name of the form field
+ * @param stream - A readable stream containing the file data
+ * @param filename - The original filename from the upload
+ * @param encoding - The encoding of the file (e.g., '7bit', 'binary')
+ * @param mimeType - The MIME type of the file (e.g., 'image/png')
+ * @returns A promise that resolves when the file has been fully processed
+ *
+ * @example
+ * ```typescript
+ * const handler: FileHandler = async (fieldname, stream, filename, encoding, mimeType) => {
+ *   const writeStream = fs.createWriteStream(`./uploads/${filename}`);
+ *   await pipeline(stream, writeStream);
+ * };
+ * ```
+ */
+export type FileHandler = (fieldname: string, stream: Readable, filename: string, encoding: string, mimeType: string) => Promise<void>;
+/**
+ * Represents parsed form field data from a multipart request.
+ */
+export type FieldData = {
+    /** The string value of the field */
+    value: string;
+    /** Whether the field name was truncated due to limits */
+    nameTruncated: boolean;
+    /** Whether the field value was truncated due to limits */
+    valueTruncated: boolean;
+    /** The encoding of the field value */
+    encoding: string;
+    /** The MIME type of the field */
+    mimeType: string;
+};
+/**
+ * Represents parsed file data from a multipart request.
+ */
+export type FileData = {
+    /** A readable stream containing the file data */
+    stream: Readable;
+    /** The original filename from the upload */
+    filename: string;
+    /** The encoding of the file */
+    encoding: string;
+    /** The MIME type of the file */
+    mimeType: string;
+};
+/**
+ * Union type representing either field data or file data from a multipart request.
+ */
+export type MultipartData = FieldData | FileData;
+/**
+ * Type guard to check if the multipart data is field data.
+ *
+ * @param data - The multipart data to check
+ * @returns True if the data is field data, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isMultipartFieldData(data)) {
+ *   console.log(data.value); // TypeScript knows this is FieldData
+ * }
+ * ```
+ */
+export declare const isMultipartFieldData: (data: MultipartData) => data is FieldData;
+/**
+ * Type guard to check if the multipart data is file data.
+ *
+ * @param data - The multipart data to check
+ * @returns True if the data is file data, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isMultipartFileData(data)) {
+ *   data.stream.pipe(destination); // TypeScript knows this is FileData
+ * }
+ * ```
+ */
+export declare const isMultipartFileData: (data: MultipartData) => data is FileData;
+/**
+ * Configuration options for limiting multipart request sizes.
+ * Used to prevent resource exhaustion from malicious or oversized uploads.
+ *
+ * @see https://github.com/fastify/busboy/blob/main/lib/main.d.ts#L104
+ */
+export interface MultipartLimits {
+    /**
+     * Maximum field name size in bytes.
+     * @default 100
+     */
+    fieldNameSize?: number | undefined;
+    /**
+     * Maximum field value size in bytes.
+     * @default 1048576 (1MB)
+     */
+    fieldSize?: number | undefined;
+    /**
+     * Maximum number of non-file fields.
+     * @default Infinity
+     */
+    fields?: number | undefined;
+    /**
+     * Maximum file size in bytes for multipart forms.
+     * @default Infinity
+     */
+    fileSize?: number | undefined;
+    /**
+     * Maximum number of file fields for multipart forms.
+     * @default Infinity
+     */
+    files?: number | undefined;
+    /**
+     * Maximum number of parts (fields + files) for multipart forms.
+     * @default Infinity
+     */
+    parts?: number | undefined;
+    /**
+     * Maximum number of header key-value pairs to parse for multipart forms.
+     * @default 2000
+     */
+    headerPairs?: number | undefined;
+    /**
+     * Maximum size of a header part in bytes for multipart forms.
+     * @default 81920
+     */
+    headerSize?: number | undefined;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEvI;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,aAAa,EAAE,OAAO,CAAC;IACvB,0DAA0D;IAC1D,cAAc,EAAE,OAAO,CAAC;IACxB,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,iDAAiD;IACjD,MAAM,EAAE,QAAQ,CAAC;IACjB,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEjD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB,GAAI,MAAM,aAAa,KAAG,IAAI,IAAI,SAElE,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM,aAAa,KAAG,IAAI,IAAI,QAEjE,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@maroonedsoftware/multipart",
+  "version": "1.0.0",
+  "description": "A robust multipart form-data and multipart/related parser for Node.js HTTP servers.",
+  "author": {
+    "name": "Marooned Software",
+    "url": "https://github.com/MaroonedSoftware/serverkit"
+  },
+  "bugs": {
+    "url": "https://github.com/MaroonedSoftware/serverkit/issues"
+  },
+  "homepage": "https://github.com/MaroonedSoftware/serverkit/packages/multipart#readme",
+  "keywords": [
+    "backend",
+    "busboy",
+    "multipart",
+    "multipart/form-data",
+    "multipart/related",
+    "serverkit",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MaroonedSoftware/serverkit.git"
+  },
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "license": "MIT",
+  "files": [
+    "dist/**"
+  ],
+  "dependencies": {
+    "@fastify/busboy": "^3.2.0",
+    "@maroonedsoftware/errors": "1.0.0"
+  },
+  "devDependencies": {
+    "@repo/config-typescript": "0.0.0",
+    "@repo/config-eslint": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --sourcemap --dts && tsc --emitDeclarationOnly --declaration",
+    "build:ci": "eslint --max-warnings=0 && pnpm run build",
+    "lint": "eslint --fix",
+    "format": "prettier --write .",
+    "test": "vitest run",
+    "test:ci": "vitest run --coverage"
+  }
+}