Meros: Multipart Response Utility

Common errors

• TypeError: parts is not async iterable

  cause This error occurs when attempting to use `for await (const part of parts)` on the value returned by `meros` when the HTTP response's `Content-Type` header was not `multipart/mixed`. In such cases, `meros` returns the original `Response` object, which is not an async iterable.
  fix Before iterating, always check if the returned `parts` object is an async iterable using `if (parts && typeof (parts as any)[Symbol.asyncIterator] === 'function')`. If not, process `parts` as a standard `Response` object (e.g., `parts.json()`).

• ReferenceError: require is not defined

  cause Attempting to use `require('meros')` or `require('meros/node')` in an environment that expects ECMAScript Modules (ESM) syntax, such as a modern Node.js project or a browser module without proper CommonJS transpilation.
  fix Meros is primarily designed for ESM. Update your import statements to use `import { meros } from 'meros';` (or specific subpath imports) and ensure your project's `package.json` specifies `"type": "module"` or your build setup correctly handles ESM.

Warnings

• gotcha Meros returns an `AsyncGenerator<Part>` only if the `content-type` HTTP header is `multipart/mixed`. For any other content type, it resolves with the original `Response` object. Developers must explicitly check the return type before attempting to iterate over `parts`.
  Fix: Implement a runtime check for the return value, such as `if (parts && typeof (parts as any)[Symbol.asyncIterator] === 'function')` to safely differentiate between an iterable of parts and the raw Response object.
• gotcha The main `meros` entry point (`import { meros } from 'meros';`) relies on bundler or environment detection to load the correct browser or Node.js-specific code. This can sometimes lead to unexpected behavior or larger bundle sizes if not configured correctly, or if a browser build is incorrectly served in Node or vice-versa.
  Fix: For explicit and robust environment targeting, use the specific subpath imports: `import { meros } from 'meros/browser';` for browser-based applications, or `import { meros } from 'meros/node';` for Node.js environments.

Install

• npm install meros npm
• yarn add meros yarn
• pnpm add meros pnpm

Imports

• meros
  wrong:

  import meros from 'meros';

  correct:

  import { meros } from 'meros';

  Meros exclusively uses named exports. The main 'meros' import relies on bundler or environment detection to serve the correct version. For explicit control and potential optimizations, consider using environment-specific subpath imports (`meros/browser` or `meros/node`).
• meros (Browser)
  wrong:

  import { meros } from 'meros';

  correct:

  import { meros } from 'meros/browser';

  This import explicitly targets browser environments. It's recommended when building for the web to ensure correct module resolution and take advantage of any browser-specific optimizations or tree-shaking by bundlers.
• meros (Node.js)
  wrong:

  const { meros } = require('meros/node');

  correct:

  import { meros } from 'meros/node';

  This import explicitly targets Node.js environments (requires `node >=13`). It's recommended for server-side applications to ensure correct module resolution and access to Node.js-specific streaming interfaces. The package is designed for ESM usage.

Quickstart

Demonstrates fetching a response, processing it with `meros`, and gracefully handling both `multipart/mixed` and non-multipart (e.g., JSON) responses using an async generator pattern.

import { meros } from 'meros';

async function fetchAndProcessMultipart() {
  // Simulate a multipart/mixed response or a regular JSON response
  // In a real application, replace with your actual fetch call
  const mockFetch = async (url: string) => {
    if (url === '/api/multipart') {
      // Example multipart response
      return new Response(
        `--boundary\r\nContent-Type: application/json\r\n\r\n{"data": "part1"}\r\n--boundary\r\nContent-Type: text/plain\r\n\r\nhello from part 2\r\n--boundary--`,
        {
          headers: { 'Content-Type': 'multipart/mixed; boundary=boundary' }
        }
      );
    } else {
      // Example non-multipart JSON response
      return new Response(JSON.stringify({ message: 'Not multipart' }), {
        headers: { 'Content-Type': 'application/json' }
      });
    }
  };

  try {
    const response = await mockFetch('/api/multipart'); // Try with '/api/json' to see the other path
    const parts = await meros(response);

    if (parts && typeof (parts as any)[Symbol.asyncIterator] === 'function') {
      console.log('Processing multipart response:');
      for await (const part of parts) {
        if (part.json) {
          console.log('  JSON Part:', part.body);
        } else {
          console.log('  Text/Other Part:', new TextDecoder().decode(part.body as Uint8Array));
        }
      }
    } else {
      console.log('Not a multipart response, processing as regular response:');
      const data = await (parts as Response).json();
      console.log('  Response Data:', data);
    }
  } catch (error) {
    console.error('Error fetching or processing:', error);
  }
}

fetchAndProcessMultipart();