fulmine.js 5.19.8 → 5.20.0

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "fulmine.js",
-    "version": "5.19.8",
-    "description": "Drop-in Express 5 replacement on uWebSockets.js. Your existing middleware keeps working.",
+    "version": "5.20.0",
+    "description": "Drop-in Express 5 replacement on uWebSockets.js, up to 20x faster. Same API, your middleware and framework keep working.",
     "main": "src/index.js",
     "exports": {
         ".": {
@@ -64,16 +64,28 @@
     "keywords": [
         "express",
         "express5",
+        "express-alternative",
+        "drop-in replacement",
         "fast",
+        "fastest",
+        "performance",
+        "web framework",
         "http",
         "http server",
         "https",
         "https server",
+        "router",
+        "middleware",
+        "rest api",
         "uwebsockets",
         "uws",
         "websocket",
         "websockets",
-        "performance"
+        "nestjs",
+        "angular ssr",
+        "nextjs",
+        "cluster",
+        "typescript"
     ],
     "types": "src/types.d.ts",
     "author": "Nigro Simone",
@@ -81,7 +93,7 @@
     "bugs": {
         "url": "https://github.com/nigrosimone/fulmine.js/issues"
     },
-    "homepage": "https://github.com/nigrosimone/fulmine.js#readme",
+    "homepage": "https://fulmine.sndesign.it",
     "dependencies": {
         "@types/express": "^5.0.6",
         "accepts": "^2.0.0",

package/src/adopt.js

@@ -14,17 +14,20 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-// The two commands that edit a config file rather than source: `npx fulmine.js override` and
-// `npx fulmine.js angular`.
+// The commands that edit a config file rather than source: `npx fulmine.js override`,
+// `npx fulmine.js angular` and `npx fulmine.js pnpm`.
 //
-// `migrate` rewrites `require("express")` in your own files. The two cases it cannot reach are
-// both a line in a JSON file:
+// `migrate` rewrites `require("express")` in your own files. The cases it cannot reach are each
+// a line in a config file:
 //
 //   override   A framework built on Express requires it in its own code, so there is no specifier
 //              to rewrite. Every package manager can answer `express` with this package instead,
 //              and each one spells it differently.
 //   angular    An Angular server bundle is built with esbuild, which inlines every dependency and
 //              cannot load uWS's native binary. Two names in `externalDependencies` fix it.
+//   pnpm       pnpm 10.26 and later refuse a git dependency of a dependency, and µWebSockets.js
+//              is one. A direct dependency is allowed, so the project takes it on itself and an
+//              override drops the copy this package asks for.
 
 "use strict";
 
@@ -37,6 +40,12 @@ const REPLACES = "express";
 /** The major this package tracks, which is the range an override should ask for. */
 const MAJOR = require("../package.json").version.split(".")[0];
 
+const UWS = "uWebSockets.js";
+/** The git spec this package pins, which is what a project taking uWS on itself has to pin too. */
+const UWS_SPEC = /** @type {string} */ (require("../package.json").dependencies[UWS]);
+/** The pnpm override that drops this package's own copy, so the project's direct one is the only one. */
+const UWS_OVERRIDE = `${SELF}>${UWS}`;
+
 /** Where each manager keeps its substitutions, and what to call it when telling someone. */
 const MANAGERS = {
     npm: { keys: ["overrides"], reinstall: "npm install" },
@@ -315,4 +324,106 @@ function angular(argv) {
     return 0;
 }
 
-module.exports = { override, angular, detectManager, serverBuilds, indentOf };
+/**
+ * The pnpm-workspace.yaml with the override in it. Written by hand rather than through a YAML
+ * library: the file is small, the block is two lines, and what is already there is kept as is.
+ *
+ * @param {string} source the file as it is, or "" when there is none
+ * @returns {string|undefined} the new file, or nothing when the override is already there
+ */
+function withPnpmOverride(source) {
+    const line = `  "${UWS_OVERRIDE}": "-"`;
+    if (
+        new RegExp(
+            `^\\s*["']?${SELF.replace(".", "\\.")}>${UWS.replace(".", "\\.")}["']?:\\s*["']?-["']?\\s*$`,
+            "m"
+        ).test(source)
+    ) {
+        return undefined;
+    }
+    const lines = source.length ? source.replace(/\r\n/g, "\n").replace(/\n*$/, "").split("\n") : [];
+    const at = lines.findIndex((one) => /^overrides:\s*$/.test(one));
+    if (at === -1) {
+        return [...lines, ...(lines.length ? [""] : []), "overrides:", line, ""].join("\n");
+    }
+    lines.splice(at + 1, 0, line);
+    return lines.join("\n") + "\n";
+}
+
+/**
+ * npx fulmine.js pnpm [dir] [--dry-run]
+ *
+ * Makes a pnpm project install this package, which pnpm 10.26 and later otherwise refuse: the
+ * project takes µWebSockets.js as a direct dependency, at the spec this package pins, and an
+ * override in pnpm-workspace.yaml drops the copy this package asks for. pnpm 11 reads its
+ * settings from that file only, so package.json's `pnpm` field is not where this goes.
+ *
+ * @param {string[]} argv everything after the command name
+ * @returns {number} exit code
+ */
+function pnpm(argv) {
+    const dryRun = argv.includes("--dry-run");
+    const dir = path.resolve(argv.find((arg) => !arg.startsWith("--")) ?? ".");
+    const file = path.join(dir, "package.json");
+    const workspaceFile = path.join(dir, "pnpm-workspace.yaml");
+
+    const read = readJson(file);
+    if ("error" in read) {
+        console.error(read.code === "ENOENT" ? `no package.json in ${dir}` : read.error);
+        return 1;
+    }
+    const { data: pkg, source } = read;
+
+    let changed = 0;
+    const existing = readPath(pkg, ["dependencies", UWS]);
+    if (existing === UWS_SPEC) {
+        console.log(`dependencies.${UWS} already says ${UWS_SPEC}`);
+    } else {
+        if (existing !== undefined) {
+            console.log(`dependencies.${UWS} says ${JSON.stringify(existing)}, and this package pins ${UWS_SPEC}:`);
+            console.log("the pin is what the code here was tested against, so it is the one written.");
+        }
+        writePath(pkg, ["dependencies", UWS], UWS_SPEC);
+        changed++;
+        console.log(`${dryRun ? "would add" : "added"} to package.json: "dependencies": { "${UWS}": "${UWS_SPEC}" }`);
+        if (!dryRun) fs.writeFileSync(file, JSON.stringify(pkg, null, indentOf(source)) + "\n");
+    }
+
+    let workspace = "";
+    try {
+        workspace = fs.readFileSync(workspaceFile, "utf8");
+    } catch {
+        // no workspace file yet, it is written below
+    }
+    const rewritten = withPnpmOverride(workspace);
+    if (rewritten === undefined) {
+        console.log(`pnpm-workspace.yaml already overrides ${UWS_OVERRIDE}`);
+    } else {
+        changed++;
+        console.log(`${dryRun ? "would add" : "added"} to pnpm-workspace.yaml: overrides: { "${UWS_OVERRIDE}": "-" }`);
+        if (!dryRun) fs.writeFileSync(workspaceFile, rewritten);
+    }
+
+    if (!changed) {
+        console.log("\nNothing to change.");
+        return 0;
+    }
+    console.log(`\nThen \`pnpm install\`. µWebSockets.js is now the project's own dependency, so it is fetched as a`);
+    console.log("direct one, which pnpm allows, and the copy this package asks for is dropped from the graph.");
+    console.log(
+        `When this package moves its pin, run this again: \`npx fulmine.js verify\` says when the two differ.\n`
+    );
+    return 0;
+}
+
+module.exports = {
+    override,
+    angular,
+    pnpm,
+    detectManager,
+    serverBuilds,
+    indentOf,
+    withPnpmOverride,
+    UWS_SPEC,
+    UWS_OVERRIDE
+};

package/src/application.js

@@ -47,7 +47,7 @@ const cpuCount = os.cpus().length;
 // mounted sub-app knows it may inherit the parent's
 const trustProxyDefaultSymbol = "@@symbol:trust_proxy_default";
 
-const workers = [];
+const workers = /** @type {FSWorker[]} */ ([]);
 let taskKey = 0;
 const workerTasks = new NullObject();
 
@@ -62,6 +62,9 @@ class FSWorker {
         this.worker = new Worker(path.join(__dirname, "worker.js"));
 
         this.worker.on("message", (message) => {
+            // node speaks on this channel too: under --watch a worker reports the files it loaded
+            // as {"watch:import": [...]}, which carries no key of ours
+            if (workerTasks[message.key] === undefined) return;
             this.busy = false;
             if (message.err) {
                 workerTasks[message.key].reject(new Error(message.err));
@@ -133,7 +136,7 @@ class Application extends Router {
             becomeSupervisor();
         }
         if (settings.uwsApp) {
-            this.uwsApp = settings.uwsApp;
+            this.uwsApp = /** @type {import("uWebSockets.js").TemplatedApp} */ (settings.uwsApp);
         } else if (settings.http3) {
             // uWS.H3App exists in the pinned build but its QUIC stack does not: the constructor
             // segfaults on Linux and hangs forever on Windows before serving a single request,
@@ -401,7 +404,7 @@ class Application extends Router {
             if (value != null && (!Array.isArray(value) || value.some((m) => typeof m !== "string"))) {
                 throw new TypeError('"etag methods" wants an array of method names, or null for all of them');
             }
-            value = value == null ? undefined : value.map((m) => m.toUpperCase());
+            value = value == null ? undefined : value.map((/** @type {string} */ m) => m.toUpperCase());
         } else if (key === "etag") {
             // The skips are not taken back here. They used to be, because send consults freshness,
             // but that branch reads if-none-match, if-modified-since and cache-control by name
@@ -594,7 +597,7 @@ class Application extends Router {
         // uWS runs this handler from inside its own listen(), so everything it hands back to the
         // caller is deferred a tick. Express binds synchronously too but reports through events,
         // and node emits both 'listening' and 'error' from a process.nextTick.
-        const onListen = (socket) => {
+        const onListen = (/** @type {import("uWebSockets.js").us_listen_socket|false} */ socket) => {
             if (!socket) {
                 /** @type {NodeJS.ErrnoException} */
                 const err = new Error("listen EADDRINUSE: address already in use :::" + port);
@@ -926,6 +929,7 @@ class Application extends Router {
 // Tried once before and reverted the same day, because a callable app broke supertest: `request(app)`
 // reads `typeof app === "function"` and wraps what it finds in http.createServer, and there was
 // nothing underneath that could serve node's IncomingMessage. src/node-shim.js closes that hole.
+/** @param {object} [options] the settings express() takes, see the Application constructor */
 module.exports = function (options) {
     return new Application(options)._asCallable();
 };

package/src/cli.js

@@ -37,6 +37,15 @@ limitations under the License.
 // The two things a project needs that are a line in a JSON file rather than a specifier in a
 // source file: the package manager substitution, for a framework that requires express in its own
 // code, and angular.json's externalDependencies. See src/adopt.js.
+//
+// npx fulmine create <dir>
+//
+// A new project for whoever has nothing to migrate: a server, a package.json and the Dockerfile
+// that works. See src/create.js.
+//
+// npx fulmine pnpm [dir]
+//
+// The two lines a pnpm project needs before it will install this at all. See src/adopt.js.
 
 const fs = require("fs");
 const path = require("path");
@@ -44,7 +53,8 @@ const acorn = require("acorn");
 // the same walk express.testing asserts on, so the command and the assertions cannot drift
 const { collectRoutes } = require("./testing.js");
 const { verify } = require("./verify.js");
-const { override, angular } = require("./adopt.js");
+const { override, angular, pnpm } = require("./adopt.js");
+const { create } = require("./create.js");
 
 /** @typedef {import("./application.js").Application} Application */
 /** @typedef {import("./router-utils.js").RouteEntry} RouteEntry */
@@ -214,6 +224,7 @@ function findSpecifiersTypeScript(source, fileName, ts, seen) {
         }
     };
 
+    /** @param {import("typescript").Node} node */
     const visit = (node) => {
         // import express from "express", import type { Request } from "express", export * from it.
         // A type-only import is rewritten too: the types come from the new package as well.
@@ -465,7 +476,7 @@ function findEntry(given) {
  * owns listen.
  *
  * @param {string} entry
- * @returns {object[]} the prototypes to stub, this command's copy first
+ * @returns {Application[]} the prototypes to stub, this command's copy first
  */
 function listenOwners(entry) {
     const builds = new Set([require("./index.js")]);
@@ -477,6 +488,7 @@ function listenOwners(entry) {
         }
     }
 
+    /** @type {Application[]} */
     const owners = [];
     for (const build of builds) {
         if (typeof build !== "function") {
@@ -531,6 +543,7 @@ function loadApps(argv, command) {
         return null;
     }
 
+    /** @type {Application[]} */
     const listened = [];
     const real = owners.map((proto) => proto.listen);
     for (const proto of owners) {
@@ -907,13 +920,23 @@ function main(argv) {
     if (command === "angular") {
         return angular(argv.slice(1));
     }
+    if (command === "create") {
+        return create(argv.slice(1));
+    }
+    if (command === "pnpm") {
+        return pnpm(argv.slice(1));
+    }
     if (command !== "migrate") {
         console.log(`Usage:
+  npx ${TO} create <dir>       start a new project: a server, a package.json and a Dockerfile that
+                               works, --ts for TypeScript, --pnpm for the two lines pnpm needs
   npx ${TO} migrate [dir]      rewrite require("${FROM}") and import from "${FROM}" to "${TO}"
   npx ${TO} override [dir]     answer ${FROM} with this package for the whole dependency tree, for
                                when a framework requires ${FROM} in its own code and not in yours
   npx ${TO} angular [dir]      declare this package external in angular.json's server build, which
                                esbuild otherwise tries to inline a native binary into
+  npx ${TO} pnpm [dir]         make a pnpm project install this: pnpm 10.26 and later refuse a git
+                               dependency of a dependency, and µWebSockets.js is one
   npx ${TO} profile [entry]    load an application without listening and print what compiling
                                its routes decided, route by route
   npx ${TO} explain <route>    what happens when a request for that route arrives
@@ -921,7 +944,7 @@ function main(argv) {
   npx ${TO} differences        print what behaves differently, without changing anything
 
 Options:
-  --dry-run                    migrate, override, angular: say what would change and change nothing`);
+  --dry-run                    migrate, override, angular, pnpm: say what would change and change nothing`);
         return command ? 1 : 0;
     }
 

package/src/compression.js

@@ -161,6 +161,7 @@ function reusableCompressor(create, finishFlag, oneShot) {
         return oneShot;
     };
 
+    /** @param {Buffer} body */
     const compress = (body) => {
         if (broken || busy) {
             return oneShot(body);

package/src/create.js

@@ -0,0 +1,248 @@
+/*
+Copyright 2026 Nigro Simone
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// npx fulmine.js create <dir> [--ts] [--pnpm]
+//
+// A new project, for whoever has no Express application to migrate. `migrate` and `override` start
+// from somebody's code; this starts from nothing and writes the few files a first run needs: a
+// server, a package.json, and the Dockerfile that works, since the base image is the one thing a
+// Dockerfile written for Express gets wrong here. Nothing is installed, that is the user's call.
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { withPnpmOverride, UWS_SPEC } = require("./adopt.js");
+
+const SELF = "fulmine.js";
+
+/** The major this package tracks, which is the range a new project should ask for. */
+const MAJOR = require("../package.json").version.split(".")[0];
+
+/**
+ * The node major the Dockerfile names: the one running this when it has a µWS binary, which is the
+ * even lines, and the newest supported one otherwise.
+ *
+ * @returns {number}
+ */
+function nodeMajor() {
+    const running = Number(process.versions.node.split(".")[0]);
+    return running >= 22 && running % 2 === 0 ? running : 26;
+}
+
+/**
+ * The server, in the flavour asked for. The same three routes either way: a page, a JSON answer
+ * with a parameter, and a body read by the built-in parser.
+ *
+ * @param {boolean} ts
+ * @returns {string}
+ */
+function serverSource(ts) {
+    const types = ts ? 'import type { Request, Response } from "fulmine.js";\n' : "";
+    const params = ts ? "(req: Request, res: Response)" : "(req, res)";
+    return `import express from "${SELF}";
+${types}
+const app = express();
+const port = Number(process.env.PORT ?? 3000);
+
+app.use(express.json());
+app.use(express.static("public"));
+
+app.get("/api/hello", ${params} => {
+    res.json({ hello: "world" });
+});
+
+app.get("/api/items/:id", ${params} => {
+    res.json({ id: req.params.id });
+});
+
+app.post("/api/items", ${params} => {
+    res.status(201).json(req.body);
+});
+
+app.listen(port, () => {
+    console.log(\`listening on http://localhost:\${port}\`);
+});
+`;
+}
+
+/**
+ * @param {string} name the package name, from the directory
+ * @param {boolean} ts
+ * @param {boolean} pnpm the project also owns µWebSockets.js, see `npx fulmine.js pnpm`
+ * @returns {string}
+ */
+function packageSource(name, ts, pnpm) {
+    const pkg = {
+        name,
+        version: "0.1.0",
+        private: true,
+        type: "module",
+        scripts: ts
+            ? {
+                  build: "tsc",
+                  start: "node dist/server.js",
+                  dev: "node --watch --experimental-strip-types src/server.ts"
+              }
+            : { start: "node server.js", dev: "node --watch server.js" },
+        dependencies: { [SELF]: `^${MAJOR}`, ...(pnpm ? { "uWebSockets.js": UWS_SPEC } : {}) },
+        ...(ts ? { devDependencies: { "@types/node": `^${nodeMajor()}`, typescript: "^5" } } : {}),
+        engines: { node: ">=22" }
+    };
+    return JSON.stringify(pkg, null, 4) + "\n";
+}
+
+const TSCONFIG = `{
+    "compilerOptions": {
+        "target": "es2022",
+        "module": "nodenext",
+        "outDir": "dist",
+        "rootDir": "src",
+        "strict": true,
+        "verbatimModuleSyntax": true,
+        "skipLibCheck": true,
+        "types": ["node"]
+    },
+    "include": ["src"]
+}
+`;
+
+/**
+ * Install with the full image, which has git for the µWS fetch, run with the slim one. trixie or
+ * newer on both, since bookworm's glibc is too old for the binary and Alpine has no build at all.
+ *
+ * @param {boolean} ts
+ * @param {boolean} pnpm install with pnpm, whose lockfile and workspace file come along
+ * @returns {string}
+ */
+function dockerfileSource(ts, pnpm) {
+    const major = nodeMajor();
+    const manifests = pnpm ? "package.json pnpm-lock.yaml pnpm-workspace.yaml" : "package*.json";
+    const install = pnpm ? "npm install -g pnpm@11 && pnpm install --frozen-lockfile" : "npm ci";
+    const build = ts
+        ? `COPY ${manifests} tsconfig.json ./
+RUN ${install}
+COPY src ./src
+RUN ${pnpm ? "pnpm run build && pnpm prune --prod" : "npm run build && npm prune --omit=dev"}`
+        : `COPY ${manifests} ./
+RUN ${install}${pnpm ? " --prod" : " --omit=dev"}`;
+    const run = ts
+        ? `COPY --from=build /app/node_modules ./node_modules
+COPY --from=build /app/dist ./dist
+COPY package.json ./
+COPY public ./public
+EXPOSE 3000
+CMD ["node", "dist/server.js"]`
+        : `COPY --from=build /app/node_modules ./node_modules
+COPY . .
+EXPOSE 3000
+CMD ["node", "server.js"]`;
+    return `FROM node:${major}-trixie AS build
+WORKDIR /app
+${build}
+
+FROM node:${major}-trixie-slim
+WORKDIR /app
+ENV NODE_ENV=production
+${run}
+`;
+}
+
+const INDEX_HTML = `<!doctype html>
+<meta charset="utf-8">
+<title>fulmine.js</title>
+<p>Served by <code>express.static()</code>. The API answers on <a href="/api/hello">/api/hello</a>.</p>
+`;
+
+/**
+ * The files a new project is made of, by path.
+ *
+ * @param {string} name
+ * @param {boolean} ts
+ * @param {boolean} pnpm
+ * @returns {Record<string, string>}
+ */
+function projectFiles(name, ts, pnpm) {
+    return {
+        "package.json": packageSource(name, ts, pnpm),
+        [ts ? "src/server.ts" : "server.js"]: serverSource(ts),
+        ...(ts ? { "tsconfig.json": TSCONFIG } : {}),
+        // pnpm refuses a git dependency of a dependency, so the project owns µWebSockets.js itself
+        ...(pnpm ? { "pnpm-workspace.yaml": /** @type {string} */ (withPnpmOverride("")) } : {}),
+        "public/index.html": INDEX_HTML,
+        Dockerfile: dockerfileSource(ts, pnpm),
+        ".dockerignore": "node_modules\n.git\ndist\n",
+        ".gitignore": "node_modules\ndist\n"
+    };
+}
+
+/**
+ * `npx fulmine.js create <dir> [--ts] [--pnpm]`
+ *
+ * pnpm is also read from how this was started: `pnpm dlx fulmine.js create` says so in the user
+ * agent npm and pnpm both set, and a project started that way would otherwise fail its first install.
+ *
+ * @param {string[]} argv everything after the command
+ * @returns {number} exit code
+ */
+function create(argv) {
+    const ts = argv.includes("--ts");
+    const pnpm = argv.includes("--pnpm") || /^pnpm\//.test(process.env.npm_config_user_agent ?? "");
+    const given = argv.find((arg) => !arg.startsWith("--"));
+    if (!given) {
+        console.error(`Usage: npx ${SELF} create <dir> [--ts] [--pnpm]`);
+        return 1;
+    }
+    const dir = path.resolve(given);
+    // a name npm accepts: what the directory is called, lowercased, anything else a dash
+    const name =
+        path
+            .basename(dir)
+            .toLowerCase()
+            .replace(/[^a-z0-9._-]+/g, "-") || "app";
+
+    if (fs.existsSync(dir) && fs.readdirSync(dir).length) {
+        console.error(`${dir} is not empty. Nothing was written: this only starts a project, it does not join one.`);
+        return 1;
+    }
+
+    const files = projectFiles(name, ts, pnpm);
+    for (const [file, content] of Object.entries(files)) {
+        const full = path.join(dir, file);
+        fs.mkdirSync(path.dirname(full), { recursive: true });
+        fs.writeFileSync(full, content);
+        console.log(`wrote ${path.join(given, file)}`);
+    }
+
+    const pm = pnpm ? "pnpm" : "npm";
+    console.log(`\nNext:\n`);
+    console.log(`  cd ${given}`);
+    console.log(`  ${pm} install`);
+    console.log(`  ${pm} run dev${ts ? `                 # or ${pm} run build && ${pm} start` : ""}\n`);
+    if (pnpm) {
+        console.log("pnpm refuses a git dependency of a dependency, and µWebSockets.js is one, so this project owns");
+        console.log(
+            "it: the pin in package.json and the override in pnpm-workspace.yaml. See docs/deployment.md#pnpm."
+        );
+    }
+    console.log(
+        `The Dockerfile uses node:${nodeMajor()}-trixie, since Alpine and bookworm cannot load µWebSockets.js.`
+    );
+    console.log(`\`npx ${SELF} verify\` says whether this machine can, before you install anything.\n`);
+    return 0;
+}
+
+module.exports = { create, projectFiles };

package/src/declarative.js

@@ -26,6 +26,7 @@ const uWSAny = /** @type {any} */ (uWS);
 const statuses = require("statuses");
 
 /** @typedef {import("./application.js").Application} Application */
+/** @typedef {import("./router.js")} Router */
 
 const parser = acorn.Parser;
 
@@ -45,7 +46,11 @@ const allowedResMethods = [
 
 const allowedIdentifiers = ["query", "params", ...allowedResMethods];
 
-/** What res.type(x) sets the content type to. A lookup on a literal. */
+/**
+ * What res.type(x) sets the content type to. A lookup on a literal.
+ *
+ * @param {string} type
+ */
 const typeValueOf = (type) => (type.indexOf("/") === -1 ? contentTypeFor(type) : type);
 
 // what one instruction of a declarative response can carry, since uWS writes its length as a u16
@@ -307,7 +312,7 @@ function readStatusAndHeaders(callExprs, headers) {
  * @param {any[]} callExprs the res calls, in run order, as readStatusAndHeaders takes them
  * @param {[string, string][]} headers the headers read so far, written to
  * @param {any[]} body the body parts, written to; loose because a literal's value is kept as it is
- * @param {Application} app the application, for the json settings
+ * @param {Application|Router} app the application or router the route hangs on, for the json settings
  * @param {string[]} queries names bound by a destructured req.query
  * @param {string[]} params names bound by a destructured req.params
  * @returns {{sendUsed: boolean, bodyFromSend: boolean}|null}
@@ -438,6 +443,7 @@ function readBody(callExprs, headers, body, app, queries, params) {
                     }
                     body.push({ type: arg.object.property.name, value: arg.property.name });
                 } else if (arg.type === "BinaryExpression") {
+                    /** @type {any[]} the parts, in the same loose shape as body */
                     const stuff = [];
                     /**
                      * Reads a chain of string concatenations right to left. Each side must be a literal or a
@@ -768,6 +774,10 @@ function identifiersAllowed(fn, args, names) {
 // - doesnt create variables
 // - only uses req.query and req.params
 // basically, its only simple, static responses
+/**
+ * @param {Function} cb the handler
+ * @param {Application|Router} app the application or router the route hangs on, for the json settings
+ */
 module.exports = function compileDeclarative(cb, app) {
     try {
         const handler = readHandler(cb);
@@ -791,8 +801,8 @@ module.exports = function compileDeclarative(cb, app) {
             return false;
         }
 
+        /** @type {[string, string][]} */
         const headers = [];
-        const body = [];
 
         const status = readStatusAndHeaders(callExprs, headers);
         if (status === null) {
@@ -800,6 +810,8 @@ module.exports = function compileDeclarative(cb, app) {
         }
         const { statusCode, sendStatusUsed } = status;
 
+        /** @type {any[]} loose because a literal's value is kept as it is, see readBody */
+        const body = [];
         const read = readBody(callExprs, headers, body, app, queries, params);
         if (read === null) {
             return false;