Merge pull request #6 from rakibulislam8226/pre-master

Refactor withTimeout function for improved clarity and efficiency; en…

Author: rakibulislam8226

CHANGELOG.md

@@ -14,6 +14,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- **`NEST_DEBUG_PANEL_ENABLED` environment variable.** Toggle the panel on or off
+  straight from the environment — no code change. When set to a recognized
+  boolean (`true`/`1`/`yes`/`on` or `false`/`0`/`no`/`off`, case-insensitive) it
+  **takes precedence** over both the `enabled` option and the `NODE_ENV` default,
+  so you can force it on in any environment or disable it in development. Leaving
+  it unset preserves the existing behavior exactly.
+- **Redesigned dashboard.** The UI is now a Telescope-style single-page app: a
+  fixed left sidebar of **monitors** (Overview, Requests, Sockets, Queries,
+  Logs, Exceptions, Slow) with live counts, and an **Overview** landing page
+  with KPI tiles (total requests, average latency, error rate, slow count, total
+  SQL, N+1 alerts), a latency chart and a recent-activity feed. Adds a global
+  **Queries** view (every SQL query across all requests, with N+1/duplicate
+  flags), plus **Exceptions** and **Slow** views, a filter/search box, relative
+  timestamps and a live-connection indicator. Fully responsive down to mobile,
+  and auto-refresh only re-renders when new data is captured (no flicker).
+- **Log capture.** `console.*` output emitted while a request or socket event is
+  executing is attached to that request's profile and surfaced in the new
+  **Logs** monitor (and a per-request Logs tab), with level, message and logger
+  context. The console is patched at bootstrap and restored on shutdown;
+  original output still prints. Turn it off with `captureLogs: false`.
+- **Automatic socket.io event capture.** Inbound NestJS WebSocket handlers
+  (`@SubscribeMessage`) are now captured like HTTP requests with **zero extra
+  setup** — `DebugModule.forRoot()` is all you need, no per-gateway decorator.
+  (NestJS does not apply global interceptors to gateways, so the panel attaches
+  itself to every gateway at startup.) Each handler runs inside the same tracing
+  context, so every SQL/Redis/HTTP call it makes is recorded automatically, with
+  N+1 detection and a timeline, plus the event name, namespace, socket id, rooms,
+  handshake (redacted), payload and acknowledgement. Socket events appear in the
+  **same list** as HTTP requests with a `WS` badge and an All / HTTP / Socket
+  filter. Turn it off with `sockets: false`. An optional `@TrackSocketEvents()`
+  decorator is exported for edge cases the auto-attach can't reach. No new
+  dependency is added, and HTTP capture is unchanged.
 - **Prisma 7 zero-config raw SQL capture.** Auto-instrumentation now wraps the
   Prisma driver adapter (e.g. `@prisma/adapter-pg`) directly, so the actual SQL
   text, params and timing are captured without setting the `log` option. Each

README.md

