fulmine.js 5.19.8 → 5.20.0

package/src/hot-settings.js

@@ -27,14 +27,21 @@ class HotSettings {
     constructor() {
         this.epoch = 0;
         this.xPoweredBy = false;
+        /** @type {((body: string|Buffer|import("fs").Stats, encoding?: BufferEncoding) => string)|undefined} */
         this.etagFn = undefined;
         // null means every method, which is express's behaviour and the default
+        /** @type {Set<string>|null} */
         this.etagMethods = null;
+        /** @type {((query: string|null) => Record<string, any>)|undefined} */
         this.queryParserFn = undefined;
+        /** @type {import("./utils.js").TrustFn|undefined} */
         this.trustProxyFn = undefined;
         this.trustProxyProtocol = false;
+        /** @type {boolean|undefined} */
         this.jsonEscape = undefined;
+        /** @type {any} the "json replacer" setting, as stringify takes it */
         this.jsonReplacer = undefined;
+        /** @type {string|number|undefined} */
         this.jsonSpaces = undefined;
     }
 }

package/src/index.js

@@ -21,6 +21,28 @@ limitations under the License.
 // package ships, so the module is read through a loose alias
 const uWS = require("uWebSockets.js");
 const uWSAny = /** @type {any} */ (uWS);
+
+// A project on pnpm owns the uWebSockets.js dependency itself, see `npx fulmine.js pnpm`, so the
+// one installed can drift from the one this package pins and was tested against. Said once, at
+// require time, where it reaches every deployment rather than only the ones that run verify.
+{
+    const pinned = /#v?([\d.]+)$/.exec(require("../package.json").dependencies["uWebSockets.js"])?.[1];
+    /** @type {string|undefined} */
+    let installed;
+    try {
+        // its exports map does not expose package.json, so it is read beside the entry point
+        const beside = require("path").join(require.resolve("uWebSockets.js"), "..", "package.json");
+        installed = JSON.parse(require("fs").readFileSync(beside, "utf8")).version;
+    } catch {
+        // nothing to compare against, which is not worth a warning of its own
+    }
+    if (pinned && installed && installed !== pinned) {
+        console.warn(
+            `fulmine.js: uWebSockets.js ${installed} is installed, this version was tested with ${pinned}.\n` +
+                "  On pnpm the pin is the project's own: `npx fulmine.js pnpm` writes the tested one."
+        );
+    }
+}
 const Application = require("./application.js");
 const Router = require("./router.js");
 const Route = require("./route.js");
@@ -68,6 +90,7 @@ try {
 module.exports = /** @type {any} */ (Application);
 
 // a router is a function too: it has to be callable to be used as middleware
+/** @param {object} [options] the options express.Router() takes */
 module.exports.Router = function (options) {
     return new Router(options)._asCallable();
 };

package/src/middlewares.js

@@ -139,6 +139,7 @@ function stripBom(text) {
     return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
 }
 
+/** @type {typeof import("iconv-lite")|undefined} */
 let iconv;
 
 /**
@@ -966,6 +967,7 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
             (contentType) => !!typeis.is(contentType, /** @type {string[]} */ (options.type))
         );
 
