@andyrmitchell/multipart-mixed 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Andy Mitchell
+
+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,88 @@
+# @andyrmitchell/multipart-mixed
+
+Streaming parser for `multipart/mixed` HTTP batch responses, such as those returned by Google's batch APIs (Gmail, Calendar, Drive…).
+
+- **Streams**: each part reaches your callback as soon as its bytes arrive. A 1,000-part batch never has to sit in memory at once.
+- **Isolates failures per part**: a malformed part is reported as `{parsed: false}`, and a failed sub-request carries its own status. Neither affects the rest of the batch.
+- **Refuses to lose data silently**: a truncated response, or one whose boundary never appears, rejects instead of resolving with fewer parts.
+- **RFC 2046 framing**: delimiters must start a line, so boundary text inside a body is safe. The preamble and epilogue are ignored, and CRLF and bare LF are both accepted.
+- **Zero dependencies**: web-platform APIs only (`Response`, `ReadableStream`, `TextDecoder`). Runs in browsers, service workers and Node 18+.
+
+## Install
+
+```sh
+npm i @andyrmitchell/multipart-mixed
+```
+
+## Usage
+
+```ts
+import { streamMultipartParts } from '@andyrmitchell/multipart-mixed';
+
+const response = await fetch('https://www.googleapis.com/batch/gmail/v1', { method: 'POST', headers, body });
+
+await streamMultipartParts(response, async part => {
+    if (!part.parsed) {
+        // The part's text was malformed. The rest of the batch still arrives.
+        console.warn(part.runtimeError?.message);
+        return;
+    }
+    if (part.statusCode !== 200) {
+        // This one sub-request failed, e.g. a 404 or 429. Its reply headers are available.
+        console.warn(part.contentId, part.statusCode, part.headers['retry-after']);
+        return;
+    }
+    await save(part.bodyData); // Record<string, unknown>: validate before reading nested fields
+});
+```
+
+Use `getMultipartParts(response)` if you want every part as an array. It buffers the whole batch.
+
+### What each part tells you
+
+For a readable part (`parsed: true`):
+
+| Field | Meaning |
+|---|---|
+| `contentId` | The part's `Content-ID`, with any `<…>` brackets removed. Use it to match replies to sub-requests. |
+| `statusCode` | The embedded reply's HTTP status. |
+| `headers` | The embedded reply's headers, keyed in lower case. |
+| `contentType` | The embedded reply's `Content-Type`, parameters included. |
+| `bodyData` | The body parsed as a JSON object. `undefined` if the body is not a JSON object. |
+| `bodyRaw` | The body text, always present when there is a body. |
+
+An unreadable part (`parsed: false`) carries only `runtimeError`, a `ParseError` that holds the offending raw text.
+
+### Error contract
+
+The call **rejects** only when the stream as a whole cannot be trusted:
+- the response has no body, or no boundary in its `Content-Type`
+- the boundary never appears in the body
+- the stream ends before the closing `--boundary--`, i.e. it was truncated. Parts completed before that point have already been delivered.
+- your callback throws or rejects. The stream is cancelled and the call rejects with your error.
+
+Everything else is reported **per part** and never rejects.
+
+## Testing helpers
+
+`@andyrmitchell/multipart-mixed/testing` builds deterministic batch responses for your own tests, with no timers and no randomness:
+
+```ts
+import { buildMultipartBody, createMultipartResponse, jsonPart, responsePart, googleErrorBody } from '@andyrmitchell/multipart-mixed/testing';
+
+const body = buildMultipartBody([
+    jsonPart('a', '{"id":"a"}'),
+    responsePart('response-b', '429 Too Many Requests', JSON.stringify(googleErrorBody(429, 'rateLimitExceeded', 'Slow down'))),
+]);
+const response = createMultipartResponse(body, { chunkPlan: 'byte-at-a-time' });
+```
+
+`createMultipartResponse` can also simulate truncation (`includeClosingDelimiter: false` on the body), a missing `Content-Type`, zero-length chunks, a failing `cancel()`, and exact chunk split points.
+
+## Scope
+
+Each part is expected to wrap an embedded HTTP reply (`Content-Type: application/http`), which is the shape of Google-style batch responses. Parts with no headers of their own, where the text starts directly at the status line, are also accepted.
+
+## License
+
+MIT

package/dist/chunk-PKBMQBKP.js

@@ -0,0 +1,7 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+export {
+  __publicField
+};

