@req-inspect/express 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,23 @@
-# Temporary Holding Version
+# @req-inspect/express
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Express middleware for [req-inspect](https://github.com/Hurishihara/req-inspect): a live request inspector dashboard.
+
+## Install
+
+```sh
+npm i @req-inspect/express
+```
+
+## Usage
+
+```js
+import express from 'express'
+import { inspector } from '@req-inspect/express'
+
+const app = express()
+app.use(inspector()) // at the app root, before routes and body parsers
+```
+
+Open `/_inspect` in your browser. Without `auth` it is only reachable from localhost.
+
+See the [root README](https://github.com/Hurishihara/req-inspect#readme) for options, security and known limitations.

package/dist/index.cjs

@@ -0,0 +1,130 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  default: () => index_default,
+  inspector: () => inspector
+});
+module.exports = __toCommonJS(index_exports);
+var import_core = require("@req-inspect/core");
+function inspector(options = {}) {
+  const insp = (0, import_core.createInspector)(options);
+  const { enabled, maxBodyBytes: max } = insp.options;
+  return (req, res, next) => {
+    if (!enabled) return next();
+    const q = req.originalUrl.indexOf("?");
+    const pathname = q < 0 ? req.originalUrl : req.originalUrl.slice(0, q);
+    if (insp.isInspectorPath(pathname)) return insp.handle(req, res);
+    if (insp.shouldIgnore(pathname)) return next();
+    const startedAt = Date.now();
+    const t0 = performance.now();
+    const chunks = [];
+    let kept = 0;
+    let total = 0;
+    let done = false;
+    let snap;
+    const snapshot = () => {
+      snap ??= {
+        route: req.route ? `${req.baseUrl}${req.route.path}` : null,
+        params: { ...req.params }
+      };
+    };
+    const collect = (args) => {
+      try {
+        snapshot();
+        const chunk = args[0];
+        if (typeof chunk !== "string" && !(chunk instanceof Uint8Array)) return;
+        const enc = typeof args[1] === "string" ? args[1] : "utf8";
+        if (kept >= max) {
+          total += typeof chunk === "string" ? Buffer.byteLength(chunk, enc) : chunk.byteLength;
+          return;
+        }
+        const room = max - kept;
+        let part;
+        if (typeof chunk === "string") {
+          const buf = Buffer.from(chunk, enc);
+          total += buf.length;
+          part = buf.length > room ? Buffer.from(buf.subarray(0, room)) : buf;
+        } else {
+          const bytes = chunk;
+          total += bytes.byteLength;
+          part = Buffer.from(bytes.subarray(0, Math.min(bytes.byteLength, room)));
+        }
+        chunks.push(part);
+        kept += part.length;
+      } catch (err) {
+        (0, import_core.warnOnce)("capture", err);
+      }
+    };
+    const origWrite = res.write;
+    const origEnd = res.end;
+    res.write = function(...args) {
+      collect(args);
+      return origWrite.apply(this, args);
+    };
+    res.end = function(...args) {
+      collect(args);
+      return origEnd.apply(this, args);
+    };
+    const finalize = (aborted) => {
+      if (done) return;
+      done = true;
+      try {
+        snapshot();
+        const reqBody = insp.captureRequestBody(req.body, req.headers["content-type"]);
+        const resBody = req.method === "HEAD" ? { kind: "none" } : (0, import_core.captureRawBody)(
+          chunks,
+          total,
+          res.getHeader("content-type"),
+          res.getHeader("content-encoding"),
+          max
+        );
+        const draft = {
+          startedAt,
+          durationMs: Math.round((performance.now() - t0) * 10) / 10,
+          method: req.method,
+          url: req.originalUrl,
+          route: snap.route,
+          status: res.statusCode,
+          ...aborted ? { aborted: true } : {},
+          request: {
+            headers: (0, import_core.normalizeHeaders)(req.headers),
+            query: req.query,
+            params: snap.params,
+            body: reqBody.kind === "binary" && reqBody.size === 0 ? { kind: "none" } : reqBody
+          },
+          response: { headers: (0, import_core.normalizeHeaders)(res.getHeaders()), body: resBody }
+        };
+        insp.record(draft);
+      } catch (err) {
+        (0, import_core.warnOnce)("capture", err);
+      }
+    };
+    res.once("finish", () => finalize(false));
+    res.once("close", () => finalize(true));
+    next();
+  };
+}
+var index_default = inspector;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  inspector
+});

package/dist/index.d.cts

