@yetanotheraryan/coldstart 1.0.0

package/dist/register.js

@@ -0,0 +1,438 @@
+"use strict";
+
+// register.ts
+var import_fs = require("fs");
+var import_path = require("path");
+var import_url = require("url");
+var import_worker_threads = require("worker_threads");
+var import_node_module = require("module");
+
+// src/cjs.ts
+var import_module = require("module");
+
+// src/tracer.ts
+var import_perf_hooks = require("perf_hooks");
+var Tracer = class {
+  events = [];
+  startTime = performance.now();
+  histogram = null;
+  constructor() {
+    try {
+      this.histogram = (0, import_perf_hooks.monitorEventLoopDelay)({ resolution: 5 });
+      this.histogram.enable();
+    } catch {
+      this.histogram = null;
+    }
+  }
+  /**
+   * Called by cjs.ts for every require() interception.
+   * Appends to the flat event list — tree is built lazily on report().
+   */
+  record(event) {
+    this.events.push(event);
+  }
+  /**
+   * Mark startup as complete and return the full report.
+   * Call this after your server/app signals it's ready.
+   */
+  report() {
+    const totalStartupMs = performance.now() - this.startTime;
+    if (this.histogram) {
+      this.histogram.disable();
+    }
+    const tree = this.buildTree();
+    const flat = this.flatten(tree).sort((a, b) => b.inclusiveMs - a.inclusiveMs);
+    const slowest = [...flat].filter((n) => !n.cached && !n.isBuiltin).sort((a, b) => b.exclusiveMs - a.exclusiveMs).slice(0, 10);
+    const nodeModuleTime = flat.filter((n) => n.isNodeModule && !n.cached).reduce((sum, n) => sum + n.exclusiveMs, 0);
+    const firstPartyTime = flat.filter((n) => !n.isNodeModule && !n.isBuiltin && !n.cached).reduce((sum, n) => sum + n.exclusiveMs, 0);
+    return {
+      totalStartupMs,
+      eventLoop: {
+        maxBlockMs: this.histogram ? this.histogram.max / 1e6 : 0,
+        meanBlockMs: this.histogram ? this.histogram.mean / 1e6 : 0,
+        p99BlockMs: this.histogram ? this.histogram.percentile(99) / 1e6 : 0
+      },
+      tree,
+      flat,
+      slowest,
+      nodeModuleTime,
+      firstPartyTime,
+      totalModulesLoaded: this.events.length,
+      cachedModulesCount: this.events.filter((e) => e.cached).length
+    };
+  }
+  /**
+   * Build the parent→child tree from the flat event list.
+   *
+   * Strategy:
+   * 1. Create a ModuleNode for each event
+   * 2. Wire children to parents using parentPath
+   * 3. Compute exclusive time = inclusive - sum(children inclusive)
+   * 4. Assign depth via BFS from roots
+   */
+  buildTree() {
+    const nodes = this.events.map((e) => ({
+      id: e.id,
+      request: e.request,
+      resolvedPath: e.resolvedPath,
+      parentPath: e.parentPath,
+      inclusiveMs: e.durationMs,
+      exclusiveMs: e.durationMs,
+      // will be adjusted below
+      cached: e.cached,
+      isNodeModule: e.isNodeModule,
+      isBuiltin: e.isBuiltin,
+      children: [],
+      depth: 0
+    }));
+    const byPath = /* @__PURE__ */ new Map();
+    for (const node of nodes) {
+      const existing = byPath.get(node.resolvedPath) ?? [];
+      existing.push(node);
+      byPath.set(node.resolvedPath, existing);
+    }
+    const roots = [];
+    for (const node of nodes) {
+      if (node.parentPath === "<entry>") {
+        roots.push(node);
+        continue;
+      }
+      const parentNodes = byPath.get(node.parentPath);
+      if (parentNodes && parentNodes.length > 0) {
+        parentNodes[parentNodes.length - 1].children.push(node);
+      } else {
+        roots.push(node);
+      }
+    }
+    const computeExclusive = (node) => {
+      for (const child of node.children) {
+        computeExclusive(child);
+      }
+      const childrenInclusiveSum = node.children.reduce(
+        (sum, c) => sum + c.inclusiveMs,
+        0
+      );
+      node.exclusiveMs = Math.max(0, node.inclusiveMs - childrenInclusiveSum);
+    };
+    for (const root of roots) {
+      computeExclusive(root);
+    }
+    const assignDepth = (node, depth) => {
+      node.depth = depth;
+      for (const child of node.children) {
+        assignDepth(child, depth + 1);
+      }
+    };
+    for (const root of roots) {
+      assignDepth(root, 0);
+    }
+    return roots;
+  }
+  /**
+   * Flatten the tree into a list (pre-order DFS).
+   */
+  flatten(nodes) {
+    const result = [];
+    const visit = (node) => {
+      result.push(node);
+      for (const child of node.children) {
+        visit(child);
+      }
+    };
+    for (const node of nodes) {
+      visit(node);
+    }
+    return result;
+  }
+  /**
+   * Reset — useful for testing multiple startups in the same process.
+   */
+  reset() {
+    this.events = [];
+    this.startTime = performance.now();
+    if (this.histogram) {
+      this.histogram.reset();
+      this.histogram.enable();
+    }
+  }
+  /** Expose raw events for testing */
+  getRawEvents() {
+    return [...this.events];
+  }
+};
+var tracer = new Tracer();
+
+// src/cjs.ts
+var originalLoad = import_module.Module._load;
+var callStack = [];
+import_module.Module._load = function coldstartLoad(request, parent, isMain) {
+  let resolvedFilename;
+  try {
+    resolvedFilename = import_module.Module._resolveFilename(request, parent, isMain);
+  } catch {
+    return originalLoad.apply(this, arguments);
+  }
+  const isCached = !!import_module.Module._cache[resolvedFilename];
+  const isBuiltin = import_module.Module.isBuiltin?.(request) ?? isBuiltinModule(request);
+  const parentFilename = callStack.length > 0 ? callStack[callStack.length - 1] : parent?.filename ?? "<entry>";
+  callStack.push(resolvedFilename);
+  const startTime = performance.now();
+  let result;
+  try {
+    result = originalLoad.apply(this, arguments);
+  } finally {
+    callStack.pop();
+    if (!isBuiltin) {
+      const duration = performance.now() - startTime;
+      tracer.record({
+        id: resolvedFilename,
+        request,
+        // original string passed to require()
+        resolvedPath: resolvedFilename,
+        parentPath: parentFilename,
+        durationMs: duration,
+        startTime,
+        cached: isCached,
+        isNodeModule: resolvedFilename.includes("node_modules"),
+        isBuiltin: false
+      });
+    }
+  }
+  return result;
+};
+var originalResolveFilename = import_module.Module._resolveFilename;
+import_module.Module._resolveFilename = function coldstartResolve(request, parent, isMain, options) {
+  if (import_module.Module.isBuiltin?.(request) ?? isBuiltinModule(request)) {
+    const parentFilename = callStack.length > 0 ? callStack[callStack.length - 1] : parent?.filename ?? "<entry>";
+    tracer.record({
+      id: `builtin:${request}`,
+      request,
+      resolvedPath: `builtin:${request}`,
+      parentPath: parentFilename,
+      durationMs: 0,
+      startTime: performance.now(),
+      cached: true,
+      isNodeModule: false,
+      isBuiltin: true
+    });
+  }
+  return originalResolveFilename.apply(this, arguments);
+};
+function isBuiltinModule(name) {
+  const builtins = /* @__PURE__ */ new Set([
+    "assert",
+    "async_hooks",
+    "buffer",
+    "child_process",
+    "cluster",
+    "console",
+    "constants",
+    "crypto",
+    "dgram",
+    "diagnostics_channel",
+    "dns",
+    "domain",
+    "events",
+    "fs",
+    "http",
+    "http2",
+    "https",
+    "inspector",
+    "module",
+    "net",
+    "os",
+    "path",
+    "perf_hooks",
+    "process",
+    "punycode",
+    "querystring",
+    "readline",
+    "repl",
+    "stream",
+    "string_decoder",
+    "sys",
+    "timers",
+    "tls",
+    "trace_events",
+    "tty",
+    "url",
+    "util",
+    "v8",
+    "vm",
+    "wasi",
+    "worker_threads",
+    "zlib"
+  ]);
+  const stripped = name.startsWith("node:") ? name.slice(5) : name;
+  return builtins.has(stripped);
+}
+
+// register.ts
+var ESM_EXIT_SYMBOL = /* @__PURE__ */ Symbol.for("coldstart:esm:exit");
+var COLDSTART_REGISTERED = /* @__PURE__ */ Symbol.for("coldstart:registered");
+var COLDSTART_ESM_PORT = /* @__PURE__ */ Symbol.for("coldstart:esm:port");
+var reportFile = process.env.COLDSTART_REPORT_FILE;
+if (!globalThis[COLDSTART_REGISTERED]) {
+  ;
+  globalThis[COLDSTART_REGISTERED] = true;
+  setupEsmHooks();
+}
+if (reportFile) {
+  let flushed = false;
+  let beforeExitScheduled = false;
+  const flushReport = () => {
+    if (flushed) {
+      return;
+    }
+    flushed = true;
+    try {
+      (0, import_fs.mkdirSync)((0, import_path.dirname)(reportFile), { recursive: true });
+      (0, import_fs.writeFileSync)(reportFile, JSON.stringify(tracer.report(), jsonReplacer), "utf8");
+    } catch {
+    }
+    closeEsmPort();
+  };
+  process.once("beforeExit", () => {
+    if (beforeExitScheduled) {
+      return;
+    }
+    beforeExitScheduled = true;
+    setImmediate(flushReport);
+  });
+  process.once("exit", flushReport);
+  process.once("SIGINT", () => {
+    flushReport();
+    process.exit(130);
+  });
+  process.once("SIGTERM", () => {
+    flushReport();
+    process.exit(143);
+  });
+  process.once("uncaughtException", (error) => {
+    flushReport();
+    throw error;
+  });
+}
+function jsonReplacer(_key, value) {
+  if (typeof value === "number" && !Number.isFinite(value)) {
+    return 0;
+  }
+  return value;
+}
+function setupEsmHooks() {
+  if (typeof import_node_module.register !== "function") {
+    return;
+  }
+  const { port1, port2 } = new import_worker_threads.MessageChannel();
+  const pendingByUrl = /* @__PURE__ */ new Map();
+  const completedAtByUrl = /* @__PURE__ */ new Map();
+  const finalizedUrls = /* @__PURE__ */ new Set();
+  let closeTimer = null;
+  globalThis[COLDSTART_ESM_PORT] = port1;
+  port1.unref();
+  const schedulePortClose = () => {
+    if (closeTimer) {
+      clearTimeout(closeTimer);
+    }
+    closeTimer = setTimeout(() => {
+      closeTimer = null;
+      closeEsmPort();
+    }, 25);
+  };
+  if (!reportFile) {
+    process.once("beforeExit", () => {
+      setImmediate(closeEsmPort);
+    });
+  }
+  process.once("exit", closeEsmPort);
+  port1.on("message", (rawMessage) => {
+    schedulePortClose();
+    if (!isEsmResolveMessage(rawMessage)) {
+      return;
+    }
+    const event = {
+      id: rawMessage.isBuiltin ? `builtin:${rawMessage.request}` : rawMessage.resolvedPath,
+      request: rawMessage.request,
+      resolvedPath: rawMessage.resolvedPath,
+      parentPath: rawMessage.parentPath,
+      durationMs: 0,
+      startTime: rawMessage.startTime,
+      cached: rawMessage.isBuiltin,
+      isNodeModule: rawMessage.isNodeModule,
+      isBuiltin: rawMessage.isBuiltin
+    };
+    if (event.isBuiltin) {
+      tracer.record(event);
+      return;
+    }
+    const completedAt = completedAtByUrl.get(event.resolvedPath);
+    if (typeof completedAt === "number" && !finalizedUrls.has(event.resolvedPath)) {
+      tracer.record({
+        ...event,
+        durationMs: Math.max(0, completedAt - event.startTime),
+        cached: false
+      });
+      finalizedUrls.add(event.resolvedPath);
+      completedAtByUrl.delete(event.resolvedPath);
+      return;
+    }
+    if (finalizedUrls.has(event.resolvedPath)) {
+      tracer.record({
+        ...event,
+        startTime: performance.now(),
+        durationMs: 0,
+        cached: true
+      });
+      return;
+    }
+    const existing = pendingByUrl.get(event.resolvedPath) ?? [];
+    existing.push(event);
+    pendingByUrl.set(event.resolvedPath, existing);
+  });
+  globalThis[ESM_EXIT_SYMBOL] = (resolvedPath) => {
+    const endTime = performance.now();
+    const pending = pendingByUrl.get(resolvedPath);
+    schedulePortClose();
+    if (!pending || pending.length === 0) {
+      completedAtByUrl.set(resolvedPath, endTime);
+      return;
+    }
+    const [primary, ...rest] = pending;
+    tracer.record({
+      ...primary,
+      durationMs: Math.max(0, endTime - primary.startTime),
+      cached: false
+    });
+    for (const cachedEdge of rest) {
+      tracer.record({
+        ...cachedEdge,
+        startTime: endTime,
+        durationMs: 0,
+        cached: true
+      });
+    }
+    pendingByUrl.delete(resolvedPath);
+    completedAtByUrl.delete(resolvedPath);
+    finalizedUrls.add(resolvedPath);
+  };
+  try {
+    (0, import_node_module.register)("./esm-loader.mjs", {
+      parentURL: (0, import_url.pathToFileURL)(__filename),
+      data: { port: port2 },
+      transferList: [port2]
+    });
+    schedulePortClose();
+  } catch {
+  }
+}
+function closeEsmPort() {
+  const port = globalThis[COLDSTART_ESM_PORT];
+  try {
+    port?.close?.();
+  } catch {
+  }
+  delete globalThis[COLDSTART_ESM_PORT];
+}
+function isEsmResolveMessage(value) {
+  return typeof value === "object" && value !== null && value.type === "resolve";
+}

