expediate 1.0.4 → 1.0.5

package/dist/cjs/misc.js

@@ -0,0 +1,787 @@
+/* Copyright 2021 Fabien Bavent
+ *
+ * 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.
+ */
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractCharset = extractCharset;
+exports.readReqBody = readReqBody;
+exports.parseMultipartBody = parseMultipartBody;
+exports.json = json;
+exports.formData = formData;
+exports.formEncoded = formEncoded;
+exports.parseBody = parseBody;
+exports.streamFormData = streamFormData;
+exports.logger = logger;
+exports.cors = cors;
+const stream_1 = require("stream");
+const zlib_1 = require("zlib");
+// ---------------------------------------------------------------------------
+// Decompression algorithm registry
+// ---------------------------------------------------------------------------
+/**
+ * Maps a supported `Content-Encoding` value to its corresponding `zlib`
+ * decompression function.  Only `gzip` and `deflate` are supported.
+ */
+const DECOMPRESS_ALGO = {
+    gzip: zlib_1.default.gunzip,
+    deflate: zlib_1.default.inflate,
+};
+// ---------------------------------------------------------------------------
+// Internal utilities
+// ---------------------------------------------------------------------------
+/**
+ * Parse a human-readable byte-size string into a number of bytes.
+ *
+ * Supported suffixes (case-insensitive): `b`, `kb`, `mb`, `gb`.
+ * The suffix is optional; a bare number is treated as bytes.
+ *
+ * @param value - The size string to parse (e.g. `'100kb'`, `'2.5mb'`).
+ * @returns The size in bytes, or `0` if the input cannot be parsed.
+ *
+ * @example
+ * ```ts
+ * readSize('100kb')  // 102400
+ * readSize('2mb')    // 2097152
+ * readSize('1024')   // 1024
+ * readSize('bad')    // 0
+ * ```
+ */
+function readSize(value) {
+    if (typeof value === 'number')
+        return value;
+    const fmt = /^(\d+(\.\d+)?)([kmg]?b?)?$/i.exec(value);
+    if (!fmt)
+        return 0;
+    const num = parseFloat(fmt[1] ?? '0');
+    const sfx = (fmt[3] ?? 'b').toLowerCase();
+    if (sfx[0] === 'k')
+        return num * 1024;
+    if (sfx[0] === 'm')
+        return num * 1024 * 1024;
+    if (sfx[0] === 'g')
+        return num * 1024 * 1024 * 1024;
+    return num;
+}
+/**
+ * Split a `Buffer` on every occurrence of a `delimiter` buffer, returning an
+ * array of sub-buffers between delimiters (the delimiters themselves are not
+ * included in the output).
+ *
+ * Behaves like `String.prototype.split` but operates on raw binary data,
+ * making it safe for multipart bodies that may contain arbitrary byte
+ * sequences.
+ *
+ * @param buffer    - The source buffer to split.
+ * @param delimiter - The byte sequence to split on.
+ * @returns An array of buffer slices; always contains at least one element.
+ */
+function splitBuffer(buffer, delimiter) {
+    const result = [];
+    let start = 0;
+    let index;
+    while ((index = buffer.indexOf(delimiter, start)) !== -1) {
+        result.push(buffer.slice(start, index));
+        start = index + delimiter.length;
+    }
+    result.push(buffer.slice(start));
+    return result;
+}
+/**
+ * Extract the `charset` parameter from a `Content-Type` header value.
+ *
+ * Handles optional whitespace around the semicolon-separated parameters.
+ * Falls back to `'utf8'` when no `charset` parameter is found.
+ *
+ * @param contentType - The raw `Content-Type` header value
+ *                      (e.g. `'text/plain; charset=iso-8859-1'`).
+ * @returns A Node.js-compatible encoding name (e.g. `'utf8'`, `'iso-8859-1'`).
+ */
+function extractCharset(contentType) {
+    const param = contentType
+        .split(';')
+        .map((s) => s.replace(/^\s+|\s+$/g, ''))
+        .find((s) => s.startsWith('charset='));
+    return param ? param.substring('charset='.length) : 'utf8';
+}
+// ---------------------------------------------------------------------------
+// Body collection
+// ---------------------------------------------------------------------------
+/**
+ * Collect the full request body into a single `Buffer`, enforce size limits,
+ * optionally decompress, and validate the `Content-Type` against an expected
+ * MIME type.
+ *
+ * When the body is successfully collected and validated, `callback` is invoked
+ * with the raw `Content-Type` header value and the (possibly decompressed)
+ * body buffer.  In all error cases the appropriate HTTP error response is sent
+ * and `callback` is never called.
+ *
+ * Callers that need to pass control to the next middleware when there is no
+ * body should rely on the `next()` call that this function makes when
+ * `Content-Length` is `0` or absent and `Transfer-Encoding` is not `chunked`.
+ *
+ * @param req       - The incoming request.
+ * @param res       - The outgoing response.
+ * @param opts      - Resolved body-parsing options.
+ * @param mimetype  - Expected MIME type (e.g. `'application/json'`), or `null`
+ *                    to accept any content type.
+ * @param next      - The next middleware callback; called when the body is
+ *                    empty or absent.
+ * @param callback  - Invoked with `(contentType, body)` on success.
+ */
+function readBody(req, res, opts, mimetype, next, callback) {
+    const length = parseInt(req.headers['content-length'] ?? '0', 10);
+    // Detect chunked transfer encoding — no Content-Length is present in this case.
+    const isChunked = req.headers['transfer-encoding']
+        ?.split(',').map((v) => v.trim()).some((v) => v.toLowerCase() === 'chunked') ?? false;
+    // No body declared and not chunked — skip to next middleware.
+    if (!isChunked && (!length || length === 0))
+        return next();
+    const maxLength = readSize(opts.limit) || 102_400;
+    // For requests with a known Content-Length we can reject upfront.
+    if (!isChunked && length > maxLength)
+        return void res.status(413).send('Content Too Large');
+    // Compression handling.
+    const encoding = req.headers['content-encoding'];
+    if (encoding && (opts.inflate === false || !DECOMPRESS_ALGO[encoding]))
+        return void res.status(415).send('Unsupported Media Type: Wrong Content-Encoding');
+    // eslint-disable-next-line @typescript-eslint/ban-types
+    const decompress = (encoding ? DECOMPRESS_ALGO[encoding] : undefined) ?? ((d, c) => c(null, d));
+    // Content-Type validation.
+    const contentType = req.headers['content-type'] ?? '';
+    if (mimetype && contentType.split(';')[0].trim() !== mimetype)
+        return void res.status(415).send('Unsupported Media Type: Wrong Content-Type');
+    // Stream collection.
+    let data = Buffer.alloc(0);
+    req.on('data', (chunk) => {
+        if (data === null)
+            return; // already aborted
+        const next_ = Buffer.concat([data, chunk]);
+        if (next_.length > maxLength) {
+            data = null;
+            res.status(413).send('Content Too Large');
+            return;
+        }
+        data = next_;
+    });
+    req.on('end', () => {
+        if (data === null)
+            return; // aborted during streaming
+        // zlib types require NonSharedBuffer; Buffer satisfies this at runtime.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        decompress(data, (err, decompressed) => {
+            if (err)
+                return void res.status(500).send(err.message);
+            callback(contentType, decompressed);
+        });
+    });
+}
+// TODO
+function readReqBody(req, opts, mimetype) {
+    return new Promise((resolve, reject) => {
+        const length = parseInt(req.headers['content-length'] ?? '0', 10);
+        // Detect chunked transfer encoding — no Content-Length is present in this case.
+        const isChunked = req.headers['transfer-encoding']
+            ?.split(',').map((v) => v.trim()).some((v) => v.toLowerCase() === 'chunked') ?? false;
+        // No body declared and not chunked — resolve with null.
+        if (!isChunked && (!length || length === 0))
+            return resolve(null);
+        const maxLength = readSize(opts.limit) || 102_400;
+        // For requests with a known Content-Length we can reject upfront.
+        if (!isChunked && length > maxLength)
+            return reject({ status: 413, message: 'Content Too Large' });
+        // Compression handling.
+        const encoding = req.headers['content-encoding'];
+        if (encoding && (opts.inflate === false || !DECOMPRESS_ALGO[encoding]))
+            return reject({ status: 415, message: 'Unsupported Media Type: Wrong Content-Encoding' });
+        // eslint-disable-next-line @typescript-eslint/ban-types
+        const decompress = (encoding ? DECOMPRESS_ALGO[encoding] : undefined) ?? ((d, c) => c(null, d));
+        // Content-Type validation.
+        const contentType = req.headers['content-type'] ?? '';
+        if (mimetype && contentType.split(';')[0].trim() !== mimetype)
+            return reject({ status: 415, message: 'Unsupported Media Type: Wrong Content-Type' });
+        // Stream collection.
+        let data = Buffer.alloc(0);
+        req.on('data', (chunk) => {
+            if (data === null)
+                return; // already aborted
+            const next_ = Buffer.concat([data, chunk]);
+            if (next_.length > maxLength) {
+                data = null;
+                reject({ status: 413, message: 'Content Too Large' });
+                return;
+            }
+            data = next_;
+        });
+        req.on('end', () => {
+            if (data === null)
+                return; // aborted during streaming
+            // zlib types require NonSharedBuffer; Buffer satisfies this at runtime.
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            decompress(data, (err, decompressed) => {
+                if (err)
+                    return reject({ status: 500, message: err.message });
+                resolve({ mimetype: contentType ?? '', content: decompressed });
+            });
+        });
+    });
+}
+// ---------------------------------------------------------------------------
+// Body parsers
+// ---------------------------------------------------------------------------
+/**
+ * Parse a collected body buffer as plain text, decode it using the charset
+ * declared in `contentType`, and assign the result to `req.body`.
+ *
+ * On success, calls `next()`.  On failure, sends a 500 Internal Server Error.
+ *
+ * @param req         - The incoming request (mutated: `req.body` is set).
+ * @param res         - The outgoing response.
+ * @param next        - Called on successful parsing.
+ * @param contentType - The raw `Content-Type` header value.
+ * @param data        - The raw body buffer.
+ */
+function readBodyAsPlainText(req, res, next, contentType, data) {
+    const charset = extractCharset(contentType);
+    try {
+        req.body = data.toString(charset);
+        next();
+    }
+    catch (ex) {
+        res.status(500).send(ex.message);
+    }
+}
+/**
+ * Parse a collected body buffer as JSON, decode it using the charset declared
+ * in `contentType`, apply an optional `reviver`, and assign the result to
+ * `req.body`.
+ *
+ * On success, calls `next()`.  On failure (invalid JSON or unsupported charset),
+ * sends a 500 Internal Server Error.
+ *
+ * @param req         - The incoming request (mutated: `req.body` is set).
+ * @param res         - The outgoing response.
+ * @param next        - Called on successful parsing.
+ * @param opts        - Resolved options; `opts.reviver` is passed to `JSON.parse`.
+ * @param contentType - The raw `Content-Type` header value.
+ * @param data        - The raw body buffer.
+ */
+function readBodyAsJson(req, res, next, opts, contentType, data) {
+    const charset = extractCharset(contentType);
+    try {
+        const parsed = JSON.parse(data.toString(charset), opts.reviver ?? undefined);
+        // FIX-10: strict mode — reject bare primitives (strings, numbers, booleans)
+        // at the top level; only objects and arrays are accepted.
+        if (opts.strict && (typeof parsed !== 'object' || parsed === null)) {
+            return void res.status(400).send('Bad Request: JSON body must be an object or array');
+        }
+        req.body = parsed;
+        next();
+    }
+    catch (ex) {
+        // Invalid JSON is a client error (400), not a server error.
+        res.status(400).send('Bad Request: ' + ex.message);
+    }
+}
+/**
+ * Parse a raw `multipart/form-data` body buffer into an array of
+ * {@link FormPart} objects.
+ *
+ * This is the shared parsing kernel used by both the {@link formData}
+ * middleware and the `req.formData()` extension method on the request object.
+ *
+ * **Multipart wire format recap:**
+ * ```
+ * --boundary\r\n
+ * Header: value\r\n
+ * \r\n
+ * <binary content>
+ * --boundary\r\n
+ * ...
+ * --boundary--\r\n
+ * ```
+ * The boundary string in `Content-Type` does **not** include the leading `--`;
+ * actual part delimiters on the wire are `\r\n--boundary`.
+ *
+ * @param contentType - The raw `Content-Type` header value (must include
+ *                      `boundary=<value>`).
+ * @param data        - The fully-collected raw body buffer.
+ * @returns An array of parsed {@link FormPart} objects.
+ * @throws `{ status: 400, message }` when the `boundary` parameter is absent.
+ */
+function parseMultipartBody(contentType, data) {
+    const boundary = contentType
+        .split(';')
+        .map((s) => s.replace(/^\s+|\s+$/g, ''))
+        .find((s) => s.startsWith('boundary='))
+        ?.substring('boundary='.length);
+    if (!boundary)
+        throw { status: 400, message: 'Bad Request: missing multipart boundary' };
+    // Wire-level delimiter: each part (after the preamble) is preceded by
+    // \r\n--boundary.  We split on this sequence so every resulting slice is
+    // the raw content of one part (headers + blank line + body), without any
+    // leading delimiter bytes.
+    const delimiter = Buffer.from(`\r\n--${boundary}`);
+    // Prepend \r\n so the very first part is also cleanly split.
+    const normalized = Buffer.concat([Buffer.from('\r\n'), data]);
+    const rawParts = splitBuffer(normalized, delimiter);
+    const parts = [];
+    for (const part of rawParts) {
+        // The closing delimiter ends with '--'; skip it.
+        if (part.toString('utf8', 0, 2) === '--')
+            continue;
+        // Each part begins with \r\n (from after the delimiter), then headers,
+        // then \r\n\r\n (blank line), then content.
+        // Skip the leading \r\n.
+        const partContent = part.slice(2);
+        const blankLine = Buffer.from('\r\n\r\n');
+        const blankIdx = partContent.indexOf(blankLine);
+        if (blankIdx === -1)
+            continue; // malformed part — skip
+        const headerSection = partContent.slice(0, blankIdx).toString('utf8');
+        const content = partContent.slice(blankIdx + blankLine.length);
+        const headers = {};
+        for (const line of headerSection.split('\r\n')) {
+            if (!line)
+                continue;
+            const colonIdx = line.indexOf(':');
+            if (colonIdx === -1)
+                continue;
+            const key = line.substring(0, colonIdx).replace(/^\s+|\s+$/g, '').toLowerCase();
+            const value = line.substring(colonIdx + 1).replace(/^\s+|\s+$/g, '');
+            headers[key] = value;
+        }
+        parts.push({ headers, content });
+    }
+    return parts;
+}
+/**
+ * Parse a collected body buffer as `multipart/form-data`, split it on the
+ * boundary declared in `contentType`, parse each part's headers, and assign
+ * an array of {@link FormPart} objects to `req.body`.
+ *
+ * On success, calls `next()`.  On failure (missing boundary, malformed parts),
+ * sends the appropriate HTTP error.
+ *
+ * @param req         - The incoming request (mutated: `req.body` is set).
+ * @param res         - The outgoing response.
+ * @param next        - Called on successful parsing.
+ * @param contentType - The raw `Content-Type` header value (must include
+ *                      `boundary=<value>`).
+ * @param data        - The raw body buffer.
+ */
+function readBodyAsFormData(req, res, next, contentType, data) {
+    try {
+        req.body = parseMultipartBody(contentType, data);
+        next();
+    }
+    catch (ex) {
+        const status = ex.status ?? 500;
+        res.status(status).send(ex.message ?? String(ex));
+    }
+}
+/**
+ * Parse a collected body buffer as `application/x-www-form-urlencoded` and
+ * assign the result to `req.body`.
+ *
+ * Repeated keys (e.g. `tags=a&tags=b`) produce an array value:
+ * `{ tags: ['a', 'b'] }`.  Single-occurrence keys produce a plain string.
+ *
+ * @param req         - The incoming request (mutated: `req.body` is set).
+ * @param res         - The outgoing response.
+ * @param next        - Called on successful parsing.
+ * @param contentType - The raw `Content-Type` header value.
+ * @param data        - The raw body buffer.
+ */
+function readBodyAsFormEncoded(req, res, next, contentType, data) {
+    const charset = extractCharset(contentType);
+    try {
+        const params = new URLSearchParams(data.toString(charset));
+        const result = {};
+        for (const [key, value] of params.entries()) {
+            const existing = result[key];
+            if (existing === undefined) {
+                result[key] = value;
+            }
+            else if (Array.isArray(existing)) {
+                existing.push(value);
+            }
+            else {
+                result[key] = [existing, value];
+            }
+        }
+        req.body = result;
+        next();
+    }
+    catch (ex) {
+        res.status(400).send('Bad Request: ' + ex.message);
+    }
+}
+/**
+ * Dispatch table mapping a MIME type to its body-parser function.
+ * Used by {@link parseBody} to select the appropriate parser at runtime.
+ */
+const BODY_READERS = {
+    'multipart/form-data': (req, res, next, _opts, ct, data) => readBodyAsFormData(req, res, next, ct, data),
+    'application/json': (req, res, next, opts, ct, data) => readBodyAsJson(req, res, next, opts, ct, data),
+    'application/x-www-form-urlencoded': (req, res, next, _opts, ct, data) => readBodyAsFormEncoded(req, res, next, ct, data),
+    'text/plain': (req, res, next, _opts, ct, data) => readBodyAsPlainText(req, res, next, ct, data),
+};
+// ---------------------------------------------------------------------------
+// Public middleware factories
+// ---------------------------------------------------------------------------
+/**
+ * Middleware factory that parses a `application/json` request body and
+ * assigns the parsed value to `req.body`.
+ *
+ * Also attaches a `res.json(data)` helper to the response object so that
+ * handlers can send JSON responses conveniently:
+ * ```ts
+ * res.json({ ok: true });
+ * ```
+ *
+ * Behaviour:
+ * - Requests without a body (`Content-Length: 0` or absent) are passed
+ *   through to `next()` without touching `req.body`.
+ * - Bodies larger than `opts.limit` receive **413 Content Too Large**.
+ * - Bodies with an unsupported `Content-Encoding` receive
+ *   **415 Unsupported Media Type**.
+ * - Bodies whose `Content-Type` is not `application/json` receive
+ *   **415 Unsupported Media Type**.
+ * - Parse errors receive **500 Internal Server Error**.
+ *
+ * @param opts - Optional configuration (see {@link BodyOptions}).
+ * @returns An Express-compatible middleware function.
+ */
+function json(opts) {
+    const resolved = {
+        inflate: true,
+        limit: '100kb',
+        reviver: null,
+        strict: true,
+        ...opts,
+    };
+    return (req, res, next) => {
+        // Attach a JSON response helper so handlers can call res.json(data).
+        res.json = (data) => {
+            res.write(JSON.stringify(data));
+            res.end();
+        };
+        readBody(req, res, resolved, 'application/json', next, (contentType, body) => {
+            readBodyAsJson(req, res, next, resolved, contentType, body);
+        });
+    };
+}
+/**
+ * Middleware factory that parses a `multipart/form-data` request body and
+ * assigns an array of {@link FormPart} objects to `req.body`.
+ *
+ * Each element in `req.body` exposes:
+ * - `headers` — the part's MIME headers (e.g. `Content-Disposition`).
+ * - `content` — the raw binary content of the part as a `Buffer`.
+ *
+ * Behaviour:
+ * - Requests without a body are passed through to `next()`.
+ * - Bodies larger than `opts.limit` receive **413 Content Too Large**.
+ * - Bodies with a missing or malformed `boundary` parameter receive
+ *   **400 Bad Request**.
+ * - Parse errors receive **500 Internal Server Error**.
+ *
+ * @param opts - Optional configuration (see {@link BodyOptions}).
+ * @returns An Express-compatible middleware function.
+ */
+function formData(opts) {
+    const resolved = {
+        inflate: true,
+        limit: '100kb',
+        reviver: null,
+        strict: true,
+        ...opts,
+    };
+    return (req, res, next) => {
+        readBody(req, res, resolved, 'multipart/form-data', next, (contentType, body) => {
+            readBodyAsFormData(req, res, next, contentType, body);
+        });
+    };
+}
+/**
+ * Middleware factory that parses an `application/x-www-form-urlencoded`
+ * request body and assigns the decoded fields to `req.body`.
+ *
+ * Repeated keys (e.g. `tags=a&tags=b`) produce an array value:
+ * `{ tags: ['a', 'b'] }`.  Single-occurrence keys produce a plain string.
+ *
+ * Behaviour:
+ * - Requests without a body are passed through to `next()`.
+ * - Bodies larger than `opts.limit` receive **413 Content Too Large**.
+ * - Bodies whose `Content-Type` is not `application/x-www-form-urlencoded`
+ *   receive **415 Unsupported Media Type**.
+ * - Parse errors receive **400 Bad Request**.
+ *
+ * @param opts - Optional configuration (see {@link BodyOptions}).
+ * @returns An Express-compatible middleware function.
+ *
+ * @example
+ * ```ts
+ * app.post('/form', formEncoded(), (req, res) => {
+ *   const { username, tags } = req.body as any;
+ *   res.json({ username, tags }); // tags may be string | string[]
+ * });
+ * ```
+ */
+function formEncoded(opts) {
+    const resolved = {
+        inflate: true,
+        limit: '100kb',
+        reviver: null,
+        strict: true,
+        ...opts,
+    };
+    return (req, res, next) => {
+        readBody(req, res, resolved, 'application/x-www-form-urlencoded', next, (contentType, body) => {
+            readBodyAsFormEncoded(req, res, next, contentType, body);
+        });
+    };
+}
+/**
+ * Middleware factory that auto-detects the `Content-Type` of the request body
+ * and parses it using the appropriate parser.
+ *
+ * Supported MIME types:
+ * - `application/json`                  → parsed as JSON; result is a JS value.
+ * - `multipart/form-data`               → parsed as multipart; result is `FormPart[]`.
+ * - `application/x-www-form-urlencoded` → decoded as key/value pairs; result is
+ *                                         `Record<string, string | string[]>`.
+ * - `text/plain`                        → decoded as text; result is a string.
+ *
+ * Requests with an unsupported MIME type receive **415 Unsupported Media Type**.
+ * All other error conditions behave identically to {@link json}, {@link formData},
+ * and {@link formEncoded}.
+ *
+ * @param opts - Optional configuration (see {@link BodyOptions}).
+ * @returns An Express-compatible middleware function.
+ */
+function parseBody(opts) {
+    const resolved = {
+        inflate: true,
+        limit: '100kb',
+        reviver: null,
+        strict: true,
+        ...opts,
+    };
+    return (req, res, next) => {
+        readBody(req, res, resolved, null, next, (contentType, body) => {
+            const mimetype = contentType.split(';')[0].trim();
+            if (!BODY_READERS[mimetype])
+                return res.status(415).send('Unsupported Media Type');
+            BODY_READERS[mimetype](req, res, next, resolved, contentType, body);
+        });
+    };
+}
+/**
+ * Async generator that yields each part of a `multipart/form-data` request
+ * body as a {@link FormPartStream} object.
+ *
+ * Unlike {@link formData} (which must be installed as middleware before a
+ * handler), `streamFormData` can be called directly inside any handler and
+ * returns an async iterable of parts:
+ *
+ * ```ts
+ * app.post('/upload', async (req, res) => {
+ *   for await (const part of streamFormData(req)) {
+ *     const name = part.headers['content-disposition'];
+ *     const chunks: Buffer[] = [];
+ *     for await (const chunk of part.stream) chunks.push(chunk);
+ *     const content = Buffer.concat(chunks);
+ *     // ... process content
+ *   }
+ *   res.send('ok');
+ * });
+ * ```
+ *
+ * **Note:** the full request body is buffered before parts are yielded,
+ * because the multipart boundary must span the entire body.  For very large
+ * uploads, prefer streaming directly from the raw request.
+ *
+ * @param req  - The incoming request (must be a `multipart/form-data` request).
+ * @param opts - Optional configuration — only `limit` and `inflate` are used.
+ * @throws `{ status: 400, message }` when the `boundary` parameter is absent.
+ * @throws `{ status: 413, message }` when the body exceeds the size limit.
+ */
+async function* streamFormData(req, opts) {
+    const maxSize = (opts?.limit !== undefined ? readSize(opts.limit) : 0) || 102_400;
+    // Collect all chunks from the raw request stream.
+    const chunks = [];
+    let totalSize = 0;
+    for await (const chunk of req) {
+        totalSize += chunk.length;
+        if (totalSize > maxSize)
+            throw { status: 413, message: 'Content Too Large' };
+        chunks.push(chunk);
+    }
+    const body = Buffer.concat(chunks);
+    const contentType = req.headers['content-type'] ?? '';
+    const parts = parseMultipartBody(contentType, body);
+    for (const part of parts) {
+        // Expose each part's Buffer content as a Readable stream so callers can
+        // pipe, pipeline, or iterate it uniformly.
+        yield { headers: part.headers, stream: stream_1.Readable.from(part.content) };
+    }
+}
+// ---------------------------------------------------------------------------
+// Logger middleware
+// ---------------------------------------------------------------------------
+/**
+ * ANSI terminal colour codes indexed by HTTP status class (1xx–5xx).
+ *
+ * Index 0 is unused (no HTTP 0xx class).
+ * - 1xx → yellow  (`\x1b[33m`)
+ * - 2xx → green   (`\x1b[32m`)
+ * - 3xx → yellow  (`\x1b[33m`)
+ * - 4xx → red     (`\x1b[31m`)
+ * - 5xx → bright red (`\x1b[91m`)
+ */
+const STATUS_COLORS = [
+    '\x1b[0m', // 0 — fallback / unknown
+    '\x1b[33m', // 1xx — informational (yellow)
+    '\x1b[32m', // 2xx — success (green)
+    '\x1b[33m', // 3xx — redirection (yellow)
+    '\x1b[31m', // 4xx — client error (red)
+    '\x1b[91m', // 5xx — server error (bright red)
+];
+/** ANSI reset escape sequence. */
+const ANSI_RESET = '\x1b[0m';
+/**
+ * Middleware factory that logs one line per completed HTTP request to the
+ * console (or a custom logger function).
+ *
+ * Each log line contains:
+ * - Timestamp (formatted with `Intl.DateTimeFormat`).
+ * - HTTP status code (ANSI-coloured by status class).
+ * - HTTP method and request path.
+ * - Client IP address (honours `X-Forwarded-For`).
+ * - User identity (from `opts.user` or `'-'`).
+ * - Elapsed time in milliseconds.
+ * - Response `Content-Length` (or `'-'` when absent).
+ *
+ * **Lost-request tracking:** when `opts.track` is `true`, a timer is started
+ * for each request.  If the response is not finished within `opts.trackTimeout`
+ * milliseconds, a `LOST` warning line is emitted.  This is useful in
+ * development to surface handlers that never call `res.end()`.
+ *
+ * @param opts - Optional configuration (see {@link LoggerOptions}).
+ * @returns An Express-compatible middleware function.
+ *
+ * @example
+ * ```ts
+ * app.use('/', logger({
+ *   track:        true,
+ *   trackTimeout: 30_000,
+ *   user:         (req) => (req as any).authUser ?? '-',
+ *   locale:       'en-US',
+ *   logger:       (msg) => process.stderr.write(msg + '\n'),
+ * }));
+ * ```
+ */
+function logger(opts) {
+    const options = opts ?? {};
+    const log = options.logger ?? console.log;
+    const formatter = new Intl.DateTimeFormat(options.locale ?? 'en-GB', options.dateFormat ?? {
+        month: 'short',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+    });
+    return (req, res, next) => {
+        // Capture timestamp and path at request-arrival time so they are stable
+        // even if later middleware mutates req.path (e.g. prefix stripping).
+        const timestamp = formatter.format(new Date());
+        const requestPath = req.path ?? req.url ?? '/';
+        const ip = req.ip ?? '';
+        const user = options.user?.(req) ?? '-';
+        const receivedAt = Date.now();
+        // Lost-request tracking.
+        const tracker = options.track === true
+            ? setTimeout(() => {
+                log(`${timestamp} LOST ${req.method} ${requestPath} ${ip} <${user}>`);
+            }, options.trackTimeout ?? 30_000)
+            : null;
+        res.on('finish', () => {
+            if (tracker !== null)
+                clearTimeout(tracker);
+            const host = req.headers.host;
+            const elapsed = Date.now() - receivedAt;
+            const statusClass = Math.floor(res.statusCode / 100);
+            const colour = STATUS_COLORS[statusClass] ?? STATUS_COLORS[0];
+            const statusStr = `${colour}${res.statusCode}${ANSI_RESET}`;
+            const contentLen = res.getHeader('content-length') ?? '-';
+            if (options.json === true)
+                log({
+                    timestamp,
+                    status: res.statusCode,
+                    method: req.method,
+                    path: requestPath,
+                    ip,
+                    user,
+                    elapsed,
+                    host,
+                    length: contentLen,
+                });
+            else
+                log(`${timestamp} ${statusStr} ${req.method} ${requestPath} ${ip} <${user}> ${elapsed}ms (${contentLen})`);
+        });
+        next();
+    };
+}
+function cors(opts) {
+    const options = {
+        origin: opts?.origin || '*',
+        allowHeaders: opts?.allowHeaders || 'Accept, Content-Type, Authorization',
+        allowMethods: opts?.allowMethods || 'GET,HEAD,PUT,PATCH,POST,DELETE',
+        allowCredentials: opts?.allowCredentials,
+        maxAge: opts?.maxAge,
+        vary: opts?.vary,
+        optionsStatus: opts?.optionsStatus || 204,
+        preflight: opts?.preflight,
+    };
+    return (req, res, next) => {
+        if (options.preflight && !options.preflight(req)) {
+            res.status(req.method == 'OPTIONS' ? 403 : 400).end();
+            return;
+        }
+        if (req.headers.origin) {
+            res.setHeader('Access-Control-Allow-Origin', options.origin);
+            if (options.vary !== undefined)
+                res.setHeader('Vary', options.vary);
+        }
+        if (req.method == 'OPTIONS') {
+            res.setHeader('Access-Control-Allow-Headers', options.allowHeaders);
+            res.setHeader('Access-Control-Allow-Methods', options.allowMethods);
+            if (options.allowCredentials !== undefined)
+                res.setHeader('Access-Control-Allow-Credentials', options.allowCredentials ? 'true' : 'false');
+            if (options.maxAge !== undefined)
+                res.setHeader('Access-Control-Max-Age', options.maxAge.toFixed(0));
+            res.status(options.optionsStatus).end();
+            return;
+        }
+        next();
+    };
+}
+exports.default = { json, formData, formEncoded, parseBody, logger, cors, streamFormData };