fulmine.js 5.19.3 → 5.19.4

package/src/router-utils.js

@@ -30,6 +30,48 @@ const { METHODS } = require("http");
  * would be a second copy of createRoute that nothing keeps in step.
  * @typedef {any} RouteEntry
  */
+/**
+ * What nativePreset builds for a literal registration: the constants every request to that route
+ * shares, read off the preset instead of the URL.
+ * @typedef {object} NativePreset
+ * @property {string} path
+ * @property {string} method
+ * @property {boolean} endsWithSlash
+ * @property {string} opPath
+ * @property {boolean} isOptions
+ * @property {boolean} isHead
+ * @property {boolean} skipHeaders written at registration, and taken back by a middleware added
+ *   after listen, see _skipPresets
+ * @property {boolean} skipQuery the same, for the query
+ */
+/**
+ * Where a granted header skip lives: the preset itself for a literal registration, a holder of its
+ * own for a parameterised one, see makeHandler in optimizer.js.
+ * @typedef {object} SkipHolder
+ * @property {boolean} skipHeaders
+ * @property {boolean} skipQuery
+ * @property {string|null} [method]
+ * @property {boolean} [isOptions]
+ * @property {boolean} [isHead]
+ */
+/**
+ * An earlier registration a mount is guarded by, see guardsInside.
+ * @typedef {{path: string, use: boolean, method: string, all: boolean}} MountGuard
+ */
+/**
+ * A layer as express shapes it, which is what app.stack and router.stack hand out.
+ * @typedef {object} Layer
+ * @property {Function} handle
+ * @property {string} name
+ * @property {undefined} params
+ * @property {undefined} path
+ * @property {never[]} keys
+ * @property {RouteEntry|undefined} route
+ */
+/**
+ * A websocket registration, kept until listen() hands it to µWS.
+ * @typedef {{path: string, behavior: Record<string, unknown>, owner: Router}} WsRoute
+ */
 
 // whether a registered path could be asked for in another case, which is what decides whether the
 // native router can be trusted to prefer it, see _optimizeRoute
