fulmine.js 5.19.3 → 5.19.5

package/src/usage.js

@@ -18,6 +18,8 @@ limitations under the License.
 
 const acorn = require("acorn");
 
+/** @typedef {import("./router-utils.js").RouteEntry} RouteEntry */
+
 // Marks a middleware the analysis may trust on a GET request without reading its source: the
 // body parsers set it, whose prologue only reads body-framing headers and leaves a bodyless
 // GET alone (and a GET that declares a body falls back to the full header copy).
@@ -107,7 +109,7 @@ function analyze(fn) {
         // class methods and native functions do not parse alone, and unread code is unknown code
         return UNKNOWN;
     }
-    let root = /** @type {any} */ (tree.body[0]);
+    let root = /** @type {import("acorn").AnyNode} */ (tree.body[0]);
     if (!root) {
         return UNKNOWN;
     }
@@ -122,7 +124,8 @@ function analyze(fn) {
         return UNKNOWN;
     }
 
-    const params = /** @type {any[]} */ (root.params);
+    // checked by the loop below, which answers UNKNOWN for anything else
+    const params = /** @type {import("acorn").Identifier[]} */ (root.params);
     // rest or destructured parameters alias the objects somewhere the walk cannot follow
     for (const p of params) {
         if (p.type !== "Identifier") {
@@ -231,9 +234,11 @@ function analyze(fn) {
  * Walks every node, handing each its parent. Arrays and nested objects are entered, nothing
  * is interpreted: the judging happens in the visitor.
  *
- * @param {any} node an acorn AST node. acorn ships no useful node types, and every shape here is checked by hand
+ * @param {any} node an acorn node, or an array or a scalar under one: walked by key, so no shape
+ *   is assumed
  * @param {any} parent its parent node, or null at the root
- * @param {(node: any, parent: any) => void} visit
+ * @param {(node: any, parent: any) => void} visit handed every node, loose because the visitor
+ *   reads edges of its own off each
  */
 function walk(node, parent, visit) {
     if (!node || typeof node.type !== "string") {
@@ -265,7 +270,7 @@ function walk(node, parent, visit) {
  * it passes only when no later route could catch the fall-through. The framework's own 404 answers
  * from the path alone.
  *
- * @param {any[]} chain the routes the native handler runs, in order, this route last
+ * @param {RouteEntry[]} chain the routes the native handler runs, in order, this route last
  * @param {boolean} allowTerminalNext whether a fall-through past the chain lands only in the
  *   framework's own final answer
  * @returns {{skipHeaders: boolean, skipQuery: boolean}}

package/src/utils.js

@@ -30,6 +30,19 @@ const { Stats } = require("fs");
 
 /** @typedef {import("./request.js")} Request */
 /** @typedef {import("./response.js")} Response */
+/**
+ * An error with the http-errors fields on it, which are what `res.status(err.status || 500)`, the
+ * error page and the body parsers read. None is required: a plain throw carries none of them.
+ * @typedef {Error & {
+ *   status?: number,
+ *   statusCode?: number,
+ *   expose?: boolean,
+ *   code?: string,
+ *   type?: string,
+ *   types?: string[],
+ *   headers?: Record<string, any>
+ * }} HttpError
+ */
 
 const EMPTY_REGEX = new RegExp(``);
 
@@ -765,8 +778,9 @@ const MEMO_LIMIT = 512;
  * The wrapped function must never answer undefined, since that is what the cache reads as a miss.
  * The mime lookups here answer false for something they do not know, which caches correctly.
  *
- * @param {(key: string) => any} fn
- * @returns {(key: string) => any}
+ * @template T
+ * @param {(key: string) => T} fn
+ * @returns {(key: string) => T}
  */
 function memoizeByString(fn) {
     const cache = new Map();
@@ -794,6 +808,16 @@ const lookupType = memoizeByString((type) => mime.lookup(type) || "application/o
  */
 const contentTypeFor = memoizeByString((type) => mime.contentType(type) || "application/octet-stream");
 
+/**
+ * The content-type res.set stores for a value, which is what express stores: an extension resolved
+ * to its media type with the charset the database gives it, and false when it resolves to nothing.
+ * A false there is falsy for every default below it, so send() and json() write their own.
+ *
+ * @param {string} value
+ * @returns {string|false}
+ */
+const contentTypeSet = memoizeByString((value) => mime.contentType(value));
+
 /**
  * A media type from either spelling: "html" is looked up in the mime database, while anything
  * containing a slash is already one and is parsed for its parameters.
@@ -811,7 +835,7 @@ function normalizeType(type) {
  * unicode escapes, so a string in the body cannot close a script tag in an HTML page that embeds
  * the response.
  *
- * @param {any} value whatever the handler passed to res.json
+ * @param {unknown} value whatever the handler passed to res.json
  * @param {any} [replacer] the "json replacer" setting
  * @param {string|number} [spaces] the "json spaces" setting
  * @param {boolean} [escape] the "json escape" setting
@@ -1042,13 +1066,17 @@ function cachedStat(file, ttl) {
 /**
  * A duration setting as milliseconds: false is off, a string is read by ms, a number is itself.
  *
- * @param {any} value the setting as the application wrote it
+ * @param {string|number|boolean|undefined} value the setting as the application wrote it
  * @param {string} name for the error, which names the setting the application wrote
  * @returns {number}
  */
 function durationSetting(value, name) {
     const parsed =
-        value === false || value === undefined ? 0 : typeof value === "string" ? ms(/** @type {any} */ (value)) : value;
+        value === false || value === undefined
+            ? 0
+            : typeof value === "string"
+              ? ms(/** @type {import("ms").StringValue} */ (value))
+              : value;
     if (typeof parsed !== "number" || !(parsed >= 0)) {
         throw new TypeError(`${name} must be a duration`);
     }
@@ -1129,8 +1157,9 @@ function deprecated(oldMethod, newMethod, full = false) {
  * request, each time picking up after the route it just ran, and Array.findIndex has no way to
  * start anywhere but the beginning.
  *
- * @param {any[]} arr
- * @param {(item: any, index: number, arr: any[]) => boolean} fn
+ * @template T
+ * @param {T[]} arr
+ * @param {(item: T, index: number, arr: T[]) => boolean} fn
  * @param {number} [index] where to start
  * @returns {number} the index, or -1
  */
@@ -1165,7 +1194,7 @@ function decode(path) {
  *
  * @param {string} value
  * @returns {string}
- * @throws {any} carrying status 400 when the value cannot be decoded
+ * @throws {HttpError} carrying status 400 when the value cannot be decoded
  */
 function decodeParam(value) {
     // the common case, and worth the check: a parameter is usually a number or a word, and
@@ -1178,7 +1207,8 @@ function decodeParam(value) {
     } catch {
         // a URIError, not an Error: express throws what decodeURIComponent threw, so an error
         // handler written as `err instanceof URIError` has to keep working here
-        const err = /** @type {any} */ (new URIError(`Failed to decode param '${value}'`));
+        /** @type {HttpError} */
+        const err = new URIError(`Failed to decode param '${value}'`);
         err.status = 400;
         err.statusCode = 400;
         err.expose = true;
@@ -1335,7 +1365,7 @@ function statTag(stat, weak) {
  * ETag comes from its size and mtime while a body's comes from its contents.
  *
  * @param {{weak: boolean}} options
- * @returns {(body: any, encoding?: BufferEncoding) => string}
+ * @returns {(body: string|Buffer|import("fs").Stats, encoding?: BufferEncoding) => string}
  */
 function createETagGenerator(options) {
     return function generateETag(body, encoding) {
@@ -1362,14 +1392,15 @@ function createETagGenerator(options) {
  * @returns {boolean}
  */
 function isRangeFresh(req, res) {
-    const ifRange = req.headers["if-range"];
+    // folded to one string, as every header but set-cookie is
+    const ifRange = /** @type {string|undefined} */ (req.headers["if-range"]);
     if (!ifRange) {
         return true;
     }
 
     // if-range as etag
     if (ifRange.indexOf('"') !== -1) {
-        const etag = res.get("etag");
+        const etag = /** @type {string|undefined} */ (res.get("etag"));
         return Boolean(etag && ifRange.indexOf(etag) !== -1);
     }
 
@@ -1496,16 +1527,73 @@ function headerError(message, code) {
     void err.stack;
     // back to the prototype's "TypeError", which is what node leaves behind. Cast because Error
     // declares name as always present, and this deletes the own property to uncover it again
-    delete (/** @type {any} */ (err).name);
+    delete (/** @type {{name?: string}} */ (err).name);
     err.code = code;
     return err;
 }
 
+/**
+ * node's ERR_HTTP_HEADERS_SENT, for a head that can no longer change: "set" from setHeader,
+ * "remove" from removeHeader, "write" from writeHead, which is how node words each one.
+ *
+ * @param {string} verb
+ * @returns {NodeJS.ErrnoException}
+ */
+function headersSentError(verb) {
+    /** @type {NodeJS.ErrnoException} */
+    const err = new Error(`Cannot ${verb} headers after they are sent to the client`);
+    // the first line of the stack reads as node's, see headerError
+    err.name = "Error [ERR_HTTP_HEADERS_SENT]";
+    void err.stack;
+    delete (/** @type {{name?: string}} */ (err).name);
+    err.code = "ERR_HTTP_HEADERS_SENT";
+    return err;
+}
+
+/**
+ * Applies the headers a writeHead call carries, in either of node's shapes, (status, headers) or
+ * (status, reason, headers), and answers the reason phrase when there was one. Shared with the
+ * middleware that hooks writeHead: what it decides at the head has to see these first, the way
+ * on-headers applies them before its listeners run.
+ *
+ * @param {{setHeader(name: string, value: import("http").OutgoingHttpHeader|undefined): unknown}} res
+ * @param {string|import("http").OutgoingHttpHeaders|import("http").OutgoingHttpHeader[]} [statusMessage]
+ * @param {import("http").OutgoingHttpHeaders|import("http").OutgoingHttpHeader[]} [headers]
+ * @returns {string|undefined} the reason phrase
+ */
+function applyWriteHead(res, statusMessage, headers) {
+    let reason;
+    if (typeof statusMessage === "string") {
+        reason = statusMessage;
+    } else if (!headers) {
+        // the two-argument shape, where what looked like a reason phrase is the headers
+        headers = 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) {
+            res.setHeader(/** @type {string} */ (headers[i]), headers[i + 1]);
+        }
+    } else if (headers) {
+        for (const header in headers) {
+            res.setHeader(header, headers[header]);
+        }
+    }
+    return reason;
+}
+
 /**
  * Refuses a header name that is not an HTTP token, the way node's setHeader does and with its
  * error, so an application catching ERR_INVALID_HTTP_TOKEN behind Express catches it here.
  *
- * @param {any} name whatever a caller passed as a header name, which is what is being checked
+ * @param {unknown} name whatever a caller passed as a header name, which is what is being checked
  * @returns {void}
  * @throws {TypeError} if the name is not a token, which includes not being a string
  */
@@ -1579,21 +1667,39 @@ const STAT_ERROR_STATUS = { ENAMETOOLONG: 404, ENOTDIR: 404, ENOENT: 404 };
  * of that handler as 500. The message is the status's own name, as http-errors writes it.
  *
  * @param {number} status
- * @returns {any}
+ * @param {string} [message] the status text unless given, as http-errors has it
+ * @returns {HttpError}
  */
-function httpError(status) {
-    const message = statuses.message[status] ?? "Error";
-    const err = /** @type {any} */ (new Error(message));
+function httpError(status, message = statuses.message[status] ?? "Error") {
+    /** @type {HttpError} */
+    const err = new Error(message);
     // http-errors names these BadRequestError, ForbiddenError and so on, and the name is what the
     // error page shows: an application looking at a 400 sees the same word Express shows it. Set
     // before anything reads the stack, which V8 formats on first read
-    err.name = `${message.replace(/\W/g, "")}Error`;
+    err.name = httpErrorName(status);
     err.expose = status < 500;
     err.statusCode = status;
     err.status = status;
     return err;
 }
 
+/**
+ * The name http-errors gives an error for a status, NotFoundError for 404: each word of the status
+ * text capitalised and run together, plus Error unless it already ends in it, which is how
+ * "Internal Server Error" stays InternalServerError.
+ *
+ * @param {number} status
+ * @returns {string}
+ */
+function httpErrorName(status) {
+    const name = (statuses.message[status] ?? "Error")
+        .split(" ")
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join("")
+        .replace(/[^ _0-9a-z]/gi, "");
+    return name.endsWith("Error") ? name : name + "Error";
+}
+
 /**
  * Marks an fs error the way send does before it is handed on, so an error handler reading
  * err.status or err.statusCode finds what it would find behind Express. The three properties are
@@ -1602,8 +1708,8 @@ function httpError(status) {
  *
  * The error itself is returned rather than a new one, so its errno, code, syscall and path survive.
  *
- * @param {any} err the fs error, which carries its errno and path
- * @returns {any} the same error
+ * @param {HttpError} err the fs error, which carries its errno and path
+ * @returns {HttpError} the same error
  */
 function asStatError(err) {
     err.expose = false;
@@ -1616,8 +1722,7 @@ function asStatError(err) {
 // A constructor whose instances have no prototype, so a key from a request body or a query string
 // cannot reach Object.prototype. Typed as returning a plain record: without that, assigning one
 // reads as assigning `any`, which resets narrowing instead of removing undefined from it.
-/** @type {new () => Record<string, any>} */
-const NullObject = /** @type {any} */ (function () {});
+const NullObject = /** @type {new () => Record<string, any>} */ (/** @type {unknown} */ (function () {}));
 NullObject.prototype = Object.create(null);
 
 module.exports = {
@@ -1646,6 +1751,7 @@ module.exports = {
     entityTag,
     statTag,
     contentTypeFor,
+    contentTypeSet,
     negotiateEncoding,
     ENCODING_BR,
     ENCODING_GZIP,
@@ -1669,6 +1775,9 @@ module.exports = {
     withUtf8Charset,
     asStatError,
     httpError,
+    httpErrorName,
+    headersSentError,
+    applyWriteHead,
     EMPTY_REGEX,
     settingsEpoch
 };

package/src/verify.js

@@ -109,7 +109,8 @@ function checkNode(running = process.versions.node, required = require("../packa
  * @returns {string|undefined}
  */
 function currentGlibc() {
-    return /** @type {any} */ (process.report.getReport()).header.glibcVersionRuntime;
+    return /** @type {{header: {glibcVersionRuntime?: string}}} */ (process.report.getReport()).header
+        .glibcVersionRuntime;
 }
 
 /**
@@ -206,7 +207,7 @@ function checkBinary(platform = process.platform, arch = process.arch, abi = pro
  */
 function abiToNode(abi) {
     const known = { 108: "18", 115: "20", 127: "22", 131: "23", 137: "24", 147: "26" };
-    return /** @type {any} */ (known)[abi] ?? `ABI ${abi}`;
+    return known[abi] ?? `ABI ${abi}`;
 }
 
 /**
@@ -269,7 +270,7 @@ function checkDependencies(dir) {
     const installed = { ...pkg.dependencies, ...pkg.devDependencies };
     for (const name of Object.keys(NEEDS_A_LOOK)) {
         if (installed[name]) {
-            results.push(result("note", `${name} needs a different API here`, /** @type {any} */ (NEEDS_A_LOOK)[name]));
+            results.push(result("note", `${name} needs a different API here`, NEEDS_A_LOOK[name]));
         }
     }
     return results;

package/src/view.js

@@ -113,7 +113,7 @@ module.exports = class View {
         this.engine(
             this.path,
             options,
-            /** @this {any} */ function onRender() {
+            /** @this {unknown} */ function onRender() {
                 if (!sync) {
                     return callback.apply(this, arguments);
                 }

package/src/walk.js

@@ -31,6 +31,7 @@ const {
 /** @typedef {import("./request.js")} Request */
 /** @typedef {import("./response.js")} Response */
 /** @typedef {import("./router.js")} Router */
+/** @typedef {import("./router-utils.js").RouteEntry} RouteEntry */
 
 /**
  * One walk of one router's routes, for one request.
@@ -46,12 +47,12 @@ class Walk {
      * @param {Router} router
      * @param {Request} req
      * @param {Response} res
-     * @param {any[]} routes the route table being walked, see createRoute in router.js
+     * @param {RouteEntry[]} routes the route table being walked, see createRoute in router.js
      * @param {boolean} skipCheck take the route at the index without matching it, which is how an
      *   already-decided chain is walked
-     * @param {any} skipUntil route to resume after when this chain runs out, or undefined
-     * @param {(value: any) => void} resolve
-     * @param {(err: any) => void} reject
+     * @param {RouteEntry|undefined} skipUntil route to resume after when this chain runs out, or undefined
+     * @param {(value: RouteEntry|false) => void} resolve
+     * @param {(err: unknown) => void} reject
      */
     constructor(router, req, res, routes, skipCheck, skipUntil, resolve, reject) {
         this.router = router;
@@ -85,7 +86,7 @@ class Walk {
      * Leaves the rest of this route, with the error if there is one, and carries on with the route
      * after it.
      *
-     * @param {any} [err] whatever was thrown, which need not be an Error
+     * @param {unknown} [err] whatever was thrown, which need not be an Error
      */
     stepOutOfRoute(err) {
         if (err) {
@@ -289,7 +290,7 @@ class Walk {
      * Enters the route the walk is on: a mount adjusts req.url, req.path and the mount stack on the
      * way in, and then the route's callbacks run one after another through next().
      *
-     * @param {any} continueRoute what _preprocessRequest decided: true to run, "route" to skip
+     * @param {true|"route"} continueRoute what _preprocessRequest decided: true to run, "route" to skip
      */
     runRoute(continueRoute) {
         const req = this.req;
@@ -439,7 +440,7 @@ class Walk {
      * One hop, which is what next() does: with nothing, run the route's next callback; with "route",
      * leave the route; with anything else, remember it as the error and carry on.
      *
-     * @param {any} thingamabob what next() was called with: nothing, "route", or an error
+     * @param {unknown} thingamabob what next() was called with: nothing, "route", or an error
      */
     step(thingamabob) {
         const req = this.req;

package/src/websocket.js

@@ -20,6 +20,12 @@ const { canBeOptimizedWithParams, decodeParam, NullObject } = require("./utils.j
 
 /** @typedef {import("./router.js")} Router */
 /** @typedef {import("./application.js").Application} Application */
+/** @typedef {import("./request.js")} Request */
+/** @typedef {import("./response.js")} Response */
+/** @typedef {import("./router-utils.js").WsRoute} WsRoute */
+/** @typedef {import("uWebSockets.js").HttpRequest} UwsRequest */
+/** @typedef {import("uWebSockets.js").HttpResponse} UwsResponse */
+/** @typedef {import("uWebSockets.js").us_socket_context_t} UwsContext */
 
 // the parameter names in a path, in the order µWS numbers them
 const PARAM = /:(\w+)/g;
@@ -55,8 +61,8 @@ function joinPaths(prefix, path) {
  * @param {Router} router
  * @param {string|null} prefix the mount path accumulated so far, or null once a mount was a
  *   shape µWS cannot match, which makes everything below it unreachable
- * @param {any[]} out
- * @param {Set<any>} seen routers already walked, since a router may be mounted twice
+ * @param {WsRoute[]} out
+ * @param {Set<Router>} seen routers already walked, since a router may be mounted twice
  */
 function collectRoutes(router, prefix, out, seen) {
     if (seen.has(router)) {
@@ -102,14 +108,17 @@ function collectRoutes(router, prefix, out, seen) {
  * The uWS upgrade handler for one route: builds this project's request and response, offers them
  * to the application's own `upgrade` hook, and completes the handshake unless that hook answered.
  *
- * @param {Application} app the application whose request and response classes serve this route
+ * @param {Router} app the router whose request and response classes serve this route
  * @param {string} path the composed path, whose parameters are read back by index
- * @param {any} behavior what the caller registered
- * @returns {(res: any, req: any, context: any) => void}
+ * @param {Record<string, unknown>} behavior what the caller registered
+ * @returns {(res: UwsResponse, req: UwsRequest, context: UwsContext) => void}
  */
 function makeUpgradeHandler(app, path, behavior) {
     const paramNames = [...path.matchAll(PARAM)].map((match) => match[1]);
-    const userUpgrade = behavior.upgrade;
+    // a function, checked by checkBehavior where it was registered
+    const userUpgrade = /** @type {((req: Request, res: Response) => void|Promise<void>)|undefined} */ (
+        behavior.upgrade
+    );
 
     return (res, req, context) => {
         // read off the uWS request before anything can await: it is neutered on return, and the
@@ -122,7 +131,7 @@ function makeUpgradeHandler(app, path, behavior) {
         if (paramNames.length) {
             const params = new NullObject();
             for (let i = 0; i < paramNames.length; i++) {
-                params[paramNames[i]] = decodeParam(req.getParameter(i));
+                params[paramNames[i]] = decodeParam(/** @type {string} */ (req.getParameter(i)));
             }
             request.params = params;
         }
@@ -216,7 +225,7 @@ function registerWebSocketRoutes(app) {
  * used: a handler under a misspelled name would otherwise never run and never say why.
  *
  * @param {string} path
- * @param {any} behavior uWS's WebSocketBehavior, whose shipped typings do not describe it
+ * @param {unknown} behavior whatever was passed as one, which is what is being checked
  */
 function checkBehavior(path, behavior) {
     if (typeof path !== "string") {

package/src/work.js

@@ -54,7 +54,7 @@ function work(req, res) {
     const native = req.route?._native;
     // cast for the three the classes do not declare: `body` is deliberately not a field of
     // Request, and the two stream states are node's own, written when a lazy stream is built
-    const loose = /** @type {any} */ (req);
+    const loose = /** @type {{body?: unknown, _readableState?: unknown}} */ (req);
     return {
         native: Boolean(native),
         declarative: Boolean(native?.declarative),
@@ -62,7 +62,7 @@ function work(req, res) {
         query: req._queryParsed,
         body: loose.body !== undefined,
         requestStream: loose._readableState !== undefined,
-        responseStream: /** @type {any} */ (res)._writableState !== undefined,
+        responseStream: /** @type {{_writableState?: unknown}} */ (res)._writableState !== undefined,
         socket: req._socketBuilt || res._socketBuilt
     };
 }
@@ -86,7 +86,7 @@ const NAMES = [
 function names(done) {
     const listed = [];
     for (const [key, name] of NAMES) {
-        if (/** @type {any} */ (done)[key]) {
+        if (done[key]) {
             listed.push(name);
         }
     }