package/dist/index.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Why one part of a batch response could not be read.
+ *
+ * Found on `runtimeError` of a `{parsed: false}` part. It describes malformed *framing or text*
+ * — not a failed sub-request, which parses fine and reports its status in `statusCode`.
+ *
+ * @example
+ * if (!part.parsed && part.runtimeError instanceof ParseError) {
+ *     log(part.runtimeError.message, part.runtimeError.rawItemString.slice(0, 200));
+ * }
+ */
+declare class ParseError extends Error {
+    /** The raw text of the part that could not be read, exactly as received, for diagnosis. */
+    rawItemString: string;
+    constructor(message: string, 
+    /** The raw text of the part that could not be read, exactly as received, for diagnosis. */
+    rawItemString: string);
+}
+
+/**
+ * One part of a multipart/mixed batch response: the reply to a single sub-request.
+ *
+ * In a batch response (e.g. Google's), each part wraps a complete embedded HTTP reply — status
+ * line, headers and body. `parsed` says whether that reply could be read at all:
+ * - `parsed: true` — the reply's fields are available. It may still be a *failed* sub-request
+ *   (check `statusCode`); a parsed part is only a readable part, not a successful one.
+ * - `parsed: false` — the part's text was malformed; `runtimeError` carries the reason and the
+ *   raw text. The rest of the batch is unaffected.
+ *
+ * @example
+ * await streamMultipartParts(response, part => {
+ *     if (!part.parsed) return reportUnreadable(part.runtimeError);
+ *     if (part.statusCode !== 200) return reportFailed(part.contentId, part.statusCode);
+ *     save(part.bodyData);
+ * });
+ */
+type ParsedPart = {
+    parsed: true;
+    /** The Content-ID from the multipart item's headers. */
+    contentId?: string;
+    /** The HTTP status code from the embedded HTTP response (e.g., 200, 304, 404). */
+    statusCode?: number;
+    /**
+     * The Content-Type of the embedded HTTP response's body, exactly as sent — including any
+     * parameters (e.g. "application/json; charset=UTF-8").
+     * Undefined if the embedded response has no Content-Type header.
+     */
+    contentType?: string;
+    /**
+     * The headers of the embedded HTTP response, keyed in lower case.
+     *
+     * These belong to the reply inside the part, not to the part itself, so `Content-ID` — which
+     * labels the part — is never among them. A reply that sent no headers has an empty record.
+     *
+     * @example
+     * // How long a rate-limited part asked the client to wait
+     * const retryAfterMs = parseRetryAfterMs(part.headers['retry-after']);
+     */
+    headers: Record<string, string>;
+    /**
+     * The parsed JSON data from the embedded HTTP response's body.
+     *
+     * It may represent the error details on some status codes.
+     *
+     * Only set when the body parses as a JSON **object**. Undefined if there's no body,
+     * the body is not JSON, or the body is a JSON array/primitive/null — in those cases
+     * the content is still available via `bodyRaw`.
+     *
+     * Every field is `unknown` because the body is external data: narrow it with a type guard,
+     * or validate it with a schema, before reading anything nested.
+     *
+     * @example
+     * // Reading a Google error code without trusting its shape
+     * const error = part.bodyData?.error;
+     * const code = typeof error === 'object' && error !== null && 'code' in error ? error.code : undefined;
+     */
+    bodyData?: Record<string, unknown>;
+    /**
+     * The body (from which `data` is inferred with JSON.parse).
+     *
+     * Useful if it's not application/json, or to explain why the json parse might have failed.
+     */
+    bodyRaw?: string;
+} | {
+    parsed: false;
+    /**
+     * A parsing problem (not a returned data problem - that will be in the status or the data)
+     */
+    runtimeError?: ParseError;
+};
+/**
+ * Receives each part of a batch response as soon as it has been parsed.
+ *
+ * Parts arrive in wire order, one at a time: when the callback returns a promise, the next part
+ * is not delivered until it settles. Throwing (or rejecting) stops the stream and rejects the
+ * surrounding `streamMultipartParts`/`getMultipartParts` call with that error.
+ *
+ * @param part - The parsed part; see {@link ParsedPart} for how to tell success from failure.
+ *
+ * @remarks
+ * Written as a union of a sync and an async signature, rather than one function returning
+ * `void | Promise<void>`, so that a concise arrow whose expression happens to produce a value
+ * (e.g. `part => seen.push(part)`) is still accepted.
+ */
+type OnItemCallback = ((part: ParsedPart) => void) | ((part: ParsedPart) => Promise<void>);
+
+/**
+ * Parses a multipart/mixed HTTP response and returns **all** parts as an array.
+ *
+ * This will buffer every part in memory before resolving.
+ *
+ *
+ * For very large responses where memory is a concern, consider using `streamMultipartParts`
+ * directly with a callback and handling parts one by one.
+ *
+ * @param response - A Fetch API Response whose body is a multipart/mixed stream.
+ * @param onItemCallback - Optional. If provided, called for each part as soon as it’s parsed.
+ * @returns A Promise that resolves to an array of all parsed parts.
+ * @throws {Error} If the response body is not available, if the boundary cannot be determined from
+ *                 the Content-Type header, if the boundary never appears in the body, or if the
+ *                 stream ends before the closing `--boundary--` delimiter (a truncated response).
+ * @example
+ * ```ts
+ * const callbackParts:ParsedPart[] = [];
+ * const parts = await getMultipartParts(response, part => {
+ *   callbackParts.push(part);
+ *   console.log("got part:", part);
+ * });
+ * isEqual(parts, callbackParts); // true (using Lodash's isEqual)
+ * ```
+ */
+declare function getMultipartParts(response: Response, onItemCallback?: OnItemCallback): Promise<ParsedPart[]>;
+/**
+ * Parses a multipart/mixed HTTP response and **streams** each part straight to your callback.
+ *
+ * This never builds a full in-memory array — once a part is parsed it’s emitted, and its bytes
+ * are released from the buffer. Parts are emitted in wire order, and each callback is awaited
+ * before the next part is emitted.
+ *
+ * Framing follows RFC 2046: delimiter lines must start at the beginning of a line (so part
+ * content that merely mentions the boundary text is safe), the preamble before the first
+ * delimiter and the epilogue after the closing `--boundary--` delimiter are ignored, and both
+ * CRLF and bare-LF framing are accepted.
+ *
+ * @param response - A Fetch API Response whose body is a multipart/mixed stream.
+ * @param onItemCallback - Called for each parsed part. If it throws, the stream is cancelled and
+ *                         the returned promise rejects with the callback’s error.
+ * @returns A Promise that resolves when the closing delimiter has been reached and every
+ *          callback has completed.
+ * @throws {Error} If the response has no body, if the multipart boundary cannot be determined
+ *                 from the Content-Type header, if the boundary never appears in the body, or if
+ *                 the stream ends before the closing delimiter (a truncated response). Parts that
+ *                 completed before a truncation point will already have been emitted.
+ * @remarks
+ * Malformed *individual* parts do not throw — they are emitted as `{parsed: false}` values so one
+ * bad part cannot destroy the rest of the batch. Throwing is reserved for whole-stream integrity
+ * failures where continuing would silently lose data.
+ * @example
+ * ```ts
+ * await streamMultipartParts(response, part => {
+ *   saveToDatabase(part);
+ * });
+ * // returns void
+ * ```
+ */
+declare function streamMultipartParts(response: Response, onItemCallback: OnItemCallback): Promise<void>;
+
+export { type OnItemCallback, ParseError, type ParsedPart, getMultipartParts, streamMultipartParts };

