fulmine.js 5.21.3 → 5.21.4

package/src/request.js

@@ -43,6 +43,7 @@ const {
 
 // whose headers #collectHeader is filling: uWS's forEach is synchronous, so one callback serves
 // every request
+/** @type {import("./request.js")|null} */
 let currentRequest = null;
 
 module.exports = class Request extends LazyReadable {
@@ -83,6 +84,12 @@ module.exports = class Request extends LazyReadable {
     /** @type {string[]|null} */
     #cachedSubdomains = null;
 
+    /** The socket stand-in `req.connection` once built, see the getter. @type {import("./socket.js")|null} */
+    #cachedConnection = null;
+
+    /** Behind `req.signal`, made on the first read. @type {AbortController|undefined} */
+    #abortController;
+
     /**
      * Copies one header out of uWS and notices what the constructor decides by. One function for
      * every request through currentRequest, an arrow per request cost a closure.
@@ -91,7 +98,8 @@ module.exports = class Request extends LazyReadable {
      * @param {string} value
      */
     static #collectHeader = (headerKey, value) => {
-        const r = currentRequest;
+        // set by the two forEach callers, never null while uWS is calling back
+        const r = /** @type {Request} */ (currentRequest);
         r.#rawHeadersEntries.push(headerKey, value);
         // the response, built right after, must not answer keep-alive to a client that said close
         if (headerKey.length === 10 && headerKey === "connection" && saysClose(value)) {
@@ -321,7 +329,10 @@ module.exports = class Request extends LazyReadable {
     /** The verbs a path answers, for an OPTIONS; null on every other method. @type {Set<string>|null} */
     _matchedMethods = null;
 
-    /** What each app.param() callback was called with, per router, made on first use. @type {Map<any, Map<any, any>>|null} */
+    /**
+     * What each app.param() callback was called with, per router, made on first use.
+     * @type {Map<Map<string, Function[]>, Map<string, import("./router.js").ParamCall>>|null}
+     */
     _paramCalled = null;
 
     /**
@@ -573,9 +584,6 @@ module.exports = class Request extends LazyReadable {
         return this.res?.finished || this.res?.aborted;
     }
 
-    /** @type {AbortController|undefined} */
-    #abortController;
-
     /**
      * node's `req.signal`, fired when the request is over: `@angular/ssr` reads it to give up a
      * render. Made on the first ask.
@@ -630,7 +638,10 @@ module.exports = class Request extends LazyReadable {
         return this;
     }
 
-    /** Readable's pull: uWS pushes, so this only lifts the backpressure a full queue put on it. */
+    /**
+     * Readable's pull: uWS pushes, so this only lifts the backpressure a full queue put on it.
+     * @override
+     */
     _read() {
         // first, so a bodyless stream still ends for a consumer arriving after the response
         if (this.#emptyBody) {
@@ -1011,9 +1022,6 @@ module.exports = class Request extends LazyReadable {
         return ip;
     }
 
-    /** @type {import("./socket.js")|null} */
-    #cachedConnection = null;
-
     /**
      * The socket stand-in, the same object as `res.socket`, kept here so it still answers once
      * the response is over and `res.socket` is null.
@@ -1214,8 +1222,8 @@ module.exports = class Request extends LazyReadable {
      *
      * @param {number} size length of the resource being served
      * @param {{combine?: boolean}} [options] combine adjacent and overlapping ranges
-     * @returns {Array|number|undefined} the ranges, -1 when unsatisfiable, -2 when malformed,
-     *   or undefined when there is no Range header
+     * @returns {import("range-parser").Ranges|-1|-2|undefined} the ranges, -1 when unsatisfiable,
+     *   -2 when malformed, or undefined when there is no Range header
      */
     range(size, options) {
         const range = this.headers["range"];
@@ -1302,10 +1310,8 @@ module.exports = class Request extends LazyReadable {
         return this.#rawHeadersEntries.slice();
     }
 
-    // the three below report work this request was made to do, for src/work.js
-
     /**
-     * Whether the folded `req.headers` object was built.
+     * Whether the folded `req.headers` object was built, which src/work.js reports.
      * @returns {boolean}
      */
     get _headersBuilt() {
@@ -1313,7 +1319,7 @@ module.exports = class Request extends LazyReadable {
     }
 
     /**
-     * Whether the query string was parsed at least once.
+     * Whether the query string was parsed at least once, which src/work.js reports.
      * @returns {boolean}
      */
     get _queryParsed() {
@@ -1321,7 +1327,7 @@ module.exports = class Request extends LazyReadable {
     }
 
     /**
-     * Whether the socket stand-in `req.connection` was allocated.
+     * Whether the socket stand-in `req.connection` was allocated, which src/work.js reports.
      * @returns {boolean}
      */
     get _socketBuilt() {

package/src/response-utils.js

@@ -38,9 +38,12 @@ const kShapeMode =
 const VALIDATED_HEADER_NAMES = new Map();
 // The names and values that recur on every response, kept as Buffers for the uWS crossing: a Buffer
 // is memcpy'd as it is, a string pays a UTF-8 scan and copy per call. A header that is not here
-// crosses as the string it was. Names must stay lowercase, as writeHeaders receives them.
-const HEADER_NAME_BUF = { __proto__: null };
-const HEADER_VALUE_BUF = { __proto__: null };
+// crosses as the string it was. Names must stay lowercase, as writeHeaders receives them. The
+// casts are for the __proto__ key, which the type checker reads as a property
+/** @type {Record<string, Buffer>} */
+const HEADER_NAME_BUF = /** @type {any} */ ({ __proto__: null });
+/** @type {Record<string, Buffer>} */
+const HEADER_VALUE_BUF = /** @type {any} */ ({ __proto__: null });
 for (const s of ["connection", "keep-alive", "content-type", "vary", "x-powered-by", "content-encoding"]) {
     HEADER_NAME_BUF[s] = Buffer.from(s);
 }
@@ -81,11 +84,45 @@ function statusLine(code, text) {
     return `${code} ${text ?? statuses.message[code] ?? "unknown"}`.trim();
 }
 
+/**
+ * The TypeError node throws for a chunk that is not a string, a Buffer or a Uint8Array, worded as
+ * node words it.
+ *
+ * @param {unknown} chunk what end() was handed, known here not to be a string or a Uint8Array
+ * @returns {NodeJS.ErrnoException}
+ */
+function invalidChunkError(chunk) {
+    let received;
+    if (chunk === null) {
+        received = "null";
+    } else if (typeof chunk === "object" || typeof chunk === "function") {
+        const name = /** @type {any} */ (chunk).constructor?.name;
+        received = name ? `an instance of ${name}` : "an instance of Object";
+    } else if (typeof chunk === "bigint") {
+        received = `type bigint (${chunk}n)`;
+    } else if (typeof chunk === "symbol") {
+        received = `type symbol (${String(chunk)})`;
+    } else {
+        received = `type ${typeof chunk} (${chunk})`;
+    }
+    /** @type {NodeJS.ErrnoException} */
+    const err = new TypeError(
+        `The "chunk" argument must be of type string or an instance of Buffer or Uint8Array. Received ${received}`
+    );
+    err.code = "ERR_INVALID_ARG_TYPE";
+    // as node: the bracketed name goes into the stack's first line, then err.name reads TypeError
+    err.name = "TypeError [ERR_INVALID_ARG_TYPE]";
+    void err.stack;
+    delete (/** @type {Record<string, unknown>} */ (/** @type {unknown} */ (err)).name);
+    return err;
+}
+
 module.exports = {
     kOutHeaders,
     kShapeMode,
     VALIDATED_HEADER_NAMES,
     HEADER_NAME_BUF,
     HEADER_VALUE_BUF,
-    statusLine
+    statusLine,
+    invalidChunkError
 };

package/src/response.js

@@ -49,39 +49,6 @@ const { isAbsolute } = require("path");
 const fs = require("fs");
 const Path = require("path");
 const statuses = require("statuses");
-
-/**
- * The TypeError node throws for a chunk that is not a string, a Buffer or a Uint8Array, worded as
- * node words it.
- *
- * @param {unknown} chunk what end() was handed, known here not to be a string or a Uint8Array
- * @returns {NodeJS.ErrnoException}
- */
-function invalidChunkError(chunk) {
-    let received;
-    if (chunk === null) {
-        received = "null";
-    } else if (typeof chunk === "object" || typeof chunk === "function") {
-        const name = /** @type {any} */ (chunk).constructor?.name;
-        received = name ? `an instance of ${name}` : "an instance of Object";
-    } else if (typeof chunk === "bigint") {
-        received = `type bigint (${chunk}n)`;
-    } else if (typeof chunk === "symbol") {
-        received = `type symbol (${String(chunk)})`;
-    } else {
-        received = `type ${typeof chunk} (${chunk})`;
-    }
-    /** @type {NodeJS.ErrnoException} */
-    const err = new TypeError(
-        `The "chunk" argument must be of type string or an instance of Buffer or Uint8Array. Received ${received}`
-    );
-    err.code = "ERR_INVALID_ARG_TYPE";
-    // as node: the bracketed name goes into the stack's first line, then err.name reads TypeError
-    err.name = "TypeError [ERR_INVALID_ARG_TYPE]";
-    void err.stack;
-    delete (/** @type {Record<string, unknown>} */ (/** @type {unknown} */ (err)).name);
-    return err;
-}
 const { sign } = require("cookie-signature");
 const ms = require("ms");
 const Socket = require("./socket.js");
@@ -92,7 +59,8 @@ const {
     VALIDATED_HEADER_NAMES,
     HEADER_NAME_BUF,
     HEADER_VALUE_BUF,
-    statusLine
+    statusLine,
+    invalidChunkError
 } = require("./response-utils.js");
 
 // How much a chunked response may gather before it goes to uWS: 33 KB in 500 pieces measured
@@ -128,6 +96,15 @@ module.exports = class Response extends LazyWritable {
     /** @type {((err?: Error|null) => void)|null} */
     #pendingCallback = null;
 
+    /**
+     * An end() that arrived while uWS still held a chunk, run once that chunk is through. Not
+     * waited for on 'drain': node emits it only after a write() that said false, and a piece
+     * under the high-water mark never says it, so a stream ending on a small piece a slow client
+     * had not taken yet was never closed (compression-file under load, 2026-09-21).
+     * @type {(() => void)|null}
+     */
+    #deferredEnd = null;
+
     /**
      * Chunks written but not yet handed to uWS: a write costs uWS everything buffered behind it, so
      * many small pieces cost quadratically, 500 writes of 66 bytes measured 13ms against 0.4ms in
@@ -333,6 +310,7 @@ module.exports = class Response extends LazyWritable {
      * A finished or aborted response only tears the stream down, touching an aborted uWS response
      * is a use after free. writableEnded reads true after this, node keeps it false until end().
      *
+     * @override
      * @param {Error} [error] whatever the caller is destroying the response with
      * @returns {this}
      */
@@ -382,8 +360,9 @@ module.exports = class Response extends LazyWritable {
     get [kOutHeaders]() {
         if (!this.#outHeaders) {
             this.#outHeaders = new Proxy(this.headers, {
+                // node keys the slot by lowercased name, and stores [name, value]
                 set: (obj, prop, value) => {
-                    this.set(prop, value[1]);
+                    this.set(/** @type {string} */ (prop), value[1]);
                     return true;
                 },
                 get: (obj, prop) => {
@@ -394,6 +373,7 @@ module.exports = class Response extends LazyWritable {
         return this.#outHeaders;
     }
 
+    /** @param {Response["headers"]|null} value */
     set [kOutHeaders](value) {
         this.#outHeaders = value;
     }
@@ -456,6 +436,7 @@ module.exports = class Response extends LazyWritable {
                 this.#pendingCallback = null;
                 this.writingChunk = false;
                 if (cb) cb(null);
+                this.#afterPending();
                 return true;
             });
         } else {
@@ -464,6 +445,18 @@ module.exports = class Response extends LazyWritable {
         }
     }
 
+    /**
+     * After a held chunk went through and the stream's callback ran: the callback may have pushed
+     * the next buffered piece into uWS's hands, so the waiting end() runs only when nothing is.
+     */
+    #afterPending() {
+        if (this.#deferredEnd !== null && !this.writingChunk) {
+            const end = this.#deferredEnd;
+            this.#deferredEnd = null;
+            end();
+        }
+    }
+
     /**
      * The booked flush. Static, so a response that never writes in pieces allocates no closure.
      *
@@ -479,6 +472,7 @@ module.exports = class Response extends LazyWritable {
      * Writable's sink: the head if not out yet, then the chunk to uWS through the queue for a
      * chunked response or tryEnd with a Content-Length. Backpressure defers the callback.
      *
+     * @override
      * @param {any} chunk whatever a Writable was handed
      * @param {BufferEncoding} encoding
      * @param {(err?: Error|null) => void} callback
@@ -488,11 +482,13 @@ module.exports = class Response extends LazyWritable {
             /** @type {NodeJS.ErrnoException} */
             const err = new Error("Request aborted");
             err.code = "ECONNABORTED";
-            return this.destroy(err);
+            this.destroy(err);
+            return;
         }
         if (this.finished) {
             const err = new Error("Response already finished");
-            return this.destroy(err);
+            this.destroy(err);
+            return;
         }
 
         this.writingChunk = true;
@@ -554,6 +550,7 @@ module.exports = class Response extends LazyWritable {
                             this.writingChunk = false;
                             handlerUsed = true;
                             callback(null);
+                            this.#afterPending();
                         }
                         return ok;
                     });
@@ -697,6 +694,7 @@ module.exports = class Response extends LazyWritable {
     }
 
     /**
+     * @override
      * @param {string|Buffer|Uint8Array|null|(() => void)} [data] the last body piece, or the callback in
      *   node's one-argument shape
      * @param {BufferEncoding|(() => void)} [encoding] how a string body is encoded, or the callback in
@@ -726,13 +724,11 @@ module.exports = class Response extends LazyWritable {
         }
         // uWS takes a string as utf-8 only: res.end(data, "binary") is how old code sends an image
         if (typeof data === "string" && encoding !== undefined && encoding !== "utf8" && encoding !== "utf-8") {
-            data = Buffer.from(data, encoding);
+            data = Buffer.from(data, /** @type {BufferEncoding} */ (encoding));
         }
 
         if (this.writingChunk) {
-            this.once("drain", () => {
-                this.end(data, cb);
-            });
+            this.#deferredEnd = () => this.end(data, cb);
             return this;
         }
         if (this.finished) {
@@ -743,10 +739,12 @@ module.exports = class Response extends LazyWritable {
             this.writeHead(this.statusCode);
         }
         // uWS corks itself for the synchronous window of its route handler, see _corkNeeded
+        // by now a function was moved to cb, which the editor's config cannot see
+        const chunk = /** @type {string|Uint8Array|null|undefined} */ (data);
         if (this._corkNeeded) {
-            this._res.cork(() => this._finish(data, cb));
+            this._res.cork(() => this._finish(chunk, cb));
         } else {
-            this._finish(data, cb);
+            this._finish(chunk, cb);
         }
         return this;
     }
@@ -823,7 +821,8 @@ module.exports = class Response extends LazyWritable {
      * Sends the body, with a Content-Type when none was set and an ETag when the setting asks.
      * A number is a value to serialise, never a status: that is `sendStatus()`.
      *
-     * @param {string|number|boolean|object|Buffer|null} [body]
+     * @param {string|number|boolean|object|null} [body] a Buffer or a Uint8Array is sent as bytes,
+     *   any other object is serialised
      * @returns {this}
      */
     send(body) {
@@ -840,6 +839,12 @@ module.exports = class Response extends LazyWritable {
                     delete this.headers["content-length"];
                     delete this.headers["transfer-encoding"];
                 }
+            } else if (this.req.fresh || this.statusCode === 204 || this.statusCode === 304) {
+                // express strips the content headers through removeHeader, which node refuses
+                // once the head is out; a fresh request is made a 304 first and lands here too
+                throw headersSentError("remove");
+            } else if (this.statusCode === 205) {
+                throw headersSentError("set");
             }
             return this.end("");
         }
@@ -866,11 +871,12 @@ module.exports = class Response extends LazyWritable {
         } else if (!isBuffer && typeof body !== "string") {
             // a symbol, a bigint or a function: what node's byteLength or from() throws is the
             // answer. A string never gets here, measuring it twice cost 157us per thousand requests
+            const unsendable = /** @type {any} */ (body);
             const generateETag = !this.headers["etag"] && typeof this.app._hot().etagFn === "function";
-            if (!generateETag && body.length < 1000) {
-                Buffer.byteLength(body, "utf8");
+            if (!generateETag && unsendable.length < 1000) {
+                Buffer.byteLength(unsendable, "utf8");
             }
-            Buffer.from(body, "utf8");
+            Buffer.from(unsendable, "utf8");
         }
         if (typeof body === "string" && !isBuffer) {
             const contentType = this.headers["content-type"];
@@ -898,7 +904,7 @@ module.exports = class Response extends LazyWritable {
             !this.req.noEtag &&
             (hot.etagMethods === null || hot.etagMethods.has(this.req.method))
         ) {
-            const etag = etagFn(body);
+            const etag = etagFn(/** @type {string|Buffer} */ (body));
             // an application's own etag function may decline
             if (etag) {
                 this.headers["etag"] = etag;
@@ -924,11 +930,11 @@ module.exports = class Response extends LazyWritable {
         // Transfer-Encoding the application set, as express 5.3
         if (this.req.method === "HEAD") {
             if (this.statusCode !== 204 && this.statusCode !== 304 && !this.headers["transfer-encoding"]) {
-                this.headers["content-length"] = String(Buffer.byteLength(body));
+                this.headers["content-length"] = String(Buffer.byteLength(/** @type {string|Buffer} */ (body)));
             }
             return this.end();
         }
-        return this.end(body);
+        return this.end(/** @type {string|Buffer} */ (body));
     }
 
     /**
@@ -1195,6 +1201,7 @@ module.exports = class Response extends LazyWritable {
                 });
         } else {
             // large files and ranges are piped
+            /** @type {{highWaterMark: number, start?: number, end?: number}} */
             const opts = {
                 highWaterMark: HIGH_WATERMARK
             };
@@ -1258,6 +1265,7 @@ module.exports = class Response extends LazyWritable {
         }
 
         // a header option of sendFile, as Express does: it only goes out once the stat succeeded
+        /** @type {Record<string, string>} */
         const headers = {
             "Content-Disposition": contentDisposition(name || path)
         };
@@ -1550,8 +1558,9 @@ module.exports = class Response extends LazyWritable {
      */
     set(field, value) {
         if (typeof field === "object") {
-            for (const header in field) {
-                this.set(header, field[header]);
+            const fields = /** @type {Record<string, string|string[]>} */ (field);
+            for (const header in fields) {
+                this.set(header, fields[header]);
             }
         } else {
             const name = field.toLowerCase();
@@ -1893,8 +1902,10 @@ module.exports = class Response extends LazyWritable {
             url = status;
             status = 302;
         }
+        // read from the closures below too, where the checker does not see the shuffle above
+        const code = /** @type {number} */ (status);
         this.location(/** @type {string} */ (url));
-        this.status(/** @type {number} */ (status));
+        this.status(code);
 
         const address = /** @type {string} */ (this.get("Location"));
         let body;
@@ -1917,11 +1928,11 @@ module.exports = class Response extends LazyWritable {
             this.format({
                 text: () => {
                     this.set("Content-Type", "text/plain; charset=utf-8");
-                    body = `${statuses.message[status]}. Redirecting to ${address}`;
+                    body = `${statuses.message[code]}. Redirecting to ${address}`;
                 },
                 html: () => {
                     this.set("Content-Type", "text/html; charset=utf-8");
-                    body = `<p>${statuses.message[status]}. Redirecting to ${escapeHtml(address)}</p>`;
+                    body = `<p>${statuses.message[code]}. Redirecting to ${escapeHtml(address)}</p>`;
                 },
                 default: () => {
                     // no Content-Type, as Express leaves it when the client accepts neither

package/src/route.js

@@ -166,12 +166,14 @@ function checkRouteHandlers(method, handlers) {
 }
 
 // every verb, plus all(), registered the same way: flattened, checked, then pushed with the verb
-// they answer. all() pushes handlers with no verb at all, which matches every request
+// they answer. all() pushes handlers with no verb at all, which matches every request. Loose:
+// the members are written here by name and not declared on the class
+const prototype = /** @type {any} */ (Route.prototype);
 for (const method of ["all", ...METHODS.map((verb) => verb.toLowerCase())]) {
-    if (method !== "all" && typeof Route.prototype[method] === "function") {
+    if (method !== "all" && typeof prototype[method] === "function") {
         continue;
     }
-    Route.prototype[method] = function (/** @type {unknown[]} */ ...handlers) {
+    prototype[method] = function (/** @type {unknown[]} */ ...handlers) {
         const flattened = handlers.flat(Infinity);
         checkRouteHandlers(method, flattened);
         // the check above threw on anything else

package/src/router-utils.js

@@ -53,7 +53,7 @@ const { METHODS } = require("http");
  */
 /**
  * An earlier registration a mount is guarded by, see guardsInside.
- * @typedef {{path: string, use: boolean, method: string, all: boolean}} MountGuard
+ * @typedef {{path: string, use: boolean, method: string, all: boolean, params: boolean}} MountGuard
  */
 /**
  * A layer as express shapes it, for app.stack and router.stack.
@@ -118,8 +118,19 @@ function anyGuardHits(guards, path) {
 }
 
 // every method the declarative compiler can emit: a patched one disables compilation
+/** @type {Record<string, string>} */
 const resCodes = {},
-    resDecMethods = ["set", "setHeader", "header", "send", "end", "append", "status", "json", "sendStatus"];
+    resDecMethods = /** @type {const} */ ([
+        "set",
+        "setHeader",
+        "header",
+        "send",
+        "end",
+        "append",
+        "status",
+        "json",
+        "sendStatus"
+    ]);
 for (const method of resDecMethods) {
     resCodes[method] = Response.prototype[method].toString();
 }
@@ -143,7 +154,7 @@ function layerFor(route, callback) {
             : callback.name || "<anonymous>",
         params: undefined,
         path: undefined,
-        keys: [],
+        keys: /** @type {never[]} */ ([]),
         route: undefined
     };
     route._layers.set(callback, layer);
@@ -685,6 +696,22 @@ function shadowsLeaf(guard, leafPath, leaf) {
     return pathsCanOverlap(guard.path.toLowerCase(), leafPath.toLowerCase(), guard.use);
 }
 
+/**
+ * Whether a HEAD of this leaf's path could enter a route of another verb written before the mount,
+ * for its param() callbacks: Express exempts HEAD from the method check. The GET leaf keeps its
+ * registration, only its HEAD twin goes to the generic walk. See headEnters in optimizer.js.
+ *
+ * @param {MountGuard} guard
+ * @param {string} leafPath the leaf's absolute path, parameters and all
+ * @returns {boolean}
+ */
+function headEntersGuard(guard, leafPath) {
+    if (guard.all || guard.use || !guard.params || guard.method === "GET" || guard.method === "HEAD") {
+        return false;
+    }
+    return pathsCanOverlap(guard.path.toLowerCase(), leafPath.toLowerCase(), false);
+}
+
 /**
  * The layers before a mount that answer some of what is inside it and not all of it, which neither
  * the chain nor uWS's specificity can say. Carried down the walk and asked about every leaf, see
@@ -714,7 +741,14 @@ function guardsInside(router, mount, pathPrefix, chain, inherited) {
         if (guards === inherited) {
             guards = [...inherited];
         }
-        guards.push({ path: pathPrefix + r.path, use: r.use === true, method: r.method, all: r.all === true });
+        guards.push({
+            path: pathPrefix + r.path,
+            use: r.use === true,
+            method: r.method,
+            all: r.all === true,
+            // whether its router has param() callbacks, which a HEAD runs on any matching verb
+            params: r.paramCallbacks.size > 0
+        });
     }
     return guards;
 }
@@ -798,7 +832,7 @@ function callablePrototypeFor(classPrototype) {
         return prototype;
     }
     prototype = Object.create(classPrototype);
-    for (const name of ["apply", "call", "toString"]) {
+    for (const name of /** @type {const} */ (["apply", "call", "toString"])) {
         Object.defineProperty(prototype, name, {
             value: Function.prototype[name],
             writable: true,
@@ -870,6 +904,7 @@ module.exports = {
     stepsOver,
     couldAnswer,
     shadowsLeaf,
+    headEntersGuard,
     guardsInside,
     rememberApp,
     restoreApp,

package/src/router.js

@@ -74,6 +74,11 @@ const {
 /** @typedef {import("./router-utils.js").WsRoute} WsRoute */
 /** @typedef {import("uWebSockets.js").HttpRequest} UwsRequest */
 /** @typedef {import("uWebSockets.js").HttpResponse} UwsResponse */
+/**
+ * One app.param() call as _runParamCallbacks records it: the value its callbacks were given, the
+ * one they left in req.params, and what they ended with.
+ * @typedef {{error: unknown, match: unknown, value: unknown}} ParamCall
+ */
 
 // one number per app.route(), so the routes it creates know they belong together
 let routeGroups = 0;
@@ -238,6 +243,11 @@ module.exports = class Router extends EventEmitter {
      */
     _asCallable() {
         const fn = /** @type {any} */ (
+            /**
+             * @param {any} req loose as handle() is
+             * @param {any} res
+             * @param {(err?: unknown) => void} [next]
+             */
             function (req, res, next) {
                 return fn.handle(req, res, next);
             }
@@ -668,6 +678,8 @@ module.exports = class Router extends EventEmitter {
                 // a RegExp mount matches a piece of path known only per request
                 regexMount: method === "USE" && path instanceof RegExp,
                 userRegexp: path instanceof RegExp,
+                // a compiled pattern that cannot be compared as text, decided below
+                complex: false,
                 methods: methodMap,
                 stack,
                 // the route as a request sees it, a view with the written path when normalised
@@ -1052,6 +1064,7 @@ module.exports = class Router extends EventEmitter {
             let name = "";
             /** @type {unknown} */
             let value;
+            /** @type {ParamCall} */
             let entry;
             /** @type {Function[]} */
             let fns = [];
@@ -1074,10 +1087,10 @@ module.exports = class Router extends EventEmitter {
                 }
                 name = names[index++];
                 value = req.params[name];
-                entry = called.get(name);
-                if (entry && (entry.match === value || (entry.error && entry.error !== "route"))) {
-                    req.params[name] = entry.value;
-                    return nextParam(entry.error);
+                const earlier = called.get(name);
+                if (earlier && (earlier.match === value || (earlier.error && earlier.error !== "route"))) {
+                    req.params[name] = earlier.value;
+                    return nextParam(earlier.error);
                 }
                 entry = { error: null, match: value, value };
                 called.set(name, entry);
@@ -1298,7 +1311,7 @@ module.exports = class Router extends EventEmitter {
      * @param {Record<string, any>} [carried] the headers the error asked for, written last
      */
     _sendErrorPage(request, response, err, checkEnv = false, carried = undefined) {
-        err = this._generateErrorPage(err, response.statusCode, checkEnv);
+        const page = this._generateErrorPage(err, response.statusCode, checkEnv);
         request.noEtag = true;
         // a header that cannot be written may be what brought the request here
         response._dropUnwritableHeaders();
@@ -1312,7 +1325,7 @@ module.exports = class Router extends EventEmitter {
         response.setHeader("Content-Type", "text/html; charset=utf-8");
         response.setHeader("X-Content-Type-Options", "nosniff");
         response.setHeader("Content-Security-Policy", "default-src 'none'");
-        response.send(err);
+        response.send(page);
     }
 
     /**
@@ -1368,10 +1381,11 @@ module.exports = class Router extends EventEmitter {
 useRouterClass(module.exports);
 
 // the verb methods on the prototype: as own arrows they closed over the instance they were built
-// on, and express.Router().post(...) answered with the object the callable was copied from
-
+// on, and express.Router().post(...) answered with the object the callable was copied from.
+// Loose: the members are written here by name and not declared on the class
+const prototype = /** @type {any} */ (module.exports.prototype);
 for (const method of methods) {
-    module.exports.prototype[method] = function (
+    prototype[method] = function (
         /** @type {string|RegExp|(string|RegExp)[]} */ path,
         /** @type {unknown[]} */ ...callbacks
     ) {