fulmine.js 5.21.2 → 5.21.4

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
@@ -115,6 +83,9 @@ const MAX_MAXAGE = 60 * 60 * 24 * 365 * 1000;
 // what send takes as a range request, checked on the header's text before parsing
 const BYTES_RANGE = /^ *bytes=/;
 
+// node's test for a Transfer-Encoding that means chunked framing
+const CHUNKED_VALUE = /(?:^|\W)chunked(?:$|\W)/i;
+
 module.exports = class Response extends LazyWritable {
     /** @type {Socket|null} */
     #socket = null;
@@ -125,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
@@ -142,6 +122,13 @@ module.exports = class Response extends LazyWritable {
     /** Whether the status line and the headers have reached uWS, which only a body write does. */
     #headOut = false;
 
+    /**
+     * Whether the application set Transfer-Encoding: chunked itself. The body then goes out
+     * through uWS's write(), which frames it and writes the header, and no Content-Length is
+     * added beside it, as express 5.3 and node do. See writeHeaders and _finish.
+     */
+    #userChunked = false;
+
     /**
      * The status as writeHead settled it, the one the wire gets: a status set later never reaches
      * the client, as in node.
@@ -323,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}
      */
@@ -372,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) => {
@@ -384,6 +373,7 @@ module.exports = class Response extends LazyWritable {
         return this.#outHeaders;
     }
 
+    /** @param {Response["headers"]|null} value */
     set [kOutHeaders](value) {
         this.#outHeaders = value;
     }
@@ -446,6 +436,7 @@ module.exports = class Response extends LazyWritable {
                 this.#pendingCallback = null;
                 this.writingChunk = false;
                 if (cb) cb(null);
+                this.#afterPending();
                 return true;
             });
         } else {
@@ -454,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.
      *
@@ -469,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
@@ -478,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;
@@ -544,6 +550,7 @@ module.exports = class Response extends LazyWritable {
                             this.writingChunk = false;
                             handlerUsed = true;
                             callback(null);
+                            this.#afterPending();
                         }
                         return ok;
                     });
@@ -619,6 +626,17 @@ module.exports = class Response extends LazyWritable {
                 this.totalSize = parseInt(value);
                 continue;
             }
+            if (
+                header === "transfer-encoding" &&
+                typeof value === "string" &&
+                res._nodeRes === undefined &&
+                CHUNKED_VALUE.test(value)
+            ) {
+                // not written: uWS writes its own on the write() path, two came out before. Node's
+                // own response, behind the shim, frames by the header itself
+                this.#userChunked = true;
+                continue;
+            }
             // the recurring names and values cross as cached Buffers, see HEADER_NAME_BUF
             const name = HEADER_NAME_BUF[header] || header;
             if (Array.isArray(value)) {
@@ -676,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
@@ -705,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) {
@@ -722,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;
     }
