nestjs-profiler 1.0.25 → 1.0.27

package/README.md

@@ -4,253 +4,360 @@
   <img src="https://raw.githubusercontent.com/MohammedRaslan/Nest-JS-Profiler/refs/heads/main/libs/nestjs-profiler/src/assets/logo.png" width="400" alt="NestJS Profiler Logo" />
 </p>
 
-A NestJS module for profiling HTTP requests, database queries, cache operations, outbound HTTP calls, application logs, package health, and code quality. Inspired by Symfony Profiler, it provides a web-based dashboard to inspect everything that happens inside a request — from DB queries to downstream API calls — in real time.
+<p align="center">
+  <a href="https://www.npmjs.com/package/nestjs-profiler"><img src="https://img.shields.io/npm/v/nestjs-profiler.svg" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/nestjs-profiler"><img src="https://img.shields.io/npm/dm/nestjs-profiler.svg" alt="npm downloads" /></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D16-brightgreen" alt="node version" />
+  <img src="https://img.shields.io/badge/license-MIT-blue" alt="license" />
+</p>
 
-## Features
+> A drop-in debugging dashboard for NestJS. Inspect HTTP requests, database queries, outbound calls, logs, events, scheduled jobs, and code health — all from one browser tab, with zero instrumentation required.
 
-- **HTTP Request Tracing** — Tracks method, URL, controller handler, duration, status code, headers, and request body.
-- **Database Profiling**
-  - **PostgreSQL** — Captures all queries via `pg` (compatible with TypeORM, MikroORM, raw pg). Supports **Auto-Explain** to run `EXPLAIN` or `EXPLAIN ANALYZE` on slow queries automatically.
-  - **MongoDB** — Profiles MongoDB commands and queries.
-  - **MySQL** — Profiles MySQL queries.
-  - **N+1 Detection** — Automatically flags repeated identical queries within the same request.
-  - **Slow Query Tagging** — Tags queries exceeding 100ms.
-  - **Sequential Scan Detection** — Tags queries using a Seq Scan from the explain plan.
-- **Outbound HTTP Tracking** — Captures every outbound `http`/`https` call made during a request: URL, method, status code, duration, and headers. Works automatically with axios, node-fetch, and any library built on Node's `http`/`https` modules. Enabled by default — no configuration required.
-- **Cache Profiling** — Tracks cache operations (get, set, del, reset) and hit/miss ratio when using `@nestjs/cache-manager`.
-- **Log Profiling** — Captures application logs associated with each request context.
-- **Live Logs Terminal** — Real-time streaming log viewer at `/__profiler/view/logs/live` via Server-Sent Events. Supports level filtering, search, pause/resume, and auto-scroll.
-- **Summary Dashboard** — Aggregate statistics: avg/p95 duration, error rate, cache hit rate, top slow endpoints, top slow queries, and recent errors.
-- **Entity Explorer** — Lists all registered TypeORM/MikroORM entities and their columns.
-- **Route Explorer** — Lists all registered routes with their controllers and handlers.
-- **Package Health** — Runs `npm audit` and `npm outdated` to surface known vulnerabilities and stale dependencies. Results are cached for 5 minutes. Works with npm, yarn, and pnpm. If the registry is unreachable, outdated packages are still shown with an inline warning.
-- **Code Quality** — Runs ESLint and TypeScript compiler checks (`tsc --noEmit`) against your source code. Issues are displayed grouped by file or by rule, with direct links to ESLint rule docs and TypeScript error references. Auto-fixable issues are flagged. File paths are copyable with one click.
-- **Web UI** — Built-in dashboard at `/__profiler` with no external dependencies.
-- **Zero Hard Dependencies** — Core functionality works out of the box; database drivers are optional peer dependencies.
+---
 
-## Installation
+> ⚠️ **Development use only.** The profiler adds request overhead and exposes internal application data. Always set `enabled: process.env.NODE_ENV !== 'production'`.
+
+---
+
+## Quick Start
+
+**1. Install**
 
 ```bash
 npm install nestjs-profiler
 ```
 