package/dist/index.js

@@ -0,0 +1,216 @@
+import {
+  __publicField
+} from "./chunk-PKBMQBKP.js";
+
+// src/part/parseMultipartMixedItem.ts
+var HTTP_STATUS_LINE_REGEX = /^HTTP\/\d+(?:\.\d+)?\s+(\d{3})\b/i;
+function parseMultipartMixedItem(itemString) {
+  try {
+    const normalizedItemString = itemString.replace(/\r\n/g, "\n").replace(/\r/g, "\n").trim();
+    const majorBlockSeparator = "\n\n";
+    const blocks = normalizedItemString.split(majorBlockSeparator);
+    let outerHeaderBlock;
+    if (HTTP_STATUS_LINE_REGEX.test(normalizedItemString)) {
+      outerHeaderBlock = "";
+    } else {
+      if (blocks.length < 2) {
+        return { parsed: false, runtimeError: new ParseError("Malformed item: Missing separator for embedded HTTP response. Expected outer headers and an embedded response.", itemString) };
+      }
+      outerHeaderBlock = blocks.shift();
+    }
+    const firstContentBlockIndex = blocks.findIndex((block) => block.trim());
+    if (firstContentBlockIndex > 0 && HTTP_STATUS_LINE_REGEX.test(blocks[firstContentBlockIndex])) {
+      blocks.splice(0, firstContentBlockIndex);
+    }
+    const embeddedStatusAndHeaderBlock = blocks.shift();
+    if (!embeddedStatusAndHeaderBlock) {
+      return { parsed: false, runtimeError: new ParseError("Malformed embedded response: Missing header block.", itemString) };
+    }
+    const bodyRaw = blocks.join(majorBlockSeparator).trim();
+    const outer = parseHeaderBlock(outerHeaderBlock);
+    let contentId = outer.headers["content-id"];
+    if (contentId && contentId.startsWith("<") && contentId.endsWith(">")) {
+      contentId = contentId.slice(1, -1);
+    }
+    const embedded = parseHeaderBlock(embeddedStatusAndHeaderBlock);
+    let data = void 0;
+    if (bodyRaw) {
+      try {
+        const parsedBody = JSON.parse(bodyRaw);
+        if (isPlainJsonObject(parsedBody)) data = parsedBody;
+      } catch {
+      }
+    }
+    return {
+      parsed: true,
+      contentId,
+      statusCode: embedded.status,
+      contentType: embedded.headers["content-type"],
+      headers: embedded.headers,
+      bodyData: data,
+      bodyRaw
+    };
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    return {
+      parsed: false,
+      runtimeError: new ParseError(message, itemString)
+    };
+  }
+}
+var ParseError = class _ParseError extends Error {
+  constructor(message, rawItemString) {
+    super(message);
+    __publicField(this, "rawItemString", rawItemString);
+    this.name = "ParseError";
+    Object.setPrototypeOf(this, _ParseError.prototype);
+  }
+};
+function isPlainJsonObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseHeaderBlock(headerBlock) {
+  const result = { headers: {} };
+  let lastHeaderKey;
+  for (const rawLine of headerBlock.split("\n")) {
+    if (!rawLine.trim()) continue;
+    if (/^[ \t]/.test(rawLine) && lastHeaderKey) {
+      const valueSoFar = result.headers[lastHeaderKey];
+      result.headers[lastHeaderKey] = valueSoFar ? `${valueSoFar} ${rawLine.trim()}` : rawLine.trim();
+      continue;
+    }
+    const statusMatch = rawLine.match(HTTP_STATUS_LINE_REGEX);
+    if (statusMatch?.[1]) {
+      result.status = parseInt(statusMatch[1], 10);
+      lastHeaderKey = void 0;
+      continue;
+    }
+    const line = rawLine.trim();
+    const colonIndex = line.indexOf(":");
+    if (colonIndex > 0) {
+      const key = line.substring(0, colonIndex).trim().toLowerCase();
+      result.headers[key] = line.substring(colonIndex + 1).trim();
+      lastHeaderKey = key;
+    }
+  }
+  return result;
+}
+
+// src/getMultipartParts.ts
+async function getMultipartParts(response, onItemCallback) {
+  const parts = [];
+  const onItemCallbackWrapped = async (part) => {
+    parts.push(part);
+    if (onItemCallback) await onItemCallback(part);
+  };
+  await streamMultipartParts(response, onItemCallbackWrapped);
+  return parts;
+}
+async function streamMultipartParts(response, onItemCallback) {
+  if (!response.body) {
+    throw new Error("Called getMultipartParts on a Response without a body or on a browser that does not support ReadableStream");
+  }
+  const contentTypeHeader = response.headers.get("content-type");
+  const boundary = extractBoundaryToken(contentTypeHeader);
+  if (!boundary) throw new Error("Could not read boundary marker from Content-Type: " + contentTypeHeader);
+  const dashBoundary = `--${boundary}`;
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let scanFrom = 0;
+  let sawOpeningDelimiter = false;
+  let streamDone = false;
+  const classifyDelimiterAt = (index) => {
+    let i = index + dashBoundary.length;
+    if (i >= buffer.length) return { type: "need-more-data" };
+    if (buffer[i] === "-") {
+      if (i + 1 >= buffer.length) return { type: "need-more-data" };
+      return buffer[i + 1] === "-" ? { type: "closing" } : { type: "not-a-delimiter" };
+    }
+    while (i < buffer.length && (buffer[i] === " " || buffer[i] === "	")) i++;
+    if (i >= buffer.length) return { type: "need-more-data" };
+    if (buffer[i] === "\r") {
+      i++;
+      if (i >= buffer.length) return { type: "need-more-data" };
+    }
+    if (buffer[i] === "\n") return { type: "middle", contentStart: i + 1 };
+    return { type: "not-a-delimiter" };
+  };
+  const scanForDelimiter = () => {
+    let idx = buffer.indexOf(dashBoundary, scanFrom);
+    while (idx !== -1) {
+      const lineAnchored = idx === 0 || buffer[idx - 1] === "\n";
+      if (lineAnchored) {
+        const classification = classifyDelimiterAt(idx);
+        if (classification.type === "need-more-data") {
+          scanFrom = idx;
+          return { type: "need-more-data" };
+        }
+        if (classification.type === "closing") return { type: "closing", index: idx };
+        if (classification.type === "middle") return { type: "middle", index: idx, contentStart: classification.contentStart };
+      }
+      idx = buffer.indexOf(dashBoundary, idx + 1);
+    }
+    scanFrom = Math.max(0, buffer.length - dashBoundary.length - 1);
+    return { type: "need-more-data" };
+  };
+  const emitPart = async (rawPart) => {
+    if (!rawPart.trim()) return;
+    const parsedPart = parseMultipartMixedItem(rawPart);
+    await onItemCallback(parsedPart);
+  };
+  try {
+    readLoop: while (true) {
+      const { value, done } = await reader.read();
+      if (value) buffer += decoder.decode(value, { stream: true });
+      if (done) {
+        buffer += decoder.decode();
+        streamDone = true;
+      }
+      while (true) {
+        const scan = scanForDelimiter();
+        if (scan.type === "need-more-data") {
+          if (!streamDone) continue readLoop;
+          if (!sawOpeningDelimiter) {
+            throw new Error(`Multipart boundary "${dashBoundary}" was never found in the response body. Content-Type was: ${contentTypeHeader}`);
+          }
+          throw new Error("Multipart response ended before the closing boundary delimiter. The response appears to be truncated.");
+        }
+        if (scan.type === "closing") {
+          if (sawOpeningDelimiter) await emitPart(buffer.substring(0, scan.index));
+          buffer = "";
+          if (!streamDone) {
+            await reader.cancel().catch(() => {
+            });
+          }
+          break readLoop;
+        }
+        if (sawOpeningDelimiter) await emitPart(buffer.substring(0, scan.index));
+        sawOpeningDelimiter = true;
+        buffer = buffer.substring(scan.contentStart);
+        scanFrom = 0;
+      }
+    }
+  } catch (e) {
+    await reader.cancel().catch(() => {
+    });
+    throw e;
+  } finally {
+    try {
+      reader.releaseLock();
+    } catch {
+    }
+  }
+}
+function extractBoundaryToken(contentTypeHeader) {
+  if (!contentTypeHeader) return null;
+  const match = contentTypeHeader.match(/boundary\s*=\s*(?:"([^"]*)"|([^;]+))/i);
+  if (!match) return null;
+  const token = (match[1] ?? match[2] ?? "").trim();
+  return token || null;
+}
+export {
+  ParseError,
+  getMultipartParts,
+  streamMultipartParts
+};