+        /** @type {string[]|null|undefined} the "body methods" setting, read on the first request */
         let additionalMethods;
 
         const parserMiddleware = (req, res, next) => {
@@ -1038,6 +1040,7 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
             // 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.
+            /** @type {string|undefined} */
             let encoding;
             if (charsetPolicy) {
                 encoding = charsetOf(type) ?? defaultCharset;
@@ -1129,7 +1132,7 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
                 // not us, and would wait for an end that is never coming
                 req.complete = true;
                 req.readable = false;
-                req._res.collectBody(limit, (body) => {
+                req._res.collectBody(limit, (/** @type {ArrayBuffer|null} */ body) => {
                     if (body === null) {
                         // over maxSize: uWS refused it natively
                         return next(
@@ -1165,6 +1168,7 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
             // known and we are not inflating, the final size is known up front, so chunks go
             // straight into one buffer and the body is copied once. The cap means a client that
             // declares a body and never sends it costs no more than one that sends it
+            /** @type {Buffer[]} */
             const abs = [];
             const declaredLength = inflate ? -1 : Number(length);
             let target =
@@ -1310,7 +1314,7 @@ function createBodyParser(defaultType, beforeReturn, checkOptions, charsetPolicy
             // if we are fast enough (not async), we can do it
             // otherwise we need to use a stream since it already started streaming it
             if (!req.receivedData) {
-                req._res.onData((ab, isLast) => {
+                req._res.onData((/** @type {ArrayBuffer} */ ab, /** @type {boolean} */ isLast) => {
                     onData(ab);
                     if (isLast) {
                         // this subscription replaced the Readable's own, so the stream will

package/src/node-shim.js

@@ -39,21 +39,30 @@ function addressToBytes(address) {
     if (!address) {
         return new ArrayBuffer(0);
     }
-    // node reports an IPv4 client on a dual stack socket as ::ffff:127.0.0.1, and the address that
-    // belongs in req.ip is the v4 one
-    const mapped = address.startsWith("::ffff:") ? address.slice(7) : address;
-    if (mapped.includes(".")) {
-        const parts = mapped.split(".");
+    // node reports an IPv4 client on a dual stack socket as ::ffff:127.0.0.1 and one on an IPv4
+    // socket as 127.0.0.1, which is the difference req.ip reads back out of the width: uWS hands
+    // the mapped peer over as the sixteen bytes, the plain one as four. Keeping node's own form
+    // rather than flattening both to four is what makes the shim answer what node answers,
+    // whichever socket accepted the connection
+    const mapped = address.startsWith("::ffff:") && address.includes(".");
+    const dotted = mapped ? address.slice(7) : address;
+    if (dotted.includes(".")) {
+        const parts = dotted.split(".");
         if (parts.length !== 4) {
             return new ArrayBuffer(0);
         }
-        const bytes = new Uint8Array(4);
+        const bytes = new Uint8Array(mapped ? 16 : 4);
+        const offset = mapped ? 12 : 0;
+        if (mapped) {
+            bytes[10] = 0xff;
+            bytes[11] = 0xff;
+        }
         for (let i = 0; i < 4; i++) {
             const value = Number(parts[i]);
             if (!Number.isInteger(value) || value < 0 || value > 255) {
                 return new ArrayBuffer(0);
             }
-            bytes[i] = value;
+            bytes[offset + i] = value;
         }
         return bytes.buffer;
     }
@@ -80,13 +89,19 @@ function addressToBytes(address) {
     return view.buffer;
 }
 
-/** A chunk as the ArrayBuffer uWS deals in, copied rather than viewed so nothing aliases node's. */
+/**
+ * A chunk as the ArrayBuffer uWS deals in, copied rather than viewed so nothing aliases node's.
+ *
+ * @param {ArrayBuffer|Buffer|string} chunk
+ * @returns {ArrayBuffer}
+ */
 function toArrayBuffer(chunk) {
     if (chunk instanceof ArrayBuffer) {
         return chunk;
     }
     const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-    return buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+    // node types the store as possibly shared, but a Buffer it made or was given here never is
+    return /** @type {ArrayBuffer} */ (buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength));
 }
 
 /**
@@ -175,6 +190,7 @@ class NodeHttpResponse {
         // how much of the body has gone out, which is what uWS reports through getWriteOffset and
         // hands back to an onWritable callback
         this._offset = 0;
+        /** @type {((offset: number) => boolean)|null} */
         this._onWritable = null;
         this._aborted = false;
         // the current body handler: uWS keeps one and a second onData replaces it, so this does too
@@ -195,6 +211,8 @@ class NodeHttpResponse {
      * uWS batches everything written inside this into one syscall. node has no equivalent that
      * means the same thing, and its own cork would hold the write until the callback returned
      * without changing what is sent, so this only runs it.
+     *
+     * @param {() => void} cb
      */
     cork(cb) {
         cb();
@@ -300,13 +318,19 @@ class NodeHttpResponse {
      * Called when there is room to write again. uWS asks the handler to answer whether it managed
      * to write everything, and calls it again if not; node's drain says nothing, so the handler is
      * kept until the next drain and its answer ignored.
+     *
+     * @param {(offset: number) => boolean} handler
      */
     onWritable(handler) {
         this._onWritable = handler;
         return this;
     }
 
-    /** Called when the connection goes before the response is finished. */
+    /**
+     * Called when the connection goes before the response is finished.
+     *
+     * @param {() => void} handler
+     */
     onAborted(handler) {
         this._nodeRes.on("close", () => {
             if (!this._nodeRes.writableFinished) {

package/src/optimizer.js

@@ -51,6 +51,7 @@ const {
 
 // router.js requires this file while it is still being evaluated, so its class cannot be required
 // from here: it hands it over on the line under its own export instead.
+/** @type {typeof import("./router.js")} */
 let Router;
 
 /**
@@ -233,6 +234,12 @@ function compileOptimizedRoutes(root) {
 
     // pathPrefix/chainPrefix accumulate across nested sole-callback mounts, and outerGuards
     // carries what was written before them and answers only part of what is under them
+    /**
+     * @param {Router} router
+     * @param {string} pathPrefix
+     * @param {RouteEntry[]} chainPrefix
+     * @param {import("./router-utils.js").MountGuard[]} outerGuards
+     */
     const walk = (router, pathPrefix, chainPrefix, outerGuards) => {
         for (const route of router._routes) {
             if (route.use) {
@@ -344,7 +351,7 @@ function compileOptimizedRoutes(root) {
                     if (route._caseGuards) {
                         // compared against the whole path µWS matched, so they carry the mount
                         // prefix, folded along with the rest of it
-                        registered._caseGuards = route._caseGuards.map((p) => pathPrefix + p);
+                        registered._caseGuards = route._caseGuards.map((/** @type {string} */ p) => pathPrefix + p);
                     }
                     root._registerUwsRoute(registered, chain);
                     // the chain holds the original object, so the request-time guard has to find
@@ -388,18 +395,27 @@ function registerUwsRoute(router, route, optimizedPath) {
         method = "del";
     }
     if (route.path.includes(":")) {
-        route.optimizedParams = route.path.match(regExParam).map((p) => p.slice(1));
+        route.optimizedParams = route.path.match(regExParam).map((/** @type {string} */ p) => p.slice(1));
     }
     // null for almost every route: only a parameter route with an earlier literal that a case
     // variant could slip past carries one, see _optimizeRoute. Built once here, and matched
     // insensitively, since that is the folding the guard exists for
     const caseGuards = route._caseGuards
-        ? route._caseGuards.map((p) => (needsConversionToRegex(p) ? patternToRegex(p, false, false) : p.toLowerCase()))
+        ? route._caseGuards.map((/** @type {string} */ p) =>
+              needsConversionToRegex(p) ? patternToRegex(p, false, false) : p.toLowerCase()
+          )
         : null;
+    /**
+     * @param {RouteEntry[]} chain
+     * @param {import("./router-utils.js").NativePreset|undefined} preset
+     * @param {{skipHeaders: boolean, skipQuery: boolean}} skips
+     * @param {string|null} wireMethod
+     */
     const makeHandler = (chain, preset, skips, wireMethod) => {
         // the mutable object a granted skip lives on, so a middleware arriving after listen can
         // take it back: a literal registration's preset doubles as it, a parameterised one gets a
         // holder of its own. It carries the method too, so the constructor settles it in one compare
+        /** @type {import("./router-utils.js").SkipHolder|undefined} */
         let skipHolder = preset;
         if (skipHolder === undefined && (skips.skipHeaders || skips.skipQuery || wireMethod !== null)) {
             skipHolder = {
@@ -504,6 +520,11 @@ function registerUwsRoute(router, route, optimizedPath) {
         }
     }
     // remembered so a middleware or setting arriving after listen can take the skips back
+    /**
+     * @param {string} path
+     * @param {string} method
+     * @param {{skipHeaders: boolean, skipQuery: boolean}} skips
+     */
     const makePreset = (path, method, skips) => {
         const preset = nativePreset(path, method);
         if (skips.skipHeaders || skips.skipQuery) {

package/src/request-utils.js

@@ -104,8 +104,9 @@ function isMappedIPv4(bytes) {
 
 /**
  * Whether node would report an IPv4 peer of this app in mapped form, "::ffff:a.b.c.d". Node maps it
- * whenever the listener is dual stack, which is every listen() without an IPv4 address. uWS already
- * gives mapped peers as sixteen bytes, four bytes come only from a v4 listener or the node shim.
+ * whenever the listener is dual stack, which is every listen() without an IPv4 address. Only the
+ * address invented after the response has ended asks: every address actually read says which form
+ * it is in by its width, uWS handing a mapped peer over as sixteen bytes and a plain one as four.
  *
  * @param {import("./application.js").Application} app the application the request arrived at
  * @returns {boolean}

package/src/request.js

@@ -204,13 +204,6 @@ module.exports = class Request extends LazyReadable {
      */
     rawIp;
 
-    /**
-     * Whether rawIp came from a PROXY protocol preamble rather than from the socket. Only the
-     * IPv4 mapping reads it, see parsedIp. Declared for the same reason as rawIp.
-     * @type {boolean}
-     */
-    _ipFromProxy = false;
-
     /**
      * Whether the request declared a body, content-length or transfer-encoding, spotted during
      * the header copy. Declared for the same reason as rawIp.
@@ -457,7 +450,9 @@ module.exports = class Request extends LazyReadable {
         this._lastMethod = this.method;
         // the folded _opPath and the percent scan of _originalPath, built on the hop that first
         // wants them and dropped by every rewrite, see _pathMatches and Walk#dispatch
+        /** @type {string|null} */
         this._opPathLower = null;
+        /** @type {boolean|null} */
         this._mayFailDecode = null;
         this.params = {};
 
@@ -478,6 +473,7 @@ module.exports = class Request extends LazyReadable {
         this._paramStack = null;
         // route and application in pairs, one pair per mounted application entered from another
         // application, so handing back puts the one that was current back, see rememberApp
+        /** @type {any[]|undefined} route and app alternating, loose because the pairs share one array */
         this._appStack = undefined;
         this.receivedData = false;
         // node's IncomingMessage flag: false until the whole body has arrived. on-finished
@@ -1048,7 +1044,6 @@ module.exports = class Request extends LazyReadable {
             const proxied = uwsRes.getProxiedRemoteAddress();
             // empty unless a preamble arrived, which is the only thing that tells the two apart
             if (proxied.byteLength !== 0) {
-                this._ipFromProxy = true;
                 return proxied;
             }
         }
@@ -1084,14 +1079,12 @@ module.exports = class Request extends LazyReadable {
         /** @type {string|undefined} */
         let ip;
         if (rawIp.byteLength === 4) {
-            // ipv4
+            // ipv4, and plain: four bytes mean the peer arrived over IPv4 on an IPv4 socket, which
+            // is what node writes plain as well. A dual stack listener hands an IPv4 peer over as
+            // the mapped sixteen below, the node shim passes node's own form through, and an
+            // address a proxy declared is the four numbers the proxy sent, so none of them wants
+            // a prefix invented here
             ip = new Uint8Array(rawIp).join(".");
-            // the mapped form belongs to a dual stack listener, which is what makes an IPv4 peer
-            // arrive as ::ffff:a.b.c.d. An address a proxy declared never came through that socket,
-            // so it is left as the four numbers the proxy sent
-            if (!this._ipFromProxy && mapsIPv4Peer(this.app)) {
-                ip = "::ffff:" + ip;
-            }
         } else if (rawIp.byteLength === 16) {
             const bytes = new Uint8Array(rawIp);
             if (isMappedIPv4(bytes)) {

package/src/response-utils.js

@@ -68,7 +68,7 @@ for (const s of [
 // One status line per code, built on first use: the default path, with no custom reason phrase,
 // paid a template string and a trim per request for a line that never changes. Bounded to real
 // HTTP codes so a wild writeHead value cannot grow the array or flip it into dictionary mode.
-const STATUS_LINES = [];
+const STATUS_LINES = /** @type {string[]} */ ([]);
 /**
  * @param {number} code
  * @param {string|undefined} text an explicit reason phrase, which bypasses the cache

package/src/response.js

@@ -208,6 +208,10 @@ module.exports = class Response extends LazyWritable {
         this.req = req;
         this._res = res;
         this.headersSent = false;
+        // whether a body goes out, decided from the method that arrived, as node decides it when
+        // it builds its ServerResponse: a middleware that rewrites req.method afterwards, which
+        // method-override does, changes what the router matches and not what the wire carries
+        this._hasBody = req._isHead !== true;
         this.app = app;
         this.locals = new NullObject();
         this.finished = false;
@@ -238,6 +242,7 @@ module.exports = class Response extends LazyWritable {
             this.headers["x-powered-by"] = "Fulmine";
         }
 
+        /** @type {unknown} a slot for whatever a middleware puts on res.body, never read here */
         this.body = undefined;
         // what was handed to uWS, kept so a caller asking for content-length after the fact can be
         // answered, see get(). Undefined until the response ends, and for one that sends no body
@@ -811,7 +816,7 @@ module.exports = class Response extends LazyWritable {
         } else {
             // a Buffer goes to uWS as the view it is: copying it into a fresh ArrayBuffer was
             // an allocation per body, and uWS reads the view's own offset and length
-            if (this.req.method === "HEAD") {
+            if (!this._hasBody) {
                 const length = Buffer.byteLength(data ?? "");
                 this.headers["content-length"] = String(length);
                 this._res.endWithoutBody(length, closeConnection);
@@ -961,6 +966,15 @@ module.exports = class Response extends LazyWritable {
             delete this.headers["transfer-encoding"];
             body = "";
         }
+        // express's send reads req.method here and hands node's end() nothing for a HEAD, the
+        // length already set, and node frames what it is handed: a GET a middleware made a HEAD
+        // answers its length and no body. end() alone decides by the wire, see _hasBody
+        if (this.req.method === "HEAD") {
+            if (this.statusCode !== 204 && this.statusCode !== 304) {
+                this.headers["content-length"] = String(Buffer.byteLength(body));
+            }
+            return this.end();
+        }
         return this.end(body);
     }
 

package/src/route.js

@@ -48,6 +48,10 @@ class Route {
      * @returns {boolean}
      */
     handlesMethod(method) {
+        // all() answers every verb, registered or not, which is what express reads _all for
+        if (this.methods._all) {
+            return true;
+        }
         const lowered = method.toLowerCase();
         return Boolean(this.methods[lowered] || (lowered === "head" && this.methods.get));
     }
@@ -87,6 +91,7 @@ class Route {
         }
         req.route = this;
 
+        /** @param {unknown} [err] */
         const next = (err) => {
             // next("route") leaves this route, and next("router") leaves whoever is running it
             if (err === "route") {
@@ -129,7 +134,7 @@ class Route {
                 // does it. A bare rejection carries none and gets the one express invents. Thenable
                 // too, which express deprecates but still waits for
                 if (out && typeof out.then === "function") {
-                    out.then(null, (thrown) => next(thrown || new Error("Rejected promise")));
+                    out.then(null, (/** @type {unknown} */ thrown) => next(thrown || new Error("Rejected promise")));
                 }
             } catch (thrown) {
                 next(thrown);
@@ -162,14 +167,15 @@ for (const method of ["all", ...METHODS.map((verb) => verb.toLowerCase())]) {
     if (method !== "all" && typeof Route.prototype[method] === "function") {
         continue;
     }
-    Route.prototype[method] = function (...handlers) {
+    Route.prototype[method] = function (/** @type {unknown[]} */ ...handlers) {
         const flattened = handlers.flat(Infinity);
         checkRouteHandlers(method, flattened);
-        for (const handle of flattened) {
+        // the check above threw on anything else
+        for (const handle of /** @type {Function[]} */ (flattened)) {
             this.stack.push({ method: method === "all" ? undefined : method, handle });
-            if (method !== "all") {
-                this.methods[method] = true;
-            }
+            // express marks the route _all rather than naming every verb, and whoever reads
+            // req.route.methods reads that key, so it is written the same way here
+            this.methods[method === "all" ? "_all" : method] = true;
         }
         return this;
     };

package/src/router-utils.js

@@ -175,8 +175,14 @@ function layerFor(route, callback) {
  * @returns {Layer} the layer object, which is express's shape and not one of ours
  */
 function routeLayer(route) {
+    /**
+     * @param {Request} req
+     * @param {Response} res
+     * @param {(err?: unknown) => void} next
+     */
     const handle = function handle(req, res, next) {
         let index = 0;
+        /** @param {unknown} [err] */
         const step = (err) => {
             const callback = route.callbacks[index++];
             if (callback === undefined) {
@@ -206,6 +212,7 @@ function routeLayer(route) {
  * The 404 epilogue stays on a microtask, where the await used to resume: a middleware that writes
  * after calling next() must still win the headersSent check, as it does in express.
  * @this {Walk}
+ * @param {RouteEntry|false} matched what the walk ended on, as the resolve receives it
  */
 function nativeDone(matched) {
     if (this.settled) {
@@ -238,6 +245,7 @@ function nativeDone(matched) {
  * an unhandled rejection. Deferred like the resolve, since every rejection used to reach the
  * handler's catch through an await.
  * @this {Walk}
+ * @param {unknown} err
  */
 function nativeFail(err) {
     if (this.settled) {
@@ -313,7 +321,7 @@ const PATH_PROPERTY = {
 const ABSORB_URL = Request.prototype._absorbUrlRewrite;
 const ABSORB_METHOD = Request.prototype._absorbMethodRewrite;
 
-const NO_PARAM_NAMES = [];
+const NO_PARAM_NAMES = /** @type {string[]} */ ([]);
 
 /**
  * The parameter names a route captures with its own pattern.
@@ -636,7 +644,8 @@ function hasErrorMiddleware(router) {
 }
 
 /**
- *
+ * @param {unknown[]} handlers what a registration was given, flattened
+ * @param {string} [emptyMessage]
  */
 function checkHandlers(handlers, emptyMessage = "argument handler is required") {
     if (handlers.length === 0) {

package/src/router.js

@@ -169,6 +169,7 @@ module.exports = class Router extends EventEmitter {
 
         this._paramCallbacks = new Map();
         this._mountpathCache = new Map();
+        /** @type {RouteEntry[]} */
         this._routes = [];
         // websocket routes, kept apart from the HTTP ones: µWS serves them itself and listen()
         // hands them over whole, mount paths and all
@@ -908,6 +909,7 @@ module.exports = class Router extends EventEmitter {
      */
     _handleError(err, handler, request, response) {
         if (handler) {
+            /** @param {unknown} [pass] */
             const next = (pass) => {
                 delete request._error;
                 delete request._errorKey;
@@ -1154,15 +1156,20 @@ module.exports = class Router extends EventEmitter {
         return new Promise((resolve) => {
             let index = 0;
             let name = "";
+            /** @type {unknown} */
             let value;
             let entry;
+            /** @type {Function[]} */
             let fns = [];
             let fnIndex = 0;
 
             // one parameter after the other, err being what the last one's callbacks ended with
+            /** @param {unknown} [err] */
             const nextParam = (err) => {
                 if (err) {
-                    if (err !== "route") {
+                    // an error already in flight stays the one in flight: express reaches a mount's
+                    // param callbacks with it pending and goes on with next(layerError || err)
+                    if (err !== "route" && !req._error) {
                         req._error = err;
                         req._errorKey = route.routeKey;
                         req._errorGroup = route.group;
@@ -1188,6 +1195,7 @@ module.exports = class Router extends EventEmitter {
             };
 
             // and one callback of the current parameter after the other
+            /** @param {unknown} [err] */
             const nextCallback = (err) => {
                 const fn = fns[fnIndex++];
                 // read before the callback runs and again after it: one that rewrites
@@ -1248,6 +1256,13 @@ module.exports = class Router extends EventEmitter {
 
     /**
      * Resolves with the route that answered, or false when nothing matched.
+     *
+     * @param {Request} req
+     * @param {Response} res
+     * @param {number} [startIndex]
+     * @param {RouteEntry[]} [routes]
+     * @param {boolean} [skipCheck] take the route at the index without matching it, see Walk
+     * @param {RouteEntry} [skipUntil] route to resume after when this chain runs out, see Walk
      * @returns {Promise<RouteEntry|false>}
      */
     _routeRequest(req, res, startIndex = 0, routes = this._routes, skipCheck = false, skipUntil) {
@@ -1366,11 +1381,16 @@ module.exports = class Router extends EventEmitter {
         // one map for the whole chain, because express builds one Route for it: a request answered
         // by the get() of an app.route() reads post() in its req.route.methods too
         const groupMethods = new NullObject();
+        /** @type {(Omit<Layer, "route"> & {method: string|undefined})[]} express's Route#stack, see createRoute */
         const groupStack = [];
         // express hands back a Route, which carries these three beside the verb methods
         fns.path = path;
         fns.methods = groupMethods;
         fns.stack = groupStack;
+        /**
+         * @param {string} method
+         * @param {unknown[]} callbacks
+         */
         const inGroup = (method, callbacks) => {
             this._pendingGroup = group;
             this._pendingGroupMethods = groupMethods;
@@ -1384,9 +1404,9 @@ module.exports = class Router extends EventEmitter {
             }
         };
         for (const method of methods) {
-            fns[method] = (...callbacks) => inGroup(method, callbacks);
+            fns[method] = (/** @type {unknown[]} */ ...callbacks) => inGroup(method, callbacks);
         }
-        fns.get = (...callbacks) => inGroup("GET", callbacks);
+        fns.get = (/** @type {unknown[]} */ ...callbacks) => inGroup("GET", callbacks);
         return fns;
     }
 
@@ -1482,7 +1502,10 @@ module.exports = class Router extends EventEmitter {
 useRouterClass(module.exports);
 
 for (const method of methods) {
-    module.exports.prototype[method] = function (path, ...callbacks) {
+    module.exports.prototype[method] = function (
+        /** @type {string|RegExp|(string|RegExp)[]} */ path,
+        /** @type {unknown[]} */ ...callbacks
+    ) {
         return this.createRoute(method, path, this, ...callbacks);
     };
 }

package/src/testing.js

@@ -134,7 +134,7 @@ function select(app, patterns, caller) {
         throw new TypeError(`${caller} needs a path, or a list of them, to check`);
     }
     const report = routeReport(app);
-    const selected = [];
+    const selected = /** @type {ReturnType<typeof routeReport>} */ ([]);
     for (const pattern of wanted) {
         const matched = report.filter((entry) => names(entry, pattern));
         if (matched.length === 0) {