package/dist/register.mjs

@@ -0,0 +1,181 @@
+import {
+  tracer
+} from "./chunk-7HD2T2AD.mjs";
+import {
+  __filename
+} from "./chunk-B5TADGOF.mjs";
+
+// register.ts
+import { mkdirSync, writeFileSync } from "fs";
+import { dirname } from "path";
+import { pathToFileURL } from "url";
+import { MessageChannel } from "worker_threads";
+import { register as registerHooks } from "module";
+var ESM_EXIT_SYMBOL = /* @__PURE__ */ Symbol.for("coldstart:esm:exit");
+var COLDSTART_REGISTERED = /* @__PURE__ */ Symbol.for("coldstart:registered");
+var COLDSTART_ESM_PORT = /* @__PURE__ */ Symbol.for("coldstart:esm:port");
+var reportFile = process.env.COLDSTART_REPORT_FILE;
+if (!globalThis[COLDSTART_REGISTERED]) {
+  ;
+  globalThis[COLDSTART_REGISTERED] = true;
+  setupEsmHooks();
+}
+if (reportFile) {
+  let flushed = false;
+  let beforeExitScheduled = false;
+  const flushReport = () => {
+    if (flushed) {
+      return;
+    }
+    flushed = true;
+    try {
+      mkdirSync(dirname(reportFile), { recursive: true });
+      writeFileSync(reportFile, JSON.stringify(tracer.report(), jsonReplacer), "utf8");
+    } catch {
+    }
+    closeEsmPort();
+  };
+  process.once("beforeExit", () => {
+    if (beforeExitScheduled) {
+      return;
+    }
+    beforeExitScheduled = true;
+    setImmediate(flushReport);
+  });
+  process.once("exit", flushReport);
+  process.once("SIGINT", () => {
+    flushReport();
+    process.exit(130);
+  });
+  process.once("SIGTERM", () => {
+    flushReport();
+    process.exit(143);
+  });
+  process.once("uncaughtException", (error) => {
+    flushReport();
+    throw error;
+  });
+}
+function jsonReplacer(_key, value) {
+  if (typeof value === "number" && !Number.isFinite(value)) {
+    return 0;
+  }
+  return value;
+}
+function setupEsmHooks() {
+  if (typeof registerHooks !== "function") {
+    return;
+  }
+  const { port1, port2 } = new MessageChannel();
+  const pendingByUrl = /* @__PURE__ */ new Map();
+  const completedAtByUrl = /* @__PURE__ */ new Map();
+  const finalizedUrls = /* @__PURE__ */ new Set();
+  let closeTimer = null;
+  globalThis[COLDSTART_ESM_PORT] = port1;
+  port1.unref();
+  const schedulePortClose = () => {
+    if (closeTimer) {
+      clearTimeout(closeTimer);
+    }
+    closeTimer = setTimeout(() => {
+      closeTimer = null;
+      closeEsmPort();
+    }, 25);
+  };
+  if (!reportFile) {
+    process.once("beforeExit", () => {
+      setImmediate(closeEsmPort);
+    });
+  }
+  process.once("exit", closeEsmPort);
+  port1.on("message", (rawMessage) => {
+    schedulePortClose();
+    if (!isEsmResolveMessage(rawMessage)) {
+      return;
+    }
+    const event = {
+      id: rawMessage.isBuiltin ? `builtin:${rawMessage.request}` : rawMessage.resolvedPath,
+      request: rawMessage.request,
+      resolvedPath: rawMessage.resolvedPath,
+      parentPath: rawMessage.parentPath,
+      durationMs: 0,
+      startTime: rawMessage.startTime,
+      cached: rawMessage.isBuiltin,
+      isNodeModule: rawMessage.isNodeModule,
+      isBuiltin: rawMessage.isBuiltin
+    };
+    if (event.isBuiltin) {
+      tracer.record(event);
+      return;
+    }
+    const completedAt = completedAtByUrl.get(event.resolvedPath);
+    if (typeof completedAt === "number" && !finalizedUrls.has(event.resolvedPath)) {
+      tracer.record({
+        ...event,
+        durationMs: Math.max(0, completedAt - event.startTime),
+        cached: false
+      });
+      finalizedUrls.add(event.resolvedPath);
+      completedAtByUrl.delete(event.resolvedPath);
+      return;
+    }
+    if (finalizedUrls.has(event.resolvedPath)) {
+      tracer.record({
+        ...event,
+        startTime: performance.now(),
+        durationMs: 0,
+        cached: true
+      });
+      return;
+    }
+    const existing = pendingByUrl.get(event.resolvedPath) ?? [];
+    existing.push(event);
+    pendingByUrl.set(event.resolvedPath, existing);
+  });
+  globalThis[ESM_EXIT_SYMBOL] = (resolvedPath) => {
+    const endTime = performance.now();
+    const pending = pendingByUrl.get(resolvedPath);
+    schedulePortClose();
+    if (!pending || pending.length === 0) {
+      completedAtByUrl.set(resolvedPath, endTime);
+      return;
+    }
+    const [primary, ...rest] = pending;
+    tracer.record({
+      ...primary,
+      durationMs: Math.max(0, endTime - primary.startTime),
+      cached: false
+    });
+    for (const cachedEdge of rest) {
+      tracer.record({
+        ...cachedEdge,
+        startTime: endTime,
+        durationMs: 0,
+        cached: true
+      });
+    }
+    pendingByUrl.delete(resolvedPath);
+    completedAtByUrl.delete(resolvedPath);
+    finalizedUrls.add(resolvedPath);
+  };
+  try {
+    registerHooks("./esm-loader.mjs", {
+      parentURL: pathToFileURL(__filename),
+      data: { port: port2 },
+      transferList: [port2]
+    });
+    schedulePortClose();
+  } catch {
+  }
+}
+function closeEsmPort() {
+  const port = globalThis[COLDSTART_ESM_PORT];
+  try {
+    port?.close?.();
+  } catch {
+  }
+  delete globalThis[COLDSTART_ESM_PORT];
+}
+function isEsmResolveMessage(value) {
+  return typeof value === "object" && value !== null && value.type === "resolve";
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@yetanotheraryan/coldstart",
+  "version": "1.0.0",
+  "description": "Profile Node.js startup by timing every require() and reporting slow modules.",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.js"
+    },
+    "./register": {
+      "types": "./dist/register.d.ts",
+      "require": "./dist/register.js",
+      "import": "./dist/register.mjs",
+      "default": "./dist/register.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "coldstart": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "readme.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "nodejs",
+    "startup",
+    "profiling",
+    "performance",
+    "require",
+    "commonjs",
+    "tracing",
+    "cli"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yetanotheraryan/coldstart.git"
+  },
+  "author": "Aryan Tiwari",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/yetanotheraryan/coldstart/issues"
+  },
+  "homepage": "https://github.com/yetanotheraryan/coldstart#readme",
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  }
+}