Multipart and Tar utilities for Web Streams

Common errors

• TypeError: require is not a function

  cause Attempting to use CommonJS `require()` syntax to import `multitars`.
  fix Use ES Module `import` syntax: `import { ... } from 'multitars';`

• Code appears to run but no data is processed / Stream hangs unexpectedly.

  cause Not properly iterating the `AsyncGenerator` returned by `parseMultipart`, `untar`, `streamMultipart`, or `tar`, or failing to consume inner file streams.
  fix Ensure all functions returning `AsyncGenerator` are consumed with `for await...of`. For `TarFile`/`StreamFile` entries, explicitly read or drain their internal `stream` property.

• TypeError: Cannot read properties of undefined (reading 'contentType') when calling parseMultipart.

  cause The `parseMultipart` function requires a `params` object with a `contentType` property.
  fix Provide the `contentType` parameter: `parseMultipart(stream, { contentType: 'multipart/form-data; boundary=...' });`

• TS2345: Argument of type 'Buffer' is not assignable to parameter of type 'Uint8Array'.

  cause `multitars` operates on `Uint8Array` for binary data, but a Node.js `Buffer` was provided.
  fix Convert `Buffer` instances to `Uint8Array` before passing them to `multitars` functions: `new Uint8Array(buffer)`.

Warnings

• gotcha This library is built exclusively for the Web Streams API and expects `Uint8Array` for binary data. Directly using Node.js `Buffer` or older Node.js `stream` interfaces will not work or will negate the memory efficiency benefits by forcing intermediate buffering.
  Fix: Ensure all input and output data adheres to `ReadableStream<Uint8Array>` or `AsyncIterable<Uint8Array>` patterns. Convert `Buffer` instances to `Uint8Array` if necessary, though this typically indicates a non-streaming pattern.
• gotcha All parsing and streaming functions (`parseMultipart`, `streamMultipart`, `untar`, `tar`) return `AsyncGenerator`s. These must be iterated using `for await...of` loops or manually with `.next()` calls to initiate and process data. Merely calling the function does not trigger any stream operations.
  Fix: Always consume the `AsyncGenerator` return value. For example: `for await (const item of parseMultipart(...)) { ... }`.
• gotcha When parsing multipart or tar archives, `StreamFile`, `TarFile`, and `TarChunk` objects contain their *own* internal `ReadableStream` (accessible via the `stream` property for `TarFile`/`StreamFile`). These inner streams must be fully consumed or explicitly skipped/cancelled before the outer `AsyncGenerator` can yield the *next* file or chunk. Failing to do so will cause the outer stream to hang or not advance.
  Fix: After receiving a `StreamFile` or `TarFile`, ensure its `stream` property is either fully read (e.g., using `new Response(entry.stream).arrayBuffer()`) or explicitly drained/skipped (e.g., `for await (const _ of entry.stream) {}`) before the next iteration of the outer `for await...of` loop.
• breaking Version 1.0.0 included a patch fix for an accidental typo in the tar decoder that previously broke non-PAX GNU long name support. While a bug fix, this corrects previous incorrect behavior, which might be a breaking behavioral change for systems that inadvertently relied on the prior buggy implementation for specific tar archives.
  Fix: Upgrade to `v1.0.0` or higher to correctly handle non-PAX GNU long names in tar archives. Review any workflows that might have relied on or compensated for the previous incorrect decoding.
• gotcha The `multipartContentType` utility provides a dynamically seeded boundary. While convenient for automatically generating a unique boundary for outgoing multipart messages, if your application requires a specific, static, or truly random boundary (e.g., for compatibility with external services or deterministic testing), you will need to manage boundary generation and the `Content-Type` header manually.
  Fix: For specific boundary requirements, generate your own boundary string and construct the `Content-Type` header (`multipart/form-data; boundary=YOUR_BOUNDARY_STRING`) before passing it to `parseMultipart` or including it with `streamMultipart`'s output.

Install

• npm install multitars npm
• yarn add multitars yarn
• pnpm add multitars pnpm

Imports

• parseMultipart
  wrong:

  const parseMultipart = require('multitars');

  correct:

  import { parseMultipart } from 'multitars';

  multitars is an ESM-only package. `parseMultipart` returns an AsyncGenerator.
• streamMultipart
  wrong:

  import { streamMultipart } from 'multitars/dist/streamMultipart';

  correct:

  import { streamMultipart, FormEntry } from 'multitars';

  Includes `FormEntry` for type safety when composing multipart data. `streamMultipart` returns an AsyncGenerator of Uint8Array chunks.