-### Peer Dependencies (Optional)
+**2. Register in your AppModule**
+
+```typescript
+import { ProfilerModule } from 'nestjs-profiler';
+
+@Module({
+  imports: [
+    ProfilerModule.forRoot({
+      enabled: process.env.NODE_ENV !== 'production',
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+**3. Initialize in main.ts**
+
+```typescript
+import { ProfilerModule } from 'nestjs-profiler';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  ProfilerModule.initialize(app); // enables Route Explorer, Entity Explorer, Scheduled Jobs
+  await app.listen(3000);
+}
+```
+
+---
+
+### Global Prefix (Required if you use global route prefix)
+
+If your app uses a global route prefix, exclude the profiler:
+
+```typescript
+app.setGlobalPrefix('api', {
+  exclude: [{ path: '__profiler/(.*)', method: RequestMethod.ALL }],
+});
+```
+
+Open `http://localhost:3000/__profiler` — the dashboard is live.
 
-Install only the dependencies relevant to your project:
+---
+
+## Features
+
+### Request Profiling
+- Traces every HTTP request: method, URL, handler, status code, duration, headers, and body
+- Summary dashboard with avg/p95 duration, error rate, cache hit rate, top slow endpoints, and recent errors
+- Full detail view per request including all associated queries, cache ops, logs, and outbound calls
+
+### Database
+- **PostgreSQL** — captures all queries via `pg`, compatible with TypeORM, MikroORM, and raw pg
+- **MongoDB** — profiles all MongoDB commands
+- **MySQL** — profiles MySQL queries via `mysql2`
+- **N+1 Detection** — flags repeated identical queries within the same request
+- **Slow Query Tagging** — highlights queries over 100ms
+- **Sequential Scan Detection** — flags full table scans from the query explain plan
+- **Auto-Explain** — automatically runs `EXPLAIN` or `EXPLAIN ANALYZE` on slow queries (opt-in)
+
+### Outbound HTTP
+Automatically captures every `http`/`https` call your app makes — including axios, node-fetch, and any library built on Node's core modules. Records method, URL, status code, duration, headers (with Authorization and Cookie values redacted), and errors. No configuration required.
+
+### Cache
+Tracks `get`, `set`, `del`, and `reset` operations with hit/miss ratio when using `@nestjs/cache-manager`.
+
+### Logs
+- Captures application logs per request context
+- **Live Logs Terminal** — real-time streaming viewer via Server-Sent Events, with level filtering, search, pause/resume, and auto-scroll
+
+### Code Analysis
+- **Package Health** — runs `npm audit` and `npm outdated` to surface vulnerabilities and stale dependencies, sorted by severity
+- **Code Quality** — runs ESLint and `tsc --noEmit` against your source. Issues shown by file or by rule, with links to rule docs and TypeScript error references. Auto-fixable issues are flagged
+
+### Application Intelligence
+- **Route Explorer** — every registered route grouped by controller, with path/query/header params, body DTOs, property types, and source file paths
+- **Entity Explorer** — all registered TypeORM/MikroORM entities with their columns
+- **Event Tracking** — intercepts every `EventEmitter2` emission and renders a cascading tree: which service fired it, which listeners handled it, individual timings, child events, and errors. Requires `@nestjs/event-emitter`
+- **Scheduled Jobs** — live view of all `@Cron`, `@Interval`, and `@Timeout` jobs from `@nestjs/schedule`, with countdowns, last run times, cycle progress, and handler details. Requires `@nestjs/schedule`
+
+### Security
+- **Dashboard Authentication** — optional login wall with HMAC-SHA256 tokens stored in `localStorage`, 24-hour TTL. No separate auth server needed
+
+---
+
+## Installation
 
 ```bash
-# For PostgreSQL
-npm install pg
+npm install nestjs-profiler
+```
 
-# For MongoDB
-npm install mongodb
+### Optional Peer Dependencies
 
-# For MySQL
-npm install mysql2
+Install only what your project uses:
 
