perfstack 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+- Initial public release.

package/LICENSE

@@ -0,0 +1,15 @@
+MIT License
+
+Copyright (c) 2026 Aftab Ahmad Khan
+
+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.

package/README.md

@@ -0,0 +1,120 @@
+# perfstack
+
+**Topics:** `dashboard` · `express` · `memory` · `mern-packages` · `merndev` · `mongodb` · `nodejs` · `npm-pm` · `observability` · `performance` · `perfstack` · `profiling` · `tracing` · `typescript`
+
+Lightweight fullstack performance profiler for Node.js. One package gives you HTTP latency histograms, slow-query tracking (Mongoose), memory snapshots, async-context tracing, and a built-in dashboard endpoint — no agents, no SaaS, no dependencies.
+
+## Install
+
+```bash
+npm install perfstack
+```
+
+## One-call setup
+
+```ts
+import express from "express";
+import { init } from "perfstack";
+
+const app = express();
+const { profiler, mongoosePlugin } = init(app, {
+  slowRequestThreshold: 500,
+  slowQueryThreshold: 200,
+  enableMemorySampling: true,
+  dashboardPath: "/__perf",
+});
+
+// Optional: track every Mongoose query
+import mongoose from "mongoose";
+mongoose.plugin(mongoosePlugin);
+
+app.get("/", (_req, res) => res.json({ hi: true }));
+app.listen(3000);
+```
+
+Now open:
+
+- `http://localhost:3000/__perf` — minimal HTML dashboard
+- `http://localhost:3000/__perf.json` — full report as JSON
+
+## What you get
+
+```jsonc
+{
+  "uptimeMs": 124562,
+  "totalRequests": 1820,
+  "totalErrors": 3,
+  "totalQueries": 4001,
+  "http": { "count": 1820, "avg": 41.2, "p50": 18, "p95": 220, "p99": 612, "max": 1820 },
+  "routes": [
+    { "method": "GET", "path": "/users/:id", "count": 720, "p95": 188, "errorCount": 0 },
+    ...
+  ],
+  "slowestRoutes": [ /* sorted by p95 */ ],
+  "queries": { "count": 4001, "p95": 30, "p99": 102 },
+  "slowestQueries": [ { "collection": "users", "op": "find", "durationMs": 612 } ],
+  "memory": { "current": { "rss": 134217728, "heapUsed": 41943040 }, "peakRss": 156000000 }
+}
+```
+
+## Pieces
+
+```ts
+import {
+  Profiler,
+  expressMiddleware,
+  dashboardMiddleware,
+  mongoosePlugin,
+  Histogram,
+  Tracer,
+} from "perfstack";
+
+const profiler = new Profiler({ slowRequestThreshold: 300 });
+
+app.use(expressMiddleware(profiler));
+app.get("/__perf", dashboardMiddleware(profiler));
+app.get("/__perf.json", dashboardMiddleware(profiler));
+mongoose.plugin(mongoosePlugin(profiler));
+```
+
+### Custom spans
+
+```ts
+await profiler.tracer.withSpan("send-email", async () => {
+  await mailer.send(...);
+});
+
+const span = profiler.tracer.start("billing.charge", "external");
+try {
+  await stripe.charge(...);
+  span.end({ status: "ok" });
+} catch (err) {
+  span.end({ error: err });
+}
+```
+
+Spans inherit the request trace id automatically (`AsyncLocalStorage`).
+
+### Memory sampling
+
+```ts
+const profiler = new Profiler({
+  enableMemorySampling: true,
+  memorySampleIntervalMs: 5_000,
+  memorySamplesMax: 120, // last 10 minutes at 5s intervals
+});
+```
+
+Disable any time with `profiler.stopMemorySampling()`.
+
+### Histogram percentiles
+
+`perfstack` keeps a rolling window of the last 1000 samples per metric and computes `min/avg/p50/p90/p95/p99/max` on demand.
+
+## Why not Datadog / New Relic / Sentry?
+
+You may still want them. `perfstack` is the *first* thing you reach for — when you want zero-config insight in dev, in tests, or in a small prod app. It runs in the same process, no auth, no UI to log into, no $$/month.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,491 @@
+"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 src_exports = {};
+__export(src_exports, {
+  Histogram: () => Histogram,
+  Profiler: () => Profiler,
+  Tracer: () => Tracer,
+  dashboardMiddleware: () => dashboardMiddleware,
+  expressMiddleware: () => expressMiddleware,
+  init: () => init,
+  mongoosePlugin: () => mongoosePlugin,
+  percentile: () => percentile
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/histogram.ts
+var Histogram = class {
+  samples = [];
+  max;
+  constructor(max = 1e3) {
+    this.max = max;
+  }
+  record(value) {
+    this.samples.push(value);
+    if (this.samples.length > this.max) {
+      this.samples.shift();
+    }
+  }
+  summary() {
+    const count = this.samples.length;
+    if (count === 0) {
+      return { count: 0, min: 0, max: 0, avg: 0, p50: 0, p90: 0, p95: 0, p99: 0 };
+    }
+    const sorted = [...this.samples].sort((a, b) => a - b);
+    const sum = sorted.reduce((s, v) => s + v, 0);
+    return {
+      count,
+      min: sorted[0],
+      max: sorted[sorted.length - 1],
+      avg: round(sum / count),
+      p50: percentile(sorted, 0.5),
+      p90: percentile(sorted, 0.9),
+      p95: percentile(sorted, 0.95),
+      p99: percentile(sorted, 0.99)
+    };
+  }
+  reset() {
+    this.samples = [];
+  }
+};
+function percentile(sortedAscending, p) {
+  if (sortedAscending.length === 0) return 0;
+  const idx = Math.min(sortedAscending.length - 1, Math.floor(p * sortedAscending.length));
+  return round(sortedAscending[idx]);
+}
+function round(n) {
+  return Math.round(n * 100) / 100;
+}
+
+// src/tracer.ts
+var import_node_async_hooks = require("async_hooks");
+var import_node_crypto = require("crypto");
+var Tracer = class {
+  storage = new import_node_async_hooks.AsyncLocalStorage();
+  spans = [];
+  max;
+  constructor(options = {}) {
+    this.max = options.maxSpans ?? 500;
+  }
+  start(name, kind = "custom", metadata = {}) {
+    const startedAt = Date.now();
+    const id = `s_${(0, import_node_crypto.randomBytes)(6).toString("hex")}`;
+    const parent = this.storage.getStore();
+    const traceId = parent?.traceId ?? `t_${(0, import_node_crypto.randomBytes)(8).toString("hex")}`;
+    const parentId = parent?.spanId;
+    return {
+      end: (info = {}) => {
+        const status = info.error ? "error" : info.status ?? "ok";
+        const errorMsg = info.error instanceof Error ? info.error.message : info.error ? String(info.error) : void 0;
+        const span = {
+          id,
+          parentId,
+          traceId,
+          name,
+          kind,
+          startedAt,
+          durationMs: Date.now() - startedAt,
+          metadata: { ...metadata, ...info.extra ?? {} },
+          status,
+          error: errorMsg
+        };
+        this.push(span);
+        return span;
+      }
+    };
+  }
+  async withSpan(name, fn, options = {}) {
+    const startedAt = Date.now();
+    const parent = this.storage.getStore();
+    const traceId = parent?.traceId ?? `t_${(0, import_node_crypto.randomBytes)(8).toString("hex")}`;
+    const spanId = `s_${(0, import_node_crypto.randomBytes)(6).toString("hex")}`;
+    return this.storage.run({ traceId, spanId }, async () => {
+      try {
+        const result = await fn();
+        this.push({
+          id: spanId,
+          parentId: parent?.spanId,
+          traceId,
+          name,
+          kind: options.kind ?? "custom",
+          startedAt,
+          durationMs: Date.now() - startedAt,
+          metadata: options.metadata ?? {},
+          status: "ok"
+        });
+        return result;
+      } catch (err) {
+        this.push({
+          id: spanId,
+          parentId: parent?.spanId,
+          traceId,
+          name,
+          kind: options.kind ?? "custom",
+          startedAt,
+          durationMs: Date.now() - startedAt,
+          metadata: options.metadata ?? {},
+          status: "error",
+          error: err instanceof Error ? err.message : String(err)
+        });
+        throw err;
+      }
+    });
+  }
+  runInContext(traceId, fn) {
+    const spanId = `s_${(0, import_node_crypto.randomBytes)(6).toString("hex")}`;
+    return this.storage.run({ traceId, spanId }, fn);
+  }
+  currentTraceId() {
+    return this.storage.getStore()?.traceId;
+  }
+  recent(limit = 100) {
+    return this.spans.slice(-limit);
+  }
+  byTrace(traceId) {
+    return this.spans.filter((s) => s.traceId === traceId);
+  }
+  reset() {
+    this.spans = [];
+  }
+  push(span) {
+    this.spans.push(span);
+    if (this.spans.length > this.max) this.spans.shift();
+  }
+};
+
+// src/profiler.ts
+var Profiler = class {
+  startedAt;
+  httpHistogram = new Histogram();
+  queryHistogram = new Histogram();
+  routes = /* @__PURE__ */ new Map();
+  slowestQueries = [];
+  memorySamples = [];
+  peakRss = 0;
+  peakHeapUsed = 0;
+  totalRequests = 0;
+  totalErrors = 0;
+  totalQueries = 0;
+  memoryInterval;
+  tracer;
+  opts;
+  constructor(options = {}) {
+    this.startedAt = options.startedAt ?? Date.now();
+    this.opts = {
+      slowRequestThreshold: options.slowRequestThreshold ?? 500,
+      slowQueryThreshold: options.slowQueryThreshold ?? 200,
+      memorySampleIntervalMs: options.memorySampleIntervalMs ?? 5e3,
+      memorySamplesMax: options.memorySamplesMax ?? 120,
+      routeBucketsMax: options.routeBucketsMax ?? 200,
+      enableMemorySampling: options.enableMemorySampling ?? false
+    };
+    this.tracer = new Tracer();
+    if (this.opts.enableMemorySampling) this.startMemorySampling();
+  }
+  recordHttp(record) {
+    this.totalRequests += 1;
+    if (record.statusCode >= 500) this.totalErrors += 1;
+    this.httpHistogram.record(record.durationMs);
+    const key = `${record.method} ${record.path}`;
+    let bucket = this.routes.get(key);
+    if (!bucket) {
+      if (this.routes.size >= this.opts.routeBucketsMax) {
+        const oldest = this.routes.keys().next().value;
+        if (oldest !== void 0) this.routes.delete(oldest);
+      }
+      bucket = { method: record.method, path: record.path, histogram: new Histogram(), errors: 0 };
+      this.routes.set(key, bucket);
+    }
+    bucket.histogram.record(record.durationMs);
+    if (record.statusCode >= 500) bucket.errors += 1;
+  }
+  recordQuery(record) {
+    this.totalQueries += 1;
+    this.queryHistogram.record(record.durationMs);
+    if (record.durationMs >= this.opts.slowQueryThreshold) {
+      this.slowestQueries.push(record);
+      this.slowestQueries.sort((a, b) => b.durationMs - a.durationMs);
+      if (this.slowestQueries.length > 50) this.slowestQueries.length = 50;
+    }
+  }
+  takeMemorySample() {
+    const m = process.memoryUsage();
+    const snap = {
+      takenAt: Date.now(),
+      rss: m.rss,
+      heapTotal: m.heapTotal,
+      heapUsed: m.heapUsed,
+      external: m.external,
+      arrayBuffers: m.arrayBuffers
+    };
+    this.memorySamples.push(snap);
+    if (this.memorySamples.length > this.opts.memorySamplesMax) this.memorySamples.shift();
+    if (snap.rss > this.peakRss) this.peakRss = snap.rss;
+    if (snap.heapUsed > this.peakHeapUsed) this.peakHeapUsed = snap.heapUsed;
+    return snap;
+  }
+  startMemorySampling() {
+    if (this.memoryInterval) return;
+    this.takeMemorySample();
+    const interval = setInterval(() => this.takeMemorySample(), this.opts.memorySampleIntervalMs);
+    interval.unref?.();
+    this.memoryInterval = interval;
+  }
+  stopMemorySampling() {
+    if (this.memoryInterval) {
+      clearInterval(this.memoryInterval);
+      this.memoryInterval = void 0;
+    }
+  }
+  report() {
+    if (this.memorySamples.length === 0) this.takeMemorySample();
+    const routes = Array.from(this.routes.values()).map((bucket) => ({
+      method: bucket.method,
+      path: bucket.path,
+      errorCount: bucket.errors,
+      ...bucket.histogram.summary()
+    }));
+    const slowestRoutes = [...routes].sort((a, b) => b.p95 - a.p95).slice(0, 10);
+    return {
+      uptimeMs: Date.now() - this.startedAt,
+      startedAt: this.startedAt,
+      takenAt: Date.now(),
+      totalRequests: this.totalRequests,
+      totalErrors: this.totalErrors,
+      totalQueries: this.totalQueries,
+      http: this.httpHistogram.summary(),
+      routes,
+      slowestRoutes,
+      queries: this.queryHistogram.summary(),
+      slowestQueries: [...this.slowestQueries],
+      memory: {
+        current: this.memorySamples.at(-1) ?? null,
+        samples: [...this.memorySamples],
+        peakRss: this.peakRss,
+        peakHeapUsed: this.peakHeapUsed
+      }
+    };
+  }
+  reset() {
+    this.httpHistogram.reset();
+    this.queryHistogram.reset();
+    this.routes.clear();
+    this.slowestQueries = [];
+    this.memorySamples = [];
+    this.peakRss = 0;
+    this.peakHeapUsed = 0;
+    this.totalRequests = 0;
+    this.totalErrors = 0;
+    this.totalQueries = 0;
+    this.tracer.reset();
+  }
+  isSlowRequest(durationMs) {
+    return durationMs >= this.opts.slowRequestThreshold;
+  }
+};
+
+// src/express.ts
+var import_node_crypto2 = require("crypto");
+function expressMiddleware(profiler, options = {}) {
+  const { ignorePaths = [], traceHeader = "x-trace-id", exposeTraceHeader = true } = options;
+  return function perfstackMiddleware(req, res, next) {
+    const path = req.originalUrl ?? req.url ?? "/";
+    if (ignorePaths.some((p) => path === p || path.startsWith(`${p}/`))) {
+      next();
+      return;
+    }
+    const traceHeaderVal = req.headers[traceHeader.toLowerCase()];
+    const traceId = typeof traceHeaderVal === "string" && traceHeaderVal || Array.isArray(traceHeaderVal) && traceHeaderVal[0] || `req_${(0, import_node_crypto2.randomBytes)(8).toString("hex")}`;
+    if (exposeTraceHeader) res.setHeader(traceHeader, traceId);
+    const startedAt = Date.now();
+    profiler.tracer.runInContext(traceId, () => {
+      res.on("finish", () => {
+        profiler.recordHttp({
+          method: req.method ?? "GET",
+          path: req.route?.path ?? simplifyPath(path),
+          statusCode: res.statusCode,
+          durationMs: Date.now() - startedAt,
+          startedAt,
+          traceId
+        });
+      });
+      next();
+    });
+  };
+}
+function dashboardMiddleware(profiler) {
+  return function perfstackDashboard(req, res) {
+    const path = req.originalUrl ?? req.url ?? "/";
+    if (path.endsWith(".json")) {
+      res.setHeader("content-type", "application/json");
+      res.statusCode = 200;
+      res.end(JSON.stringify(profiler.report(), null, 2));
+      return;
+    }
+    res.setHeader("content-type", "text/html; charset=utf-8");
+    res.statusCode = 200;
+    res.end(renderDashboard(profiler));
+  };
+}
+function simplifyPath(p) {
+  return p.split("?")[0].replace(/\/[0-9a-f]{24}\b/gi, "/:id").replace(/\/\d+\b/g, "/:id");
+}
+function renderDashboard(profiler) {
+  const report = profiler.report();
+  return `<!doctype html>
+<html><head><meta charset="utf-8" />
+<title>perfstack</title>
+<style>
+body{font:14px/1.4 ui-monospace,Menlo,monospace;background:#0b1020;color:#e6e6e6;margin:0;padding:24px}
+h1,h2{font-weight:600;margin:0 0 12px}h2{margin-top:24px}
+table{border-collapse:collapse;width:100%;margin-top:8px}
+th,td{padding:6px 10px;text-align:left;border-bottom:1px solid #1d2440}
+th{color:#8aa6ff;font-weight:600}
+.bad{color:#ff8a8a}.good{color:#8aff9c}
+.card{background:#121838;border-radius:8px;padding:16px;margin-bottom:16px}
+.grid{display:grid;grid-template-columns:repeat(4,1fr);gap:16px}
+.k{color:#8a93b3}.v{font-size:20px;font-weight:600}
+</style></head>
+<body>
+<h1>perfstack</h1>
+<div class="grid">
+  <div class="card"><div class="k">uptime</div><div class="v">${Math.round(report.uptimeMs / 1e3)}s</div></div>
+  <div class="card"><div class="k">requests</div><div class="v">${report.totalRequests}</div></div>
+  <div class="card"><div class="k">errors</div><div class="v ${report.totalErrors ? "bad" : "good"}">${report.totalErrors}</div></div>
+  <div class="card"><div class="k">queries</div><div class="v">${report.totalQueries}</div></div>
+</div>
+
+<h2>HTTP latency (ms)</h2>
+<table><tr><th>count</th><th>min</th><th>avg</th><th>p50</th><th>p90</th><th>p95</th><th>p99</th><th>max</th></tr>
+<tr><td>${report.http.count}</td><td>${report.http.min}</td><td>${report.http.avg}</td><td>${report.http.p50}</td><td>${report.http.p90}</td><td>${report.http.p95}</td><td>${report.http.p99}</td><td>${report.http.max}</td></tr>
+</table>
+
+<h2>Slowest routes (p95)</h2>
+<table><tr><th>route</th><th>count</th><th>p95</th><th>p99</th><th>max</th><th>errors</th></tr>
+${report.slowestRoutes.map((r) => `<tr><td>${escapeHtml(r.method)} ${escapeHtml(r.path)}</td><td>${r.count}</td><td>${r.p95}</td><td>${r.p99}</td><td>${r.max}</td><td>${r.errorCount}</td></tr>`).join("\n")}
+</table>
+
+<h2>Slowest queries</h2>
+<table><tr><th>collection</th><th>op</th><th>duration</th></tr>
+${report.slowestQueries.map((q) => `<tr><td>${escapeHtml(q.collection)}</td><td>${escapeHtml(q.op)}</td><td>${q.durationMs}ms</td></tr>`).join("\n")}
+</table>
+
+<h2>Memory</h2>
+<table><tr><th>rss</th><th>heap used</th><th>heap total</th><th>peak rss</th><th>peak heap</th></tr>
+<tr>
+  <td>${fmtBytes(report.memory.current?.rss ?? 0)}</td>
+  <td>${fmtBytes(report.memory.current?.heapUsed ?? 0)}</td>
+  <td>${fmtBytes(report.memory.current?.heapTotal ?? 0)}</td>
+  <td>${fmtBytes(report.memory.peakRss)}</td>
+  <td>${fmtBytes(report.memory.peakHeapUsed)}</td>
+</tr>
+</table>
+
+</body></html>`;
+}
+function fmtBytes(n) {
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  if (n < 1024 * 1024 * 1024) return `${(n / 1024 / 1024).toFixed(1)} MB`;
+  return `${(n / 1024 / 1024 / 1024).toFixed(2)} GB`;
+}
+function escapeHtml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
+// src/mongoose.ts
+var HOOKS = [
+  "find",
+  "findOne",
+  "findOneAndUpdate",
+  "findOneAndDelete",
+  "count",
+  "countDocuments",
+  "updateOne",
+  "updateMany",
+  "deleteOne",
+  "deleteMany",
+  "distinct"
+];
+function mongoosePlugin(profiler) {
+  return function perfstackMongoose(schema) {
+    for (const hook of HOOKS) {
+      schema.pre(hook, function() {
+        this._perfstackStart = Date.now();
+        this._perfstackOp = hook;
+        this._perfstackCollection = this.model?.collection?.name ?? this.model?.modelName ?? "unknown";
+      });
+      schema.post(hook, function() {
+        const startedAt = this._perfstackStart ?? Date.now();
+        profiler.recordQuery({
+          collection: this._perfstackCollection ?? "unknown",
+          op: this._perfstackOp ?? hook,
+          durationMs: Date.now() - startedAt,
+          startedAt,
+          traceId: profiler.tracer.currentTraceId()
+        });
+      });
+    }
+    schema.pre("aggregate", function() {
+      this._perfstackStart = Date.now();
+      const model = typeof this.model === "function" ? this.model() : void 0;
+      this._perfstackCollection = model?.collection?.name ?? model?.modelName ?? "unknown";
+    });
+    schema.post("aggregate", function() {
+      const startedAt = this._perfstackStart ?? Date.now();
+      profiler.recordQuery({
+        collection: this._perfstackCollection ?? "unknown",
+        op: "aggregate",
+        durationMs: Date.now() - startedAt,
+        startedAt,
+        traceId: profiler.tracer.currentTraceId()
+      });
+    });
+  };
+}
+
+// src/index.ts
+function init(app, options = {}) {
+  const profiler = new Profiler(options);
+  const middleware = expressMiddleware(profiler);
+  const dashboard = dashboardMiddleware(profiler);
+  const plugin = mongoosePlugin(profiler);
+  if (app) {
+    app.use(middleware);
+    if (typeof app.get === "function") {
+      app.get(options.dashboardPath ?? "/__perf", dashboard);
+      app.get((options.dashboardPath ?? "/__perf") + ".json", dashboard);
+    }
+  }
+  return { profiler, middleware, dashboard, mongoosePlugin: plugin };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Histogram,
+  Profiler,
+  Tracer,
+  dashboardMiddleware,
+  expressMiddleware,
+  init,
+  mongoosePlugin,
+  percentile
+});
+//# sourceMappingURL=index.cjs.map