fulmine.js 5.19.3 → 5.19.5

package/src/middlewares.js

@@ -26,6 +26,7 @@ const mime = require("mime-types");
 const compressible = require("compressible");
 const ms = require("ms");
 const qs = require("qs");
+const statuses = require("statuses");
 const parseQuery = require("./parse-query.js");
 const { kGetSafe } = require("./usage.js");
 const { AsyncResource } = require("async_hooks");
@@ -48,6 +49,7 @@ const {
     NullObject,
     asStatError,
     httpError,
+    httpErrorName,
     memoizeByString,
     containsDotFile,
     negotiateEncoding,
@@ -74,6 +76,26 @@ const PRECOMPRESSED = [
 
 /** @typedef {import("./request.js")} Request */
 /** @typedef {import("./response.js")} Response */
+/** @typedef {import("./utils.js").HttpError} HttpError */
+/** @typedef {import("./options").BodyParserOptions} BodyParserOptions */
+/**
+ * A decompressor from fast-zlib, carrying the flag its final flush passes, see createInflate.
+ * @typedef {(import("fast-zlib").Inflate|import("fast-zlib").Gunzip|import("fast-zlib").BrotliDecompress)
+ *   & {_finishFlag?: number}} Inflater
+ */
+/**
+ * What a parser does with the collected bytes: turns them into req.body and carries on. `body` is
+ * deliberately not a field of Request, see the comment there, so it is added here. The charset is
+ * undefined only for raw, which never decodes: the others settle it before a byte is read.
+ * @typedef {(
+ *   req: Request & {body?: unknown},
+ *   res: Response,
+ *   next: (err?: unknown) => void,
+ *   options: BodyParserOptions,
+ *   buf: Buffer,
+ *   encoding: string|undefined
+ * ) => void} BodyHandler
+ */
 
 // The failures express.static answers by moving on to the next handler rather than by reporting
 // them, when fallthrough is on. They all mean the same thing: the request is not a file here.
@@ -123,7 +145,7 @@ let iconv;
  * iconv-lite, loaded only when a request names a charset the Buffer cannot decode, so the common
  * utf-8 request never pays for it.
  *
- * @returns {any}
+ * @returns {typeof import("iconv-lite")}
  */
 function loadIconv() {
     if (!iconv) iconv = require("iconv-lite");
@@ -200,7 +222,7 @@ function decodeBody(buf, encoding) {
         case "iso-8859-1":
             return buf.toString("latin1");
         default:
-            return loadIconv().decode(buf, encoding);
+            return loadIconv().decode(buf, /** @type {import("iconv-lite").Encoding} */ (encoding));
     }
 }
 
@@ -210,29 +232,51 @@ function decodeBody(buf, encoding) {
  *
  * @param {Request} req
  * @param {Response} res
- * @param {(err?: any) => void} next
- * @param {any} options the parser options, settled by createBodyParser
+ * @param {(err?: unknown) => void} next
+ * @param {BodyParserOptions} options the parser options, settled by createBodyParser
  * @param {Buffer} buf
+ * @param {string|undefined} encoding the charset the body is about to be decoded with, undefined
+ *   for raw, which never decodes
  * @returns {boolean}
  */
-function runVerify(req, res, next, options, buf) {
+function runVerify(req, res, next, options, buf, encoding) {
     if (!options.verify) {
         return true;
     }
     try {
-        options.verify(req, res, buf);
+        // the charset goes too, as body-parser hands it over: a hook checking a signature over
+        // the decoded text needs it. raw gets null, which is what body-parser gives it there
+        options.verify(req, res, buf, encoding ?? null);
         return true;
     } catch (e) {
-        const err = /** @type {any} */ (e);
-        next(
-            asBodyError(err, err.status ?? err.statusCode ?? 403, err.type ?? "entity.verify.failed", {
-                body: buf
-            })
-        );
+        next(verifyError(e, buf));
         return false;
     }
 }
 
+/**
+ * The error a verify hook's throw becomes, as http-errors shapes it for body-parser. An Error is
+ * kept, with its own status when that is one a client can be answered with; a thrown string
+ * becomes a 403 with that message, and anything else a plain 403.
+ *
+ * @param {unknown} thrown
+ * @param {Buffer} buf the body, which rides on the error as body-parser puts it there
+ * @returns {HttpError}
+ */
+function verifyError(thrown, buf) {
+    const own = thrown instanceof Error ? /** @type {HttpError} */ (thrown) : undefined;
+    let status = own ? own.status || own.statusCode || 403 : 403;
+    // http-errors answers 500 for a status it cannot answer with: not a number, or outside 4xx
+    // and 5xx with no message of its own
+    if (typeof status !== "number" || (!statuses.message[status] && (status < 400 || status >= 600))) {
+        status = 500;
+    }
+    const err = own ?? httpError(status, typeof thrown === "string" ? thrown : undefined);
+    // read off whatever was thrown, as body-parser reads it
+    const type = /** @type {{type?: string}|null|undefined} */ (thrown)?.type || "entity.verify.failed";
+    return asBodyError(err, status, type, { body: buf });
+}
+
 /**
  * The message a strict violation gets, which is the one V8 would have produced had the body been
  * invalid JSON rather than merely not an object.
@@ -255,22 +299,13 @@ function strictSyntaxMessage(text, char) {
         JSON.parse(partial);
     } catch (e) {
         // put the real characters back where the placeholders were named
-        return /** @type {any} */ (e).message.replace(/#+/g, (/** @type {string} */ placeholder) =>
+        return /** @type {SyntaxError} */ (e).message.replace(/#+/g, (/** @type {string} */ placeholder) =>
             text.substring(index, index + placeholder.length)
         );
     }
     return "strict violation";
 }
 
-// The name http-errors gives each status body-parser answers with. An application reading
-// err.name, or a logger printing it, sees "PayloadTooLargeError" from Express and would have
-// seen a bare "Error" here.
-const BODY_ERROR_NAMES = {
-    400: "BadRequestError",
-    413: "PayloadTooLargeError",
-    415: "UnsupportedMediaTypeError"
-};
-
 /**
  * The error a body parser hands to next(), shaped as body-parser shapes it: with a status, since
  * `res.status(err.status || 500)` would otherwise answer 500 to a request that was merely too
@@ -283,10 +318,11 @@ const BODY_ERROR_NAMES = {
  * @returns {Error}
  */
 function bodyError(message, status, type, extra) {
-    const err = /** @type {any} */ (new Error(message));
-    if (BODY_ERROR_NAMES[status]) {
-        err.name = BODY_ERROR_NAMES[status];
-    }
+    /** @type {HttpError} */
+    const err = new Error(message);
+    // the name http-errors gives it: an application reading err.name, or a logger printing it,
+    // sees "PayloadTooLargeError" from Express and would have seen a bare "Error" here
+    err.name = httpErrorName(status);
     return asBodyError(err, status, type, extra);
 }
 
@@ -296,7 +332,7 @@ function bodyError(message, status, type, extra) {
  * its stack and any property the thrower put on it are all still there when the application
  * reads it.
  *
- * @param {any} err whatever was thrown, which need not be an Error
+ * @param {HttpError} err the error the fields go on: JSON.parse's SyntaxError, or a verify hook's own
  * @param {number} status
  * @param {string} type body-parser's own name for the kind of failure
  * @param {object} [extra] anything else body-parser puts on that particular error
@@ -411,7 +447,7 @@ function pickPrecompressed(filePath, accept, ttl, statTtl) {
  *
  * @param {string} dir the directory to look in
  * @param {string[]} indexList the index names, in order
- * @returns {{stat: any, name: string, candidate: string}|null} the file to serve, or null
+ * @returns {{stat: import("fs").Stats, name: string, candidate: string}|null} the file to serve, or null
  */
 function findIndexFile(dir, indexList) {
     let lastError;
@@ -445,7 +481,7 @@ function findIndexFile(dir, indexList) {
  *
  * @param {string} root directory to serve from
  * @param {import("./options").StaticOptions} [options]
- * @returns {(req: any, res: any, next: (err?: any) => void) => any}
+ * @returns {(req: Request, res: Response, next: (err?: unknown) => void) => void}
  */
 function serveStatic(root, options) {
     // serve-static's own messages, thrown where the middleware is written rather than where a
@@ -478,21 +514,22 @@ function serveStatic(root, options) {
     if (options.setHeaders !== undefined && typeof options.setHeaders !== "function") {
         throw new TypeError("option setHeaders must be function");
     }
+    // serve-static's own option, which res.sendFile does not take, so it goes down under a name
+    // only this middleware writes, see sendFile
+    options._setHeaders = options.setHeaders;
     // How long express.static remembers which twins a path has. A second is short enough that a
     // deploy is picked up while it is still going out, and long enough that the lookup costs
     // nothing under any traffic at all. { cache: false } asks the disk on every request.
     let twinTtl = 0;
     if (options.preCompressed) {
-        const cache = /** @type {any} */ (
-            typeof options.preCompressed === "object" ? options.preCompressed.cache : undefined
-        );
+        const cache = typeof options.preCompressed === "object" ? options.preCompressed.cache : undefined;
         twinTtl =
             cache === undefined
                 ? 1000
                 : cache === false
                   ? 0
                   : typeof cache === "string"
-                    ? ms(/** @type {any} */ (cache))
+                    ? ms(/** @type {import("ms").StringValue} */ (cache))
                     : cache;
         if (typeof twinTtl !== "number" || !(twinTtl >= 0)) {
             throw new TypeError("option preCompressed.cache must be a duration");
@@ -662,7 +699,7 @@ function serveStatic(root, options) {
                     // error handler with its errno, code, syscall and path still on it, and an
                     // error handler doing res.send(err) sends those as JSON. Passing the string
                     // sent an HTML page instead.
-                    return next(asStatError(statError));
+                    return next(asStatError(/** @type {HttpError} */ (statError)));
                 } else return next();
             }
         }
@@ -707,7 +744,7 @@ function serveStatic(root, options) {
                         res.status(404);
                         // the fs error, as above: the index file is missing and the error handler
                         // is told which one and where
-                        return next(asStatError(err));
+                        return next(asStatError(/** @type {HttpError} */ (err)));
                     } else return next();
                 }
                 if (found === null) {
@@ -773,12 +810,59 @@ function serveStatic(root, options) {
     };
 }
 
+/**
+ * A zlib throw as the 400 body-parser answers a corrupt body with. zlib reports it twice, and the
+ * 'error' a tick later would land on nothing and end the process, so the listener goes back on.
+ *
+ * @param {Inflater} inflate
+ * @param {HttpError} err what inflate.process threw
+ * @returns {HttpError} the same error, carrying its status
+ */
+function inflateError(inflate, err) {
+    inflate.instance?.on?.("error", () => {});
+    err.status = 400;
+    err.statusCode = 400;
+    err.expose = true;
+    return err;
+}
+
+/**
+ * What a Content-Encoding means here: the decompressor to run, or the 415 it is refused with. An
+ * empty body is judged the same way, so both callers share this.
+ *
+ * @param {string|undefined} rawContentEncoding
+ * @param {any} options the parser's options, read loosely: only inflate is looked at
+ * @returns {{inflate?: Inflater, error?: HttpError}}
+ */
+function encodingFor(rawContentEncoding, options) {
+    if (!options.inflate) {
+        const contentEncoding = (rawContentEncoding || "identity").toLowerCase();
+        if (contentEncoding !== "identity") {
+            return {
+                error: bodyError("content encoding unsupported", 415, "encoding.unsupported", {
+                    encoding: contentEncoding
+                })
+            };
+        }
+        return {};
+    }
+    const inflate = createInflate(rawContentEncoding);
+    if (inflate === false) {
+        return {
+            error: bodyError('unsupported content encoding "' + rawContentEncoding + '"', 415, "encoding.unsupported", {
+                encoding: rawContentEncoding
+            })
+        };
+    }
+    return { inflate };
+}
+
 /**
  * The decompressor for a Content-Encoding, or undefined when the body is not compressed. An
  * encoding nobody knows throws, since decoding it wrong is worse than refusing.
  *
  * @param {string|undefined} contentEncoding
- * @returns {any|undefined}
+ * @returns {Inflater|false|undefined}
  */
 function createInflate(contentEncoding) {
     const encoding = (contentEncoding || "identity").toLowerCase();
@@ -799,7 +883,7 @@ function createInflate(contentEncoding) {
             return false;
     }
     // the flag the final flush passes, so a truncated stream errors instead of resolving empty
-    /** @type {any} */ (stream)._finishFlag =
+    /** @type {Inflater} */ (stream)._finishFlag =
         encoding === "br" ? zlib.constants.BROTLI_OPERATION_FINISH : zlib.constants.Z_FINISH;
     return stream;
 }
@@ -810,9 +894,9 @@ function createInflate(contentEncoding) {
  * bytes over. They differ in the content type they claim and in what they turn the bytes into.
  *
  * @param {string} defaultType the type matched when the caller names none
- * @param {(...args: any[]) => any} beforeReturn turns the collected bytes into req.body. Called
- *   with the request, the response, next, the options, the body and its charset
- * @param {(options: any) => void} [checkOptions] whatever this parser alone has to check
+ * @param {BodyHandler} beforeReturn turns the collected bytes into req.body. Called with the
+ *   request, the response, next, the options, the body and its charset
+ * @param {(options: BodyParserOptions) => void} [checkOptions] whatever this parser alone has to check
  * @param {string} [charsetPolicy] which charsets this parser accepts, as body-parser draws the
  *   lines: "utf" (json, utf-* only), "urlencoded" (utf-8 and iso-8859-1), "any" (anything iconv
  *   knows), or undefined for a parser that never decodes (raw)
@@ -949,8 +1033,11 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
                 }
             }
 
-            // the charset is settled before anything is read, as body-parser settles it: a bad one
-            // answers 415 even for an empty body, and before the verify hook can run
+            // The charset is settled before anything is read, as body-parser settles it: a bad one
+            // answers 415 even for an empty body, and before the verify hook can run. Its two
+            // halves sit on either side of the encoding, which is the order body-parser reads
+            // them in: the charset this parser accepts at all, then the Content-Encoding, then
+            // whether iconv knows the charset.
             let encoding;
             if (charsetPolicy) {
                 encoding = charsetOf(type) ?? defaultCharset;
@@ -960,9 +1047,16 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
                 ) {
                     return next(charsetError(encoding));
                 }
-                if (!BUFFER_CHARSETS.has(encoding) && !loadIconv().encodingExists(encoding)) {
-                    return next(charsetError(encoding));
-                }
+            }
+
+            const encoded = encodingFor(req._rawHeader("content-encoding"), options);
+            if (encoded.error) {
+                return next(encoded.error);
+            }
+            const inflate = encoded.inflate;
+
+            if (encoding !== undefined && !BUFFER_CHARSETS.has(encoding) && !loadIconv().encodingExists(encoding)) {
+                return next(charsetError(encoding));
             }
 
             // an empty body still has to produce this parser's empty value the way express does -
@@ -971,8 +1065,18 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
             // and the verify hook still runs first: webhook signature checks rely on that
             if (lengthNumber === 0) {
                 req.bodyRead = true;
-                const empty = Buffer.alloc(0);
-                if (!runVerify(req, res, next, options, empty)) {
+                /** @type {Buffer<ArrayBufferLike>} what the parser is handed: zlib's tail is wider */
+                let empty = Buffer.alloc(0);
+                if (inflate) {
+                    // nothing to inflate is a stream cut short for zlib, and body-parser answers
+                    // that with a 400 rather than with the empty value
+                    try {
+                        empty = inflate.process(EMPTY_BUFFER, inflate._finishFlag);
+                    } catch (e) {
+                        return next(inflateError(inflate, /** @type {HttpError} */ (e)));
+                    }
+                }
+                if (!runVerify(req, res, next, options, empty, encoding)) {
                     return;
                 }
                 return beforeReturn(req, res, next, options, empty, encoding);
@@ -1002,32 +1106,7 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
                 return next();
             }
 
-            let inflate;
             let totalSize = 0;
-            const rawContentEncoding = req._rawHeader("content-encoding");
-            const contentEncoding = (rawContentEncoding || "identity").toLowerCase();
-            if (!options.inflate && contentEncoding !== "identity") {
-                return next(
-                    bodyError("content encoding unsupported", 415, "encoding.unsupported", {
-                        encoding: contentEncoding
-                    })
-                );
-            }
-            if (options.inflate) {
-                inflate = createInflate(rawContentEncoding);
-                if (inflate === false) {
-                    return next(
-                        bodyError(
-                            'unsupported content encoding "' + rawContentEncoding + '"',
-                            415,
-                            "encoding.unsupported",
-                            {
-                                encoding: rawContentEncoding
-                            }
-                        )
-                    );
-                }
-            }
 
             // From here the body really gets read, and uWS delivers it on native callbacks that
             // carry no async context, so this is the one continuation that has to be bound: an
@@ -1070,7 +1149,7 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
                     if (copyBody) {
                         buf = Buffer.from(buf);
                     }
-                    if (!runVerify(req, res, next, options, buf)) {
+                    if (!runVerify(req, res, next, options, buf, encoding)) {
                         return;
                     }
                     beforeReturn(req, res, next, options, buf, encoding);
@@ -1099,24 +1178,16 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
             let finished = false;
 
             /**
-             * A zlib throw becomes the 400 body-parser answers a corrupt body with.
-             *
-             * zlib reports it twice: process() throws, and the stream emits 'error' a tick later.
-             * fast-zlib removes its own listeners on the way out, so that second one lands on
-             * nothing, and an unhandled 'error' event ends the process. The listener goes on after
-             * the throw, since process() would have removed it.
+             * A zlib throw becomes the 400 body-parser answers a corrupt body with, and what was
+             * kept of the body goes.
              *
-             * @param {any} err what inflate.process threw
+             * @param {HttpError} err what inflate.process threw
              */
             function failInflate(err) {
-                /** @type {any} */ (inflate).instance?.on?.("error", () => {});
                 finished = true;
                 abs.length = 0;
                 target = null;
-                err.status = 400;
-                err.statusCode = 400;
-                err.expose = true;
-                next(err);
+                next(inflateError(/** @type {Inflater} */ (inflate), err));
             }
 
             /**
@@ -1162,7 +1233,7 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
              * finished flag matters: uWS goes on delivering chunks after an oversized body has
              * been refused, and without it every further chunk would answer the request again.
              *
-             * @param {any} buf a Buffer, or an ArrayBuffer straight from uWS
+             * @param {Buffer|ArrayBuffer} buf a Buffer, or an ArrayBuffer straight from uWS
              */
             function onData(buf) {
                 if (finished) {
@@ -1177,7 +1248,7 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
                     } catch (e) {
                         // a body that does not decompress is the client's mistake, and zlib
                         // throwing here used to escape into whatever called us
-                        return failInflate(e);
+                        return failInflate(/** @type {HttpError} */ (e));
                     }
                 }
 
@@ -1198,7 +1269,7 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
                     try {
                         tail = inflate.process(EMPTY_BUFFER, inflate._finishFlag);
                     } catch (e) {
-                        return failInflate(e);
+                        return failInflate(/** @type {HttpError} */ (e));
                     }
                     if (tail.length && !keepChunk(tail)) {
                         return;
@@ -1226,7 +1297,7 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
                     : abs.length === 1
                       ? abs[0]
                       : Buffer.concat(abs);
-                if (!runVerify(req, res, next, options, buf)) {
+                if (!runVerify(req, res, next, options, buf, encoding)) {
                     return;
                 }
                 beforeReturn(req, res, next, options, buf, encoding);
@@ -1274,7 +1345,7 @@ const json = createBodyParser(
         // either: it decodes through iconv, which strips it, so by the time the first character is
         // looked at the mark is gone. JSON.parse would refuse it, so without this a body saved by
         // an editor that writes a BOM is answered 400 here and 200 by Express.
-        const text = stripBom(decodeBody(buf, encoding));
+        const text = stripBom(decodeBody(buf, /** @type {string} */ (encoding)));
 
         // "strict" means only an object or an array is a body, which is body-parser's default and
         // was not honoured here at all: the check read req.body before this function had parsed
@@ -1302,7 +1373,7 @@ const json = createBodyParser(
         } catch (e) {
             // V8's own error, which is what body-parser hands on: its message says where the parse
             // gave up, and it is still the SyntaxError an application may be testing for
-            const err = /** @type {any} */ (e);
+            const err = /** @type {SyntaxError} */ (e);
             return next(asBodyError(err, 400, "entity.parse.failed", { body: text }));
         }
 
@@ -1329,7 +1400,7 @@ const text = createBodyParser(
     "text/plain",
     function (req, res, next, options, buf, encoding) {
         try {
-            req.body = decodeBody(buf, encoding);
+            req.body = decodeBody(buf, /** @type {string} */ (encoding));
         } catch (e) {
             return next(e);
         }
@@ -1371,7 +1442,7 @@ const urlencoded = createBodyParser(
     "application/x-www-form-urlencoded",
     function (req, res, next, options, buf, encoding) {
         try {
-            const body = decodeBody(buf, encoding);
+            const body = decodeBody(buf, /** @type {string} */ (encoding));
             // Express 5 defaults extended to false, so nested keys need opting in
             const extended = typeof options.extended !== "undefined" ? options.extended : false;
             // qs has to know the charset itself for anything but utf-8, and the sentinel options
@@ -1387,7 +1458,8 @@ const urlencoded = createBodyParser(
                 }
                 req.body = parsed;
             } else {
-                const count = parameterCount(body, options.parameterLimit);
+                // settled by the check below the parser, so it is a number by the time a body arrives
+                const count = parameterCount(body, /** @type {number} */ (options.parameterLimit));
                 if (count === undefined) {
                     return next(bodyError("too many parameters", 413, "parameters.too.many"));
                 }
@@ -1401,7 +1473,7 @@ const urlencoded = createBodyParser(
                         arrayLimit: Math.max(100, count + 1),
                         charsetSentinel: options.charsetSentinel,
                         interpretNumericEntities: options.interpretNumericEntities,
-                        charset: encoding,
+                        charset: /** @type {"utf-8"|"iso-8859-1"} */ (encoding),
                         parameterLimit: options.parameterLimit
                     };
                     req.body = needsQs
@@ -1419,7 +1491,7 @@ const urlencoded = createBodyParser(
                             strictDepth: true,
                             charsetSentinel: options.charsetSentinel,
                             interpretNumericEntities: options.interpretNumericEntities,
-                            charset: encoding,
+                            charset: /** @type {"utf-8"|"iso-8859-1"} */ (encoding),
                             parameterLimit: options.parameterLimit
                         })
                     );

package/src/nest.js

@@ -47,7 +47,8 @@ const fulmine = require("./index.js");
  */
 class FulmineExpressAdapter extends ExpressAdapter {
     /**
-     * @param {any} [instance] an application from `fulmine()`; one is created when omitted
+     * @param {import("fulmine.js").FulmineApplication} [instance] an application from `fulmine()`; one is
+     *   created when omitted
      */
     constructor(instance) {
         super(instance || fulmine());
@@ -61,7 +62,7 @@ class FulmineExpressAdapter extends ExpressAdapter {
     /**
      * The app is the server. Nest calls this once, from NestApplication's constructor.
      *
-     * @param {any} [options] the options NestFactory.create was given
+     * @param {import("@nestjs/common").NestApplicationOptions} [options] the options NestFactory.create was given
      * @returns {void}
      */
     initHttpServer(options) {

package/src/node-shim.js

@@ -389,7 +389,7 @@ class NodeHttpResponse {
 
 /**
  * Whether these are node's own request and response rather than this project's.
- * @param {any} req anything a caller handed the router, which is the point of the check
+ * @param {unknown} req anything a caller handed the router, which is the point of the check
  */
 function isNodeRequest(req) {
     return req instanceof IncomingMessage;
@@ -398,14 +398,19 @@ function isNodeRequest(req) {
 /**
  * Serves a request that arrived through node's HTTP server with the given router or app.
  *
- * @param {any} router the router or application serving this request
+ * @param {import("./router.js")} router the router or application serving this request
  * @param {import("http").IncomingMessage} nodeReq
  * @param {import("http").ServerResponse} nodeRes
- * @param {(err?: any) => void} [next] called when nothing in the router answered
+ * @param {(err?: unknown) => void} [next] called when nothing in the router answered
  */
 function serveNodeRequest(router, nodeReq, nodeRes, next) {
-    const shimRes = new NodeHttpResponse(nodeReq, nodeRes);
-    const shimReq = new NodeHttpRequest(nodeReq);
+    // the shims stand in for uWS's pair, and the checker is told so once, here
+    const shimRes = /** @type {import("uWebSockets.js").HttpResponse} */ (
+        /** @type {unknown} */ (new NodeHttpResponse(nodeReq, nodeRes))
+    );
+    const shimReq = /** @type {import("uWebSockets.js").HttpRequest} */ (
+        /** @type {unknown} */ (new NodeHttpRequest(nodeReq))
+    );
     const request = router.handleRequest(shimRes, shimReq);
     const response = request.res;
     // the shim's onAborted rides node's own close event, needed on every request here

package/src/optimizer.js

@@ -19,6 +19,7 @@ limitations under the License.
 
 /** @typedef {import("./router.js")} Router */
 /** @typedef {import("./router-utils.js").RouteEntry} RouteEntry */
+/** @typedef {import("./application.js").Application} Application */
 
 const {
     patternToRegex,
@@ -53,7 +54,7 @@ const {
 let Router;
 
 /**
- * @param {any} cls the Router class, passed in to keep this module out of its require cycle
+ * @param {typeof import("./router.js")} cls the Router class, passed in to keep this module out of its require cycle
  */
 function useRouterClass(cls) {
     Router = cls;
@@ -66,8 +67,8 @@ function useRouterClass(cls) {
  *
  * @param {Router} router
  * @param {RouteEntry} route
- * @param {any[]} routes every route of this router, in registration order
- * @returns {any[]|false} the chain, ending in the route itself
+ * @param {RouteEntry[]} routes every route of this router, in registration order
+ * @returns {RouteEntry[]|false} the chain, ending in the route itself
  */
 function optimizeRoute(router, route, routes) {
     const optimizedPath = [];
@@ -216,7 +217,8 @@ function optimizeRoute(router, route, routes) {
  * routers and carrying their prefix down. Runs once, when the app starts listening, since it
  * needs every route to have been registered first.
  *
- * @param {any} root the application whose routes are being compiled
+ * @param {Router} root the application whose routes are being compiled. A plain router, which has
+ *   no uwsApp, is left alone
  */
 function compileOptimizedRoutes(root) {
     if (!root.uwsApp) {
@@ -376,7 +378,7 @@ function compileOptimizedRoutes(root) {
  *
  * @param {Router} router
  * @param {RouteEntry} route
- * @param {any[]} optimizedPath the routes to run, in order, ending with this one
+ * @param {RouteEntry[]} optimizedPath the routes to run, in order, ending with this one
  */
 function registerUwsRoute(router, route, optimizedPath) {
     let method = route.method.toLowerCase();
@@ -428,7 +430,7 @@ function registerUwsRoute(router, route, optimizedPath) {
             // this one
             if (caseGuards !== null && anyGuardHits(caseGuards, req.getUrl())) {
                 // an application is what registers native routes, and only it serves
-                return /** @type {any} */ (router)._serveGeneric(res, req);
+                return /** @type {Application} */ (router)._serveGeneric(res, req);
             }
             const request = router.handleRequest(res, req, preset, skipHolder);
             const response = request.res;
@@ -526,7 +528,7 @@ function registerUwsRoute(router, route, optimizedPath) {
 
     // the response prototype the route will really run under: its own app's, which sees a
     // method patched there or inherited from a parent app, falling back to the registering app
-    const responseProto = /** @type {any} */ (route.owner)?.response ?? /** @type {any} */ (router).response;
+    const responseProto = route.owner?.response ?? /** @type {Application} */ (router).response;
     // check if route is declarative
     if (
         optimizedPath.length === 1 && // must not have middlewares