@@ -54,7 +54,7 @@ Start your app and open:
 http://localhost:<your-port>/__debug
 ```
 
-That's it. Hit any endpoint of your API and watch it appear in the dashboard (it refreshes every 2 seconds). If the list stays empty, make sure `NODE_ENV` isn't `production`, or pass `enabled: true` explicitly.
+That's it. Hit any endpoint of your API and watch it appear in the dashboard (it refreshes every 2 seconds). If the list stays empty, make sure `NODE_ENV` isn't `production`, pass `enabled: true` explicitly, or set `NEST_DEBUG_PANEL_ENABLED=true` in your environment (see [Enabling & disabling](#enabling--disabling)).
 
 Works with Node.js 18+, NestJS 9/10/11, and both Express and Fastify. No runtime dependencies.
 
@@ -70,6 +70,17 @@ On top of that:
 - **Exceptions** with name, message, stack trace, and how long the request ran before failing
 - **Memory**: heap and RSS deltas per request, event-loop delay
 - **A timeline** that lays all of the above in order, plus your own custom marks
+- **Socket.io events** — inbound `@SubscribeMessage` handlers captured like a request, with all the SQL/Redis/HTTP they run (see below)
+
+## Socket.io events
+
+If your app uses NestJS WebSocket gateways (`@WebSocketGateway` + `@SubscribeMessage`), every incoming event is captured **automatically** — just like HTTP. You don't touch your gateways or add any decorator; `DebugModule.forRoot()` is all it takes. (NestJS doesn't apply global interceptors to gateways, so the panel attaches itself to each gateway at startup for you.)
+
+Each event runs inside the same tracing context, so **every query it runs shows up automatically**, with N+1 detection, timeline and all — plus the event name, namespace, socket id, rooms, handshake (redacted), payload and acknowledgement.
+
+Socket events appear in the **same list** as HTTP requests, tagged with a `WS` badge; use the **All / HTTP / Socket** filter at the top to narrow down. Set `sockets: false` in `forRoot()` to turn socket capture off.
+
+> Capture is on by default. For rare cases the automatic attachment can't reach (e.g. a single handler, or a gateway created outside the module scan), the `@TrackSocketEvents()` decorator is exported as an explicit opt-in — normally you won't need it.
 
 ## Database, Redis and HTTP capture is automatic
 
@@ -94,7 +105,7 @@ Everything is optional. These are the defaults:
 
 ```ts
 DebugModule.forRoot({
-  enabled: process.env.NODE_ENV !== 'production',
+  enabled: process.env.NODE_ENV !== 'production', // NEST_DEBUG_PANEL_ENABLED env var overrides this
   maxRequests: 200,             // how many profiles to keep; oldest are evicted
   captureRequestBody: true,
   captureResponseBody: true,
@@ -103,6 +114,8 @@ DebugModule.forRoot({
   captureSql: true,
   captureRedis: true,
   captureHttp: true,
+  captureLogs: true,            // capture console.* emitted during a request (Logs monitor)
+  sockets: true,                // capture socket.io gateway events (automatic, no per-gateway setup)
   autoInstrument: true,         // scan providers and hook them automatically
   slowQueryThreshold: 100,      // ms; queries at or above get flagged
   slowRequestThreshold: 500,    // ms; requests at or above get flagged
@@ -121,6 +134,22 @@ DebugModule.forRoot({
 
 `forRootAsync({ imports, useFactory, inject, routePrefix })` works too. Note that `routePrefix` must be static in async mode, because routes are registered before async factories run.
 
+### Enabling & disabling
+
+The panel resolves its on/off state with this precedence (first match wins):
+
+1. **`NEST_DEBUG_PANEL_ENABLED` environment variable** — when set to a recognized boolean, it overrides everything below, so you can flip the panel on or off **without changing code**.
+2. **The `enabled` option** passed to `forRoot()` / `forRootAsync()`.
+3. **Default** — on when `NODE_ENV !== 'production'`, off otherwise.
+
+```bash
+NEST_DEBUG_PANEL_ENABLED=true   # force ON anywhere — even in production
+NEST_DEBUG_PANEL_ENABLED=false  # force OFF anywhere — even in development
+# (unset)                       # fall back to the `enabled` option, then NODE_ENV
+```
+
+Accepted values are case-insensitive: `true` / `1` / `yes` / `on` enable it, `false` / `0` / `no` / `off` disable it. Anything unrecognized (or an unset/empty var) is ignored, so the option and `NODE_ENV` default still apply. When disabled, the interceptor passes every request straight through, nothing is instrumented or stored, and the dashboard routes return 404.
+
 To exclude routes from profiling, use the `ignore` option (`'/health'`, globs like `'/static/*'`, or RegExps) or put `@DebugIgnore()` on a controller or handler. The panel's own routes are always excluded.
 
 ## Works with any ORM, any database
@@ -258,7 +287,7 @@ Build your own frontend or tooling on top of it if you like.
 
 ## Security
 
-- Off in production automatically, unless you explicitly set `enabled: true`. When off, the interceptor passes requests straight through and the debug routes return 404.
+- Off in production automatically, unless you set `enabled: true` or `NEST_DEBUG_PANEL_ENABLED=true` (see [Enabling & disabling](#enabling--disabling)). When off, the interceptor passes requests straight through and the debug routes return 404.
 - Sensitive body keys and headers are redacted before anything is stored.
 - Gate the dashboard with `authorize: (req) => req.user?.isAdmin === true`.
 - Profiles live in process memory by default and never leave your machine.

example/app.module.ts

@@ -1,6 +1,7 @@
 import { Module } from '@nestjs/common';
 import { DebugModule, FetchPlugin } from '../src';
 import { DemoController } from './demo.controller';
+import { DemoGateway } from './demo.gateway';
 import { FakeDatabaseService } from './fake-database.service';
 
 @Module({
@@ -23,6 +24,6 @@ import { FakeDatabaseService } from './fake-database.service';
     }),
   ],
   controllers: [DemoController],
-  providers: [FakeDatabaseService],
+  providers: [FakeDatabaseService, DemoGateway],
 })
 export class AppModule {}

example/demo.gateway.ts

@@ -0,0 +1,52 @@
+import {
+  ConnectedSocket,
+  MessageBody,
+  SubscribeMessage,
+  WebSocketGateway,
+} from '@nestjs/websockets';
+import type { Socket } from 'socket.io';
+import { FakeDatabaseService } from './fake-database.service';
+
+/**
+ * Socket.io gateway for the demo. No debug-panel setup here at all — every
+ * @SubscribeMessage handler is captured automatically (just like HTTP), and the
+ * SQL each one runs shows up in the panel with N+1 detection.
+ */
+@WebSocketGateway({ cors: { origin: '*' } })
+export class DemoGateway {
+  constructor(private readonly db: FakeDatabaseService) {}
+
+  @SubscribeMessage('users.list')
+  async listUsers(): Promise<{ users: Array<{ id: number; name: string }> }> {
+    const users = await this.db.findUsers();
+    return { users };
+  }
+
+  @SubscribeMessage('users.get')
+  async getUser(@MessageBody() payload: { id: number }): Promise<{ user: unknown }> {
+    const user = await this.db.findUser(Number(payload?.id ?? 1));
+    return { user };
+  }
+
+  // Triggers the N+1 detector — one query per user, captured on the Sockets page.
+  @SubscribeMessage('users.withPosts')
+  async withPosts(): Promise<{ users: unknown[] }> {
+    const users = await this.db.findUsersWithPosts();
+    return { users };
+  }
+
+  @SubscribeMessage('chat.send')
+  async send(
+    @MessageBody() payload: { room?: string; text: string },
+    @ConnectedSocket() client: Socket,
+  ): Promise<{ delivered: true }> {
+    await this.db.findUser(1); // pretend we persist the message
+    if (payload?.room) client.to(payload.room).emit('chat.new', payload);
+    return { delivered: true };
+  }
+
+  @SubscribeMessage('boom')
+  fail(): never {
+    throw new Error('socket handler blew up on purpose');
+  }
+}

example/main.ts

@@ -1,23 +1,52 @@
 import { NestFactory } from '@nestjs/core';
+import { IoAdapter } from '@nestjs/platform-socket.io';
+import { io } from 'socket.io-client';
 import { AppModule } from './app.module';
 
+/**
+ * Fires a few socket events at our own server so the panel has socket data to
+ * show as soon as you open it — no separate command needed. Dev-demo only.
+ */
+async function driveSocketDemo(port: number): Promise<void> {
+  const socket = io(`http://localhost:${port}`, { transports: ['websocket'] });
+  const emit = (event: string, payload?: unknown): Promise<unknown> =>
+    new Promise((resolve) => {
+      const timer = setTimeout(() => resolve('(no ack)'), 1000);
+      socket.emit(event, payload, (ack: unknown) => {
+        clearTimeout(timer);
+        resolve(ack);
+      });
+    });
+
+  await new Promise<void>((resolve) => socket.on('connect', () => resolve()));
+  await emit('users.list');
+  await emit('users.get', { id: 2 });
+  await emit('users.withPosts'); // N+1 demo
+  await emit('chat.send', { text: 'hello', password: 's3cret' });
+  socket.disconnect();
+}
+
 async function bootstrap(): Promise<void> {
   const app = await NestFactory.create(AppModule);
+  app.useWebSocketAdapter(new IoAdapter(app)); // enable socket.io
   const port = Number(process.env.PORT ?? 3000);
   await app.listen(port);
+
+  // Populate some socket events automatically (dev demo).
+  void driveSocketDemo(port).catch(() => undefined);
+
   console.log(`
   Example app:     http://localhost:${port}
-  Debug dashboard: http://localhost:${port}/__debug
+  Debug panel:     http://localhost:${port}/__debug   (HTTP + Socket, filter at the top)
 
-  Try:
+  Try more HTTP:
     curl http://localhost:${port}/users
-    curl http://localhost:${port}/users/1
-    curl -X POST http://localhost:${port}/users -H 'content-type: application/json' -d '{"name":"Joan","password":"s3cret"}'
     curl http://localhost:${port}/n-plus-one   # N+1 detection demo
-    curl http://localhost:${port}/slow         # slow query + slow request
-    curl http://localhost:${port}/external     # outgoing HTTP capture
     curl http://localhost:${port}/boom         # exception capture
-  `);
+
+  Socket events are fired automatically at startup and show up in the panel
+  under the "Socket" filter — no extra command, no gateway setup needed.
+`);
 }
 
 void bootstrap();