fulmine.js 5.21.0 → 5.21.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "fulmine.js",
-    "version": "5.21.0",
+    "version": "5.21.1",
     "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": {
@@ -116,7 +116,7 @@
         "statuses": "^2.0.2",
         "tseep": "^1.3.1",
         "type-is": "^2.1.0",
-        "uWebSockets.js": "github:uNetworking/uWebSockets.js#v20.69.0",
+        "uWebSockets.js": "github:uNetworking/uWebSockets.js#v20.71.0",
         "vary": "^1.1.2"
     },
     "peerDependencies": {

package/src/application.js

@@ -17,7 +17,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-const uWS = require("uWebSockets.js");
+const { loadUWS } = require("./uws.js");
 const Router = require("./router.js");
 const {
     removeDuplicateSlashes,
@@ -59,7 +59,10 @@ class FSWorker {
      */
     constructor() {
         this.busy = false;
-        this.worker = new Worker(path.join(__dirname, "worker.js"));
+        // its own execArgv, not the parent thread's: a worker inherits them, and a --require or
+        // --import written for the parent (Angular's route extraction registers a loader that reads
+        // workerData) throws inside a thread that only reads files
+        this.worker = new Worker(path.join(__dirname, "worker.js"), { execArgv: [] });
 
         this.worker.on("message", (message) => {
             // node speaks on this channel too: under --watch a worker reports the files it loaded
@@ -113,6 +116,15 @@ class Application extends Router {
      */
     _testingCompiled;
 
+    /**
+     * The uWS app once made, or the one settings.uwsApp handed in. See the uwsApp getter.
+     * @type {any}
+     */
+    _uwsApp;
+
+    /** What uWS.App or uWS.SSLApp is given, kept until the app is made. */
+    _uwsOptions;
+
     /**
      * @param {object} [settings] the options express() takes. uwsOptions goes to uWS and decides
      *   between an HTTP, an HTTPS and an HTTP/3 server; threads sizes the file-reading pool, and 0
@@ -135,9 +147,7 @@ class Application extends Router {
         if (this._clusterWorkers > 0 && cluster.isPrimary) {
             becomeSupervisor();
         }
-        if (settings.uwsApp) {
-            this.uwsApp = /** @type {import("uWebSockets.js").TemplatedApp} */ (settings.uwsApp);
-        } else if (settings.http3) {
+        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,
             // verified 2026-08-05 with uWS alone. A clear throw beats a native crash; this
@@ -146,12 +156,12 @@ class Application extends Router {
                 "http3 is not usable with the pinned uWebSockets.js build: its H3App crashes " +
                     "during construction. Track uNetworking/uWebSockets.js for working QUIC support."
             );
-        } else if (settings.uwsOptions.key_file_name && settings.uwsOptions.cert_file_name) {
-            this.uwsApp = uWS.SSLApp(settings.uwsOptions);
-        } else {
-            this.uwsApp = uWS.App(settings.uwsOptions);
         }
         this.ssl = settings.uwsOptions.key_file_name && settings.uwsOptions.cert_file_name;
+        // the uWS app is made on first use, see the uwsApp getter: what listen(), ws() and the
+        // optimizer need, and what an app served through node's http never asks for
+        this._uwsApp = settings.uwsApp;
+        this._uwsOptions = settings.uwsOptions;
         this.cache = new NullObject();
         this.engines = { __proto__: null };
         // a null prototype, as express gives app.locals, so a local named like an Object method
@@ -509,6 +519,22 @@ class Application extends Router {
         return request;
     }
 
+    /**
+     * The µWS app underneath, for anything µWS offers that this does not: socket.io attaches to
+     * it. Made the first time it is asked for, so an application that only ever answers through
+     * node's http, a test through supertest or Angular's build extracting routes in a worker
+     * thread, never loads the binary. See src/uws.js for why that matters.
+     *
+     * @returns {any}
+     */
+    get uwsApp() {
+        if (this._uwsApp === undefined) {
+            const uWS = loadUWS();
+            this._uwsApp = this.ssl ? uWS.SSLApp(this._uwsOptions) : uWS.App(this._uwsOptions);
+        }
+        return this._uwsApp;
+    }
+
     /**
      * Registers the catch-all uWS handler, which is what serves every request that no optimized
      * route took natively. It walks this app's own chain and, when nothing in it answered, decides
@@ -617,7 +643,7 @@ class Application extends Router {
             // listen() returns. The callback is not: running it here would run it before listen()
             // had returned, and `const server = app.listen(p, () => server.address())` - the form
             // the Express docs use - would die on the temporal dead zone.
-            this.port = uWS.us_socket_local_port(socket);
+            this.port = loadUWS().us_socket_local_port(socket);
             this.listening = true;
             this._listenHost = host;
             // kept so close() can stop accepting without dropping what is in flight
@@ -888,7 +914,7 @@ class Application extends Router {
             return this;
         }
         if (this._listenSocket) {
-            uWS.us_listen_socket_close(this._listenSocket);
+            loadUWS().us_listen_socket_close(this._listenSocket);
             this._listenSocket = undefined;
         }
         this._draining = true;

package/src/declarative.js

@@ -21,8 +21,7 @@ const acorn = require("acorn");
 const { stringify, contentTypeSet, withUtf8Charset, contentTypeFor, headerIsWritable } = require("./utils.js");
 // H3App, DeclarativeResponse and _cfg exist at runtime but are missing from the .d.ts the
 // package ships, so the module is read through a loose alias
-const uWS = require("uWebSockets.js");
-const uWSAny = /** @type {any} */ (uWS);
+const { loadUWS } = require("./uws.js");
 const statuses = require("statuses");
 
 /** @typedef {import("./application.js").Application} Application */
@@ -836,7 +835,7 @@ module.exports = function compileDeclarative(cb, app) {
             return false;
         }
 
-        let decRes = new uWSAny.DeclarativeResponse();
+        let decRes = new (loadUWS().DeclarativeResponse)();
 
         if (statusCode !== 200) {
             const statusMessage = statuses.message[statusCode] ?? "unknown";

package/src/index.js

@@ -17,11 +17,6 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-// H3App, DeclarativeResponse and _cfg exist at runtime but are missing from the .d.ts the
-// 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.
@@ -50,13 +45,6 @@ const middlewares = require("./middlewares.js");
 const Request = require("./request.js");
 const Response = require("./response.js");
 
-try {
-    // disable Uwebsockets header
-    uWSAny._cfg("999999990007");
-} catch (error) {
-    // older uWS builds do not expose _cfg; there is nothing to fall back to
-}
-
 try {
     // the compile cache, node 22.8 and up: the next boot skips compiling the same code. Respects
     // NODE_DISABLE_COMPILE_CACHE, and booting without a cache is not an error

package/src/router.js

@@ -100,9 +100,11 @@ module.exports = class Router extends EventEmitter {
      * it have already established that, so the honest `TemplatedApp|undefined` would only add
      * casts where the guard already is.
      *
-     * @type {any}
+     * @returns {any}
      */
-    uwsApp;
+    get uwsApp() {
+        return undefined;
+    }
 
     /**
      * Whether an unset routing flag reads on through the mount parent. Only an application does,

package/src/types.d.ts

@@ -18,6 +18,7 @@ declare module "fulmine.js" {
     import e from "express";
     import uWS from "uWebSockets.js";
     import { ZlibOptions, BrotliOptions } from "zlib";
+    import serveStatic = require("serve-static");
 
     type Settings = {
         uwsOptions?: uWS.AppOptions;
@@ -36,7 +37,16 @@ declare module "fulmine.js" {
         export import request = e.request;
         export import response = e.response;
 
-        export import static = e.static;
+        /** serve-static's options plus preCompressed, which is this project's. */
+        interface StaticOptions extends serveStatic.ServeStaticOptions<e.Response> {
+            /**
+             * Serve `file.br` or `file.gz` in place of `file` when one is on disk and the client
+             * takes it. Off by default. Which twins a path has is remembered for a second;
+             * `{ cache: false }` asks the disk every time, a duration sets how long.
+             */
+            preCompressed?: boolean | { cache?: number | string | false };
+        }
+        function static(root: string, options?: StaticOptions): e.RequestHandler;
         // export import query = e.query;
 
         // express has no compression middleware, so there is nothing to re-export: these are the

package/src/uws.js

@@ -0,0 +1,45 @@
+/*
+Copyright 2024 dimden.dev
+Copyright 2026 Nigro Simone
+
+This file is derived from Ultimate Express and has been modified.
+
+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.
+
+// µWebSockets.js, loaded the first time something needs it rather than when this package is
+// required. An application that is built and never listens never loads the binary. Angular's
+// build imports server.ts in a worker thread to extract the routes and serves it through node's
+// http, and on Windows the binary crashes the process when a thread that loaded it exits
+// (uNetworking/uWebSockets.js#668), so the build only works if nothing in that thread loads it.
+
+/** @type {any} */
+let uWS;
+
+/**
+ * The µWS module. H3App, DeclarativeResponse and _cfg exist at runtime but are missing from the
+ * .d.ts the package ships, so it is handed back loosely typed.
+ *
+ * @returns {any}
+ */
+function loadUWS() {
+    if (uWS === undefined) {
+        uWS = /** @type {any} */ (require("uWebSockets.js"));
+        try {
+            // disable Uwebsockets header
+            uWS._cfg("999999990007");
+        } catch (error) {
+            // older uWS builds do not expose _cfg; there is nothing to fall back to
+        }
+    }
+    return uWS;
+}
+
+module.exports = { loadUWS };