it-multipart: Async Iterable Multipart Parser

Common errors

• TypeError: multipart is not a function or not iterable

  cause Attempting to use `require` with `it-multipart` in a strict ESM context, or an incorrect named import.
  fix Ensure you are using `import multipart from 'it-multipart'` in ESM modules. If using CommonJS, verify the environment's support for importing ESM default exports, or use `const multipart = require('it-multipart')` and test its functionality.

• Error: stream has ended or has no more data

  cause Attempting to read from `part.body` after it has been fully consumed or if the upstream stream has closed prematurely, possibly due to not consuming `part.body` for a previous part.
  fix Confirm that `part.body` is fully consumed for each part within its loop, and that the upstream HTTP request stream is correctly handled and not closed before all parts are processed.

Warnings

• gotcha When iterating over multipart parts, the `part.body` async iterable for the current part MUST be fully consumed before the next part can be emitted by the `multipart` parser. Failing to consume `part.body` will lead to stalls or incomplete parsing.
  Fix: Ensure a `for await...of` loop or a similar consumption mechanism processes `part.body` completely for each `part` before the outer loop proceeds to the next `part`.
• breaking The `multipart` function now expects the `boundary` string to be passed as a second argument, or inferred from the `req.headers['content-type']`. In previous versions, the boundary might have been automatically extracted or handled differently. Explicitly extracting and passing the boundary ensures correct parsing.
  Fix: When using `multipart(req)`, ensure `req.headers['content-type']` is available and contains the boundary, or extract it manually and pass it as `multipart(req, boundary)`.
• gotcha The `it-multipart` library is built around async iterables. Directly attempting to use it with older Node.js stream APIs (e.g., piping to traditional `Writable` streams) without proper adaptation (e.g., using `it-pipe` or manually iterating) can lead to unexpected behavior or errors.
  Fix: Embrace the async iterable pattern. Use `for await...of` loops to consume streams or leverage utilities from the `it-pipe` package for more complex stream compositions between async iterables.

Install

• npm install it-multipart npm
• yarn add it-multipart yarn
• pnpm add it-multipart pnpm

Imports

• multipart
  wrong:

  import { multipart } from 'it-multipart'

  correct:

  import multipart from 'it-multipart'

  The primary `multipart` function is a default export.
• multipart (CommonJS)
  wrong:

  const { multipart } = require('it-multipart')

  correct:

  const multipart = require('it-multipart')

  While primarily an ESM-first library, recent updates in the 'it' monorepo (for related packages like 'it-to-buffer') indicate efforts to support CommonJS `require()` syntax for default exports. Verify compatibility in your specific environment if encountering issues.
• Part

  import type { Part } from 'it-multipart'

  Import the `Part` type for explicit type annotations when working with parsed multipart segments in TypeScript.

Quickstart

This code demonstrates how to create an HTTP server that listens for POST requests with a 'multipart/form-data' content type, parses the incoming multipart message using `it-multipart`, and logs the headers and content of each part.

import http from 'http'
import multipart from 'it-multipart'

const server = http.createServer(async (req, res) => {
  if (req.method === 'POST' && req.headers['content-type']) {
    try {
      const boundary = req.headers['content-type'].split('boundary=')[1]
      if (!boundary) {
        res.writeHead(400, { 'Content-Type': 'text/plain' })
        res.end('Missing boundary in Content-Type header')
        return
      }

      for await (const part of multipart(req, boundary)) {
        console.log(`Received part with headers:`, part.headers)

        let partContent = ''
        // nb. part.body must be consumed before the next part is emitted
        for await (const chunk of part.body) {
          partContent += chunk.toString()
        }
        console.log(`Part name: ${part.name}, Content:`, partContent)
      }

      console.log('Finished parsing multipart message.')
      res.writeHead(200, { 'Content-Type': 'text/plain' })
      res.end('Multipart message parsed successfully.')
    } catch (error) {
      console.error('Error parsing multipart message:', error)
      res.writeHead(500, { 'Content-Type': 'text/plain' })
      res.end('Error parsing multipart message: ' + error.message)
    }
  } else {
    res.writeHead(404, { 'Content-Type': 'text/plain' })
    res.end('Not Found or Unsupported Method')
  }
})

server.listen(5001, () => {
  console.log('Server listening on port 5001')
})

// Example usage with curl:
// curl -X POST -H "Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW" -F "field1=value1" -F "file1=@./package.json" http://localhost:5001