MultipartReader

MultipartReader parses a multipart/form-data or multipart/mixed request body and exposes each part as a typed field or file item. It uses multipasta under the hood and writes uploaded files to the OS temp directory.

A key advantage over older busboy-based parsers: part-level headers (e.g. Content-Id, Request-Id) are fully preserved and exposed on every item via item.headers.

Package: @opra/http

Obtaining an instance

Do not construct MultipartReader directly. Obtain one from the operation context:

import { HttpContext, MultipartReader } from '@opra/http';

async upload(ctx: HttpContext) {
  if (!ctx.isMultipart) return;
  const reader = await ctx.getMultipartReader();
}

Methods

`getAll()`

getAll(): Promise<MultipartReader.Item[]>

Reads all remaining parts from the stream and returns them as an array. Waits until the entire request body has been consumed.

Use getAll() when the upload is small and bounded, or when you need all parts before starting any processing.

const parts = await reader.getAll();

for (const part of parts) {
  if (part.kind === 'file') {
    await store(part.storedPath, part.filename);
  }
  if (part.kind === 'field') {
    console.log(part.field, part.value);
  }
}

await reader.purge(); // delete temp files when done

`getNext()`

getNext(): Promise<MultipartReader.Item | undefined>

Reads and returns the next part from the stream. Returns undefined when all parts have been consumed.

Use getNext() for large uploads or when you want to start processing a part before the rest of the body has arrived.

let part: MultipartReader.Item | undefined;

while ((part = await reader.getNext())) {
  if (part.kind === 'file') {
    // File is already written to disk at part.storedPath.
    await processFile(part.storedPath);
    await part.delete(); // free disk space as soon as possible
  }

  if (part.kind === 'field') {
    options[part.field] = part.value;
  }
}

note

If a field declared as required in .MultipartContent() was never sent by the client, getNext() throws a BadRequestError after the last part is consumed and the stream closes.

`cancel()`

cancel(): void

Aborts stream processing. No further parts are emitted after cancel() is called. Useful when an early validation error makes reading the rest of the body unnecessary.

const part = await reader.getNext();
if (!isAllowed(part)) {
  reader.cancel();
  throw new ForbiddenError('Upload not permitted');
}

`purge()`

purge(): Promise<void>

Deletes all temporary files created during this request. By default, uploaded files are automatically deleted when the LocalFile object is garbage-collected (autoDelete: true). Call purge() to delete them immediately after you are done processing.

const parts = await reader.getAll();
try {
  await processAll(parts);
} finally {
  await reader.purge();
}

Properties

Property	Type	Description
`items`	`MultipartReader.Item[]`	All parts received so far (grows as the stream is consumed).
`scope`	`string \| undefined`	Validation scope applied to field decoding.

Events

MultipartReader extends AsyncEventEmitter. Listen to events for reactive processing instead of polling with getNext().

Event	Payload	Emitted when
`'item'`	`MultipartReader.Item`	Any part arrives from the raw stream (before validation).
`'field'`	`MultipartReader.Field`	A field part is decoded and validated (inside `getNext()`).
`'file'`	`MultipartReader.File`	A file part passes content-type validation (inside `getNext()`).
`'error'`	`Error`	The stream encounters an error or required field validation fails.

note

'item' fires as soon as a part arrives from the parser — before schema validation. 'field' and 'file' fire later, inside getNext(), after the part has been validated against your .MultipartContent() declaration. For most use cases, use getNext() or getAll() instead of listening to events directly.

reader.on('file', (file: MultipartReader.File) => {
  console.log(`Received file: ${file.filename}`);
  // Access part-level headers, e.g. a custom Request-Id
  console.log(file.headers['x-request-id']);
});

reader.on('field', (field: MultipartReader.Field) => {
  console.log(`Received field: ${field.field} = ${field.value}`);
});

reader.resume(); // start the stream when using event mode

Interfaces