@@ -0,0 +1,7 @@
+import { RequestHandler } from 'express';
+import { InspectorOptions } from '@req-inspect/core';
+export { InspectorOptions } from '@req-inspect/core';
+
+declare function inspector(options?: InspectorOptions): RequestHandler;
+
+export { inspector as default, inspector };

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { RequestHandler } from 'express';
+import { InspectorOptions } from '@req-inspect/core';
+export { InspectorOptions } from '@req-inspect/core';
+
+declare function inspector(options?: InspectorOptions): RequestHandler;
+
+export { inspector as default, inspector };

package/dist/index.js

@@ -0,0 +1,110 @@
+// src/index.ts
+import {
+  captureRawBody,
+  createInspector,
+  normalizeHeaders,
+  warnOnce
+} from "@req-inspect/core";
+function inspector(options = {}) {
+  const insp = createInspector(options);
+  const { enabled, maxBodyBytes: max } = insp.options;
+  return (req, res, next) => {
+    if (!enabled) return next();
+    const q = req.originalUrl.indexOf("?");
+    const pathname = q < 0 ? req.originalUrl : req.originalUrl.slice(0, q);
+    if (insp.isInspectorPath(pathname)) return insp.handle(req, res);
+    if (insp.shouldIgnore(pathname)) return next();
+    const startedAt = Date.now();
+    const t0 = performance.now();
+    const chunks = [];
+    let kept = 0;
+    let total = 0;
+    let done = false;
+    let snap;
+    const snapshot = () => {
+      snap ??= {
+        route: req.route ? `${req.baseUrl}${req.route.path}` : null,
+        params: { ...req.params }
+      };
+    };
+    const collect = (args) => {
+      try {
+        snapshot();
+        const chunk = args[0];
+        if (typeof chunk !== "string" && !(chunk instanceof Uint8Array)) return;
+        const enc = typeof args[1] === "string" ? args[1] : "utf8";
+        if (kept >= max) {
+          total += typeof chunk === "string" ? Buffer.byteLength(chunk, enc) : chunk.byteLength;
+          return;
+        }
+        const room = max - kept;
+        let part;
+        if (typeof chunk === "string") {
+          const buf = Buffer.from(chunk, enc);
+          total += buf.length;
+          part = buf.length > room ? Buffer.from(buf.subarray(0, room)) : buf;
+        } else {
+          const bytes = chunk;
+          total += bytes.byteLength;
+          part = Buffer.from(bytes.subarray(0, Math.min(bytes.byteLength, room)));
+        }
+        chunks.push(part);
+        kept += part.length;
+      } catch (err) {
+        warnOnce("capture", err);
+      }
+    };
+    const origWrite = res.write;
+    const origEnd = res.end;
+    res.write = function(...args) {
+      collect(args);
+      return origWrite.apply(this, args);
+    };
+    res.end = function(...args) {
+      collect(args);
+      return origEnd.apply(this, args);
+    };
+    const finalize = (aborted) => {
+      if (done) return;
+      done = true;
+      try {
+        snapshot();
+        const reqBody = insp.captureRequestBody(req.body, req.headers["content-type"]);
+        const resBody = req.method === "HEAD" ? { kind: "none" } : captureRawBody(
+          chunks,
+          total,
+          res.getHeader("content-type"),
+          res.getHeader("content-encoding"),
+          max
+        );
+        const draft = {
+          startedAt,
+          durationMs: Math.round((performance.now() - t0) * 10) / 10,
+          method: req.method,
+          url: req.originalUrl,
+          route: snap.route,
+          status: res.statusCode,
+          ...aborted ? { aborted: true } : {},
+          request: {
+            headers: normalizeHeaders(req.headers),
+            query: req.query,
+            params: snap.params,
+            body: reqBody.kind === "binary" && reqBody.size === 0 ? { kind: "none" } : reqBody
+          },
+          response: { headers: normalizeHeaders(res.getHeaders()), body: resBody }
+        };
+        insp.record(draft);
+      } catch (err) {
+        warnOnce("capture", err);
+      }
+    };
+    res.once("finish", () => finalize(false));
+    res.once("close", () => finalize(true));
+    next();
+  };
+}
+var index_default = inspector;
+export {
+  index_default as default,
+  inspector
+};

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@req-inspect/express",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup"
+  },
+  "dependencies": {
+    "@req-inspect/core": "^0.1.0"
+  },
+  "peerDependencies": {
+    "express": "^4.18 || ^5"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "express4": "npm:express@^4.21",
+    "express5": "npm:express@^5.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Hurishihara/req-inspect.git",
+    "directory": "packages/express"
+  },
+  "homepage": "https://github.com/Hurishihara/req-inspect#readme",
+  "bugs": {
+    "url": "https://github.com/Hurishihara/req-inspect/issues"
+  },
+  "keywords": [
+    "req-inspect",
+    "request",
+    "inspector",
+    "debug",
+    "express",
+    "middleware"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}