peekinside 0.0.0-stage → 1.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Steycode
+
+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,46 @@
-# Temporary Holding Version
+# PeekInside
 
-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.
+Debug Node.js from the inside: every error with the request that set it off, the queries and calls it made, what it logged and your code around the line that threw. A free dashboard on your computer while you develop, and encrypted monitoring for your servers.
+
+[![npm](https://img.shields.io/npm/v/peekinside?color=18b69b)](https://www.npmjs.com/package/peekinside)
+![License](https://img.shields.io/badge/license-MIT-18b69b)
+![Node](https://img.shields.io/badge/node-%3E%3D18-18b69b)
+
+## Install
+
+```bash
+npm install peekinside
+```
+
+```javascript
+import express from 'express';
+import PeekInside from 'peekinside';
+
+const app = express();
+PeekInside.attach(app);
+```
+
+Start your app, and PeekInside prints the link to its dashboard. It works with Express, Koa, Fastify and the native http module.
+
+Check the setup before anything breaks on its own: `npx peekinside test` sends a test error from your project.
+
+Also recorded: background jobs (node-cron, cron, BullMQ, or `PeekInside.job()`, with an email when a scheduled job misses its run), log lines from the console, pino and winston, event-loop blocks and memory, the deploy each error came from, the user it happened to (`PeekInside.setUser()`), and TypeScript lines through your source maps.
+
+## Documentation
+
+Everything else is in the docs: **[peekinside.dev/docs](https://peekinside.dev/docs)**
+
+- [Quick start](https://peekinside.dev/docs/quick-start)
+- [Local dashboard](https://peekinside.dev/docs/local-dashboard)
+- [PeekInside Cloud](https://peekinside.dev/docs/cloud)
+- [Exceptions](https://peekinside.dev/docs/exceptions)
+- [Timeline and queries](https://peekinside.dev/docs/timeline)
+- [Logs](https://peekinside.dev/docs/logs)
+- [Jobs and schedules](https://peekinside.dev/docs/jobs)
+- [Runtime](https://peekinside.dev/docs/runtime)
+- [Configuration](https://peekinside.dev/docs/configuration)
+- [API](https://peekinside.dev/docs/api)
+
+## License
+
+MIT

package/bin/peekinside.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * peekinside: manage the free local dashboard. See src/cli.js for the commands.
+ */
+
+import { Cli } from '../src/cli.js';
+
+new Cli().run(process.argv.slice(2));

package/index.d.ts

@@ -0,0 +1,389 @@
+/**
+ * Type definitions for PeekInside: records every request and response your Node.js app handles,
+ * and the exceptions that happen while handling them. In development they go to the free local
+ * dashboard; with an API key they are encrypted and sent to PeekInside Cloud.
+ *
+ * The signatures are structural, so Express, Connect, Koa, Fastify and node:http objects fit
+ * without PeekInside depending on any of those packages.
+ */
+
+import type { IncomingMessage, Server, ServerResponse } from "node:http";
+
+/**
+ * A path that is never recorded: a prefix such as `"/health"`, a regular expression, or a
+ * function that receives the pathname and returns `true` to skip it.
+ */
+export type IgnorePath = string | RegExp | ((pathname: string) => boolean);
+
+export interface PeekInsideOptions {
+  /**
+   * Maximum bytes captured per request or response body. Longer bodies are truncated and
+   * marked as such in the dashboard.
+   * @default 65536
+   */
+  maxBodySize?: number;
+
+  /** Paths that are never recorded. */
+  ignorePaths?: IgnorePath | IgnorePath[];
+
+  /**
+   * Name of this app in the local dashboard.
+   * @default process.env.PEEKINSIDE_PROJECT, then the name in package.json
+   */
+  project?: string;
+
+  /**
+   * Turns the free local dashboard on or off. By default it is on, except when NODE_ENV is
+   * "production" or "test", or in CI. Requests that reach the app as a deployed server are
+   * never recorded locally either way: servers need PeekInside Cloud.
+   */
+  local?: boolean;
+
+  /**
+   * PeekInside Cloud API key. When set, requests are encrypted and sent to
+   * PeekInside Cloud instead of the local dashboard.
+   * @default process.env.PEEKINSIDE_API_KEY
+   */
+  apiKey?: string;
+
+  /**
+   * Environment label shown with each request, such as `"staging"`.
+   * @default process.env.PEEKINSIDE_ENV, then process.env.NODE_ENV
+   */
+  environment?: string;
+
+  /**
+   * The deploy that is running, such as `"v2.4.0"` or a commit hash. Stored with every request
+   * and exception, so the dashboard shows the deploy an issue first happened in.
+   * @default process.env.PEEKINSIDE_RELEASE, then the commit your host deployed (Vercel, Render,
+   *   Railway, Heroku, Netlify, Fly.io...), then the commit checked out in the project folder
+   */
+  release?: string;
+
+  /**
+   * The project's folder: its name, git commit and source files are read from there.
+   * @default the folder of the package.json nearest to the app's entry file
+   */
+  projectRoot?: string;
+
+  /**
+   * Records exceptions automatically: errors that reach Express, Koa or Fastify error handling,
+   * uncaught exceptions and unhandled rejections. `report()` works either way.
+   * @default true
+   */
+  captureExceptions?: boolean;
+
+  /**
+   * Includes the source lines around your own code's stack frames in exception records.
+   * @default true
+   */
+  sourceContext?: boolean;
+
+  /**
+   * Maps stack frames of compiled code (TypeScript output, bundles) back to your source files,
+   * with the source maps your build writes (a `.map` file, or inline). Frames keep where they ran
+   * in `generated`.
+   * @default true
+   */
+  sourceMaps?: boolean;
+
+  /**
+   * Records a timeline for each request: its database queries, outgoing HTTP calls, console
+   * lines and exceptions, with counters (queries, slow queries, N+1 statements...) for the
+   * request list. `false` turns the whole timeline off.
+   * @default true
+   */
+  timeline?: boolean;
+
+  /**
+   * Records database queries: pg, mysql2, MongoDB (and Mongoose), Prisma. ORMs and query
+   * builders running on them (Knex, Sequelize, TypeORM, Drizzle, Kysely) are covered too.
+   * @default true
+   */
+  captureQueries?: boolean;
+
+  /**
+   * Records outgoing HTTP calls: node:http/https requests (and clients built on them) and fetch.
+   * @default true
+   */
+  captureOutgoing?: boolean;
+
+  /**
+   * Records log lines from the console, pino and winston: on the timeline of the request (or job
+   * run) they are written in, and on the Logs page, from anywhere in the app.
+   * @default true
+   */
+  captureLogs?: boolean;
+
+  /**
+   * The lowest level the Logs page records. Request timelines keep every level.
+   * @default "info"
+   */
+  logLevel?: "debug" | "info" | "warn" | "error";
+
+  /**
+   * Records runs of node-cron, cron and BullMQ jobs automatically (see `job()` for other jobs).
+   * @default true
+   */
+  captureJobs?: boolean;
+
+  /**
+   * Keeps the values sent with queries, masked (passwords, tokens and secret-looking values
+   * never leave the process).
+   * @default true
+   */
+  queryParams?: boolean;
+
+  /**
+   * Queries that take this many milliseconds or longer are flagged as slow.
+   * @default 100
+   */
+  slowQueryMs?: number;
+
+  /**
+   * A statement run this many times in one request is flagged as an N+1.
+   * @default 5
+   */
+  nPlusOneThreshold?: number;
+
+  /**
+   * Event-loop blocks this long or longer (synchronous work: a large JSON.parse, a slow regular
+   * expression, a sync file read) are recorded on the timelines of the requests that waited for
+   * them. `false` turns detection off.
+   * @default 100
+   */
+  loopBlockMs?: number | false;
+
+  /**
+   * Samples the process's memory, CPU and event-loop delay for the Runtime page: every 10 seconds
+   * for the local dashboard, every minute for PeekInside Cloud.
+   * @default true
+   */
+  runtime?: boolean;
+}
+
+/** Options of `job()`. */
+export interface JobOptions {
+  /**
+   * The job's cron expression (`"0 * * * *"`), when it runs on one: the Jobs page then shows when
+   * it misses a run, and PeekInside Cloud can email you.
+   */
+  schedule?: string;
+  /** The schedule's time zone, such as `"Europe/Paris"`. */
+  timezone?: string;
+  /** The queue it came from. */
+  queue?: string;
+  /** @default 1 */
+  attempt?: number;
+  /** The job's input, shown with the run (the first 8 KB). */
+  data?: unknown;
+}
+
+/** Options of `report()`. */
+export interface ReportOptions {
+  /**
+   * The request the error relates to. By default, the request being handled when `report()` is
+   * called, if any.
+   */
+  request?: IncomingMessage;
+
+  /** Up to 32 short labels shown with the exception, such as `{ provider: "stripe" }`. */
+  tags?: Record<string, string>;
+
+  /** Any JSON-safe data shown with the exception. Past 16 KB, only a preview is kept. */
+  extra?: unknown;
+
+  /**
+   * Whether your app handled the error.
+   * @default true
+   */
+  handled?: boolean;
+
+  /** Who it happened to. By default, the user set for the current request (see `setUser`). */
+  user?: PeekInsideUser | string | number | null;
+}
+
+/** Who a request or an exception was for. Encrypted with the rest in PeekInside Cloud. */
+export interface PeekInsideUser {
+  id?: string | number;
+  email?: string;
+  name?: string;
+}
+
+/** Options that can still change after the instance is created (see `attachTo`). */
+export type CaptureOptions = Pick<PeekInsideOptions, "maxBodySize" | "ignorePaths">;
+
+/**
+ * What `PeekInside.attach()` understands: an Express or Connect app, a Koa app, a Fastify
+ * instance, or a node:http (or https) server.
+ */
+export type AttachTarget = Server | { use(...args: any[]): unknown } | { addHook(...args: any[]): unknown };
+
+/** Express and Connect style middleware. */
+export type NodeMiddleware = (req: IncomingMessage, res: ServerResponse, next: (error?: unknown) => void) => void;
+
+/** Koa style middleware. */
+export type KoaMiddleware = (
+  context: { req: IncomingMessage; res: ServerResponse },
+  next: () => Promise<unknown>,
+) => Promise<void>;
+
+/**
+ * Records every request and response an app handles.
+ *
+ * @example
+ * import PeekInside from "peekinside";
+ *
+ * PeekInside.attach(app); // Express, Koa, Fastify or an http.Server
+ */
+declare class PeekInside {
+  /**
+   * Creates an instance without attaching it. Use the middleware methods to record traffic,
+   * or `PeekInside.attach()` to do both in one line.
+   */
+  constructor(options?: PeekInsideOptions);
+
+  /** The effective configuration. */
+  readonly options: PeekInsideOptions & Required<CaptureOptions>;
+
+  /** Whether new requests are recorded (see `setEnabled`). */
+  readonly isEnabled: boolean;
+
+  /** The deploy that is running (see the `release` option), or `null` when none was found. */
+  readonly release: string | null;
+
+  /**
+   * One-line setup: records every request the app handles.
+   *
+   * @param app - Express or Connect app, Koa app, Fastify instance, or http.Server
+   */
+  static attach(app: AttachTarget, options?: PeekInsideOptions): PeekInside;
+
+  /** Attaches this instance to an app; see `PeekInside.attach`. */
+  attachTo(app: AttachTarget, options?: CaptureOptions): this;
+
+  /**
+   * Records an error, linked to the request being handled (or `options.request`).
+   *
+   * @param error - An Error, or any thrown value
+   * @returns The exception's id, or `null` when nothing was recorded (recording is off or paused,
+   *   the request isn't recorded, or too many exceptions were recorded this second)
+   *
+   * @example
+   * try {
+   *   await chargeCard(order);
+   * } catch (error) {
+   *   peekInside.report(error, { tags: { provider: "stripe" } });
+   * }
+   */
+  report(error: unknown, options?: ReportOptions): string | null;
+
+  /**
+   * Records an error with the instance that tracks the current request, or else the most
+   * recently created instance that records. See `report()`.
+   */
+  static report(error: unknown, options?: ReportOptions): string | null;
+
+  /**
+   * Runs `fn` and records how long it took on the request's timeline. Async functions are
+   * measured until their promise settles. Outside a request, just runs `fn`.
+   *
+   * @example
+   * const pdf = await peekInside.measure("render invoice", () => renderPdf(order));
+   */
+  measure<T>(name: string, fn: () => T): T;
+
+  /**
+   * `measure()` with the instance that tracks the current request, or else the most recently
+   * created instance that records. Without one, just runs `fn`.
+   */
+  static measure<T>(name: string, fn: () => T): T;
+
+  /**
+   * The id of the request the calling code runs for, as the dashboard knows it: put it in your
+   * own logs to find the request from a log line. `null` outside a recorded request.
+   */
+  static requestId(): string | null;
+
+  /**
+   * Tells PeekInside who the current request is for: the request and every exception it runs into
+   * carry the user, so the dashboard counts the users an issue affects and lists everything one
+   * customer ran into. Call it once the user is known, such as in your authentication middleware.
+   *
+   * @param user - The user, or just their id; `null` forgets it
+   * @returns Whether a request was running to attach it to
+   *
+   * @example
+   * app.use((req, res, next) => {
+   *   if (req.user) PeekInside.setUser({ id: req.user.id, email: req.user.email });
+   *   next();
+   * });
+   */
+  static setUser(user: PeekInsideUser | string | number | null): boolean;
+
+  /** Same as `PeekInside.setUser()`: the user belongs to the request running now. */
+  setUser(user: PeekInsideUser | string | number | null): boolean;
+
+  /**
+   * Runs a background job as a recorded job run: the Jobs page lists it with how long it took and
+   * how it ended, and its queries, calls, log lines and exceptions link to it. A job that throws or
+   * rejects is recorded as failed, and its error as an exception. `fn` runs exactly as without
+   * PeekInside, and its result (or error) is returned (or thrown) unchanged.
+   *
+   * @example
+   * cron.schedule("0 * * * *", () =>
+   *   peekInside.job("send-invoices", sendInvoices, { schedule: "0 * * * *" }));
+   */
+  job<T>(name: string, fn: () => T, options?: JobOptions): T;
+
+  /**
+   * `job()` with the instance that tracks the current request, or else the most recently created
+   * instance that records. Without one, just runs `fn`.
+   */
+  static job<T>(name: string, fn: () => T, options?: JobOptions): T;
+
+  /**
+   * Instruments database modules that automatic patching can't reach (bundled apps, a monorepo
+   * package with its own copy): pg, mysql2, mysql2/promise, mongodb, mongoose, a PrismaClient
+   * class or instance, or the @prisma/client module. Other values are ignored.
+   *
+   * @example
+   * import pg from "pg";
+   * peekInside.instrument(pg);
+   */
+  instrument(...modules: unknown[]): this;
+
+  /**
+   * Records one request/response pair, for frameworks without a ready-made integration.
+   * Request bodies are captured as the app reads them, so call it before reading the body.
+   *
+   * @param next - Called once tracking is set up (middleware style); its result is returned
+   */
+  intercept(req: IncomingMessage, res: ServerResponse, next?: () => unknown): unknown;
+
+  /** Pauses (`false`) or resumes (`true`) recording. */
+  setEnabled(enabled: boolean): void;
+
+  /** Express and Connect middleware that records requests. */
+  expressMiddleware(): NodeMiddleware;
+
+  /** Koa middleware that records requests. */
+  koaMiddleware(): KoaMiddleware;
+
+  /** Registers a Fastify `onRequest` hook that records requests. */
+  fastifyHook(fastify: { addHook(...args: any[]): unknown; server?: Server }): void;
+
+  /** Records every request a node:http (or https) server handles. Returns the same server. */
+  wrapHttpServer<T extends Server>(server: T): T;
+
+  /**
+   * Sends everything still queued. Call it before a short-lived process (script, serverless
+   * function, test) exits.
+   */
+  flush(): Promise<void>;
+
+  /** Stops recording and sending. */
+  stop(): void;
+}
+
+export default PeekInside;

package/index.js

@@ -0,0 +1,3 @@
+import PeekInside from './src/PeekInside.js';
+
+export default PeekInside;

package/package.json

@@ -1,6 +1,79 @@
 {
   "name": "peekinside",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.2.1",
+  "description": "Debug Node.js from the inside: errors with the requests, queries, logs and jobs behind them. A free local dashboard, and encrypted monitoring for production",
+  "main": "index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "peekinside": "bin/peekinside.js"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "src/",
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "scripts": {
+    "demo": "node examples/demo.js",
+    "test": "node --test",
+    "test:types": "tsc -p test-d && tsc -p test-d/tsconfig.bundler.json && tsc -p test-d/tsconfig.cjs.json",
+    "prepublishOnly": "npm test && npm run test:types"
+  },
+  "keywords": [
+    "peekinside",
+    "http",
+    "inspector",
+    "debugging",
+    "monitoring",
+    "observability",
+    "express",
+    "koa",
+    "fastify",
+    "middleware",
+    "nodejs"
+  ],
+  "author": "Jesbin",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thejesbin/peekinside.git"
+  },
+  "bugs": {
+    "url": "https://github.com/thejesbin/peekinside/issues",
+    "email": "support@peekinside.dev"
+  },
+  "homepage": "https://peekinside.dev",
+  "devDependencies": {
+    "@types/express": "4.17.25",
+    "@types/koa": "2.15.0",
+    "@types/node": "24.10.1",
+    "bullmq": "6.3.14",
+    "cron": "4.4.0",
+    "express": "4.22.3",
+    "express5": "npm:express@5.1.0",
+    "fastify": "5.12.5",
+    "koa": "2.16.4",
+    "mongodb": "6.21.0",
+    "mongodb-memory-server-core": "11.3.0",
+    "mongoose": "8.24.5",
+    "mysql2": "3.24.5",
+    "node-cron": "4.6.0",
+    "pg": "8.23.1",
+    "pino": "10.4.0",
+    "typescript": "5.9.3",
+    "winston": "3.19.0"
+  }
+}