fulmine.js 5.19.8 → 5.19.9

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "fulmine.js",
-    "version": "5.19.8",
+    "version": "5.19.9",
     "description": "Drop-in Express 5 replacement on uWebSockets.js. Your existing middleware keeps working.",
     "main": "src/index.js",
     "exports": {

package/src/application.js

@@ -47,7 +47,7 @@ const cpuCount = os.cpus().length;
 // mounted sub-app knows it may inherit the parent's
 const trustProxyDefaultSymbol = "@@symbol:trust_proxy_default";
 
-const workers = [];
+const workers = /** @type {FSWorker[]} */ ([]);
 let taskKey = 0;
 const workerTasks = new NullObject();
 
@@ -133,7 +133,7 @@ class Application extends Router {
             becomeSupervisor();
         }
         if (settings.uwsApp) {
-            this.uwsApp = settings.uwsApp;
+            this.uwsApp = /** @type {import("uWebSockets.js").TemplatedApp} */ (settings.uwsApp);
         } else if (settings.http3) {
             // uWS.H3App exists in the pinned build but its QUIC stack does not: the constructor
             // segfaults on Linux and hangs forever on Windows before serving a single request,
@@ -401,7 +401,7 @@ class Application extends Router {
             if (value != null && (!Array.isArray(value) || value.some((m) => typeof m !== "string"))) {
                 throw new TypeError('"etag methods" wants an array of method names, or null for all of them');
             }
-            value = value == null ? undefined : value.map((m) => m.toUpperCase());
+            value = value == null ? undefined : value.map((/** @type {string} */ m) => m.toUpperCase());
         } else if (key === "etag") {
             // The skips are not taken back here. They used to be, because send consults freshness,
             // but that branch reads if-none-match, if-modified-since and cache-control by name
@@ -594,7 +594,7 @@ class Application extends Router {
         // uWS runs this handler from inside its own listen(), so everything it hands back to the
         // caller is deferred a tick. Express binds synchronously too but reports through events,
         // and node emits both 'listening' and 'error' from a process.nextTick.
-        const onListen = (socket) => {
+        const onListen = (/** @type {import("uWebSockets.js").us_listen_socket|false} */ socket) => {
             if (!socket) {
                 /** @type {NodeJS.ErrnoException} */
                 const err = new Error("listen EADDRINUSE: address already in use :::" + port);
@@ -926,6 +926,7 @@ class Application extends Router {
 // Tried once before and reverted the same day, because a callable app broke supertest: `request(app)`
 // reads `typeof app === "function"` and wraps what it finds in http.createServer, and there was
 // nothing underneath that could serve node's IncomingMessage. src/node-shim.js closes that hole.
+/** @param {object} [options] the settings express() takes, see the Application constructor */
 module.exports = function (options) {
     return new Application(options)._asCallable();
 };

package/src/cli.js

@@ -214,6 +214,7 @@ function findSpecifiersTypeScript(source, fileName, ts, seen) {
         }
     };
 
+    /** @param {import("typescript").Node} node */
     const visit = (node) => {
         // import express from "express", import type { Request } from "express", export * from it.
         // A type-only import is rewritten too: the types come from the new package as well.
@@ -465,7 +466,7 @@ function findEntry(given) {
  * owns listen.
  *
  * @param {string} entry
- * @returns {object[]} the prototypes to stub, this command's copy first
+ * @returns {Application[]} the prototypes to stub, this command's copy first
  */
 function listenOwners(entry) {
     const builds = new Set([require("./index.js")]);
@@ -477,6 +478,7 @@ function listenOwners(entry) {
         }
     }
 
+    /** @type {Application[]} */
     const owners = [];
     for (const build of builds) {
         if (typeof build !== "function") {
@@ -531,6 +533,7 @@ function loadApps(argv, command) {
         return null;
     }
 
+    /** @type {Application[]} */
     const listened = [];
     const real = owners.map((proto) => proto.listen);
     for (const proto of owners) {

package/src/compression.js

@@ -161,6 +161,7 @@ function reusableCompressor(create, finishFlag, oneShot) {
         return oneShot;
     };
 
+    /** @param {Buffer} body */
     const compress = (body) => {
         if (broken || busy) {
             return oneShot(body);

package/src/declarative.js

@@ -26,6 +26,7 @@ const uWSAny = /** @type {any} */ (uWS);
 const statuses = require("statuses");
 
 /** @typedef {import("./application.js").Application} Application */
+/** @typedef {import("./router.js")} Router */
 
 const parser = acorn.Parser;
 
@@ -45,7 +46,11 @@ const allowedResMethods = [
 
 const allowedIdentifiers = ["query", "params", ...allowedResMethods];
 
-/** What res.type(x) sets the content type to. A lookup on a literal. */
+/**
+ * What res.type(x) sets the content type to. A lookup on a literal.
+ *
+ * @param {string} type
+ */
 const typeValueOf = (type) => (type.indexOf("/") === -1 ? contentTypeFor(type) : type);
 
 // what one instruction of a declarative response can carry, since uWS writes its length as a u16
@@ -307,7 +312,7 @@ function readStatusAndHeaders(callExprs, headers) {
  * @param {any[]} callExprs the res calls, in run order, as readStatusAndHeaders takes them
  * @param {[string, string][]} headers the headers read so far, written to
  * @param {any[]} body the body parts, written to; loose because a literal's value is kept as it is
- * @param {Application} app the application, for the json settings
+ * @param {Application|Router} app the application or router the route hangs on, for the json settings
  * @param {string[]} queries names bound by a destructured req.query
  * @param {string[]} params names bound by a destructured req.params
  * @returns {{sendUsed: boolean, bodyFromSend: boolean}|null}
@@ -438,6 +443,7 @@ function readBody(callExprs, headers, body, app, queries, params) {
                     }
                     body.push({ type: arg.object.property.name, value: arg.property.name });
                 } else if (arg.type === "BinaryExpression") {
+                    /** @type {any[]} the parts, in the same loose shape as body */
                     const stuff = [];
                     /**
                      * Reads a chain of string concatenations right to left. Each side must be a literal or a
@@ -768,6 +774,10 @@ function identifiersAllowed(fn, args, names) {
 // - doesnt create variables
 // - only uses req.query and req.params
 // basically, its only simple, static responses
+/**
+ * @param {Function} cb the handler
+ * @param {Application|Router} app the application or router the route hangs on, for the json settings
+ */
 module.exports = function compileDeclarative(cb, app) {
     try {
         const handler = readHandler(cb);
@@ -791,8 +801,8 @@ module.exports = function compileDeclarative(cb, app) {
             return false;
         }
 
+        /** @type {[string, string][]} */
         const headers = [];
-        const body = [];
 
         const status = readStatusAndHeaders(callExprs, headers);
         if (status === null) {
@@ -800,6 +810,8 @@ module.exports = function compileDeclarative(cb, app) {
         }
         const { statusCode, sendStatusUsed } = status;
 
+        /** @type {any[]} loose because a literal's value is kept as it is, see readBody */
+        const body = [];
         const read = readBody(callExprs, headers, body, app, queries, params);
         if (read === null) {
             return false;

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

@@ -68,6 +68,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) {

package/src/utils.js

@@ -208,6 +208,9 @@ function getPatternMeta(pattern) {
  * A bare `*`, an unnamed parameter, an inline regex like :id(\\d+) and the `+`, `?`, `()` operators
  * throw: a route that quietly stops matching is worse than one that fails at startup. The names it
  * captures go in a WeakMap beside the regex, see PatternMeta.
+ *
+ * @param {string|RegExp} pattern
+ * @returns {RegExp}
  */
 function patternToRegex(pattern, isPrefix = false, caseSensitive = true, strict = false) {
     if (pattern instanceof RegExp) {
@@ -222,11 +225,12 @@ function patternToRegex(pattern, isPrefix = false, caseSensitive = true, strict
     let regexPattern = "";
     let i = 0;
     const len = pattern.length;
-    const wildcardNames = [];
+    const wildcardNames = /** @type {string[]} */ ([]);
     // express takes /:a/:a, and two capture groups cannot share a name, so a repeat is compiled
     // under a spelling of its own and mapped back when the parameters are read out. Reading them
     // in order then leaves the last occurrence in place, which is the value express reports
-    const groupOutputName = new Map();
+    const groupOutputName = /** @type {Map<string, string>} */ (new Map());
+    /** @param {string} name */
     const uniqueGroupName = (name) => {
         if (!groupOutputName.has(name)) {
             groupOutputName.set(name, name);
@@ -255,7 +259,11 @@ function patternToRegex(pattern, isPrefix = false, caseSensitive = true, strict
     let lastCaptureWasWildcard = false;
     let wildcardInSegment = false;
     let paramInSegment = false;
-    /** Records literal text as it is emitted, which is what the rules above are written against. */
+    /**
+     * Records literal text as it is emitted, which is what the rules above are written against.
+     *
+     * @param {string} text
+     */
     const literal = (text) => {
         backtrack += text;
         if (lastCaptureWasWildcard) {
@@ -750,7 +758,8 @@ function acceptParams(str) {
     const length = str.length;
     const colonIndex = str.indexOf(";");
     let index = colonIndex === -1 ? length : colonIndex;
-    const ret = { value: str.slice(0, index).trim(), quality: 1, params: {} };
+    const params = /** @type {Record<string, string>} */ ({});
+    const ret = { value: str.slice(0, index).trim(), quality: 1, params };
 
     while (index < length) {
         const splitIndex = str.indexOf("=", index);
@@ -1098,13 +1107,20 @@ function durationSetting(value, name) {
     return parsed;
 }
 
+/**
+ * The predicate "trust proxy" compiles to: whether the address at hop i is trusted. The address is
+ * undefined over a unix socket, see Request#parsedIp.
+ *
+ * @typedef {(addr: string|undefined, i: number) => boolean} TrustFn
+ */
+
 /**
  * Turns whatever "trust proxy" was set to into the function proxy-addr wants: a predicate saying
  * whether the address at hop i is trusted. true trusts everything, a number trusts that many hops,
  * and a string or a list is read as addresses and subnet names.
  *
- * @param {boolean|number|string|string[]|Function} val
- * @returns {Function}
+ * @param {boolean|number|string|string[]|TrustFn} val
+ * @returns {TrustFn}
  */
 function compileTrust(val) {
     if (typeof val === "function") return val;
@@ -1118,8 +1134,9 @@ function compileTrust(val) {
 
     if (typeof val === "number") {
         // Support trusting hop count
-        return function (a, i) {
-            return i < val;
+        const hops = val;
+        return function (/** @type {string|undefined} */ a, /** @type {number} */ i) {
+            return i < hops;
         };
     }
 
@@ -1130,7 +1147,9 @@ function compileTrust(val) {
         });
     }
 
-    return proxyaddr.compile(val || []);
+    // proxy-addr answers false to an address it cannot parse, undefined included, though its
+    // typing does not admit one
+    return /** @type {TrustFn} */ (proxyaddr.compile(val || []));
 }
 
 const shownWarnings = new Set();

package/src/walk.js

@@ -79,6 +79,7 @@ class Walk {
         //
         // Null here and bound on the first route with more than one callback, the only shape that
         // reads it: a request that never meets one paid a bind for nothing
+        /** @type {((err?: unknown) => void)|null} */
         this.leaveRoute = null;
     }
 
@@ -103,6 +104,7 @@ class Walk {
      * a chain of N middlewares costs one promise instead of N nested ones.
      *
      * @param {number} startIndex where to resume the scan
+     * @returns {void}
      */
     dispatch(startIndex) {
         const req = this.req;
@@ -226,7 +228,7 @@ class Walk {
                 .then((resumed) => this.runRoute(resumed))
                 // wrapped so the native pair keeps the walk as receiver; a promise's reject
                 // would not have cared
-                .catch((err) => this.reject(err));
+                .catch((/** @type {unknown} */ err) => this.reject(err));
             return;
         }
         return this.runRoute(continueRoute);
@@ -291,6 +293,7 @@ class Walk {
      * way in, and then the route's callbacks run one after another through next().
      *
      * @param {true|"route"} continueRoute what _preprocessRequest decided: true to run, "route" to skip
+     * @returns {void}
      */
     runRoute(continueRoute) {
         const req = this.req;
@@ -347,6 +350,7 @@ class Walk {
      *
      * @param {number} kind what the callback is, one of the CALLBACK_ constants
      * @param {Function} callback
+     * @returns {void}
      */
     errorHop(kind, callback) {
         const req = this.req;
@@ -441,6 +445,7 @@ class Walk {
      * leave the route; with anything else, remember it as the error and carry on.
      *
      * @param {unknown} thingamabob what next() was called with: nothing, "route", or an error
+     * @returns {void}
      */
     step(thingamabob) {
         const req = this.req;
@@ -492,7 +497,7 @@ class Walk {
             }
             callback
                 ._routeRequest(req, res, 0)
-                .then((routed) => {
+                .then((/** @type {RouteEntry|false} */ routed) => {
                     // the child's params are scoped to it, and must not leak into the routes after
                     if (pushedParams) {
                         req._paramStack.pop();
@@ -531,7 +536,7 @@ class Walk {
                 // a rejection out of the nested walk, or a throw above, must reject this one
                 // instead of dying as an unhandled rejection; wrapped for the native pair's
                 // receiver
-                .catch((err) => this.reject(err));
+                .catch((/** @type {unknown} */ err) => this.reject(err));
         } else {
             // errors and error handlers live out of line: this is the cold path, and its size
             // was pushing step past the inlining threshold

package/src/websocket.js

@@ -208,7 +208,7 @@ function makeUpgradeHandler(app, path, behavior) {
  * @param {Application} app
  */
 function registerWebSocketRoutes(app) {
-    const routes = [];
+    const routes = /** @type {WsRoute[]} */ ([]);
     collectRoutes(app, "", routes, new Set());
     for (const route of routes) {
         const uwsBehavior = { ...route.behavior };