@@ -759,9 +778,10 @@ module.exports = class Response extends LazyWritable {
             this._res.endWithoutBody();
         } else if (!data && contentLength) {
             this._res.endWithoutBody(contentLength.toString(), closeConnection);
-        } else if (headWasAlreadyOut && this.chunkedTransfer) {
+        } else if ((headWasAlreadyOut && this.chunkedTransfer) || (this.#userChunked && this._hasBody && data)) {
             // the queue first, then the last piece as a chunk: the head already went out without a
-            // length, and uWS's end() would append one
+            // length, or the application asked for chunked framing, and uWS's end() would append one.
+            // An empty body under that header takes end() below: uWS frames nothing without a write()
             this.#flushQueued(null);
             if (data) {
                 this._res.write(data);
@@ -770,9 +790,15 @@ module.exports = class Response extends LazyWritable {
             this._res.endWithoutBody();
         } else {
             if (!this._hasBody) {
-                const length = Buffer.byteLength(data ?? "");
-                this.headers["content-length"] = String(length);
-                this._res.endWithoutBody(length, closeConnection);
+                if (this.#userChunked) {
+                    // a HEAD under the application's chunked framing carries no length, as node.
+                    // No arguments: given a close flag alone, uWS writes a 2^63 length
+                    this._res.endWithoutBody();
+                } else {
+                    const length = Buffer.byteLength(data ?? "");
+                    this.headers["content-length"] = String(length);
+                    this._res.endWithoutBody(length, closeConnection);
+                }
             } else {
                 this._sentBody = data ?? "";
                 // null is the empty body: uWS never ends a response given end(null)
@@ -795,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) {
@@ -812,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("");
         }
@@ -838,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"];
@@ -870,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;
@@ -892,14 +926,15 @@ module.exports = class Response extends LazyWritable {
             body = "";
         }
         // by req.method as express's send does, so a GET a middleware made a HEAD answers its
-        // length and no body; end() alone decides by the wire, see _hasBody
+        // length and no body; end() alone decides by the wire, see _hasBody. No length beside a
+        // Transfer-Encoding the application set, as express 5.3
         if (this.req.method === "HEAD") {
-            if (this.statusCode !== 204 && this.statusCode !== 304) {
-                this.headers["content-length"] = String(Buffer.byteLength(body));
+            if (this.statusCode !== 204 && this.statusCode !== 304 && !this.headers["transfer-encoding"]) {
+                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));
     }
 
     /**
@@ -1166,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
             };
@@ -1229,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)
         };
@@ -1521,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();
@@ -1864,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;
@@ -1888,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
     ) {

package/src/server-shape.js

@@ -32,7 +32,7 @@ const kIsApplication = Symbol.for("fulmine.application");
  * Teaches `instanceof` that an application is a server, once per class. The original answer is
  * asked first and never overruled.
  *
- * @param {Function} klass http.Server or net.Server
+ * @param {Function & {[kIsApplication]?: boolean}} klass http.Server or net.Server
  */
 function acceptApplications(klass) {
     const previous = klass[Symbol.hasInstance];
@@ -48,7 +48,7 @@ function acceptApplications(klass) {
             }
             // an application is a function and a property read works on one. The guard is for the
             // primitives and nulls that reach any instanceof
-            return value != null && value[kIsApplication] === true;
+            return value != null && /** @type {{[kIsApplication]?: unknown}} */ (value)[kIsApplication] === true;
         },
         configurable: true,
         writable: true
@@ -104,7 +104,7 @@ function addServerMembers(prototype) {
      * Registers the callback like node's does and remembers the value, which is all a caller can
      * observe. The timeout belongs to uWS and is set through uwsOptions.idleTimeout.
      *
-     * @this {Application & {timeout?: number}}
+     * @this {Application & {timeout?: number|undefined}}
      * @param {number} [msecs]
      * @param {() => void} [callback]
      * @returns {Application}

package/src/server-timing.js

@@ -25,6 +25,12 @@ const { work, names } = require("./work.js");
 const { applyWriteHead } = require("./utils.js");
 
 /** @typedef {import("./response.js")} Response */
+/**
+ * What the hooks below take: writeHead's arguments in node's two shapes, see applyWriteHead, and
+ * the callback write() and end() may carry in place of the encoding.
+ * @typedef {Parameters<Response["writeHead"]>} WriteHeadArgs
+ * @typedef {(err?: Error|null) => void} WriteCallback
+ */
 
 /**
  * A duration in milliseconds, as Server-Timing writes them: two decimals.
@@ -167,15 +173,30 @@ function serverTiming(options) {
         const _writeHead = res.writeHead;
         // writeHead settles the head, so a handler that calls it is stamped there, with the headers
         // it carries applied first, as on-headers orders it
+        /**
+         * @param {WriteHeadArgs[0]} statusCode
+         * @param {WriteHeadArgs[1]} [statusMessage]
+         * @param {WriteHeadArgs[2]} [headers]
+         */
         res.writeHead = function writeHead(statusCode, statusMessage, headers) {
             const reason = applyWriteHead(this, statusMessage, headers);
             stamp();
             return _writeHead.call(this, statusCode, reason);
         };
+        /**
+         * @param {any} chunk
+         * @param {BufferEncoding|WriteCallback} [encoding]
+         * @param {WriteCallback} [callback]
+         */
         res.write = function write(chunk, encoding, callback) {
             stamp();
             return _write.call(this, chunk, encoding, callback);
         };
+        /**
+         * @param {any} [chunk]
+         * @param {BufferEncoding|WriteCallback} [encoding]
+         * @param {WriteCallback} [callback]
+         */
         res.end = function end(chunk, encoding, callback) {
             stamp();
             return _end.call(this, chunk, encoding, callback);

package/src/testing.js

@@ -242,7 +242,8 @@ function expectLazy(req, res, options) {
     const done = work(req, res);
     const unwanted = { ...done };
     for (const field of allowed) {
-        unwanted[field] = false;
+        // checked against LAZY above
+        unwanted[/** @type {keyof import("./work.js").Work} */ (field)] = false;
     }
     const listed = workNames(unwanted);
     if (listed.length === 0) {