-# For Cache Profiling
-npm install @nestjs/cache-manager cache-manager
+```bash
+npm install pg                              # PostgreSQL
+npm install mongodb                         # MongoDB
+npm install mysql2                          # MySQL
+npm install @nestjs/cache-manager cache-manager   # Cache profiling
+npm install @nestjs/event-emitter           # Event tracking
+npm install @nestjs/schedule                # Scheduled jobs
 ```
 
+---
+
 ## Configuration
 
-Import `ProfilerModule` in your root `AppModule`:
+All options are passed to `ProfilerModule.forRoot()`. Only `enabled` is required — everything else is opt-in.
 
 ```typescript
-import { Module } from '@nestjs/common';
 import { ProfilerModule } from 'nestjs-profiler';
 import * as pg from 'pg';
 
 @Module({
   imports: [
     ProfilerModule.forRoot({
-      // Global enable/disable (default: true)
-      // Recommended: disable in production
       enabled: process.env.NODE_ENV !== 'production',
 
-      // ── Database ─────────────────────────────────────────────────
-      // PostgreSQL — pass the pg driver instance
+      // PostgreSQL
       pgDriver: pg,
       collectQueries: true,
-
-      // Auto-Explain for slow queries
       explain: {
         enabled: true,
-        thresholdMs: 50,   // Only explain queries taking > 50ms
-        analyze: false,    // true = EXPLAIN ANALYZE (actually executes!)
+        thresholdMs: 100,  // explain queries slower than this
+        analyze: false,    // true = EXPLAIN ANALYZE (executes the query!)
       },
 
-      // MongoDB — pass the mongodb driver instance
+      // MongoDB
       mongoDriver: require('mongodb'),
       collectMongo: true,
 
-      // MySQL — pass the mysql2 driver instance
+      // MySQL
       mysqlDriver: require('mysql2'),
       collectMysql: true,
 
-      // ── Outbound HTTP ─────────────────────────────────────────────
-      // Tracks all outbound http/https calls made during each request.
-      // Enabled by default — set false to disable.
+      // Outbound HTTP (on by default)
       collectHttp: true,
 
-      // ── Cache ─────────────────────────────────────────────────────
-      collectCache: true,   // requires @nestjs/cache-manager
+      // Cache
+      collectCache: true,
 
-      // ── Logs ──────────────────────────────────────────────────────
+      // Logs
       collectLogs: true,
 
-      // ── Storage ───────────────────────────────────────────────────
-      // Default: in-memory (last 100 requests).
-      // Pass a custom object implementing ProfilerStorage for persistence.
-      storage: 'memory',
+      // Auth (off by default)
+      auth: {
+        enabled: true,
+        username: 'admin',
+        password: 'supersecret',
+      },
     }),
   ],
 })
 export class AppModule {}
 ```
 
-### Default behaviour
+### Options Reference
 
-| Option | Default | Notes |
+| Option | Default | Description |
 |---|---|---|
-| `enabled` | `true` | Set `false` or tie to `NODE_ENV` |
-| `collectHttp` | `true` | Patches `http`/`https` automatically |
-| `collectLogs` | `true` | |
-| `collectQueries` | `true` | Requires `pgDriver` / `mongoDriver` / `mysqlDriver` |
-| `collectCache` | `true` | Requires `@nestjs/cache-manager` |
-| `explain.enabled` | `false` | Opt-in only |
-
-## Usage
+| `enabled` | `true` | Master switch. Tie to `NODE_ENV` in production |
+| `collectHttp` | `true` | Outbound HTTP tracking (patches `http`/`https`) |
+| `collectLogs` | `true` | Log capture per request |
+| `collectQueries` | `true` | DB query capture. Requires a driver to be passed |
+| `collectCache` | `true` | Cache op tracking. Requires `@nestjs/cache-manager` |
+| `explain.enabled` | `false` | Auto-Explain for slow queries |
+| `explain.thresholdMs` | `100` | Minimum query duration to trigger explain |
+| `explain.analyze` | `false` | Run `EXPLAIN ANALYZE` instead of `EXPLAIN` |
+| `auth.enabled` | `false` | Enable login wall. `username` and `password` required when `true` |
+| Event Tracking | automatic | Activates when `@nestjs/event-emitter` is detected |
+| Scheduled Jobs | automatic | Activates when `@nestjs/schedule` is detected |
 
