expediate 1.0.4 → 1.0.6

package/dist/misc.js

@@ -19,28 +19,63 @@
  * DEALINGS IN THE SOFTWARE.
  */
 'use strict';
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.extractCharset = extractCharset;
-exports.readReqBody = readReqBody;
-exports.json = json;
-exports.formData = formData;
-exports.parseBody = parseBody;
-exports.logger = logger;
-exports.cors = cors;
-const zlib_1 = __importDefault(require("zlib"));
+import { Readable } from 'stream';
+import zlib from 'zlib';
+/**
+ * Build a fully-resolved {@link BodyOptions} object, applying defaults for any
+ * unspecified field.  `defaultType` is the parser's natural content type, used
+ * when the caller does not supply `opts.type`.
+ */
+function resolveBodyOptions(opts, defaultType) {
+    return {
+        inflate: opts?.inflate ?? true,
+        limit: opts?.limit ?? '100kb',
+        reviver: opts?.reviver ?? null,
+        strict: opts?.strict ?? true,
+        type: opts?.type ?? defaultType,
+        verify: opts?.verify ?? null,
+    };
+}
+/**
+ * Test whether a request's `Content-Type` matches a {@link BodyTypeMatcher}.
+ * Returns `true` for any request when `matcher` is `null`.
+ */
+function matchesBodyType(req, matcher) {
+    if (matcher === null)
+        return true;
+    if (typeof matcher === 'function')
+        return matcher(req);
+    const actual = ((req.headers['content-type']) ?? '')
+        .split(';')[0].trim().toLowerCase();
+    if (!actual)
+        return false;
+    const patterns = Array.isArray(matcher) ? matcher : [matcher];
+    return patterns.some((pattern) => matchMimePattern(actual, pattern.toLowerCase()));
+}
+/**
+ * Match a concrete media type (e.g. `'application/json'`) against a pattern
+ * that may contain wildcards (`'*\/*'`, `'application/*'`).
+ */
+function matchMimePattern(actual, pattern) {
+    if (pattern === '*/*' || pattern === '*')
+        return true;
+    if (pattern === actual)
+        return true;
+    const [pType, pSub] = pattern.split('/');
+    const [aType] = actual.split('/');
+    return pSub === '*' && pType === aType;
+}
 // ---------------------------------------------------------------------------
 // Decompression algorithm registry
 // ---------------------------------------------------------------------------
 /**
  * Maps a supported `Content-Encoding` value to its corresponding `zlib`
- * decompression function.  Only `gzip` and `deflate` are supported.
+ * decompression function.  `gzip`, `deflate`, and `br` (Brotli) are supported.
  */
 const DECOMPRESS_ALGO = {
-    gzip: zlib_1.default.gunzip,
-    deflate: zlib_1.default.inflate,
+    gzip: zlib.gunzip,
+    deflate: zlib.inflate,
+    br: zlib.brotliDecompress,
 };
 // ---------------------------------------------------------------------------
 // Internal utilities
@@ -70,11 +105,11 @@ function readSize(value) {
         return 0;
     const num = parseFloat(fmt[1] ?? '0');
     const sfx = (fmt[3] ?? 'b').toLowerCase();
-    if (sfx[0] === 'k')
+    if (sfx.startsWith('k'))
         return num * 1024;
-    if (sfx[0] === 'm')
+    if (sfx.startsWith('m'))
         return num * 1024 * 1024;
-    if (sfx[0] === 'g')
+    if (sfx.startsWith('g'))
         return num * 1024 * 1024 * 1024;
     return num;
 }