@@ -100,8 +142,9 @@ for (const method of resDecMethods) {
  * them off the handle.
  *
  * @param {RouteEntry} route
- * @param {any} callback a handler, or a mounted router, which is callable and carries _routes
- * @returns {any} the layer object, which is express's shape and not one of ours
+ * @param {Function & {_routes?: RouteEntry[], _isApplication?: boolean}} callback a handler, or a
+ *   mounted router, which is callable and carries _routes
+ * @returns {Layer} the layer object, which is express's shape and not one of ours
  */
 function layerFor(route, callback) {
     const layer = {
@@ -129,7 +172,7 @@ function layerFor(route, callback) {
  * that name.
  *
  * @param {RouteEntry} route
- * @returns {any} the layer object, which is express's shape and not one of ours
+ * @returns {Layer} the layer object, which is express's shape and not one of ours
  */
 function routeLayer(route) {
     const handle = function handle(req, res, next) {
@@ -172,7 +215,9 @@ function nativeDone(matched) {
     if (!matched) {
         queueMicrotask(() => {
             const response = this.res;
-            if (response.headersSent || response.aborted) {
+            // a 404 after the head is left as it is, as express's final handler leaves it; an error
+            // after it goes on to _handleError, which closes the connection as that handler does
+            if (response.aborted || (response.headersSent && !this.req._error)) {
                 return;
             }
             try {
@@ -326,7 +371,7 @@ const EMPTY_INDICES = /** @type {number[]} */ ([]);
  * patterns are pure literals, everything else, "/*" included, stays in alwaysVisit and is still
  * matched per request by _pathMatches.
  *
- * @param {any[]} routes the router's own table
+ * @param {RouteEntry[]} routes the router's own table
  * @param {boolean} caseFlag the frozen case-sensitivity flag
  * @returns {{map: Map<string, number[]>, alwaysVisit: number[]}}
  */
@@ -513,7 +558,7 @@ function logError(router, err) {
 /**
  * The uWS onAborted handler, bound to the response: a closure here captured two locals and cost
  * a context plus a function per request, for a path that only ever runs on a client abort.
- * @this {any} the response, with the request linked as this.req
+ * @this {Response} the response, with the request linked as this.req
  */
 function onNativeAborted() {
     const response = this;
@@ -620,7 +665,7 @@ const CALLBACK_ROUTER = 2;
  *
  * @param {Request} req
  * @param {RouteEntry} route
- * @param {any} err whatever decoding threw
+ * @param {unknown} err whatever decoding threw
  */
 function raiseDecodeFailure(req, route, err) {
     if (req._error) {
@@ -686,7 +731,7 @@ function stepsOver(route, req) {
     // it would answer a GET differently from express. See the same seeding in middlewares.js
     if (!("body" in req)) {
         // cast because `body` is deliberately not a field of Request, see the comment there
-        /** @type {any} */ (req).body = undefined;
+        /** @type {{body?: unknown}} */ (req).body = undefined;
     }
     return true;
 }
@@ -740,10 +785,10 @@ function shadowsLeaf(guard, leafPath, leaf) {
  * @param {Router} router the router the mount belongs to
  * @param {RouteEntry} mount
  * @param {string} pathPrefix what the mounts above this one consumed
- * @param {any[]} chain the layers that always run before the mount, which need no guard
- * @param {any[]} inherited the guards from further out, since a mount two levels down is under
+ * @param {RouteEntry[]} chain the layers that always run before the mount, which need no guard
+ * @param {MountGuard[]} inherited the guards from further out, since a mount two levels down is under
  *   everything written before either of them
- * @returns {any[]|null} null when a path cannot be read segment by segment, which leaves the mount
+ * @returns {MountGuard[]|null} null when a path cannot be read segment by segment, which leaves the mount
  *   to ordinary dispatch rather than guessing about it
  */
 function guardsInside(router, mount, pathPrefix, chain, inherited) {
@@ -809,10 +854,13 @@ function restoreApp(route, req) {
 /**
  * useApp
  * @param {Request} req
- * @param {any} app the application taking the request over
+ * @param {Router & {request?: object, response?: object}} app the application taking the request
+ *   over. Typed as a router because the callers hold one, and only an application carries the two
+ *   prototype layers read below
  */
 function useApp(req, app) {
-    req.app = app;
+    // only an application takes a request over, see rememberApp
+    req.app = /** @type {import("./application.js").Application} */ (app);
     if (req.res) {
         req.res.app = app;
     }
@@ -864,7 +912,7 @@ function callablePrototypeFor(classPrototype) {
     prototype = Object.create(classPrototype);
     for (const name of ["apply", "call", "toString"]) {
         Object.defineProperty(prototype, name, {
-            value: /** @type {any} */ (Function.prototype)[name],
+            value: Function.prototype[name],
             writable: true,
             configurable: true,
             enumerable: false

package/src/router.js

@@ -26,6 +26,7 @@ const {
     pathsCanOverlap,
     regexpGroupKeys,
     NullObject,
+    headersSentError,
     EMPTY_REGEX,
     settingsEpoch
 } = require("./utils.js");
@@ -67,6 +68,12 @@ const {
 } = require("./router-utils.js");
 
 /** @typedef {import("./router-utils.js").RouteEntry} RouteEntry */
+/** @typedef {import("./router-utils.js").SkipHolder} SkipHolder */
+/** @typedef {import("./router-utils.js").NativePreset} NativePreset */
+/** @typedef {import("./router-utils.js").Layer} Layer */
+/** @typedef {import("./router-utils.js").WsRoute} WsRoute */
+/** @typedef {import("uWebSockets.js").HttpRequest} UwsRequest */
+/** @typedef {import("uWebSockets.js").HttpResponse} UwsResponse */
 
 // hands out one number per app.route(), so the routes it creates know they belong together
 let routeGroups = 0;
@@ -76,7 +83,7 @@ let routeKey = 0;
 module.exports = class Router extends EventEmitter {
     /**
      * The router or application this one is mounted on, undefined until it is.
-     * @type {any}
+     * @type {Router|undefined}
      */
     parent;
 
@@ -165,11 +172,11 @@ module.exports = class Router extends EventEmitter {
         this._routes = [];
         // websocket routes, kept apart from the HTTP ones: µWS serves them itself and listen()
         // hands them over whole, mount paths and all
-        /** @type {any[]|null} */
+        /** @type {WsRoute[]|null} */
         this._wsRoutes = null;
         // the native presets allowed to skip the header copy, so a late middleware or an etag
         // arriving after listen can take the permission back; null until one is granted
-        /** @type {Set<any>|null} */
+        /** @type {Set<SkipHolder>|null} */
         this._skipPresets = null;
         /** @type {boolean|undefined} */
         this._hasErrMwCache = undefined;
@@ -226,13 +233,13 @@ module.exports = class Router extends EventEmitter {
      *
      * @param {any} req a Request, or the plain object express's own router tests drive it with
      * @param {any} res a Response, or whatever the caller is serving with
-     * @param {(err?: any) => void} [next]
+     * @param {(err?: unknown) => void} [next]
      * @returns {Promise<void>}
      */
     async handle(req, res, next) {
         // a request from node's own server, which is what http.createServer(app) delivers
         if (isNodeRequest(req)) {
-            return serveNodeRequest(this, req, /** @type {any} */ (res), next);
+            return serveNodeRequest(this, req, res, next);
         }
         // an app taking over a request becomes that request's app, as it does when mounted, so
         // req.app.get("view engine") inside a sub-app reads the sub-app's settings. A plain router
@@ -562,7 +569,7 @@ module.exports = class Router extends EventEmitter {
      * splicing one out moves nothing. The layer objects are kept, so identities compare across two
      * reads the way they do in Express.
      *
-     * @returns {any[]}
+     * @returns {Layer[]}
      */
     get stack() {
         const layers = [];
@@ -585,9 +592,11 @@ module.exports = class Router extends EventEmitter {
      * anything not comparable as a string is compiled to a regular expression and marked complex.
      *
      * @param {string} method HTTP method, or USE for a mount
-     * @param {any} path one path or several
-     * @param {any} [parent] what to return, so chaining lands on the app rather than the router
-     * @param {...any} callbacks
+     * @param {string|RegExp|(string|RegExp)[]} path one path or several
+     * @param {any} [parent] what to return, so chaining lands on the app rather than the router.
+     *   Loose because it is also the builder app.route() hands back
+     * @param {...any} callbacks handlers, or arrays of them at any depth, flattened below. Loose
+     *   because a parameter keeps its declared type through that reassignment
      * @returns {any} parent
      */
     createRoute(method, path, parent = this, ...callbacks) {
@@ -706,7 +715,7 @@ module.exports = class Router extends EventEmitter {
                 stack,
                 // the route as a request sees it, which is the route itself unless the path was
                 // normalised. Written into the literal so every route keeps one shape
-                exposed: /** @type {any} */ (undefined),
+                exposed: /** @type {RouteEntry|undefined} */ (undefined),
                 routeKey: routeKey++,
                 // which app.route() this came from, when it came from one, so the routes it built
                 // count as one route where an error is concerned. undefined for every other route
@@ -768,8 +777,8 @@ module.exports = class Router extends EventEmitter {
      * as a method because a mounted router is asked for its own through it.
      *
      * @param {RouteEntry} route
-     * @param {any[]} routes every route of this router, in registration order
-     * @returns {any[]|false} the chain, ending in the route itself
+     * @param {RouteEntry[]} routes every route of this router, in registration order
+     * @returns {RouteEntry[]|false} the chain, ending in the route itself
      */
     _optimizeRoute(route, routes) {
         return optimizeRoute(this, route, routes);
@@ -788,12 +797,12 @@ module.exports = class Router extends EventEmitter {
      * request does whichever path serves it. The response rides back as request.res: returning
      * a `{ request, response }` pair was one throwaway object per request.
      *
-     * @param {any} res uWS response, which the shipped typings do not describe
-     * @param {any} req uWS request, readable only during this call
-     * @param {any} [preset] a literal registration's constants, see nativePreset
-     * @param {any} [skipHolder] the object a granted header skip lives on: the preset itself
+     * @param {UwsResponse} res uWS response
+     * @param {UwsRequest} req uWS request, readable only during this call
+     * @param {NativePreset} [preset] a literal registration's constants, see nativePreset
+     * @param {SkipHolder} [skipHolder] the object a granted header skip lives on: the preset itself
      *   for a literal registration, a holder of its own for a parameterised one
-     * @returns {any} the request, with the response reachable as request.res
+     * @returns {Request} the request, with the response reachable as request.res
      */
     handleRequest(res, req, preset, skipHolder) {
         const request = new this._request(req, res, this, preset, skipHolder);
@@ -830,7 +839,7 @@ module.exports = class Router extends EventEmitter {
      * for a response that outlives its handler callback: the native handler arms it in its
      * finally when the answer is still pending, which on a synchronous route it never is.
      *
-     * @param {any} res uWS response, which the shipped typings do not describe
+     * @param {UwsResponse} res uWS response
      * @param {Response} response
      */
     _armAbort(res, response) {
@@ -846,7 +855,7 @@ module.exports = class Router extends EventEmitter {
      * are compared segment by segment.
      *
      * @param {RouteEntry} route
-     * @param {any[]} routes every route of the router this one belongs to
+     * @param {RouteEntry[]} routes every route of the router this one belongs to
      * @returns {boolean}
      */
     _isFollowedByAnOverlap(route, routes) {
@@ -881,7 +890,7 @@ module.exports = class Router extends EventEmitter {
      * the optimizer tests replace it to see which routes went native.
      *
      * @param {RouteEntry} route
-     * @param {any[]} optimizedPath the chain the route was optimized with
+     * @param {RouteEntry[]} optimizedPath the chain the route was optimized with
      */
     _registerUwsRoute(route, optimizedPath) {
         registerUwsRoute(this, route, optimizedPath);
@@ -913,6 +922,14 @@ module.exports = class Router extends EventEmitter {
             }
         }
         logError(this, err);
+        // no error page can follow a head that is out, so express's final handler closes the
+        // connection instead, and leaves a response that was already ended as it is
+        if (response.headersSent) {
+            if (!response.finished) {
+                response.destroy();
+            }
+            return;
+        }
         if (response.statusCode === 200) {
             // the status the error carries, as express's own final handler reads it: a body that
             // was too large or a request cut short is the client's 4xx, not a 500 from here
@@ -926,7 +943,7 @@ module.exports = class Router extends EventEmitter {
      * The HTML for an error, which in production says only what the status means rather than what
      * went wrong, so a stack trace does not reach the client.
      *
-     * @param {any} err whatever was thrown, which need not be an Error
+     * @param {unknown} err whatever was thrown, which need not be an Error
      * @param {number} statusCode
      * @param {boolean} [checkEnv] whether production should redact it
      * @returns {string}
@@ -1223,7 +1240,7 @@ module.exports = class Router extends EventEmitter {
 
     /**
      * Resolves with the route that answered, or false when nothing matched.
-     * @returns {Promise<any>}
+     * @returns {Promise<RouteEntry|false>}
      */
     _routeRequest(req, res, startIndex = 0, routes = this._routes, skipCheck = false, skipUntil) {
         return new Promise((resolve, reject) => {
@@ -1289,7 +1306,8 @@ module.exports = class Router extends EventEmitter {
                 settingsEpoch.n++;
             }
         }
-        this.createRoute("USE", path, this, ...callbacks);
+        // a handler in the path position was moved to the callbacks above
+        this.createRoute("USE", /** @type {string|RegExp|(string|RegExp)[]} */ (path), this, ...callbacks);
         return this;
     }
 
@@ -1314,7 +1332,7 @@ module.exports = class Router extends EventEmitter {
      * });
      *
      * @param {string} path a literal path, or one whose parameters are whole segments
-     * @param {object} behavior uWS's WebSocketBehavior, plus the optional `upgrade` above
+     * @param {Record<string, unknown>} behavior uWS's WebSocketBehavior, plus the optional `upgrade` above
      * @returns {this}
      */
     ws(path, behavior) {
@@ -1350,7 +1368,7 @@ module.exports = class Router extends EventEmitter {
             this._pendingGroupMethods = groupMethods;
             this._pendingGroupStack = groupStack;
             try {
-                return this.createRoute(method, path, /** @type {any} */ (fns), ...callbacks);
+                return this.createRoute(method, path, fns, ...callbacks);
             } finally {
                 this._pendingGroup = undefined;
                 this._pendingGroupMethods = undefined;
@@ -1370,7 +1388,7 @@ module.exports = class Router extends EventEmitter {
      *
      * @param {Request} request
      * @param {Response} response
-     * @param {any} err whatever was thrown, which need not be an Error
+     * @param {unknown} err whatever was thrown, which need not be an Error
      * @param {boolean} [checkEnv] whether production should redact it
      */
     _sendErrorPage(request, response, err, checkEnv = false) {
@@ -1395,8 +1413,8 @@ module.exports = class Router extends EventEmitter {
      * @param {Set<string>} methods the verbs the answering router knows, which are its own
      */
     _sendOptionsReply(request, response, methods) {
-        if (response._headWritten) {
-            throw new Error("Cannot set headers after they are sent to the client");
+        if (response.headersSent) {
+            throw headersSentError("set");
         }
         // Express 5 sorts the methods and joins them with ", ", so the header reads the same
         // regardless of the order the routes happened to be registered in

package/src/server-shape.js

@@ -34,6 +34,8 @@ limitations under the License.
 const http = require("http");
 const net = require("net");
 
+/** @typedef {import("./application.js").Application} Application */
+
 // what marks an application, read by the instanceof hook below. A symbol, so no plain field name
 // can be mistaken for it
 const kIsApplication = Symbol.for("fulmine.application");
@@ -45,20 +47,20 @@ const kIsApplication = Symbol.for("fulmine.application");
  * @param {Function} klass http.Server or net.Server
  */
 function acceptApplications(klass) {
-    const previous = /** @type {any} */ (klass)[Symbol.hasInstance];
+    const previous = klass[Symbol.hasInstance];
     // already taught, which happens when two copies of this package share one process
-    if (/** @type {any} */ (klass)[kIsApplication] === true) {
+    if (klass[kIsApplication] === true) {
         return;
     }
     Object.defineProperty(klass, Symbol.hasInstance, {
-        /** @param {any} value @returns {boolean} */
+        /** @param {unknown} value @returns {boolean} */
         value: function (value) {
             if (previous.call(this, value)) {
                 return true;
             }
             // 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 && /** @type {any} */ (value)[kIsApplication] === true;
+            return value != null && value[kIsApplication] === true;
         },
         configurable: true,
         writable: true
@@ -73,7 +75,8 @@ acceptApplications(net.Server);
  * The net.Server members Express's API does not give, on the application prototype. Each one
  * answers for uWS, not for a node socket.
  *
- * @param {any} prototype Application.prototype
+ * @param {any} prototype Application.prototype, loose because the members are written here and not
+ *   declared on the class
  */
 function addServerMembers(prototype) {
     Object.defineProperty(prototype, kIsApplication, { value: true, configurable: true });
@@ -97,13 +100,14 @@ function addServerMembers(prototype) {
      * A handle this does not own: uWS's loop keeps the process alive and a caller cannot unref it.
      * Both are no-ops returning the server, so a chain written against node's API keeps working.
      *
-     * @returns {any}
+     * @this {Application}
+     * @returns {Application}
      */
     prototype.ref = function ref() {
         return this;
     };
 
-    /** @returns {any} */
+    /** @this {Application} @returns {Application} */
     prototype.unref = function unref() {
         return this;
     };
@@ -112,10 +116,10 @@ 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 {any}
+     * @this {Application & {timeout?: number}}
      * @param {number} [msecs]
      * @param {() => void} [callback]
-     * @returns {any}
+     * @returns {Application}
      */
     prototype.setTimeout = function setTimeout(msecs, callback) {
         this.timeout = msecs;
@@ -127,7 +131,7 @@ function addServerMembers(prototype) {
 
     // The numbers node's http.Server carries. Inert here, but declared rather than left undefined:
     // a library reads `server.keepAliveTimeout` to work out what it is talking to.
-    for (const [name, value] of /** @type {[string, any][]} */ ([
+    for (const [name, value] of /** @type {[string, number|null][]} */ ([
         ["timeout", 0],
         ["keepAliveTimeout", 5000],
         ["headersTimeout", 60000],

package/src/server-timing.js

@@ -34,6 +34,9 @@ limitations under the License.
 "use strict";
 
 const { work, names } = require("./work.js");
+const { applyWriteHead } = require("./utils.js");
+
+/** @typedef {import("./response.js")} Response */
 
 /**
  * A duration in milliseconds, as Server-Timing writes them: two decimals.
@@ -63,7 +66,8 @@ function describe(text) {
  *   true. Nothing is written for a request that built none of it, which is the usual one.
  * @param {boolean} [options.total] whether to report the time up to the head. Default true.
  * @param {string} [options.name] what the total is called. Default "total".
- * @returns {(req: any, res: any, next: (err?: any) => void) => void}
+ * @returns {(req: any, res: any, next: (err?: unknown) => void) => void} the middleware. The pair is
+ *   loose because the two methods below are added to the response here
  */
 function serverTiming(options) {
     const opts = options || {};
@@ -84,7 +88,7 @@ function serverTiming(options) {
          * @param {string} name a token: letters, digits, dash and underscore
          * @param {number} [duration] milliseconds
          * @param {string} [description]
-         * @returns {any} the response, so calls chain
+         * @returns {Response} the response, so calls chain
          */
         res.timing = function timing(name, duration, description) {
             let mark = String(name).replace(/[^\w-]/g, "");
@@ -118,11 +122,11 @@ function serverTiming(options) {
             }
             if (value && typeof value.then === "function") {
                 return value.then(
-                    /** @param {any} resolved */ (resolved) => {
+                    /** @param {unknown} resolved */ (resolved) => {
                         done();
                         return resolved;
                     },
-                    /** @param {any} err */ (err) => {
+                    /** @param {unknown} err */ (err) => {
                         done();
                         throw err;
                     }
@@ -172,6 +176,14 @@ 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
+        res.writeHead = function writeHead(statusCode, statusMessage, headers) {
+            const reason = applyWriteHead(this, statusMessage, headers);
+            stamp();
+            return _writeHead.call(this, statusCode, reason);
+        };
         res.write = function write(chunk, encoding, callback) {
             stamp();
             return _write.call(this, chunk, encoding, callback);

package/src/socket.js

@@ -29,8 +29,8 @@ class Socket extends EventEmitter {
      * The Socket's error listener, shared across sockets: an error closes the stand-in, which is
      * the close connection trackers wait for. EventEmitter calls it with this = the emitter.
      *
-     * @this {any}
-     * @param {any} err whatever the response reported, which need not be an Error
+     * @this {Socket}
+     * @param {unknown} err whatever the response reported, which need not be an Error
      */
     static _onError(err) {
         this.emit("close");
@@ -96,7 +96,7 @@ class Socket extends EventEmitter {
     /**
      * Finishes the response through the socket, which is how the middleware that only knows
      * about sockets ends one.
-     * @param {any} [body] whatever node's socket.end() would take
+     * @param {string|Buffer|Uint8Array} [body] whatever node's socket.end() would take
      */
     end(body) {
         this.response.end(body);

package/src/testing.js

@@ -31,6 +31,7 @@ const { work, names: workNames } = require("./work.js");
 /** @typedef {import("./response.js")} Response */
 /** @typedef {import("./router.js")} Router */
 /** @typedef {import("./application.js").Application} Application */
+/** @typedef {import("./router-utils.js").RouteEntry} RouteEntry */
 
 /**
  * Every route of an application and of the routers mounted under it, each with the path it answers
@@ -38,8 +39,8 @@ const { work, names: workNames } = require("./work.js");
  *
  * @param {Router} router
  * @param {string} prefix
- * @param {any[]} [into]
- * @returns {{route: any, full: string}[]}
+ * @param {{route: RouteEntry, full: string}[]} [into]
+ * @returns {{route: RouteEntry, full: string}[]}
  */
 function collectRoutes(router, prefix, into = []) {
     for (const route of router._routes ?? []) {
@@ -263,7 +264,7 @@ function expectLazy(req, res, options) {
     const done = work(req, res);
     const unwanted = { ...done };
     for (const field of allowed) {
-        /** @type {any} */ (unwanted)[field] = false;
+        unwanted[field] = false;
     }
     const listed = workNames(unwanted);
     if (listed.length === 0) {

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}}