-### 1. Initialize Explorers (Optional but Recommended)
+---
 
-To enable the **Entity Explorer** and **Route Explorer**, call `initialize` in `main.ts` after creating the app:
+## Dashboard
 
-```typescript
-import { NestFactory } from '@nestjs/core';
-import { AppModule } from './app.module';
-import { ProfilerModule } from 'nestjs-profiler';
+Navigate to `/__profiler` after starting your app.
 
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-
-  ProfilerModule.initialize(app);
-
-  await app.listen(3000);
-}
-bootstrap();
-```
-
-### 2. Accessing the Dashboard
-
-Once configured, start your application. The profiler automatically intercepts all requests.
-
-Navigate to `http://localhost:3000/__profiler`.
-
-#### Dashboard Pages
-
-| Path | Description |
+| Page | Description |
 |---|---|
-| `/__profiler` | Redirects to Summary (default landing page) |
 | `/__profiler/view/summary` | Aggregate stats: avg/p95 duration, error rate, top slow endpoints |
-| `/__profiler/view/requests` | All captured requests |
-| `/__profiler/view/queries` | All database queries across requests, sorted by duration |
-| `/__profiler/view/http-calls` | All outbound HTTP calls across requests, sorted by duration |
+| `/__profiler/view/requests` | All captured requests with status, duration, and method |
+| `/__profiler/view/queries` | All DB queries across requests, sortable by duration |
+| `/__profiler/view/http-calls` | All outbound HTTP calls, sortable by duration |
 | `/__profiler/view/logs` | Paginated application logs |
-| `/__profiler/view/logs/live` | Live streaming terminal — real-time log output |
+| `/__profiler/view/logs/live` | Real-time streaming log terminal |
 | `/__profiler/view/cache` | Cache operations with hit/miss breakdown |
-| `/__profiler/view/entities` | Registered database entities |
-| `/__profiler/view/routes` | All registered application routes |
+| `/__profiler/view/entities` | Registered database entities and their columns |
+| `/__profiler/view/routes` | All registered routes with DTOs and parameter types |
 | `/__profiler/view/health` | Package vulnerabilities and outdated dependency report |
-| `/__profiler/view/code-quality` | ESLint and TypeScript static analysis report |
+| `/__profiler/view/code-quality` | ESLint and TypeScript static analysis |
+| `/__profiler/view/events` | Event cascade tree for `EventEmitter2` emissions |
+| `/__profiler/view/cron-jobs` | Live scheduled job monitor — cron, intervals, and timeouts |
 | `/__profiler/:id` | Full detail view for a single request |
 
-### 3. Outbound HTTP Tracking
+### JSON API
 
-Outbound HTTP tracking is **enabled by default**. Any `http.request`, `https.request`, `http.get`, or `https.get` call made during a request is automatically captured — including calls made via axios, node-fetch, and similar libraries.
+All data is also available as JSON for programmatic use:
 
-Each captured call records:
+```
+GET /__profiler/json                  # all captured requests
+GET /__profiler/:id/json              # single request detail
+GET /__profiler/api/health            # package health (5 min cache)
+GET /__profiler/api/health?force=true
+GET /__profiler/api/code-quality      # static analysis (5 min cache)
+GET /__profiler/api/code-quality?force=true
+GET /__profiler/api/events            # event log (live, not cached)
+GET /__profiler/api/cron-jobs         # scheduled job state (live, not cached)
+```
 
-- Method and full URL
-- HTTP vs HTTPS protocol
-- Response status code
-- Duration in ms
-- Request and response headers (Authorization/Cookie values are automatically redacted)
-- Error message if the call failed
+---
 
-You can view outbound calls for a specific request in the request detail view, or browse all calls across all requests at `/__profiler/view/http-calls`.
+## Feature Guides
 
-To disable:
+### Dashboard Authentication
 
 ```typescript
-ProfilerModule.forRoot({ collectHttp: false })
+ProfilerModule.forRoot({
+  auth: {
+    enabled: true,
+    username: 'admin',
+    password: 'supersecret',
+  },
+})
 ```
 