package/dist/testing.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Deterministic builders for multipart/mixed `Response` objects in tests.
+ *
+ * `buildMultipartBody` assembles RFC 2046 framing (delimiter lines, optional
+ * preamble/epilogue/closing delimiter) around part strings, and
+ * `createMultipartResponse` wraps a body in a real `Response` whose
+ * `ReadableStream` delivers bytes according to an explicit chunk plan —
+ * no timers, no randomness, so chunk-boundary behavior is reproducible.
+ */
+/** The line ending used for multipart framing: CRLF as the RFC requires, or bare LF as some servers send. */
+type MultipartLineEnding = '\r\n' | '\n';
+type BuildMultipartBodyOptions = {
+    /** Boundary token used in delimiter lines. Defaults to `batch_foobarbaz`. */
+    boundary?: string;
+    /**
+     * Line ending used for all framing; part strings are normalized to it too.
+     * Defaults to CRLF, matching the real wire format.
+     */
+    lineEnding?: MultipartLineEnding;
+    /** Text placed before the first delimiter line (RFC 2046 preamble). */
+    preamble?: string;
+    /** Text placed after the closing delimiter (RFC 2046 epilogue). */
+    epilogue?: string;
+    /**
+     * Emit the final `--boundary--` closing delimiter.
+     * Defaults to true — real servers always send it; set false to simulate truncation.
+     */
+    includeClosingDelimiter?: boolean;
+};
+/**
+ * Assemble a multipart/mixed body string from part contents.
+ *
+ * Each entry in `parts` is the full content of one part (its headers, blank
+ * line, and embedded payload), written with any line endings — they are
+ * normalized to `lineEnding`. The framing around them is exactly what a server
+ * sends, so the result can be fed to `createMultipartResponse` as-is.
+ *
+ * @param parts - The content of each part, in wire order. `responsePart` and `jsonPart` build these.
+ * @param options - Boundary, line ending, preamble/epilogue, and whether to close the body.
+ * @returns The complete body text, from the first delimiter line (or preamble) to the closing
+ *          delimiter (or epilogue).
+ * @example
+ * const body = buildMultipartBody([jsonPart('a', '{"id":"a"}')]);
+ * // '--batch_foobarbaz\r\nContent-Type: application/http\r\n...\r\n--batch_foobarbaz--'
+ *
+ * // A response cut off before its closing delimiter
+ * const truncated = buildMultipartBody([jsonPart('a', '{"id":"a"}')], { includeClosingDelimiter: false });
+ */
+declare function buildMultipartBody(parts: string[], options?: BuildMultipartBodyOptions): string;
+/**
+ * How a test response's body bytes are split into stream chunks.
+ *
+ * - `'single'`: the whole body in one chunk.
+ * - `'byte-at-a-time'`: one chunk per byte, the harshest split possible.
+ * - `{ chunkSize }`: fixed-size chunks; the last may be shorter.
+ * - `{ splitAtBytes }`: split at exact byte offsets (out-of-range or repeated offsets are ignored),
+ *   to land a chunk edge precisely inside a delimiter or a multi-byte character.
+ */
+type ChunkPlan = 'single' | 'byte-at-a-time' | {
+    chunkSize: number;
+} | {
+    splitAtBytes: number[];
+};
+type CreateMultipartResponseOptions = {
+    /** Boundary advertised in the default Content-Type header. Defaults to `batch_foobarbaz`. */
+    boundary?: string;
+    /**
+     * Full Content-Type header value. `null` omits the header entirely.
+     * Defaults to `multipart/mixed; boundary=${boundary}`.
+     */
+    contentType?: string | null;
+    /** How the body bytes are split into stream chunks. Defaults to a single chunk. */
+    chunkPlan?: ChunkPlan;
+    /** Enqueue a zero-length chunk before every data chunk (browsers may deliver these). */
+    interleaveEmptyChunks?: boolean;
+    /** Make the underlying stream's cancel() throw — for testing cancellation error handling. */
+    cancelRejects?: boolean;
+    /**
+     * Called each time the stream hands over a chunk, with the body bytes handed over so far and
+     * the body's total size. Lets a test observe how much of the response existed at the moment
+     * something happened — e.g. that a part reached a consumer before the body was fully read.
+     */
+    onChunkDelivered?: (bytesDeliveredSoFar: number, totalBytes: number) => void;
+};
+/**
+ * Wrap a multipart body in a real `Response` whose stream delivers bytes
+ * according to `chunkPlan`, deterministically (pull-based, no timers).
+ *
+ * A parser under test reads it exactly as it would read a `fetch` result, so
+ * chunk-boundary bugs reproduce on every run instead of depending on the network.
+ *
+ * @param body - The response body, usually from `buildMultipartBody`.
+ * @param options - Content-Type (or its absence), chunk plan, and hooks for
+ *                  observing delivery or forcing `cancel()` to fail.
+ * @returns A `Response` with a streaming body and a `multipart/mixed` Content-Type
+ *          (unless `contentType` overrides it).
+ * @example
+ * const response = createMultipartResponse(body, { chunkPlan: 'byte-at-a-time' });
+ * const parts = await getMultipartParts(response);
+ */
+declare function createMultipartResponse(body: string, options?: CreateMultipartResponseOptions): Response;
+
+/**
+ * Builders for the parts of a Google batch response, in the shape Gmail sends them.
+ *
+ * Every part of a batch response wraps one embedded HTTP reply: the part's own headers
+ * (`Content-Type: application/http`, usually a `Content-ID`), a blank line, then the reply's
+ * status line, headers, a blank line and its body. Building that wire shape in one place means
+ * every test that needs a success, an error or a body-less reply writes it the same way.
+ *
+ * Parts are returned with LF line endings; `buildMultipartBody` normalises them to whichever
+ * line ending the framing uses.
+ */
+/**
+ * Build one batch response part wrapping an embedded HTTP reply.
+ *
+ * @param contentId - The part's `Content-ID`, written exactly as given (Gmail sends it without
+ *                    angle brackets). `null` omits the header, as a misbehaving server might.
+ * @param statusLine - The embedded reply's status after `HTTP/1.1 `, e.g. `'429 Too Many Requests'`.
+ * @param body - The embedded reply's body text. `null` sends a reply with neither a body nor a
+ *               `Content-Type`, as a `204 No Content` does.
+ * @param contentType - The embedded reply's `Content-Type`. Defaults to Gmail's JSON type.
+ * @returns The part's text, ready to pass to `buildMultipartBody`.
+ * @example
+ * buildMultipartBody([
+ *     responsePart('response-a', '200 OK', JSON.stringify({ id: 'a' })),
+ *     responsePart('response-b', '204 No Content', null)
+ * ]);
+ */
+declare function responsePart(contentId: string | null, statusLine: string, body: string | null, contentType?: string): string;
+/**
+ * Build a JSON batch response part whose `Content-ID` is `response-<id>`.
+ *
+ * A shorthand for the commonest part in splitting tests: a JSON reply identified by a short id.
+ *
+ * @param id - Suffix for the part's `Content-ID`; `'a'` gives `response-a`.
+ * @param json - The embedded reply's body, as JSON text.
+ * @param statusLine - The embedded reply's status after `HTTP/1.1 `. Defaults to `'200 OK'`.
+ * @returns The part's text, ready to pass to `buildMultipartBody`.
+ * @example
+ * jsonPart('a', '{"id":"a"}');                              // a 200 whose Content-ID is response-a
+ * jsonPart('b', '{"error":{"code":404}}', '404 Not Found');
+ */
+declare function jsonPart(id: string, json: string, statusLine?: string): string;
+/**
+ * Build the error body a Google API returns alongside a failing status.
+ *
+ * Batch consumers read the `reason` to tell, for example, a rate limit (`rateLimitExceeded`)
+ * from a missing resource, so error tests need this envelope rather than an arbitrary object.
+ *
+ * @param code - The HTTP status the error accompanies, e.g. `429`.
+ * @param reason - Google's machine-readable reason, e.g. `'rateLimitExceeded'`.
+ * @param message - The human-readable message.
+ * @returns `{ error: { errors: [{ domain: 'global', reason, message }], code, message } }`.
+ * @example
+ * responsePart('response-a', '429 Too Many Requests', JSON.stringify(googleErrorBody(429, 'rateLimitExceeded', 'Slow down')));
+ */
+declare function googleErrorBody(code: number, reason: string, message: string): {
+    error: {
+        errors: {
+            domain: string;
+            reason: string;
+            message: string;
+        }[];
+        code: number;
+        message: string;
+    };
+};
+
+export { type BuildMultipartBodyOptions, type ChunkPlan, type CreateMultipartResponseOptions, type MultipartLineEnding, buildMultipartBody, createMultipartResponse, googleErrorBody, jsonPart, responsePart };

