@vipin733/nodescope 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vipin
+
+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

@@ -0,0 +1,412 @@
+# @vipin733/nodescope
+
+> 🔭 A Laravel Telescope-inspired debugging and monitoring package for Node.js and Bun applications
+
+[![npm version](https://img.shields.io/npm/v/@vipin733/nodescope.svg)](https://www.npmjs.com/package/@vipin733/nodescope)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+## ✨ Features
+
+- 📊 **Real-time Monitoring** - Watch requests, queries, and logs as they happen via WebSocket streaming
+- 💾 **Multiple Storage Backends** - Choose from in-memory, SQLite, PostgreSQL, or MySQL
+- 🔌 **Framework Agnostic** - First-class support for Express, Hono, Fastify, and vanilla Node.js
+- 🎨 **Beautiful Dashboard** - React-based UI with dark/light mode (coming soon)
+- 🚀 **Zero Configuration** - Sensible defaults, just install and go
+- 🔍 **Comprehensive Watchers** - Track requests, database queries, logs, exceptions, and more
+- ⚡ **Blazing Fast** - Minimal performance overhead, designed for production use
+- 🌐 **WebSocket Support** - Real-time data streaming to connected clients
+
+## 📦 Installation
+
+```bash
+npm install @vipin733/nodescope
+# or
+pnpm add @vipin733/nodescope
+# or
+yarn add @vipin733/nodescope
+# or
+bun add @vipin733/nodescope
+```
+
+### Optional Database Drivers
+
+NodeScope supports multiple storage backends. Install the driver you need:
+
+```bash
+# SQLite
+npm install better-sqlite3
+
+# PostgreSQL
+npm install pg
+
+# MySQL
+npm install mysql2
+```
+
+## 🚀 Quick Start
+
+### Express.js
+
+```typescript
+import express from 'express';
+import { NodeScope } from '@vipin733/nodescope';
+
+const app = express();
+
+// Initialize NodeScope
+const nodescope = new NodeScope({
+  storage: 'sqlite',
+  storagePath: './nodescope.db',
+  dashboardPath: '/_debug',
+  enabled: process.env.NODE_ENV === 'development',
+});
+
+// Mount NodeScope middleware and routes
+app.use(nodescope.middleware());
+nodescope.mountExpressRoutes(app);
+
+// Your app routes
+app.get('/', (req, res) => {
+  res.send('Hello World!');
+});
+
+// Start server
+app.listen(3000, () => {
+  console.log('Server running on http://localhost:3000');
+  console.log('Dashboard available at http://localhost:3000/_debug');
+});
+```
+
+### Hono (Bun/Node)
+
+```typescript
+import { Hono } from 'hono';
+import { createHonoMiddleware } from '@vipin733/nodescope';
+
+const app = new Hono();
+
+// Add NodeScope middleware
+app.use('*', createHonoMiddleware({ 
+  storage: 'memory',
+  dashboardPath: '/_debug'
+}));
+
+// Your app routes
+app.get('/', (c) => c.text('Hello Hono!'));
+
+export default app;
+```
+
+### Fastify
+
+```typescript
+import Fastify from 'fastify';
+import { createFastifyPlugin } from '@vipin733/nodescope';
+
+const fastify = Fastify({ logger: true });
+
+// Register NodeScope plugin
+await fastify.register(createFastifyPlugin, {
+  storage: 'memory',
+  dashboardPath: '/_debug',
+});
+
+// Your app routes
+fastify.get('/', async (request, reply) => {
+  return { hello: 'world' };
+});
+
+await fastify.listen({ port: 3000 });
+```
+
+## ⚙️ Configuration
+
+### Constructor Options
+
+```typescript
+interface NodeScopeOptions {
+  // Enable/disable NodeScope (default: true)
+  enabled?: boolean;
+  
+  // Storage backend: 'memory' | 'sqlite' | 'postgresql' | 'mysql'
+  storage?: StorageType;
+  
+  // Storage configuration
+  storagePath?: string; // For SQLite
+  databaseUrl?: string; // For PostgreSQL/MySQL
+  
+  // Dashboard configuration
+  dashboardPath?: string; // Default: '/_debug'
+  
+  // Data retention
+  maxEntries?: number; // Default: 1000
+  pruneInterval?: number; // In milliseconds, default: 60000
+  
+  // WebSocket configuration
+  wsPath?: string; // Default: '/_debug/ws'
+  
+  // Watchers to enable
+  watchers?: {
+    request?: boolean;
+    query?: boolean;
+    cache?: boolean;
+    log?: boolean;
+    exception?: boolean;
+    httpClient?: boolean;
+    event?: boolean;
+    job?: boolean;
+  };
+}
+```
+
+### Example Configurations
+
+#### Development (In-Memory)
+
+```typescript
+const nodescope = new NodeScope({
+  storage: 'memory',
+  maxEntries: 500,
+});
+```
+
+#### Production (PostgreSQL)
+
+```typescript
+const nodescope = new NodeScope({
+  storage: 'postgresql',
+  databaseUrl: process.env.DATABASE_URL,
+  maxEntries: 5000,
+  pruneInterval: 300000, // Prune every 5 minutes
+  enabled: process.env.ENABLE_NODESCOPE === 'true',
+});
+```
+
+#### SQLite for Local Development
+
+```typescript
+const nodescope = new NodeScope({
+  storage: 'sqlite',
+  storagePath: './data/nodescope.db',
+  dashboardPath: '/_telescope',
+});
+```
+
+## 📊 Watchers
+
+NodeScope includes the following watchers to monitor different aspects of your application:
+
+| Watcher | Description | Status |
+|---------|-------------|--------|
+| **Request** | HTTP requests and responses with timing | ✅ Active |
+| **Query** | Database queries with execution time | ✅ Active |
+| **Cache** | Cache operations (Redis, memory) | 🚧 Coming Soon |
+| **Log** | Console and custom logs | ✅ Active |
+| **Exception** | Errors with stack traces | ✅ Active |
+| **HTTP Client** | Outgoing HTTP requests | 🚧 Coming Soon |
+| **Event** | Application events | 🚧 Coming Soon |
+| **Job** | Background job processing | 🚧 Coming Soon |
+
+## 💾 Storage Options
+
+### Memory (Development)
+
+Fast, in-memory storage. **Not recommended for production** as data is lost on restart.
+
+```typescript
+{ storage: 'memory' }
+```
+
+### SQLite (Development/Small Production)
+
+Single-file database, perfect for local development and small production deployments.
+
+```typescript
+{
+  storage: 'sqlite',
+  storagePath: './nodescope.db'
+}
+```
+
+### PostgreSQL (Production)
+
+Production-ready with connection pooling and excellent performance.
+
+```typescript
+{
+  storage: 'postgresql',
+  databaseUrl: 'postgresql://user:password@localhost:5432/mydb'
+}
+```
+
+### MySQL (Production)
+
+Production-ready MySQL support with connection pooling.
+
+```typescript
+{
+  storage: 'mysql',
+  databaseUrl: 'mysql://user:password@localhost:3306/mydb'
+}
+```
+
+## 🔍 Manual Logging
+
+You can manually log events to NodeScope:
+
+```typescript
+import { nodescope } from '@vipin733/nodescope';
+
+// Log a request
+nodescope.record('request', {
+  method: 'GET',
+  path: '/api/users',
+  statusCode: 200,
+  duration: 145,
+});
+
+// Log a database query
+nodescope.record('query', {
+  sql: 'SELECT * FROM users WHERE id = ?',
+  bindings: [1],
+  duration: 12,
+});
+
+// Log an exception
+nodescope.record('exception', {
+  message: 'User not found',
+  stack: error.stack,
+});
+
+// Log a custom log
+nodescope.record('log', {
+  level: 'info',
+  message: 'User logged in',
+  context: { userId: 123 },
+});
+```
+
+## 🌐 WebSocket API
+
+NodeScope provides real-time updates via WebSocket. Connect to the WebSocket endpoint to receive live data:
+
+```javascript
+const ws = new WebSocket('ws://localhost:3000/_debug/ws');
+
+ws.onmessage = (event) => {
+  const data = JSON.parse(event.data);
+  console.log('New entry:', data);
+};
+```
+
+## 🔒 Security Considerations
+
+**⚠️ Important**: NodeScope can expose sensitive application data. Always ensure proper security measures:
+
+1. **Never enable in production** without authentication
+2. **Use environment variables** to control when it's enabled
+3. **Restrict access** to the dashboard endpoint using middleware
+4. **Consider IP whitelisting** for production debugging
+
+### Example: Protect Dashboard with Auth
+
+```typescript
+// Express example
+app.use('/_debug', (req, res, next) => {
+  const auth = req.headers.authorization;
+  if (auth !== 'Bearer YOUR_SECRET_TOKEN') {
+    return res.status(401).send('Unauthorized');
+  }
+  next();
+});
+
+app.use(nodescope.middleware());
+nodescope.mountExpressRoutes(app);
+```
+
+## 📖 API Reference
+
+### `NodeScope` Class
+
+#### Constructor
+
+```typescript
+new NodeScope(options?: NodeScopeOptions)
+```
+
+#### Methods
+
+- `middleware()` - Returns middleware function for your framework
+- `record(type: string, data: any)` - Manually record an entry
+- `getEntries(type?: string, limit?: number)` - Retrieve stored entries
+- `clear()` - Clear all stored entries
+- `mountExpressRoutes(app: Express)` - Mount Express routes (Express only)
+
+### Framework Helpers
+
+#### Express
+
+```typescript
+import { NodeScope } from '@vipin733/nodescope';
+const nodescope = new NodeScope(options);
+app.use(nodescope.middleware());
+nodescope.mountExpressRoutes(app);
+```
+
+#### Hono
+
+```typescript
+import { createHonoMiddleware } from '@vipin733/nodescope';
+app.use('*', createHonoMiddleware(options));
+```
+
+#### Fastify
+
+```typescript
+import { createFastifyPlugin } from '@vipin733/nodescope';
+await fastify.register(createFastifyPlugin, options);
+```
+
+## 🛠️ Development
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/nodescope.git
+cd nodescope
+
+# Install dependencies
+npm install
+
+# Build the package
+npm run build
+
+# Run tests
+npm test
+
+# Watch mode for development
+npm run dev
+```
+
+## 📝 Examples
+
+Check out the [examples](https://github.com/yourusername/nodescope/tree/main/examples) directory for complete working examples:
+
+- Express.js example
+- Hono example
+- Fastify example
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 📄 License
+
+MIT © [Your Name]
+
+## 🙏 Acknowledgments
+
+Inspired by [Laravel Telescope](https://laravel.com/docs/telescope) - the amazing debugging assistant for Laravel applications.
+
+---
+
+**Made with ❤️ for the Node.js and Bun communities**

package/dist/chunk-6H665NNC.js

@@ -0,0 +1,198 @@
+import {
+  defaultEntryCounts
+} from "./chunk-OF6NKXP5.js";
+
+// src/storage/postgresql.ts
+var PostgreSQLStorage = class {
+  pool;
+  connectionString;
+  constructor(connectionString) {
+    this.connectionString = connectionString;
+  }
+  async initialize() {
+    const { Pool } = await import("pg");
+    this.pool = new Pool({ connectionString: this.connectionString });
+    await this.pool.query(`
+      CREATE TABLE IF NOT EXISTS nodescope_entries (
+        id TEXT PRIMARY KEY,
+        batch_id TEXT NOT NULL,
+        type TEXT NOT NULL,
+        content JSONB NOT NULL,
+        tags JSONB NOT NULL,
+        created_at TIMESTAMPTZ NOT NULL,
+        duration INTEGER,
+        memory_usage INTEGER
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_nodescope_entries_batch_id ON nodescope_entries(batch_id);
+      CREATE INDEX IF NOT EXISTS idx_nodescope_entries_type ON nodescope_entries(type);
+      CREATE INDEX IF NOT EXISTS idx_nodescope_entries_created_at ON nodescope_entries(created_at);
+      CREATE INDEX IF NOT EXISTS idx_nodescope_entries_tags ON nodescope_entries USING GIN(tags);
+    `);
+  }
+  async save(entry) {
+    await this.pool.query(
+      `INSERT INTO nodescope_entries (id, batch_id, type, content, tags, created_at, duration, memory_usage)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+       ON CONFLICT (id) DO UPDATE SET
+         content = EXCLUDED.content,
+         tags = EXCLUDED.tags,
+         duration = EXCLUDED.duration,
+         memory_usage = EXCLUDED.memory_usage`,
+      [
+        entry.id,
+        entry.batchId,
+        entry.type,
+        JSON.stringify(entry.content),
+        JSON.stringify(entry.tags),
+        entry.createdAt,
+        entry.duration ?? null,
+        entry.memoryUsage ?? null
+      ]
+    );
+  }
+  async saveBatch(entries) {
+    const client = await this.pool.connect();
+    try {
+      await client.query("BEGIN");
+      for (const entry of entries) {
+        await client.query(
+          `INSERT INTO nodescope_entries (id, batch_id, type, content, tags, created_at, duration, memory_usage)
+           VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+           ON CONFLICT (id) DO UPDATE SET
+             content = EXCLUDED.content,
+             tags = EXCLUDED.tags,
+             duration = EXCLUDED.duration,
+             memory_usage = EXCLUDED.memory_usage`,
+          [
+            entry.id,
+            entry.batchId,
+            entry.type,
+            JSON.stringify(entry.content),
+            JSON.stringify(entry.tags),
+            entry.createdAt,
+            entry.duration ?? null,
+            entry.memoryUsage ?? null
+          ]
+        );
+      }
+      await client.query("COMMIT");
+    } catch (error) {
+      await client.query("ROLLBACK");
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+  async find(id) {
+    const result = await this.pool.query(
+      "SELECT * FROM nodescope_entries WHERE id = $1",
+      [id]
+    );
+    if (result.rows.length === 0) return null;
+    return this.rowToEntry(result.rows[0]);
+  }
+  async list(options = {}) {
+    const { type, batchId, tags, search, before, after, limit = 50, offset = 0 } = options;
+    let where = "1=1";
+    const params = [];
+    let paramIndex = 1;
+    if (type) {
+      where += ` AND type = $${paramIndex++}`;
+      params.push(type);
+    }
+    if (batchId) {
+      where += ` AND batch_id = $${paramIndex++}`;
+      params.push(batchId);
+    }
+    if (tags && tags.length > 0) {
+      where += ` AND tags ?| $${paramIndex++}`;
+      params.push(tags);
+    }
+    if (before) {
+      where += ` AND created_at < $${paramIndex++}`;
+      params.push(before);
+    }
+    if (after) {
+      where += ` AND created_at > $${paramIndex++}`;
+      params.push(after);
+    }
+    if (search) {
+      where += ` AND content::text ILIKE $${paramIndex++}`;
+      params.push(`%${search}%`);
+    }
+    const countResult = await this.pool.query(
+      `SELECT COUNT(*) as count FROM nodescope_entries WHERE ${where}`,
+      params
+    );
+    const total = parseInt(countResult.rows[0].count, 10);
+    const dataResult = await this.pool.query(
+      `SELECT * FROM nodescope_entries WHERE ${where} ORDER BY created_at DESC LIMIT $${paramIndex++} OFFSET $${paramIndex++}`,
+      [...params, limit, offset]
+    );
+    return {
+      data: dataResult.rows.map((row) => this.rowToEntry(row)),
+      total,
+      limit,
+      offset,
+      hasMore: offset + limit < total
+    };
+  }
+  async findByBatch(batchId) {
+    const result = await this.pool.query(
+      "SELECT * FROM nodescope_entries WHERE batch_id = $1 ORDER BY created_at ASC",
+      [batchId]
+    );
+    return result.rows.map((row) => this.rowToEntry(row));
+  }
+  async prune(beforeDate) {
+    const result = await this.pool.query(
+      "DELETE FROM nodescope_entries WHERE created_at < $1",
+      [beforeDate]
+    );
+    return result.rowCount ?? 0;
+  }
+  async clear() {
+    await this.pool.query("DELETE FROM nodescope_entries");
+  }
+  async stats() {
+    const entriesByType = defaultEntryCounts();
+    const typeResult = await this.pool.query(
+      "SELECT type, COUNT(*) as count FROM nodescope_entries GROUP BY type"
+    );
+    for (const row of typeResult.rows) {
+      entriesByType[row.type] = parseInt(row.count, 10);
+    }
+    const totalResult = await this.pool.query(
+      "SELECT COUNT(*) as count FROM nodescope_entries"
+    );
+    const rangeResult = await this.pool.query(
+      "SELECT MIN(created_at) as oldest, MAX(created_at) as newest FROM nodescope_entries"
+    );
+    return {
+      totalEntries: parseInt(totalResult.rows[0].count, 10),
+      entriesByType,
+      oldestEntry: rangeResult.rows[0].oldest ? new Date(rangeResult.rows[0].oldest) : void 0,
+      newestEntry: rangeResult.rows[0].newest ? new Date(rangeResult.rows[0].newest) : void 0
+    };
+  }
+  async close() {
+    await this.pool.end();
+  }
+  rowToEntry(row) {
+    return {
+      id: row.id,
+      batchId: row.batch_id,
+      type: row.type,
+      content: typeof row.content === "string" ? JSON.parse(row.content) : row.content,
+      tags: typeof row.tags === "string" ? JSON.parse(row.tags) : row.tags,
+      createdAt: new Date(row.created_at),
+      duration: row.duration ?? void 0,
+      memoryUsage: row.memory_usage ?? void 0
+    };
+  }
+};
+
+export {
+  PostgreSQLStorage
+};