-### 4. Package Health
+When enabled, all `/__profiler` pages check for a valid token in `localStorage` before rendering. If none is found, the browser redirects to the login page. Tokens use HMAC-SHA256 keyed on the password and expire after 24 hours — changing the password invalidates all active sessions automatically.
 
-The Health tab runs `npm audit` and `npm outdated` from your project root and displays the results in a searchable UI.
+TypeScript enforces that `username` and `password` are present when `enabled: true`. Omitting either is a compile-time error.
 
-- **Vulnerabilities** — sorted by severity (critical → high → moderate → low), with fix availability and whether the package is a direct or transitive dependency.
-- **Outdated packages** — shows current, wanted, and latest versions with major-update warnings.
-- Results are **cached for 5 minutes** server-side. Navigating back to the tab shows the cached result instantly without re-running. Click **Re-run audit** to force a fresh scan.
-- If `npm audit` cannot reach the registry (e.g. VPN or proxy), the outdated packages section still renders with an inline warning for the unavailable audit.
-- No configuration required — works automatically for npm, yarn, and pnpm projects.
+> Auth is enforced client-side. It prevents casual access on shared dev/staging environments but is not a security boundary for sensitive data.
 
-#### JSON endpoint
+| Route | Purpose |
+|---|---|
+| `GET /__profiler/login` | Login page |
+| `POST /__profiler/api/login` | Validates credentials, returns a session token |
+| `GET /__profiler/logout` | Clears the token and redirects to login |
 
-```
-GET /__profiler/api/health           # cached result (5 min TTL)
-GET /__profiler/api/health?force=true  # force fresh scan
-```
+---
 
-### 5. Code Quality
+### Event Tracking
 
-The Code Quality tab runs static analysis tools against your source code and surfaces every issue without AI or external services.
+Requires `@nestjs/event-emitter`:
 
-**ESLint** — uses your project's existing ESLint configuration (`node_modules/.bin/eslint`). Results are shown in two views:
+```typescript
+import { EventEmitterModule } from '@nestjs/event-emitter';
 
-- **By File** — expandable accordion rows per file. Each issue shows line:column, severity badge, message, fix indicator (⚡ auto-fixable), and a clickable rule badge linking to the ESLint documentation.
-- **By Rule** — sorted by severity then count, showing how many files are affected per rule.
+@Module({
+  imports: [EventEmitterModule.forRoot()],
+})
+export class AppModule {}
+```
 
-**TypeScript** — runs `tsc --noEmit` using your project's `tsconfig.json`. Each error links to `typescript.tv/errors` for explanations.
+The profiler intercepts every `emit` and `emitAsync` call automatically. No decorators or instrumentation needed. The dashboard renders a full cascade tree showing the emitter, all listeners with timings, child events, and any listener errors.
 
-**Summary cards** show total issues, errors, warnings, auto-fixable count, and files affected at a glance.
+**Example — what you see in the dashboard:**
 
-File paths have a **copy-to-clipboard** button that appears on hover, making it easy to jump to the file in your editor.
+```
+🔔 order.created  (async)  ⬆ OrderService.createOrder  145ms
+  ✓ onOrderCreated [InventoryListener]   45ms
+  ✓ onOrderCreated [InvoiceListener]     80ms
+  ✓ onOrderCreated [AuditListener]        5ms
+    └── 🔔 inventory.reserved  ⬆ InventoryListener  23ms
+          ✓ onInventoryReserved [NotificationListener]  20ms
+    └── 🔔 invoice.created  ⬆ InvoiceListener  4ms
+          ✓ onInvoiceCreated [AuditListener]   3ms
+```
 
-Results are cached for 5 minutes. Click **Re-run** to force a fresh analysis.
+---
 