• untar
  wrong:

  const { untar } = require('multitars');

  correct:

  import { untar, TarFile, TarChunk, TarTypeFlag } from 'multitars';

  Includes types for Tar entries and flags. `untar` returns an AsyncGenerator of `TarFile` or `TarChunk`.
• tar

  import { tar } from 'multitars';

  `tar` accepts an AsyncIterable of `TarChunk` or `TarFile` and returns an AsyncGenerator of Uint8Array chunks.

Quickstart

Demonstrates how to create and parse multipart/form-data and Tar archives using Web Streams, highlighting the `AsyncGenerator` pattern for consuming entries and file content. This example simulates network request/response flows.

import { parseMultipart, streamMultipart, FormEntry, untar, tar, TarTypeFlag } from 'multitars';

// --- Simulate a multipart/form-data request body ---
async function createMultipartBody() {
  const entries: FormEntry[] = [
    ['field1', 'hello world'],
    ['file1', new Uint8Array([1, 2, 3, 4])],
    ['file2', new Blob(['another file content'], { type: 'text/plain' })],
  ];
  const multipartStream = streamMultipart(entries);

  // To get the full body as a ReadableStream, you'd typically do:
  // const bodyStream = new ReadableStream({
  //   async pull(controller) {
  //     const { value, done } = await multipartStream.next();
  //     if (done) {
  //       controller.close();
  //     } else {
  //       controller.enqueue(value);
  //     }
  //   },
  // });
  // For quickstart, let's collect chunks to simulate a full body
  const chunks: Uint8Array[] = [];
  for await (const chunk of multipartStream) {
    chunks.push(chunk);
  }
  return new ReadableStream({
    start(controller) {
      chunks.forEach(chunk => controller.enqueue(chunk));
      controller.close();
    }
  });
}

async function handleMultipartRequest(requestBodyStream: ReadableStream<Uint8Array>, contentTypeHeader: string) {
  console.log('--- Parsing Multipart Request ---');
  for await (const entry of parseMultipart(requestBodyStream, { contentType: contentTypeHeader })) {
    console.log(`Found entry: ${entry.name}, type: ${entry.type}, filename: ${entry.name}, size: ${entry.size}`);
    if (entry.type === 'file') {
      const fileContent = await new Response(entry.stream).arrayBuffer();
      console.log(`  File content length: ${fileContent.byteLength}`);
    }
  }
}

// --- Simulate a tar archive ---
async function createTarArchive() {
  const tarEntries = [
    { name: 'hello.txt', size: 13, typeflag: TarTypeFlag.FILE, mtime: Date.now() / 1000, stream: new ReadableStream({ start(controller) { controller.enqueue(new TextEncoder().encode('Hello, Tar!\n')); controller.close(); } }) },
    { name: 'dir/', typeflag: TarTypeFlag.DIRECTORY, mtime: Date.now() / 1000 },
    { name: 'link.txt', typeflag: TarTypeFlag.SYMLINK, linkname: 'hello.txt', mtime: Date.now() / 1000 }
  ];
  const tarStream = tar(tarEntries);

  const chunks: Uint8Array[] = [];
  for await (const chunk of tarStream) {
    chunks.push(chunk);
  }
  return new ReadableStream({
    start(controller) {
      chunks.forEach(chunk => controller.enqueue(chunk));
      controller.close();
    }
  });
}

async function handleTarArchive(tarBodyStream: ReadableStream<Uint8Array>) {
  console.log('\n--- Untarring Archive ---');
  for await (const entry of untar(tarBodyStream)) {
    console.log(`Found entry: ${entry.name}, type: ${entry.typeflag === TarTypeFlag.FILE ? 'file' : entry.typeflag === TarTypeFlag.DIRECTORY ? 'directory' : 'link'}`);
    if (entry.typeflag === TarTypeFlag.FILE && 'stream' in entry) {
      const fileContent = await new Response(entry.stream).text();
      console.log(`  File content: ${fileContent.trim()}`);
    }
  }
}

(async () => {
  // Example Usage:
  const multipartRequestStream = await createMultipartBody();
  const multipartBoundary = `----------${Math.random().toString(36).substring(2)}`; // Simulate a boundary
  await handleMultipartRequest(multipartRequestStream, `multipart/form-data; boundary=${multipartBoundary}`);

  const tarArchiveStream = await createTarArchive();
  await handleTarArchive(tarArchiveStream);
})();