fulmine.js 5.19.3 → 5.19.4

package/src/response.js

@@ -38,6 +38,8 @@ const {
     withUtf8Charset,
     asStatError,
     httpError,
+    headersSentError,
+    applyWriteHead,
     contentTypeFor,
     statTag,
     cachedStat,
@@ -79,6 +81,9 @@ const JSON_UTF8 = "application/json; charset=utf-8";
 // than written out, since a year is already longer than any cache will honour.
 const MAX_MAXAGE = 60 * 60 * 24 * 365 * 1000;
 
+// what send takes as a range request: the bytes unit, checked on the header's text before parsing
+const BYTES_RANGE = /^ *bytes=/;
+
 module.exports = class Response extends LazyWritable {
     /** @type {Socket|null} */
     #socket = null;
@@ -106,15 +111,21 @@ module.exports = class Response extends LazyWritable {
     /** Whether a flush is already booked for the end of this turn. */
     #flushBooked = false;
 
-    /** @type {any} */
-    #outHeaders = null;
+    /** Whether the status line and the headers have reached uWS, which only a body write does. */
+    #headOut = false;
 
     /**
-     * Whether node's writeHead has run, which only the per-app subclass sets. _sendOptionsReply
-     * refuses to write a second head over it, as node's setHeader does.
-     * @type {boolean|undefined}
+     * The status line as writeHead settled it, which is the one the wire gets: node stores the
+     * head at writeHead, so a status set later never reaches the client.
+     * @type {number}
      */
-    _headWritten;
+    #status = 200;
+
+    /** @type {string|undefined} */
+    #statusText = undefined;
+
+    /** @type {Response["headers"]|null} */
+    #outHeaders = null;
 
     /**
      * The request this response answers, linked so either reaches the other.
@@ -127,10 +138,9 @@ module.exports = class Response extends LazyWritable {
      * two that describe the connection, since every response carries them, and x-powered-by only
      * when the setting asks for it.
      *
-     * @param {any} res the uWS response
-     * @param {any} req the Request, already built. Loose because the per-app subclass in
-     *   application.js inherits this constructor and its own shape has to stay assignable
-     * @param {any} app the application or router this request arrived at
+     * @param {import("uWebSockets.js").HttpResponse} res the uWS response
+     * @param {InstanceType<typeof import("./request.js")>} req the Request, already built
+     * @param {import("./application.js").Application} app the application this request arrived at
      */
     constructor(res, req, app) {
         super();
@@ -139,6 +149,7 @@ module.exports = class Response extends LazyWritable {
         // the order node's own Writable constructor lays down, so the hidden class is the one every
         // other stream in the process has, and node's init keeps this object when the state is
         // finally built
+        /** @type {Record<string, Function|undefined>} */
         this._events = {
             close: undefined,
             error: undefined,
@@ -191,7 +202,7 @@ module.exports = class Response extends LazyWritable {
         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
-        /** @type {string|Buffer|undefined} */
+        /** @type {string|Buffer|Uint8Array|undefined} */
         this._sentBody = undefined;
         // false while the uWS route handler is still in its synchronous window, where uWS holds
         // the socket corked itself; the two uWS entry points flip it once that window closes
@@ -206,8 +217,7 @@ module.exports = class Response extends LazyWritable {
         //
         // The condition is the safety of it: a fresh response has no listeners, so both slots are
         // free, and anything else falls back to on(), which finds what this wrote.
-        // cast because _events and _eventsCount are EventEmitter's own bookkeeping and have no type
-        const self = /** @type {any} */ (this);
+        const self = this;
         const events = self._events;
         if (
             self._eventsCount === 0 &&
@@ -252,7 +262,7 @@ module.exports = class Response extends LazyWritable {
      * aborted uWS response is a use after free. writableEnded reads true after this, where node
      * leaves it false until end() is called.
      *
-     * @param {any} [error] whatever the caller is destroying the response with
+     * @param {Error} [error] whatever the caller is destroying the response with
      * @returns {this}
      */
     destroy(error) {
@@ -282,7 +292,7 @@ module.exports = class Response extends LazyWritable {
             return;
         }
         this._pendingLinked = false;
-        const pending = /** @type {any} */ (this)._pendingIn;
+        const pending = /** @type {{_pendingIn?: {head: Response|null}}} */ (this)._pendingIn;
         const prev = this._pendingPrev;
         const next = this._pendingNext;
         if (prev) {
@@ -337,7 +347,7 @@ module.exports = class Response extends LazyWritable {
      * over, as node's does; the request's `socket` is the same object and stays, so it comes
      * through here instead.
      *
-     * @returns {any}
+     * @returns {Socket}
      */
     _socketShim() {
         if (!this.#socket) {
@@ -428,13 +438,15 @@ module.exports = class Response extends LazyWritable {
 
         this.writingChunk = true;
         this._res.cork(() => {
-            if (!this.headersSent) {
-                this.writeHead(this.statusCode);
+            if (!this.#headOut) {
+                if (!this.headersSent) {
+                    this.writeHead(this.statusCode);
+                }
                 // "unknown" and not the bare number: node writes that reason phrase for a code it
                 // has no message for, so the raw status lines match. The default 200 with no
                 // phrase is uWS's own head, byte for byte, so it is not written at all
-                if (this.statusCode !== 200 || this.statusText !== undefined) {
-                    this._res.writeStatus(statusLine(this.statusCode, this.statusText));
+                if (this.#status !== 200 || this.#statusText !== undefined) {
+                    this._res.writeStatus(statusLine(this.#status, this.#statusText));
                 }
                 this.writeHeaders(typeof chunk === "string");
             }
@@ -503,8 +515,9 @@ module.exports = class Response extends LazyWritable {
 
     /**
      * Sets the status and, optionally, a batch of headers, the way node does. The second argument
-     * is either the status message or the headers, since node allows both shapes. Nothing is
-     * written here despite the name: the headers go out when the body does.
+     * is either the status message or the headers, since node allows both shapes. The bytes go out
+     * with the body, but the head is settled here, as node's is: headersSent reads true from now
+     * on, what is set later throws, and a status written later never reaches the wire.
      *
      * Every header goes through setHeader and not through set. This is node's method, not
      * Express's: a content-type given here keeps the value it was given, where res.set would append
@@ -512,38 +525,23 @@ module.exports = class Response extends LazyWritable {
      * @sveltejs/adapter-node included, so the charset was added to pages nobody asked it for.
      *
      * @param {number} statusCode
-     * @param {string|Record<string, any>|any[]} [statusMessage] the reason phrase, or the headers
-     * @param {Record<string, any>|any[]} [headers]
+     * @param {string|import("http").OutgoingHttpHeaders|import("http").OutgoingHttpHeader[]} [statusMessage] the
+     *   reason phrase, or the headers
+     * @param {import("http").OutgoingHttpHeaders|import("http").OutgoingHttpHeader[]} [headers]
      * @returns {this}
      */
     writeHead(statusCode, statusMessage, headers) {
-        this.statusCode = statusCode;
-        if (typeof statusMessage === "string") {
-            this.statusText = statusMessage;
-        }
-        if (!headers) {
-            if (!statusMessage) return this;
-            // the two-argument shape, where what looked like a reason phrase is the headers. A
-            // string reaching here was already taken as the phrase above and simply has no keys.
-            headers = /** @type {Record<string, any>} */ (statusMessage);
-        }
-        if (Array.isArray(headers)) {
-            // node takes a flat list here, name then value, and not a list of pairs. An odd length
-            // is the caller's mistake and node names the argument in what it throws
-            if (headers.length % 2 !== 0) {
-                /** @type {NodeJS.ErrnoException} */
-                const err = new TypeError(`The argument 'headers' is invalid. Received ${JSON.stringify(headers)}`);
-                err.code = "ERR_INVALID_ARG_VALUE";
-                throw err;
-            }
-            for (let i = 0; i < headers.length; i += 2) {
-                this.setHeader(headers[i], headers[i + 1]);
-            }
-            return this;
+        if (this.headersSent) {
+            throw headersSentError("write");
         }
-        for (const header in headers) {
-            this.setHeader(header, headers[header]);
+        this.statusCode = statusCode;
+        const reason = applyWriteHead(this, statusMessage, headers);
+        if (reason !== undefined) {
+            this.statusText = reason;
         }
+        this.#status = statusCode;
+        this.#statusText = this.statusText;
+        this.headersSent = true;
         return this;
     }
 
@@ -597,16 +595,19 @@ module.exports = class Response extends LazyWritable {
             }
         }
         this.headersSent = true;
+        this.#headOut = true;
     }
 
     /**
-     * What node calls before writing a body when the caller never called writeHead. Here there is
-     * nothing to flush, since the headers are written with the body, so this only fixes the status.
+     * What node calls before writing a body when the caller never called writeHead: it settles the
+     * head, and nothing is flushed, since the headers are written with the body. Not once the head
+     * is settled: the compression module calls this on the strength of node's _header, which this
+     * response does not keep, so the guard is here instead of there.
      */
     _implicitHeader() {
-        // compatibility function
-        // usually should send headers but this is useless for us
-        this.writeHead(this.statusCode);
+        if (!this.headersSent) {
+            this.writeHead(this.statusCode);
+        }
     }
 
     /**
@@ -645,17 +646,29 @@ module.exports = class Response extends LazyWritable {
     }
 
     /**
-     * @param {any} [data] the last body piece, or the callback in node's two-argument shape
-     * @param {any} [cb]
+     * @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
+     *   node's two-argument shape
+     * @param {() => void} [cb]
      * @returns {this}
      */
-    end(data, cb) {
+    end(data, encoding, cb) {
         if (typeof data === "function") {
             cb = data;
             data = undefined;
+            encoding = undefined;
+        } else if (typeof encoding === "function") {
+            cb = encoding;
+            encoding = undefined;
         }
         if (typeof cb !== "function") {
-            cb = undefined; // silence the error?
+            cb = undefined;
+        }
+        // uWS takes a string as utf-8 and nothing else, so any other encoding is applied here, the
+        // way write() applies it: 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);
         }
 
         if (this.writingChunk) {
@@ -667,7 +680,11 @@ module.exports = class Response extends LazyWritable {
         if (this.finished) {
             return this;
         }
-        this.writeHead(this.statusCode);
+        // as node's end() calls _implicitHeader: not after an explicit writeHead, which settled the
+        // head already and told on-headers' listeners
+        if (!this.headersSent) {
+            this.writeHead(this.statusCode);
+        }
         // uWS holds the socket corked for the synchronous window of its route handler, and
         // cork inside cork is a passthrough: the wrapper and its closure are only paid once the
         // answer has outlived that window, which is what _corkNeeded records
@@ -683,23 +700,23 @@ module.exports = class Response extends LazyWritable {
      * The corked tail of end(): status, headers, body and the finish events. Split out so a
      * synchronous answer calls it straight, already inside uWS's own cork.
      *
-     * @param {any} data the last body piece
-     * @param {any} cb
+     * @param {string|Buffer|Uint8Array|null|undefined} data the last body piece
+     * @param {(() => void)|undefined} cb
      */
     _finish(data, cb) {
         // read before the head is written below, which is what sets the flag: what matters further
         // down is whether something had already committed the framing, a flushHeaders() or a first
         // res.write(), not whether this call is about to write the head itself
-        const headWasAlreadyOut = this.headersSent;
-        if (!this.headersSent) {
+        const headWasAlreadyOut = this.#headOut;
+        if (!this.#headOut) {
             // freshness is not decided here. node's end() knows nothing about conditional requests,
             // and Express answers 304 from send() and from sendFile(), each of which strips the
             // entity headers first. Deciding it here made res.end("body") answer 304 and drop the
             // body the caller had just written.
             // "unknown" for a code without a message, as node's status line has it. The default 200
             // with no phrase is not written at all: uWS emits the identical head on its own
-            if (this.statusCode !== 200 || this.statusText !== undefined) {
-                this._res.writeStatus(statusLine(this.statusCode, this.statusText));
+            if (this.#status !== 200 || this.#statusText !== undefined) {
+                this._res.writeStatus(statusLine(this.#status, this.#statusText));
             }
             this.writeHeaders(true);
         }
@@ -714,7 +731,7 @@ module.exports = class Response extends LazyWritable {
         const closeConnection = this.req._connectionClose === true;
         // 204 and 304 carry no body, so no Content-Length may describe one either; 1xx is the
         // third case, by range
-        if (this.statusCode === 204 || this.statusCode === 304 || this.statusCode < 200) {
+        if (this.#status === 204 || this.#status === 304 || this.#status < 200) {
             // no body and no length describing one, whatever the caller passed. node decides
             // this the same way, from the status alone, so res.status(304).end("x") sends the
             // status and nothing else on either.
@@ -739,7 +756,7 @@ module.exports = class Response extends LazyWritable {
             if (this.req.method === "HEAD") {
                 const length = Buffer.byteLength(data ?? "");
                 this.headers["content-length"] = String(length);
-                this._res.endWithoutBody(length.toString(), closeConnection);
+                this._res.endWithoutBody(length, closeConnection);
             } else {
                 // remembered rather than measured: only a caller that asks for content-length pays
                 // for it, and uWS is measuring the same bytes for the wire anyway
@@ -774,7 +791,8 @@ module.exports = class Response extends LazyWritable {
      */
     send(body) {
         if (this.headersSent) {
-            throw new Error("Can't write body: Response was already sent");
+            // what express's send meets first once the head is out is setHeader's refusal
+            throw headersSentError("set");
         }
         // a typed array is bytes to send, not an object to serialise: res.send(new Uint8Array([104,
         // 101, 121])) is "hey" and not {"0":104,"1":101,"2":121}. Uint8Array and not every view
@@ -874,10 +892,11 @@ module.exports = class Response extends LazyWritable {
      * options position is the callback.
      *
      * Options: `root`, `maxAge`, `lastModified`, `headers`, `dotfiles` ("allow", "deny" or
-     * "ignore"), `acceptRanges`, `cacheControl`, `immutable`, `etag` and `setHeaders`.
+     * "ignore"), `acceptRanges`, `cacheControl`, `immutable` and `etag`.
      *
      * @param {string} path
-     * @param {import("./options").SendFileOptions} [options]
+     * @param {import("./options").SendFileOptions|((err?: Error) => void)} [options] or the callback in
+     *   its place
      * @param {(err?: Error) => void} [callback] called once sent, or with the error
      */
     sendFile(path, options = new NullObject(), callback) {
@@ -890,7 +909,7 @@ module.exports = class Response extends LazyWritable {
             throw new TypeError("path must be a string to res.sendFile");
         }
         if (typeof options === "function") {
-            callback = /** @type {any} */ (options);
+            callback = options;
             options = new NullObject();
         }
         if (!options) options = new NullObject();
@@ -900,7 +919,7 @@ module.exports = class Response extends LazyWritable {
         // The router's next and not the route's: express reports a file it could not serve past the
         // rest of the route, so a four argument handler inside the route never sees it
         const next = this.req._leaveRoute ?? this.req.next;
-        const done = /** @type {(err?: any) => void} */ (
+        const done = /** @type {(err?: NodeJS.ErrnoException) => void} */ (
             (err) => {
                 if (callback) return callback(err);
                 if (err && err.code === "EISDIR") return next();
@@ -914,7 +933,9 @@ module.exports = class Response extends LazyWritable {
         // the branch that is already a number: ms() answers undefined for a duration it cannot
         // read, and Number.isNaN(undefined) is false, so an unreadable string reached it as NaN
         const maxAge = Number(
-            typeof options.maxAge === "string" ? ms(/** @type {any} */ (options.maxAge)) : options.maxAge
+            typeof options.maxAge === "string"
+                ? ms(/** @type {import("ms").StringValue} */ (options.maxAge))
+                : options.maxAge
         );
         options.maxAge = Number.isNaN(maxAge) ? 0 : Math.min(Math.max(0, maxAge), MAX_MAXAGE);
         if (typeof options.lastModified === "undefined") {
@@ -1005,14 +1026,15 @@ module.exports = class Response extends LazyWritable {
             } catch (err) {
                 // the fs error itself, carrying its errno and path, with send's status written on
                 // it: a missing file is the request's 404, an unreadable one is the server's 500
-                return done(asStatError(/** @type {any} */ (err)));
+                return done(asStatError(/** @type {import("./utils.js").HttpError} */ (err)));
             }
             if (stat.isDirectory()) {
                 // Express reports a directory as an EISDIR with no status, because send tells it
                 // apart from an error: it emits "directory", and res.sendFile has no listener for
                 // one. So this is not a 404, and an error handler reading err.code sees the code
                 // it expects. Without a callback, done() turns it into a plain next().
-                const err = /** @type {any} */ (new Error("EISDIR, read"));
+                /** @type {NodeJS.ErrnoException} */
+                const err = new Error("EISDIR, read");
                 err.code = "EISDIR";
                 return done(err);
             }
@@ -1040,8 +1062,10 @@ module.exports = class Response extends LazyWritable {
                 this.setHeader(header, options.headers[header]);
             }
         }
-        if (options.setHeaders) {
-            options.setHeaders(/** @type {any} */ (this), fullpath, stat);
+        // express.static's setHeaders, which res.sendFile does not take: express ignores it here,
+        // so it travels under a name only the middleware writes
+        if (options._setHeaders) {
+            options._setHeaders(this, fullpath, stat);
         }
 
         // etag, from the stat and never from the app's "etag fn". send computes this itself with
@@ -1090,7 +1114,10 @@ module.exports = class Response extends LazyWritable {
 
         // range requests
         if (options.acceptRanges) {
-            if (this.req.headers.range) {
+            // only the bytes unit, and send checks the header's text for it before parsing:
+            // "items=0-1" or "Bytes=0-1" is not a range request, and answers the whole file
+            const rangeHeader = this.req.headers.range;
+            if (rangeHeader !== undefined && BYTES_RANGE.test(rangeHeader)) {
                 // the branch above established the header is there, so range() cannot answer
                 // the undefined it uses to mean "no Range header"
                 let ranges = /** @type {ReturnType<typeof import("range-parser")>} */ (
@@ -1149,7 +1176,8 @@ module.exports = class Response extends LazyWritable {
                         // ECONNABORTED to a callback and never to next(), so aborts stay out of
                         // the error middleware.
                         if (this.aborted && callback) {
-                            const err = /** @type {any} */ (new Error("Request aborted"));
+                            /** @type {NodeJS.ErrnoException} */
+                            const err = new Error("Request aborted");
                             err.code = "ECONNABORTED";
                             callback(err);
                         }
@@ -1267,7 +1295,8 @@ module.exports = class Response extends LazyWritable {
      * what a media type is. res.set does that, and is what Express code should use.
      *
      * @param {string} field
-     * @param {any} value an array sends the header once per entry
+     * @param {number|string|readonly string[]|undefined} value an array sends the header once per
+     *   entry; undefined is refused, as node refuses it
      * @returns {this}
      * @throws {Error} once the headers have gone out
      * @throws {TypeError} if the name is not a token, the value is undefined, or the value holds a
@@ -1275,7 +1304,7 @@ module.exports = class Response extends LazyWritable {
      */
     setHeader(field, value) {
         if (this.headersSent) {
-            throw new Error("Cannot set headers after they are sent to the client");
+            throw headersSentError("set");
         }
         // one Map hit for a name already validated and lowercased: middleware writes the same
         // constant names on every request. Insert-only after validation, so no bad name can enter
@@ -1338,15 +1367,17 @@ module.exports = class Response extends LazyWritable {
      * @returns {void}
      */
     flushHeaders() {
-        if (this.headersSent || this.finished || this.aborted) {
+        if (this.#headOut || this.finished || this.aborted) {
             return;
         }
         this._res.cork(() => {
-            this.writeHead(this.statusCode);
+            if (!this.headersSent) {
+                this.writeHead(this.statusCode);
+            }
             // the same rule the chunked write path follows: uWS emits the 200 head itself, byte for
             // byte, so writing it again would only cost a crossing
-            if (this.statusCode !== 200 || this.statusText !== undefined) {
-                this._res.writeStatus(statusLine(this.statusCode, this.statusText));
+            if (this.#status !== 200 || this.#statusText !== undefined) {
+                this._res.writeStatus(statusLine(this.#status, this.#statusText));
             }
             // true, as the chunked path passes for a string chunk: what follows a flush is a body
             // written in pieces, and the framing has to be the one that allows them
@@ -1403,10 +1434,7 @@ module.exports = class Response extends LazyWritable {
      */
     #refuseInformationAfterHead() {
         if (this.headersSent) {
-            /** @type {NodeJS.ErrnoException} */
-            const err = new Error("Cannot write headers after they are sent to the client");
-            err.code = "ERR_HTTP_HEADERS_SENT";
-            throw err;
+            throw headersSentError("write");
         }
     }
 
@@ -1439,7 +1467,7 @@ module.exports = class Response extends LazyWritable {
      * node's `assignSocket`, which the http server uses when a response is
      * handed a raw socket. There is no such socket here.
      *
-     * @param {any} [socket] node takes one here and there is none to take
+     * @param {import("net").Socket} [socket] node takes one here and there is none to take
      * @returns {void}
      */
     assignSocket(socket) {}
@@ -1447,7 +1475,7 @@ module.exports = class Response extends LazyWritable {
     /**
      * node's `detachSocket`, which the http server uses when a response is
      * handed a raw socket. There is no such socket here.
-     * @param {any} [socket] node takes one here and there is none to take
+     * @param {import("net").Socket} [socket] node takes one here and there is none to take
      * @returns {void}
      */
     detachSocket(socket) {}
@@ -1508,10 +1536,10 @@ module.exports = class Response extends LazyWritable {
         const key = name.toLowerCase();
         const current = this.headers[key];
         if (current === undefined) {
-            return this.setHeader(name, /** @type {any} */ (value));
+            return this.setHeader(name, value);
         }
-        const merged = [].concat(/** @type {any} */ (current), /** @type {any} */ (value));
-        return this.setHeader(name, /** @type {any} */ (merged));
+        const merged = /** @type {string[]} */ ([]).concat(current, value);
+        return this.setHeader(name, merged);
     }
 
     /**
@@ -1526,15 +1554,15 @@ module.exports = class Response extends LazyWritable {
         if (typeof Headers === "function" && headers instanceof Headers) {
             for (const name of new Set([...headers.keys()])) {
                 if (name === "set-cookie") {
-                    this.setHeader(name, /** @type {any} */ (headers.getSetCookie()));
+                    this.setHeader(name, headers.getSetCookie());
                 } else {
-                    this.setHeader(name, /** @type {any} */ (headers.get(name)));
+                    this.setHeader(name, /** @type {string} */ (headers.get(name)));
                 }
             }
             return this;
         }
         for (const [name, value] of headers) {
-            this.setHeader(name, /** @type {any} */ (value));
+            this.setHeader(name, value);
         }
         return this;
     }
@@ -1551,8 +1579,8 @@ module.exports = class Response extends LazyWritable {
 
     /**
      * The Express name for set(), including the charset it adds to a content-type.
-     * @param {any} field a header name, or an object of them
-     * @param {any} [value] the header value, or nothing when the first argument is an object
+     * @param {string|object} field a header name, or an object of them
+     * @param {string|string[]} [value] the header value, or nothing when the first argument is an object
      * @returns {this}
      */
     header(field, value) {
@@ -1644,6 +1672,9 @@ module.exports = class Response extends LazyWritable {
      * @param {string} field
      */
     removeHeader(field) {
+        if (this.headersSent) {
+            throw headersSentError("remove");
+        }
         const key = field.toLowerCase();
         // the delete is a runtime call, and helmet removes a header most responses never carry
         if (key in this.headers) {
@@ -1677,12 +1708,13 @@ module.exports = class Response extends LazyWritable {
      * Renders a view and sends it. With a callback the result goes to the callback instead, and
      * nothing is sent. A function in the options position is taken as the callback.
      * @param {string} view view name
-     * @param {Record<string, any>} [options] locals for the view
+     * @param {Record<string, any>|((err: Error|null, html?: string) => void)} [options] locals for the
+     *   view, or the callback in its place
      * @param {(err: Error|null, html?: string) => void} [callback]
      */
     render(view, options, callback) {
         if (typeof options === "function") {
-            callback = /** @type {any} */ (options);
+            callback = /** @type {(err: Error|null, html?: string) => void} */ (options);
             options = {};
         }
         if (!options) {
@@ -1720,7 +1752,7 @@ module.exports = class Response extends LazyWritable {
         const opt = { ...(options ?? {}) }; // create a new ref because we change original object (https://github.com/dimdenGD/ultimate-express/issues/68)
         // cookie-parser hangs the secret on the request, so it is read off it rather than
         // declared here: without that middleware there is none, which is what this checks
-        const req = /** @type {any} */ (this.req);
+        const req = /** @type {{secret?: string}} */ (this.req);
         if (opt.signed && !req.secret) {
             // the message has to read like this: it is the one Express throws, and it names the
             // thing that is actually missing rather than the library that noticed
@@ -1739,7 +1771,7 @@ module.exports = class Response extends LazyWritable {
             delete opt.maxAge;
         }
         if (opt.signed) {
-            val = "s:" + sign(val, req.secret);
+            val = "s:" + sign(val, /** @type {string} */ (req.secret));
         }
 
         if (opt.path == null) {
@@ -1784,7 +1816,7 @@ module.exports = class Response extends LazyWritable {
      * Answers according to the Accept header, calling the handler whose key matches best. A
      * `default` key catches everything else; without one an unmatched request gets 406.
      * Sets Vary: Accept.
-     * @param {Record<string, any>} object handlers keyed by extension or mime type
+     * @param {Record<string, Function>} object handlers keyed by extension or mime type
      * @returns {this}
      */
     format(object) {
@@ -1822,11 +1854,14 @@ module.exports = class Response extends LazyWritable {
      * @returns {this}
      */
     json(body) {
+        const hot = this.app._hot();
+        // serialised before the type is set, as express orders it: a body JSON.stringify refuses,
+        // a BigInt for one, throws out of here with the response's headers as they were
+        const json = stringify(body, hot.jsonReplacer, hot.jsonSpaces, hot.jsonEscape);
         if (!this.headers["content-type"]) {
             this.headers["content-type"] = JSON_UTF8;
         }
-        const hot = this.app._hot();
-        return this.send(stringify(body, hot.jsonReplacer, hot.jsonSpaces, hot.jsonEscape));
+        return this.send(json);
     }
 
     /**
@@ -1878,7 +1913,7 @@ module.exports = class Response extends LazyWritable {
 
     /**
      * Adds to the Link header, one entry per key, the key being the rel.
-     * @param {Record<string, any>} links rel to url
+     * @param {Record<string, string>} links rel to url
      * @returns {this}
      */
     links(links) {
@@ -2001,7 +2036,7 @@ module.exports = class Response extends LazyWritable {
     vary(field) {
         // the vary package decides: it throws when there is no field at all, and does nothing at
         // all for an empty list, which is not the same thing and used to be refused here as well
-        vary(/** @type {any} */ (this), field);
+        vary(/** @type {import("http").ServerResponse} */ (/** @type {unknown} */ (this)), field);
         return this;
     }
 
@@ -2036,4 +2071,5 @@ module.exports = class Response extends LazyWritable {
 
 // res.contentType is res.type under express's other name. On the prototype rather than an instance
 // field, which wrote one own property per response in the constructor.
-/** @type {any} */ (module.exports.prototype).contentType = module.exports.prototype.type;
+/** @type {{contentType?: typeof module.exports.prototype.type}} */ (module.exports.prototype).contentType =
+    module.exports.prototype.type;

package/src/route.js

@@ -70,7 +70,7 @@ class Route {
      *
      * @param {any} req a Request, or whatever a caller that built this Route by hand is serving
      * @param {any} res the matching response
-     * @param {(err?: any) => void} done called when the route is finished with the request, with
+     * @param {(err?: unknown) => void} done called when the route is finished with the request, with
      *   whatever error it ended on
      */
     dispatch(req, res, done) {
@@ -113,7 +113,7 @@ class Route {
                 return done(err);
             }
 
-            const handle = /** @type {any} */ (layer).handle;
+            const handle = /** @type {{handle: Function}} */ (layer).handle;
             // an error only reaches the four-argument handlers, and everything else only runs
             // while there is no error, which is the same rule ordinary dispatch follows
             if (err) {
@@ -146,7 +146,7 @@ class Route {
  * Refuses a handler that could never be called, worded as express words it.
  *
  * @param {string} method the verb this was registered for, for the message
- * @param {any[]} handlers
+ * @param {unknown[]} handlers
  */
 function checkRouteHandlers(method, handlers) {
     for (const handle of handlers) {