@@ -112,10 +147,7 @@ function splitBuffer(buffer, delimiter) {
  *                      (e.g. `'text/plain; charset=iso-8859-1'`).
  * @returns A Node.js-compatible encoding name (e.g. `'utf8'`, `'iso-8859-1'`).
  */
-function extractCharset(contentType) {
-    // BUG FIX: the original regex `'s+$` was a literal quote followed by `s+$`
-    // instead of `\s+$`. The trim therefore left leading/trailing whitespace on
-    // every parameter, breaking charset detection. Corrected to `\s+$`.
+export function extractCharset(contentType) {
     const param = contentType
         .split(';')
         .map((s) => s.replace(/^\s+|\s+$/g, ''))
@@ -137,44 +169,46 @@ function extractCharset(contentType) {
  *
  * 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.
+ * `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 type      - Content-type matcher (see {@link BodyTypeMatcher}), 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);
-    // No body declared — skip to next middleware.
-    if (!length || length === 0)
+function readBody(req, res, opts, type, 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;
-    if (length > maxLength)
+    // 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');
+    // When the request's content type does not match, pass through to the next
+    // middleware (Express-compatible composable behaviour).  Returning 415 here
+    // would break parser stacking: json() + formEncoded() + …
+    const contentType = (req.headers['content-type']) ?? '';
+    if (!matchesBodyType(req, type))
+        return next();
     // Stream collection.
     let data = Buffer.alloc(0);
     req.on('data', (chunk) => {
         if (data === null)
             return; // already aborted
-        // BUG FIX: the size check must happen AFTER concatenating the new chunk,
-        // not before. Checking before allowed a stream of (maxLength-1)-byte chunks
-        // to bypass the limit entirely.
-        // BUG FIX: the original code referenced `chink` (typo) instead of `chunk`.
         const next_ = Buffer.concat([data, chunk]);
         if (next_.length > maxLength) {
             data = null;
@@ -187,32 +221,60 @@ function readBody(req, res, opts, mimetype, next, callback) {
         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);
+            const body = decompressed;
+            // Optional verify hook — runs on the raw bytes before parsing. A throw
+            // rejects the request with the error's status (default 403).
+            if (opts.verify) {
+                try {
+                    opts.verify(req, res, body, extractCharset(contentType));
+                }
+                catch (e) {
+                    const status = e.status
+                        ?? e.statusCode ?? 403;
+                    return void res.status(status).send(e.message ?? 'Forbidden');
+                }
+            }
+            callback(contentType, body);
         });
     });
 }
-// TODO
-function readReqBody(req, opts, mimetype) {
+/**
+ * Promise-based body collector used by the `req.json()`, `req.text()`, and
+ * `req.formData()` request helpers.
+ *
+ * @param req      - The incoming request.
+ * @param opts     - Resolved body-parsing options.
+ * @param mimetype - Expected MIME type, or `null` to accept any content type.
+ * @param res      - The outgoing response, required only so an `opts.verify`
+ *                   hook receives the Express-style `(req, res, buf, encoding)`
+ *                   arguments.  When omitted, the verify hook is skipped.
+ * @returns The collected `{ mimetype, content }`, or `null` for an empty body.
+ *          Rejects with `{ status, message }` on size, encoding, type, or
+ *          verify-hook failures.
+ */
+export function readReqBody(req, opts, mimetype, res) {
     return new Promise((resolve, reject) => {
-        const length = parseInt(req.headers['content-length'] ?? '0', 10);
-        // No body declared
-        if (!length || length === 0)
+        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;
-        if (length > maxLength)
+        // 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'] ?? '';
+        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.
@@ -220,10 +282,6 @@ function readReqBody(req, opts, mimetype) {
         req.on('data', (chunk) => {
             if (data === null)
                 return; // already aborted
-            // BUG FIX: the size check must happen AFTER concatenating the new chunk,
-            // not before. Checking before allowed a stream of (maxLength-1)-byte chunks
-            // to bypass the limit entirely.
-            // BUG FIX: the original code referenced `chink` (typo) instead of `chunk`.
             const next_ = Buffer.concat([data, chunk]);
             if (next_.length > maxLength) {
                 data = null;
@@ -236,11 +294,23 @@ function readReqBody(req, opts, mimetype) {
             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 });
+                const body = decompressed;
+                // Optional verify hook — runs on the raw bytes before parsing. A throw
+                // rejects the promise with the error's status (default 403).
+                if (opts.verify && res) {
+                    try {
+                        opts.verify(req, res, body, extractCharset(contentType));
+                    }
+                    catch (e) {
+                        const status = e.status
+                            ?? e.statusCode ?? 403;
+                        return reject({ status, message: e.message ?? 'Forbidden' });
+                    }
+                }
+                resolve({ mimetype: contentType ?? '', content: body });
             });
         });
     });
@@ -288,20 +358,26 @@ function readBodyAsPlainText(req, res, next, contentType, data) {
 function readBodyAsJson(req, res, next, opts, contentType, data) {
     const charset = extractCharset(contentType);
     try {
-        req.body = JSON.parse(data.toString(charset), opts.reviver ?? undefined);
+        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) {
-        res.status(500).send(ex.message);
+        // Invalid JSON is a client error (400), not a server error.
+        res.status(400).send('Bad Request: ' + ex.message);
     }
 }
 /**
- * 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`.
+ * Parse a raw `multipart/form-data` body buffer into an array of
+ * {@link FormPart} objects.
  *
- * On success, calls `next()`.  On failure (missing boundary, malformed parts),
- * sends a 500 Internal Server Error.
+ * 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:**
  * ```
@@ -316,68 +392,118 @@ function readBodyAsJson(req, res, next, opts, contentType, data) {
  * The boundary string in `Content-Type` does **not** include the leading `--`;
  * actual part delimiters on the wire are `\r\n--boundary`.
  *
- * @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.
+ * @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 readBodyAsFormData(req, res, next, contentType, data) {
-    // BUG FIX: the original regex used `'s+$` (literal quote) instead of `\s+$`.
+export 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)
-        return void res.status(400).send('Bad Request: missing multipart boundary');
-    try {
-        // 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.
-        // BUG FIX: the original code passed `buffer` (undefined) instead of `data`.
-        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.
-            // BUG FIX: the original check `buf.length == 2 && buf.toString() == '--'`
-            // was incorrect. After splitting on \r\n--boundary, the terminal entry
-            // is '--\r\n' (or just '--'), not a 2-byte '--'. Use startsWith.
-            if (part.toString('utf8', 0, 2) === '--')
+        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;
-            // 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;
+            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];
             }
-            parts.push({ headers, content });
         }
-        req.body = parts;
+        req.body = result;
         next();
     }
     catch (ex) {
-        res.status(500).send(ex.message);
+        res.status(400).send('Bad Request: ' + ex.message);
     }
 }
 /**
@@ -387,49 +513,34 @@ function readBodyAsFormData(req, res, next, contentType, data) {
 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
+ * Middleware factory that parses an `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`.
+ * - Requests whose `Content-Type` is not `application/json` are also passed
+ *   through to `next()` unchanged, allowing other parsers to handle them
+ *   (Express-compatible composable behaviour).
  * - 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,
-    };
+export function json(opts) {
+    const resolved = resolveBodyOptions(opts, 'application/json');
     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) => {
+        readBody(req, res, resolved, resolved.type, next, (contentType, body) => {
             readBodyAsJson(req, res, next, resolved, contentType, body);
         });
     };
@@ -452,46 +563,71 @@ function json(opts) {
  * @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,
-    };
+export function formData(opts) {
+    const resolved = resolveBodyOptions(opts, 'multipart/form-data');
     return (req, res, next) => {
-        readBody(req, res, resolved, 'multipart/form-data', next, (contentType, body) => {
+        readBody(req, res, resolved, resolved.type, 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**.
+ * - Requests whose `Content-Type` is not `application/x-www-form-urlencoded`
+ *   are passed through to `next()` unchanged (Express-compatible composable behaviour).
+ * - 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[]
+ * });
+ * ```
+ */
+export function formEncoded(opts) {
+    const resolved = resolveBodyOptions(opts, 'application/x-www-form-urlencoded');
+    return (req, res, next) => {
+        readBody(req, res, resolved, resolved.type, 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[]`.
- * - `text/plain`          → decoded as text; result is a string.
+ * - `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} and
- * {@link formData}.
+ * 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,
-    };
+export function parseBody(opts) {
+    // parseBody matches any content type by default (`null`); callers may still
+    // narrow it via `opts.type`.
+    const resolved = resolveBodyOptions(opts, null);
     return (req, res, next) => {
-        readBody(req, res, resolved, null, next, (contentType, body) => {
+        readBody(req, res, resolved, resolved.type, next, (contentType, body) => {
             const mimetype = contentType.split(';')[0].trim();
             if (!BODY_READERS[mimetype])
                 return res.status(415).send('Unsupported Media Type');
@@ -499,6 +635,113 @@ function parseBody(opts) {
         });
     };
 }
+/**
+ * Middleware factory that collects the request body into a `Buffer` and assigns
+ * it to `req.body` without any parsing.
+ *
+ * Behaviour:
+ * - Defaults to handling `application/octet-stream`; override with `opts.type`
+ *   (e.g. `raw({ type: '*\/*' })` to capture every body).
+ * - Requests without a body are passed through to `next()`.
+ * - Requests whose `Content-Type` does not match are passed through unchanged.
+ * - Bodies larger than `opts.limit` receive **413 Content Too Large**.
+ * - Bodies with an unsupported `Content-Encoding` receive
+ *   **415 Unsupported Media Type**.
+ *
+ * @param opts - Optional configuration (see {@link BodyOptions}).
+ * @returns An Express-compatible middleware function.
+ *
+ * @example
+ * ```ts
+ * app.post('/webhook', raw({ type: 'application/json' }), (req, res) => {
+ *   const raw = req.body as Buffer; // untouched bytes
+ *   res.send('ok');
+ * });
+ * ```
+ */
+export function raw(opts) {
+    const resolved = resolveBodyOptions(opts, 'application/octet-stream');
+    return (req, res, next) => {
+        readBody(req, res, resolved, resolved.type, next, (_contentType, body) => {
+            req.body = body;
+            next();
+        });
+    };
+}
+/**
+ * Middleware factory that decodes the request body as text (using the charset
+ * from the `Content-Type` header) and assigns the resulting string to
+ * `req.body`.
+ *
+ * Behaviour:
+ * - Defaults to handling `text/plain`; override with `opts.type`
+ *   (e.g. `text({ type: 'text/*' })`).
+ * - Requests without a body are passed through to `next()`.
+ * - Requests whose `Content-Type` does not match are passed through unchanged.
+ * - Bodies larger than `opts.limit` receive **413 Content Too Large**.
+ * - Decoding errors receive **500 Internal Server Error**.
+ *
+ * @param opts - Optional configuration (see {@link BodyOptions}).
+ * @returns An Express-compatible middleware function.
+ */
+export function text(opts) {
+    const resolved = resolveBodyOptions(opts, 'text/plain');
+    return (req, res, next) => {
+        readBody(req, res, resolved, resolved.type, next, (contentType, body) => {
+            readBodyAsPlainText(req, res, next, 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.
+ */
+export 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: Readable.from(part.content) };
+    }
+}
 // ---------------------------------------------------------------------------
 // Logger middleware
 // ---------------------------------------------------------------------------
@@ -554,7 +797,7 @@ const ANSI_RESET = '\x1b[0m';
  * }));
  * ```
  */
-function logger(opts) {
+export function logger(opts) {
     const options = opts ?? {};
     const log = options.logger ?? console.log;
     const formatter = new Intl.DateTimeFormat(options.locale ?? 'en-GB', options.dateFormat ?? {
@@ -568,9 +811,7 @@ function logger(opts) {
         // 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.headers['x-forwarded-for']
-            ?? req.socket?.remoteAddress
-            ?? '-';
+        const ip = req.ip ?? '';
         const user = options.user?.(req) ?? '-';
         const receivedAt = Date.now();
         // Lost-request tracking.
@@ -601,20 +842,57 @@ function logger(opts) {
                     length: contentLen,
                 });
             else
-                log(`${timestamp} ${statusStr} ${req.method} ${requestPath} ${ip} <${user}> ${elapsed}ms (${contentLen})`);
+                log(`${timestamp} ${statusStr} ${req.method} ${requestPath} ${ip} <${user}> ${elapsed}ms (${String(contentLen)})`);
         });
         next();
     };
 }
-function cors(opts) {
+/**
+ * Resolve the single `Access-Control-Allow-Origin` value for a request, given
+ * the configured {@link CorsOptions.origin} and the request's `Origin` header.
+ *
+ * @param origin        - The configured allow-list (string or array form).
+ * @param requestOrigin - The request's `Origin` header value.
+ * @returns The string to send as `Access-Control-Allow-Origin`, or `undefined`
+ *          when `origin` is an array with no matching entry (the header
+ *          should then be omitted entirely).
+ */
+function resolveAllowOrigin(origin, requestOrigin) {
+    if (typeof origin === 'string')
+        return origin;
+    return origin.includes(requestOrigin) ? requestOrigin : undefined;
+}
+/**
+ * Middleware factory that adds Cross-Origin Resource Sharing (CORS) response
+ * headers and answers `OPTIONS` preflight requests.
+ *
+ * CORS headers are only set when the request carries an `Origin` header
+ * (browser-only; server-to-server requests typically omit it). When
+ * {@link CorsOptions.origin} is an array, the request's `Origin` is matched
+ * against it via {@link resolveAllowOrigin} and only the matching value is
+ * echoed back — see that option's documentation for why a plain array cannot
+ * be passed straight to `res.setHeader()`.
+ *
+ * @param opts - Optional configuration (see {@link CorsOptions}). All fields
+ *               are optional; unset fields fall back to permissive defaults
+ *               (wildcard origin, no credentials, no max-age).
+ * @returns An Express-compatible middleware function.
+ *
+ * @example
+ * ```ts
+ * // Allow exactly two known origins, denying everything else
+ * app.use(cors({ origin: ['https://app.example.com', 'https://admin.example.com'] }));
+ * ```
+ */
+export function cors(opts) {
     const options = {
-        origin: opts?.origin || '*',
-        allowHeaders: opts?.allowHeaders || 'Accept, Content-Type, Authorization',
-        allowMethods: opts?.allowMethods || 'GET,HEAD,PUT,PATCH,POST,DELETE',
+        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,
+        optionsStatus: opts?.optionsStatus ?? 204,
         preflight: opts?.preflight,
     };
     return (req, res, next) => {
@@ -623,9 +901,12 @@ function cors(opts) {
             return;
         }
         if (req.headers.origin) {
-            res.setHeader('Access-Control-Allow-Origin', options.origin);
-            if (options.vary !== undefined)
-                res.setHeader('Vary', options.vary);
+            const allowOrigin = resolveAllowOrigin(options.origin, req.headers.origin);
+            if (allowOrigin !== undefined) {
+                res.setHeader('Access-Control-Allow-Origin', allowOrigin);
+                if (options.vary !== undefined)
+                    res.setHeader('Vary', options.vary);
+            }
         }
         if (req.method == 'OPTIONS') {
             res.setHeader('Access-Control-Allow-Headers', options.allowHeaders);
@@ -640,5 +921,5 @@ function cors(opts) {
         next();
     };
 }
-exports.default = { json, formData, parseBody, logger, cors };
+export default { json, formData, formEncoded, parseBody, logger, cors, streamFormData };
 //# sourceMappingURL=misc.js.map