flow-debugger 1.0.0

package/example/server.ts

@@ -0,0 +1,234 @@
+// ─────────────────────────────────────────────────────────────
+// flow-debugger — Example Server
+// Simulates real-world APIs with DB, Redis, and external calls
+// Demonstrates all features: tracing, root cause, timeline, dashboard
+// ─────────────────────────────────────────────────────────────
+
+import express from 'express';
+import { flowDebugger } from '../src/middleware/express';
+
+const app = express();
+app.use(express.json());
+
+// ─── Initialize Flow Debugger ─────────────────────────────
+const debugger_ = flowDebugger({
+    slowThreshold: 300,
+    slowQueryThreshold: 300,
+    enableTimeline: true,
+    enableDashboard: true,
+    samplingRate: 1, // 100% for testing
+});
+
+app.use(debugger_.middleware);
+
+// ─── Simulated DB / Redis helpers ─────────────────────────
+function simulateDelay(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+function randomBetween(min: number, max: number): number {
+    return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+
+// ─── API Routes ───────────────────────────────────────────
+
+// 1. Login — simulates DB + Redis + JWT
+app.post('/api/login', async (req, res) => {
+    const tracer = req.tracer!;
+
+    try {
+        // Step 1: Find user in DB
+        const user = await tracer.step('DB find user', async () => {
+            await simulateDelay(randomBetween(5, 25));
+            return { id: 'u_123', name: 'Saurabh', email: 'saurabh@test.com' };
+        }, { service: 'mongo' });
+
+        // Step 2: Verify password
+        await tracer.step('Verify password', async () => {
+            await simulateDelay(randomBetween(2, 10));
+            return true;
+        }, { service: 'internal' });
+
+        // Step 3: Cache session in Redis
+        await tracer.step('Redis set session', async () => {
+            await simulateDelay(randomBetween(1, 8));
+            return 'OK';
+        }, { service: 'redis' });
+
+        // Step 4: Generate JWT
+        const token = await tracer.step('JWT generate', async () => {
+            await simulateDelay(randomBetween(1, 5));
+            return 'eyJhbGciOiJIUzI1NiJ9.mock_token';
+        }, { service: 'internal' });
+
+        res.json({ success: true, token, user });
+    } catch (err: any) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+// 2. Orders — simulates slow DB query
+app.get('/api/orders', async (req, res) => {
+    const tracer = req.tracer!;
+
+    try {
+        // Slow query simulation
+        const orders = await tracer.step('DB query orders', async () => {
+            const delay = randomBetween(100, 600); // Sometimes slow!
+            await simulateDelay(delay);
+            return [
+                { id: 'ord_1', amount: 2500, status: 'completed' },
+                { id: 'ord_2', amount: 1800, status: 'pending' },
+            ];
+        }, { service: 'postgres', metadata: { sql: 'SELECT * FROM orders WHERE user_id = ?' } });
+
+        // Cache result
+        await tracer.step('Redis cache orders', async () => {
+            await simulateDelay(randomBetween(1, 5));
+            return 'OK';
+        }, { service: 'redis' });
+
+        res.json({ orders });
+    } catch (err: any) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+// 3. Dashboard — simulates multiple DB queries
+app.get('/api/dashboard', async (req, res) => {
+    const tracer = req.tracer!;
+
+    try {
+        const [stats, recentOrders, notifications] = await Promise.all([
+            tracer.step('MySQL stats query', async () => {
+                await simulateDelay(randomBetween(10, 40));
+                return { totalUsers: 1200, totalOrders: 890, revenue: 125000 };
+            }, { service: 'mysql', metadata: { sql: 'SELECT COUNT(*) FROM users' } }),
+
+            tracer.step('Postgres recent orders', async () => {
+                await simulateDelay(randomBetween(15, 50));
+                return [{ id: 'ord_1', amount: 500 }];
+            }, { service: 'postgres', metadata: { sql: 'SELECT * FROM orders ORDER BY created_at DESC LIMIT 10' } }),
+
+            tracer.step('Redis get notifications', async () => {
+                await simulateDelay(randomBetween(2, 8));
+                return [{ msg: 'New order received' }];
+            }, { service: 'redis' }),
+        ]);
+
+        res.json({ stats, recentOrders, notifications });
+    } catch (err: any) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+// 4. User Profile — simulates Redis failure
+app.get('/api/profile/:id', async (req, res) => {
+    const tracer = req.tracer!;
+
+    try {
+        // Try Redis cache first
+        let cached: any = null;
+        try {
+            cached = await tracer.step('Redis get cache', async () => {
+                // Randomly fail to simulate Redis issues
+                if (Math.random() > 0.5) {
+                    throw new Error('ECONNREFUSED: Redis connection refused');
+                }
+                await simulateDelay(randomBetween(1, 5));
+                return null; // cache miss
+            }, { service: 'redis' });
+        } catch {
+            // Redis failed, fall through to DB
+        }
+
+        // Fetch from DB
+        const user = await tracer.step('Mongo find user', async () => {
+            await simulateDelay(randomBetween(8, 30));
+            return { id: req.params.id, name: 'Saurabh', role: 'admin' };
+        }, { service: 'mongo' });
+
+        res.json({ user, fromCache: false });
+    } catch (err: any) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+// 5. Payment — simulates external API call with timeout potential
+app.post('/api/payment', async (req, res) => {
+    const tracer = req.tracer!;
+
+    try {
+        // Validate in DB
+        await tracer.step('MySQL validate order', async () => {
+            await simulateDelay(randomBetween(5, 20));
+            return true;
+        }, { service: 'mysql', metadata: { sql: 'SELECT * FROM orders WHERE id = ? AND status = ?' } });
+
+        // Call external payment gateway
+        await tracer.step('Payment Gateway API', async () => {
+            const delay = randomBetween(50, 400);
+            await simulateDelay(delay);
+            if (delay > 350) throw new Error('Gateway timeout');
+            return { transactionId: 'txn_abc123', status: 'success' };
+        }, { service: 'external', timeout: 5000 });
+
+        // Update DB
+        await tracer.step('MySQL update payment', async () => {
+            await simulateDelay(randomBetween(5, 15));
+            return true;
+        }, { service: 'mysql', metadata: { sql: 'UPDATE orders SET payment_status = ? WHERE id = ?' } });
+
+        // Clear cache
+        await tracer.step('Redis clear cache', async () => {
+            await simulateDelay(randomBetween(1, 5));
+            return 'OK';
+        }, { service: 'redis' });
+
+        res.json({ success: true, transactionId: 'txn_abc123' });
+    } catch (err: any) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+// 6. Search — simulates heavy query
+app.get('/api/search', async (req, res) => {
+    const tracer = req.tracer!;
+    const q = req.query.q || 'test';
+
+    try {
+        const results = await tracer.step('Postgres full-text search', async () => {
+            // Simulate a potentially slow full-text search
+            const delay = randomBetween(50, 800);
+            await simulateDelay(delay);
+            return [{ id: 1, title: `Result for: ${q}` }];
+        }, { service: 'postgres', metadata: { sql: `SELECT * FROM products WHERE to_tsvector(name) @@ to_tsquery('${q}')` } });
+
+        res.json({ results, count: results.length });
+    } catch (err: any) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+// ─── Start Server ─────────────────────────────────────────
+const PORT = process.env.PORT || 3500;
+app.listen(PORT, () => {
+    console.log('');
+    console.log('  ┌──────────────────────────────────────────────────┐');
+    console.log('  │                                                  │');
+    console.log('  │   🔍 Flow Debugger — Example Server              │');
+    console.log(`  │   Server:    http://localhost:${PORT}               │`);
+    console.log(`  │   Dashboard: http://localhost:${PORT}/__debugger/dashboard │`);
+    console.log(`  │   API:       http://localhost:${PORT}/__debugger    │`);
+    console.log('  │                                                  │');
+    console.log('  │   Test endpoints:                                │');
+    console.log('  │   POST /api/login        (DB + Redis + JWT)      │');
+    console.log('  │   GET  /api/orders       (Slow DB query)         │');
+    console.log('  │   GET  /api/dashboard    (Multi-service)         │');
+    console.log('  │   GET  /api/profile/:id  (Redis failures)        │');
+    console.log('  │   POST /api/payment      (External API)          │');
+    console.log('  │   GET  /api/search?q=x   (Heavy Postgres)        │');
+    console.log('  │                                                  │');
+    console.log('  └──────────────────────────────────────────────────┘');
+    console.log('');
+});

package/jest.config.js

@@ -0,0 +1,8 @@
+module.exports = {
+    preset: 'ts-jest',
+    testEnvironment: 'node',
+    roots: ['<rootDir>/tests'],
+    testMatch: ['**/*.test.ts'],
+    moduleFileExtensions: ['ts', 'js', 'json'],
+    collectCoverageFrom: ['src/**/*.ts'],
+};

package/package.json

@@ -0,0 +1,110 @@
+{
+    "name": "flow-debugger",
+    "version": "1.0.0",
+    "description": "Production-safe flow-level debugging SDK. Traces requests, measures timing, classifies errors, detects root causes, and provides endpoint analytics with a live dashboard.",
+    "main": "dist/cjs/index.js",
+    "module": "dist/esm/index.js",
+    "types": "dist/types/index.d.ts",
+    "exports": {
+        ".": {
+            "require": "./dist/cjs/index.js",
+            "import": "./dist/esm/index.js",
+            "types": "./dist/types/index.d.ts"
+        },
+        "./express": {
+            "require": "./dist/cjs/middleware/express.js",
+            "import": "./dist/esm/middleware/express.js",
+            "types": "./dist/types/middleware/express.d.ts"
+        },
+        "./mongo": {
+            "require": "./dist/cjs/integrations/mongo.js",
+            "import": "./dist/esm/integrations/mongo.js",
+            "types": "./dist/types/integrations/mongo.d.ts"
+        },
+        "./mysql": {
+            "require": "./dist/cjs/integrations/mysql.js",
+            "import": "./dist/esm/integrations/mysql.js",
+            "types": "./dist/types/integrations/mysql.d.ts"
+        },
+        "./postgres": {
+            "require": "./dist/cjs/integrations/postgres.js",
+            "import": "./dist/esm/integrations/postgres.js",
+            "types": "./dist/types/integrations/postgres.d.ts"
+        },
+        "./redis": {
+            "require": "./dist/cjs/integrations/redis.js",
+            "import": "./dist/esm/integrations/redis.js",
+            "types": "./dist/types/integrations/redis.d.ts"
+        }
+    },
+    "scripts": {
+        "build": "npm run build:cjs && npm run build:esm && npm run build:types",
+        "build:cjs": "tsc --project tsconfig.cjs.json",
+        "build:esm": "tsc --project tsconfig.esm.json",
+        "build:types": "tsc --project tsconfig.types.json",
+        "dev": "ts-node example/server.ts",
+        "test": "jest --config jest.config.js",
+        "prepublishOnly": "npm run build"
+    },
+    "keywords": [
+        "debugger",
+        "trace",
+        "flow",
+        "monitoring",
+        "performance",
+        "analytics",
+        "root-cause",
+        "express",
+        "mongodb",
+        "mysql",
+        "postgresql",
+        "redis",
+        "apm",
+        "observability"
+    ],
+    "author": "",
+    "license": "MIT",
+    "peerDependencies": {
+        "express": "^4.0.0 || ^5.0.0",
+        "mongoose": "^6.0.0 || ^7.0.0 || ^8.0.0",
+        "mysql2": "^2.0.0 || ^3.0.0",
+        "pg": "^8.0.0",
+        "redis": "^4.0.0",
+        "axios": "^0.27.0 || ^1.0.0"
+    },
+    "peerDependenciesMeta": {
+        "express": {
+            "optional": true
+        },
+        "mongoose": {
+            "optional": true
+        },
+        "mysql2": {
+            "optional": true
+        },
+        "pg": {
+            "optional": true
+        },
+        "redis": {
+            "optional": true
+        },
+        "axios": {
+            "optional": true
+        }
+    },
+    "devDependencies": {
+        "@types/express": "^4.17.21",
+        "@types/jest": "^29.5.12",
+        "@types/node": "^20.11.19",
+        "@types/pg": "^8.10.9",
+        "express": "^4.18.2",
+        "jest": "^29.7.0",
+        "mongoose": "^8.1.0",
+        "mysql2": "^3.7.0",
+        "pg": "^8.11.3",
+        "ts-jest": "^29.1.2",
+        "ts-node": "^10.9.2",
+        "typescript": "^5.3.3",
+        "autocannon": "^7.15.0"
+    }
+}

package/portfolio-repo/README.md

@@ -0,0 +1,182 @@
+# 🚀 Sannu Kumar - Full-Stack & Systems Engineer
+
+> **Portfolio:** [sannu-portfolio.vercel.app](https://sannu-portfolio.vercel.app/portfolio) | **Catalog:** [Projects Catalog](https://sannu-portfolio.vercel.app/portfolio/projects)
+
+Welcome to my professional laboratory. Here, I build production-grade NPM packages, enterprise-scale web applications, and high-performance mobile solutions.
+
+---
+
+
+## 💎 Featured NPM Packages
+
+### 📊 1. API Response Monitor
+**Debug production API issues in seconds with request tracing and slow endpoint detection.**
+
+[![NPM Version](https://img.shields.io/npm/v/@sannuk792/api-response-monitor?color=brightgreen)](https://www.npmjs.com/package/@sannuk792/api-response-monitor)
+[![NPM Downloads](https://img.shields.io/npm/dm/@sannuk792/api-response-monitor)](https://www.npmjs.com/package/@sannuk792/api-response-monitor)
+
+![API Monitor Dashboard](./APIRESPONSE%20DASH.png)
+
+### � Workflow Overview
+```mermaid
+graph LR
+    A[Request] --> B[Generate RequestID]
+    B --> C[Intercept Response]
+    C --> D[Calculate Metrics]
+    D --> E[Async Logging/Storage]
+    E --> F[Dashboard/Analytics]
+```
+
+- **Production Tracing**: Auto-generated `requestId` in every response.
+- **Protocol Metadata**: Built-in SDK version, platform, and service tagging for microservices.
+- **Hardened Stability**: Verified with a **14-point stress test** (100 req/sec, circular ref protection, middleware isolation).
+- **Advanced Monitoring**: Built-in slow endpoint detection & health metrics.
+- **Fail-Safe Design**: Monitoring logic never blocks or crashes your API.
+- **Non-Blocking**: Non-allocation fast paths with ~0.2ms overhead.
+
+
+### ⛑️ Maintained actively.
+**Bug fixes usually within 24–48 hours.**
+
+
+**[View on NPM](https://www.npmjs.com/package/@sannuk792/api-response-monitor)** | **[Source Code](https://github.com/sannuk79/ApiMonitor)**
+
+---
+
+### 🛡️ 2. Payload Guard
+**Lightweight, zero-dependency shape-based filtering & sanitization.**
+
+[![NPM Version](https://img.shields.io/npm/v/payload-guard-filter?color=blue)](https://www.npmjs.com/package/payload-guard-filter)
+
+![Payload Guard Workflow](./PAYLOAD.png)
+
+### �️ Workflow Overview
+```mermaid
+graph LR
+    A[Request] --> B(Gatekeeper)
+    B --> C{Shape Check}
+    C -- Valid --> D[Redact & Clean]
+    C -- Invalid --> E[Strict Error / Fail Safe]
+    D --> F[Secure Response]
+    E --> F
+    F --> G((Metrics))
+```
+
+- **Shape-based Filtering**: Define what you want, auto-remove everything else.
+- **Sensitive Protection**: `password`, `token`, `secret` auto-redacted.
+- **High Performance**: Optimized schema compilation for sub-millisecond execution.
+
+**[View on NPM](https://www.npmjs.com/package/payload-guard-filter)**
+
+---
+
+### 🔍 3. Flow Debugger
+**Production-safe request tracing with root cause detection and live analytics dashboard.**
+
+[![NPM Version](https://img.shields.io/npm/v/flow-debugger?color=purple)](https://www.npmjs.com/package/flow-debugger)
+[![GitHub](https://img.shields.io/badge/GitHub-debugerpackages-purple)](https://github.com/sannuk79/debugerpackages)
+
+![Flow Debugger Architecture](https://via.placeholder.com/800x400/1a1a2e/7c3aed?text=Flow+Debugger+Dashboard)
+
+### 🔄 Workflow Overview
+```mermaid
+graph LR
+    A[Request] --> B[Generate TraceID]
+    B --> C[Step-by-Step Tracking]
+    C --> D[Auto-Classify: INFO/WARN/ERROR/CRITICAL]
+    D --> E[Root Cause Detection]
+    E --> F[Analytics Dashboard]
+    F --> G[Search & Filter]
+```
+
+**Key Features:**
+- **Auto-Instrumentation**: MongoDB, MySQL, PostgreSQL, Redis, Fetch, Axios — zero code changes
+- **External API Tracing**: Stripe, Razorpay, SendGrid, Twilio auto-tagged
+- **Root Cause Detection**: Timeout → Failure → Slow bottleneck algorithm
+- **Error Stack Preview**: Shows `errorFile:line` in dashboard (e.g., `auth.service.ts:42`)
+- **Payload Size Detection**: Warns on large payloads (>1MB) slowing requests
+- **Environment Tagging**: Filter traces by dev/staging/production
+- **Trace Search**: Search by traceId, endpoint, error message
+- **Live Dashboard**: Real-time analytics at `/__debugger/dashboard`
+- **Production-Safe**: Never blocks requests, all try/catch wrapped
+
+**Performance:**
+- **Load Tested**: 56,000 requests in 10s (100 concurrent connections)
+- **Throughput**: 5,600 req/sec
+- **Overhead**: <1ms per request
+
+**[View on NPM](https://www.npmjs.com/package/flow-debugger)** | **[Source Code](https://github.com/sannuk79/debugerpackages)**
+
+---
+
+## 📂 Project Catalog
+
+A selection of production-grade applications and experimental prototypes.
+
+| Project | Category | Description | Tech Stack |
+|:---|:---|:---|:---|
+| **DRIVERRUNNER** | Mobile | Complete Ride Sharing Platform with real-time tracking & payments. | Node, Mongo, RN, Socket.IO |
+| **SHOPMIND AI** | Web | AI-powered price comparison with Rust-accelerated scraping. | Next.js 15, FastAPI, Rust |
+| **URBANCRUISE LMS** | Web | Enterprise Lead Management System with real-time visualization. | Next.js, Express, MySQL |
+| **TASKVISTA** | Web | Team Management Dashboard for developer communities. | React, Kendo UI, Tailwind |
+| **BIOMETRIC AUTH** | Tools | WebAuthn system for passwordless fingerprint login. | WebAuthn, React 19, Security |
+| **API MONITOR** | Tools | The official NPM package for API latency and health tracking. | NPM, Node.js, Metrics |
+
+### ✨ Project Deep Dives
+
+#### 🚕 [DriverRunner](#)
+A comprehensive ride-hailing solution featuring 3 separate apps. Includes OTP-based authentication, real-time driver tracking (React Native Maps), and live booking systems via Socket.IO.
+
+#### 🤖 [ShopMind AI](https://shopmind-ai.vercel.app/)
+Intelligent price comparison platform. Uses Rust-accelerated scraping engines for speed and WebAuthn for biometric fingerprint login.
+
+#### 📊 [UrbanCruise LMS](https://lms-leadmangsystem.vercel.app/)
+Enterprise-grade lead tracking system. Handles multi-source collection (Meta, Google Ads) with real-time dashboards using Recharts and role-based access control.
+
+---
+
+## ⚡ Performance Benchmarks
+
+### 🛡️ Payload Guard (Production Scale)
+| Benchmark | ops/sec | avg (ms) |
+|-----------|---------|----------|
+| **Small payload** | 449,365 | **0.0022ms** |
+| **Medium payload** | 7,791 | **0.1284ms** |
+| **Large payload** | 246 | **4.0724ms** |
+
+### 📊 API Monitor (Middleware Overhead)
+| Metric | Full Mode | Minimal Mode |
+|-----------|---------|----------|
+| **Latency** | ~0.18ms | **<0.05ms** |
+| **Throughput** | 50k+ RPM | 100k+ RPM |
+
+---
+
+## 🛠️ Combined Usage
+
+Build a hardened, monitored, and debuggable API:
+```javascript
+const { apiMonitor } = require('@sannuk792/api-response-monitor');
+const { guard } = require('payload-guard-filter');
+const { flowDebugger } = require('flow-debugger');
+
+const debugger_ = flowDebugger({ environment: 'production' });
+
+app.use(apiMonitor({ mode: 'minimal' }));  // Global Monitoring
+app.use(debugger_.middleware);              // Request Tracing
+
+app.post('/api/secure-data', (req, res) => {
+  const safeBody = userShape(req.body);     // Precise Filtering
+  res.json(safeBody);
+});
+
+// Dashboard: http://localhost:3000/__debugger/dashboard
+```
+
+---
+
+<p align="center">
+  Connect with me on <strong>[Portfolio](https://sannu-portfolio.vercel.app/portfolio)</strong>
+  <br>
+  Made with ❤️ for High-Performance Systems
+</p>