fulmine.js 5.19.2 → 5.19.3

package/src/work.js

@@ -16,27 +16,21 @@ limitations under the License.
 
 // What one request actually made this framework do, read from state it already keeps.
 //
-// Most of what makes this faster than Express is work that does not happen: the Readable and the
-// Writable are not built, the headers are not folded into an object, the query is not parsed, the
-// socket stand-in is not allocated. None of that is visible from the outside, and all of it is one
-// careless middleware away from coming back: a `req.headers.host` where `req.get("host")` would do
-// puts the folded object back on every request, and the answer stays correct, so nothing fails.
+// Most of the speed here is work that does not happen: no Readable, no Writable, no folded headers
+// object, no parsed query, no socket stand-in. One careless middleware brings it back, and the
+// answer stays correct, so nothing fails. Every field below is already kept for other reasons, so
+// asking costs a load and nothing is counted or wrapped for the sake of being asked.
 //
-// Every field below is a property this framework already had to keep for its own reasons, so
-// asking costs a load and nothing is counted, stamped or wrapped for the sake of being asked. That
-// is the whole design rule here: a probe that charges the requests nobody is probing would be
-// paid for by everyone, forever, to be read once.
+// Not here: whether the constructor copied the headers out of uWS. That is about the chain and
+// `routeReport().skipHeaders` reports it already.
 //
-// What is deliberately not here is whether the constructor copied the headers out of µWS. That is
-// a decision about the chain rather than about the request, `routeReport().skipHeaders` reports it
-// already, and the one case where the two differ, a granted route whose request declares a body,
-// would cost a flag written on every request to be read on almost none.
-//
-// The two readers are `express.testing.expectLazy`, which fails a build that lost one of these,
-// and `express.serverTiming()`, which writes them into the header for a browser to show.
+// Read by `express.testing.expectLazy` and by `express.serverTiming()`.
 
 "use strict";
 
+/** @typedef {import("./request.js")} Request */
+/** @typedef {import("./response.js")} Response */
+
 /**
  * @typedef {object} Work
  * @property {boolean} native whether µWS matched this route itself
@@ -50,29 +44,30 @@ limitations under the License.
  */
 
 /**
- * What this request did, as it stands right now: the answer changes while the chain runs, so a
- * reader that wants the whole picture asks at the end of it.
+ * What this request did so far. The answer changes while the chain runs, so ask at the end of it.
  *
- * @param {any} req
- * @param {any} res the response, since half of this is about the response
+ * @param {Request} req
+ * @param {Response} res the response, since half of this is about the response
  * @returns {Work}
  */
 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);
     return {
         native: Boolean(native),
         declarative: Boolean(native?.declarative),
         headers: req._headersBuilt,
         query: req._queryParsed,
-        body: req.body !== undefined,
-        requestStream: req._readableState !== undefined,
-        responseStream: res._writableState !== undefined,
+        body: loose.body !== undefined,
+        requestStream: loose._readableState !== undefined,
+        responseStream: /** @type {any} */ (res)._writableState !== undefined,
         socket: req._socketBuilt || res._socketBuilt
     };
 }
 
-// The order the two readers list them in: what the request was made to do, cheapest first, so a
-// header and a failure message read the same way.
+// The order both readers list them in, cheapest first, so a header and a failure message agree.
 const NAMES = [
     ["headers", "headers"],
     ["query", "query"],
@@ -83,8 +78,7 @@ const NAMES = [
 ];
 
 /**
- * The names of everything that did happen, for a message or a header. Empty for the request that
- * did none of it, which is the one this framework is built to serve.
+ * The names of everything that did happen, for a message or a header. Empty is the good case.
  *
  * @param {Work} done
  * @returns {string[]}