package/dist/testing.js

@@ -0,0 +1,104 @@
+import "./chunk-PKBMQBKP.js";
+
+// src/testing/createMultipartResponse.ts
+function buildMultipartBody(parts, options = {}) {
+  const {
+    boundary = "batch_foobarbaz",
+    lineEnding = "\r\n",
+    preamble,
+    epilogue,
+    includeClosingDelimiter = true
+  } = options;
+  const normalize = (s) => s.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n").join(lineEnding);
+  const dashBoundary = `--${boundary}`;
+  let body = "";
+  if (preamble !== void 0) body += normalize(preamble) + lineEnding;
+  for (const part of parts) {
+    body += dashBoundary + lineEnding + normalize(part) + lineEnding;
+  }
+  if (includeClosingDelimiter) {
+    body += dashBoundary + "--";
+    if (epilogue !== void 0) body += lineEnding + normalize(epilogue);
+  }
+  return body;
+}
+function createMultipartResponse(body, options = {}) {
+  const {
+    boundary = "batch_foobarbaz",
+    contentType = `multipart/mixed; boundary=${boundary}`,
+    chunkPlan = "single",
+    interleaveEmptyChunks = false,
+    cancelRejects = false,
+    onChunkDelivered
+  } = options;
+  const bytes = new TextEncoder().encode(body);
+  const dataChunks = splitIntoChunks(bytes, chunkPlan);
+  const chunks = interleaveEmptyChunks ? dataChunks.flatMap((chunk) => [new Uint8Array(0), chunk]) : dataChunks;
+  let nextChunk = 0;
+  let bytesDelivered = 0;
+  const stream = new ReadableStream({
+    pull(controller) {
+      if (nextChunk < chunks.length) {
+        const chunk = chunks[nextChunk];
+        controller.enqueue(chunk);
+        nextChunk++;
+        bytesDelivered += chunk.byteLength;
+        onChunkDelivered?.(bytesDelivered, bytes.length);
+      } else {
+        controller.close();
+      }
+    },
+    cancel() {
+      if (cancelRejects) throw new Error("Underlying source cancel failure");
+    }
+  });
+  const headers = new Headers();
+  if (contentType !== null) headers.set("Content-Type", contentType);
+  return new Response(stream, { headers });
+}
+function splitIntoChunks(bytes, plan) {
+  if (plan === "single") return [bytes];
+  if (plan === "byte-at-a-time") return splitIntoChunks(bytes, { chunkSize: 1 });
+  const out = [];
+  if ("chunkSize" in plan) {
+    for (let i = 0; i < bytes.length; i += plan.chunkSize) {
+      out.push(bytes.subarray(i, i + plan.chunkSize));
+    }
+    return out;
+  }
+  const offsets = [...plan.splitAtBytes].sort((a, b) => a - b);
+  let previous = 0;
+  for (const offset of offsets) {
+    if (offset <= previous || offset >= bytes.length) continue;
+    out.push(bytes.subarray(previous, offset));
+    previous = offset;
+  }
+  out.push(bytes.subarray(previous));
+  return out;
+}
+
+// src/testing/batchResponseParts.ts
+function responsePart(contentId, statusLine, body, contentType = "application/json; charset=UTF-8") {
+  return `Content-Type: application/http${contentId !== null ? `
+Content-ID: ${contentId}` : ""}
+
+HTTP/1.1 ${statusLine}${body !== null ? `
+Content-Type: ${contentType}
+
+${body}` : ""}`;
+}
+function jsonPart(id, json, statusLine = "200 OK") {
+  return responsePart(`response-${id}`, statusLine, json);
+}
+function googleErrorBody(code, reason, message) {
+  return {
+    error: { errors: [{ domain: "global", reason, message }], code, message }
+  };
+}
+export {
+  buildMultipartBody,
+  createMultipartResponse,
+  googleErrorBody,
+  jsonPart,
+  responsePart
+};