-> **Note:** Code Quality only lints the `src/` directory (or project root if `src/` doesn't exist) and automatically ignores `dist/`, `build/`, `coverage/`, and other generated directories.
+### Scheduled Jobs
 
-#### JSON endpoint
+Requires `@nestjs/schedule`:
 
+```bash
+npm install @nestjs/schedule
 ```
-GET /__profiler/api/code-quality             # cached result (5 min TTL)
-GET /__profiler/api/code-quality?force=true  # force fresh scan
+
+```typescript
+import { ScheduleModule } from '@nestjs/schedule';
+
+@Module({
+  imports: [ScheduleModule.forRoot()],
+})
+export class AppModule {}
 ```
 
-### 6. JSON API
+The profiler detects `SchedulerRegistry` at startup via `ProfilerModule.initialize(app)` — no additional configuration needed. The dashboard has three tabs:
 
-Retrieve profile data programmatically:
+**Cron Jobs** — one card per `@Cron()` method showing the expression with a plain-English translation (e.g. `0 */5 * * * *` → *Every 5 minutes*), a live next-run countdown, last run time, cycle progress bar, handler name, and source file path. An *Upcoming — next 3 hours* strip at the top plots all jobs on a shared timeline.
 
-- `GET /__profiler/json` — List all captured requests
-- `GET /__profiler/:id/json` — Details for a specific request
+**Intervals** — one card per `@Interval()` method with an animated frequency ring, the repeat period displayed prominently (e.g. *Every 30s*), and fires-per-minute count.
 
-## Global Prefix
+**Timeouts** — one card per `@Timeout()` method. Pending jobs show a live countdown in amber; fired jobs turn grey with a *Fired* badge. Both show the configured delay and the handler that will run.
 
-If your app uses a global prefix (e.g. `/api`), exclude the profiler routes:
+All tabs auto-refresh every 15 seconds. If `@nestjs/schedule` is not installed, the page shows an install prompt instead of an error.
+
+**Example:**
 
 ```typescript
-app.setGlobalPrefix('api', {
-  exclude: [{ path: '__profiler/(.*)', method: RequestMethod.ALL }],
-});
+import { Cron, CronExpression, Interval, Timeout } from '@nestjs/schedule';
+
+@Injectable()
+export class TasksService {
+
+  @Cron(CronExpression.EVERY_MINUTE, { name: 'health-ping' })
+  handleHealthPing() { /* ... */ }
+
+  @Cron('0 0 * * *', { name: 'nightly-cleanup' })
+  handleNightlyCleanup() { /* ... */ }
+
+  @Interval('metrics-flush', 30_000)
+  handleMetricsFlush() { /* ... */ }
+
+  @Timeout('deferred-init', 10_000)
+  handleDeferredInit() { /* ... */ }
+}
 ```
 
-## Important Notes
+---
+
+### Route Explorer
+
+Populated by `ProfilerModule.initialize(app)`. Lists every route grouped by controller in an expandable accordion. Each route surfaces:
+
+- HTTP method and full path (including global prefix)
+- Path parameters, query parameters, and headers with their TypeScript types
+- Body DTO — class name, all decorated properties and types (discovered via `reflect-metadata`)
+- Source file path with a one-click copy button
 
-- The profiler is designed for **development and debugging only**. Do not enable in production — it adds request overhead and exposes internal application data.
-- The default in-memory storage holds the last 100 requests. Older profiles are evicted automatically.
-- Outbound HTTP tracking patches `http`/`https` at the Node.js module level. The patch is applied once on module init and is safe for hot-reload (double-patch is guarded).
+Works with `emitDecoratorMetadata: true` (standard in NestJS). No OpenAPI/Swagger required.
 
 ## License
 

package/collectors/event-collector.d.ts

@@ -0,0 +1,18 @@
+import { OnModuleInit } from '@nestjs/common';
+import { ProfilerService } from '../services/profiler.service';
+export declare class EventCollector implements OnModuleInit {
+    private readonly profilerService;
+    private readonly eventEmitter?;
+    private resolvedListenerNames;
+    private readonly listenerRegistrationCounters;
+    constructor(profilerService: ProfilerService, eventEmitter?: any | undefined);
+    setListenerNames(map: Map<string, Array<{
+        name: string;
+        file: string;
+    }>>): void;
+    onModuleInit(): void;
+    private patchEmitter;
+    private buildProfile;
+    private serializePayload;
+    private getCallerLocation;
+}