fulmine.js 5.19.9 → 5.20.0

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "fulmine.js",
-    "version": "5.19.9",
-    "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

@@ -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));

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 */
@@ -910,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
@@ -924,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/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/index.js

@@ -21,6 +21,28 @@ limitations under the License.
 // package ships, so the module is read through a loose alias
 const uWS = require("uWebSockets.js");
 const uWSAny = /** @type {any} */ (uWS);
+
+// A project on pnpm owns the uWebSockets.js dependency itself, see `npx fulmine.js pnpm`, so the
+// one installed can drift from the one this package pins and was tested against. Said once, at
+// require time, where it reaches every deployment rather than only the ones that run verify.
+{
+    const pinned = /#v?([\d.]+)$/.exec(require("../package.json").dependencies["uWebSockets.js"])?.[1];
+    /** @type {string|undefined} */
+    let installed;
+    try {
+        // its exports map does not expose package.json, so it is read beside the entry point
+        const beside = require("path").join(require.resolve("uWebSockets.js"), "..", "package.json");
+        installed = JSON.parse(require("fs").readFileSync(beside, "utf8")).version;
+    } catch {
+        // nothing to compare against, which is not worth a warning of its own
+    }
+    if (pinned && installed && installed !== pinned) {
+        console.warn(
+            `fulmine.js: uWebSockets.js ${installed} is installed, this version was tested with ${pinned}.\n` +
+                "  On pnpm the pin is the project's own: `npx fulmine.js pnpm` writes the tested one."
+        );
+    }
+}
 const Application = require("./application.js");
 const Router = require("./router.js");
 const Route = require("./route.js");