package/package.json

@@ -0,0 +1,66 @@
+{
+    "name": "@andyrmitchell/multipart-mixed",
+    "version": "0.1.1",
+    "description": "Streaming parser for multipart/mixed HTTP batch responses (e.g. Google batch APIs), with per-part error isolation and truncation detection.",
+    "type": "module",
+    "sideEffects": false,
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./testing": {
+            "types": "./dist/testing.d.ts",
+            "default": "./dist/testing.js"
+        }
+    },
+    "files": [
+        "dist",
+        "README.md",
+        "LICENSE"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "pkglint": "./build/publint_pipeable.sh",
+        "build_release": "npm run build_prepare && np --no-cleanup",
+        "build_prepare": "npm run build && npm run pkglint",
+        "build": "tsup",
+        "test": "vitest run",
+        "typecheck": "tsc --noEmit",
+        "lint": "eslint .",
+        "prepublishOnly": "npm run typecheck && npm run lint && npm test && npm run build"
+    },
+    "keywords": [
+        "multipart",
+        "multipart/mixed",
+        "batch",
+        "gmail",
+        "google-api",
+        "stream",
+        "parser"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/andymitchell/multipart-mixed.git"
+    },
+    "homepage": "https://github.com/andymitchell/multipart-mixed#readme",
+    "bugs": {
+        "url": "https://github.com/andymitchell/multipart-mixed/issues"
+    },
+    "author": "Andy Mitchell",
+    "license": "MIT",
+    "engines": {
+        "node": ">=18.0.0"
+    },
+    "devDependencies": {
+        "@eslint/js": "^10.0.1",
+        "@types/node": "^25.9.8",
+        "eslint": "^10.4.1",
+        "tsup": "^8.5.1",
+        "typescript": "^6.0.3",
+        "typescript-eslint": "^8.60.1",
+        "vitest": "^4.1.8"
+    }
+}