node-runtime-guardian 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Node Runtime Guardian Contributors
+
+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,423 @@
+<div align="center">
+  <h1>Node Runtime Guardian</h1>
+  <img src="assets/node-runtime-guardian.gif" alt="Node Runtime Guardian Logo" width="600">
+  <p><strong>Runtime visibility and self-protection for Node.js applications</strong></p>
+</div>
+
+---
+
+Node Runtime Guardian is a lightweight, dependency-free runtime diagnostics and protection layer for Node.js. It runs inside your process to observe event loop health, memory behavior, garbage collection pressure, and thread pool saturation — and can optionally shed load when your application is under stress.
+
+This project is intentionally calm, explicit, and production-focused. It is built for backend developers who want to understand how the Node.js runtime behaves under real load, not just what dashboards report after the fact.
+
+## Table of Contents
+
+- [Why This Exists](#why-this-exists)
+- [When Should You Use This?](#when-should-you-use-this)
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Documentation](#documentation)
+- [API Reference](#api-documentation)
+- [Usage Examples](#usage-examples)
+- [Metrics](#metrics)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Why This Exists
+
+Most Node.js production issues don't show up as errors.
+
+They show up as:
+
+- **Latency spikes** with no obvious cause
+- **Memory usage** slowly creeping upward
+- **GC pauses** causing jittery response times
+- **Pods restarting** due to OOM without clear signals
+- **Services degrading** under burst traffic
+
+By the time traditional monitoring alerts fire, the system is often already unhealthy.
+
+Node Runtime Guardian was built to observe these problems from inside the Node.js runtime itself — where the event loop, garbage collector, and thread pool actually live.
+
+## When Should You Use This?
+
+Node Runtime Guardian is useful if:
+
+- You suspect event loop blocking or synchronous CPU work
+- Your service slows down under load without throwing errors
+- Memory usage grows steadily and heap snapshots aren't obvious
+- You want runtime insight without a full APM stack
+- You want a last-line defense against cascading failures
+
+It is especially well-suited for:
+
+- High-traffic API servers
+- Background workers and job processors
+- Memory-constrained containers
+- High-throughput Node.js services
+
+## Features
+
+- **Event Loop Monitoring**: Track event loop delay using `perf_hooks`
+- **Memory Monitoring**: Detect memory leaks and drift patterns
+- **GC Pressure Estimation**: Monitor garbage collection behavior
+- **Thread Pool Saturation Detection**: Infer thread pool queue buildup
+- **Load Shedding**: Automatic request rejection when thresholds are exceeded
+- **Metrics Endpoint**: HTTP endpoint for runtime metrics
+- **Plugin System**: Extensible architecture for custom integrations
+- **Worker Thread Pool**: Managed worker pool utility
+- **Zero Dependencies**: Uses only Node.js built-in modules
+
+## Installation
+
+```bash
+npm install node-runtime-guardian
+```
+
+## Quick Start
+
+```typescript
+import { Guardian } from 'node-runtime-guardian';
+
+// Initialize Guardian
+const guardian = new Guardian({
+  eventLoop: {
+    thresholdMs: 100,
+  },
+  memory: {
+    rssLimit: 512 * 1024 * 1024, // 512MB
+    driftDetectionEnabled: true,
+  },
+  protection: {
+    enabled: true,
+    loadShedding: {
+      enabled: true,
+      eventLoopThreshold: 200,
+    },
+  },
+  metricsServer: {
+    enabled: true,
+    port: 9090,
+  },
+});
+
+// Start monitoring
+guardian.start();
+
+// Listen for warnings
+guardian.on('warning', (warning) => {
+  console.warn('Guardian warning:', warning);
+});
+
+// Get current metrics
+const metrics = guardian.getMetrics();
+console.log('Health score:', guardian.getHealthScore());
+```
+
+> 💡 **Tip**: For more detailed examples and configuration options, see the [Usage Documentation](docs/USAGE.md).
+
+## Documentation
+
+📖 **For comprehensive usage guides, configuration options, integration patterns, and best practices, see the [Usage Documentation](docs/USAGE.md).**
+
+The [Usage Documentation](docs/USAGE.md) provides detailed information on:
+
+- **Configuration Examples**: Development, production, memory-sensitive, and CPU-intensive setups
+- **Integration Patterns**: Express.js, Fastify, Koa.js middleware integration
+- **Usage Patterns**: Background job monitoring, microservices health reporting
+- **Best Practices**: Configuration tuning, event handling, request tracking
+- **Troubleshooting**: Common issues and solutions
+- **Advanced Topics**: Custom health scoring, APM integration, metrics export
+
+## API Documentation
+
+### Guardian Class
+
+Main class that orchestrates all monitoring and protection.
+
+#### Constructor
+
+```typescript
+new Guardian(config?: GuardianConfig)
+```
+
+#### Methods
+
+- `init(config?: GuardianConfig): void` - Initialize and start monitoring
+- `start(): void` - Start all monitors
+- `stop(): void` - Stop all monitors
+- `getMetrics(): RuntimeMetrics` - Get current aggregated metrics
+- `getHealthScore(): number` - Get health score (0-1, where 1 is healthy)
+- `isProtectionActive(): boolean` - Check if protection is active
+- `shouldRejectRequest(): boolean` - Check if a request should be rejected
+- `getRejectionResponse(): { statusCode: number; message: string }` - Get rejection response
+- `trackRequest(): void` - Track incoming request
+- `trackRequestComplete(): void` - Track completed request
+
+#### Events
+
+- `metric` - Emitted when metrics are collected
+- `warning` - Emitted when thresholds are exceeded
+- `eventLoopBlocked` - Emitted when event loop delay exceeds threshold
+- `memoryDrift` - Emitted when memory drift is detected
+- `gcPressure` - Emitted when GC pressure is high
+- `threadPoolSaturated` - Emitted when thread pool is saturated
+- `protectionActivated` - Emitted when protection is activated
+- `protectionDeactivated` - Emitted when protection is deactivated
+
+### Configuration
+
+```typescript
+interface GuardianConfig {
+  eventLoop?: {
+    enabled?: boolean;
+    thresholdMs?: number; // Default: 100
+    intervalMs?: number; // Default: 1000
+  };
+  memory?: {
+    enabled?: boolean;
+    rssLimit?: number;
+    heapLimit?: number;
+    externalLimit?: number;
+    driftDetectionEnabled?: boolean; // Default: true
+    driftThreshold?: number; // Default: 0.1
+  };
+  gc?: {
+    enabled?: boolean;
+    pressureThreshold?: number; // Default: 0.7
+  };
+  threadPool?: {
+    enabled?: boolean;
+    saturationThreshold?: number; // Default: 0.8
+  };
+  protection?: {
+    enabled?: boolean;
+    loadShedding?: {
+      enabled?: boolean;
+      eventLoopThreshold?: number; // Default: 200
+      memoryThreshold?: number; // Default: 0.9
+      responseCode?: number; // Default: 503
+      responseMessage?: string;
+    };
+  };
+  metricsServer?: {
+    enabled?: boolean;
+    port?: number; // Default: 9090
+    path?: string; // Default: '/guardian/metrics'
+  };
+  workerPool?: {
+    enabled?: boolean;
+    poolSize?: number; // Default: 4
+    maxQueueSize?: number; // Default: 100
+  };
+}
+```
+
+## Usage Examples
+
+> 📚 **See [Usage Documentation](docs/USAGE.md) for more comprehensive examples including Express, Fastify, Koa.js integrations, and advanced patterns.**
+
+### Basic Monitoring
+
+```typescript
+import { Guardian } from 'node-runtime-guardian';
+
+const guardian = new Guardian({
+  eventLoop: { thresholdMs: 100 },
+  memory: { driftDetectionEnabled: true },
+});
+
+guardian.start();
+
+guardian.on('warning', (warning) => {
+  console.error('Warning:', warning.message);
+});
+```
+
+### Load Shedding Integration
+
+```typescript
+import express from 'express';
+import { Guardian } from 'node-runtime-guardian';
+
+const app = express();
+const guardian = new Guardian({
+  protection: {
+    enabled: true,
+    loadShedding: {
+      enabled: true,
+      eventLoopThreshold: 200,
+    },
+  },
+});
+
+guardian.start();
+
+// Middleware to check protection
+app.use((req, res, next) => {
+  guardian.trackRequest();
+
+  if (guardian.shouldRejectRequest()) {
+    const response = guardian.getRejectionResponse();
+    guardian.trackRequestComplete();
+    return res.status(response.statusCode).json({ error: response.message });
+  }
+
+  res.on('finish', () => {
+    guardian.trackRequestComplete();
+  });
+
+  next();
+});
+
+app.get('/api/data', (req, res) => {
+  res.json({ data: 'Hello World' });
+});
+```
+
+### Metrics Endpoint
+
+```typescript
+import { Guardian, MetricsServer } from 'node-runtime-guardian';
+
+const guardian = new Guardian();
+guardian.start();
+
+const metricsServer = new MetricsServer(guardian, {
+  port: 9090,
+  path: '/guardian/metrics',
+});
+
+metricsServer.start();
+
+// Access metrics at http://localhost:9090/guardian/metrics
+```
+
+### Plugin System
+
+```typescript
+import {
+  Guardian,
+  GuardianPlugin,
+  RuntimeMetrics,
+} from 'node-runtime-guardian';
+
+class CustomLoggerPlugin implements GuardianPlugin {
+  name = 'custom-logger';
+
+  onMetricUpdate(data: RuntimeMetrics): void {
+    console.log('Metrics:', {
+      eventLoopDelay: data.eventLoopDelay.mean,
+      memory: data.memory.heapUsed,
+      health: data.healthScore,
+    });
+  }
+}
+
+const guardian = new Guardian();
+guardian.start();
+
+// Register plugin (would need plugin registry integration)
+// This is a conceptual example
+```
+
+### Worker Pool
+
+```typescript
+import { WorkerPool } from 'node-runtime-guardian';
+
+const pool = new WorkerPool('./worker.js', {
+  poolSize: 4,
+  maxQueueSize: 100,
+});
+
+// Run a task
+const result = await pool.run({ task: 'process-data' });
+
+// Get pool statistics
+const stats = pool.getStats();
+console.log('Active tasks:', stats.activeTasks);
+console.log('Queue size:', stats.queueSize);
+```
+
+## Metrics
+
+The metrics endpoint returns the following data:
+
+```json
+{
+  "eventLoopDelay": {
+    "mean": 2.5,
+    "max": 10.2,
+    "min": 0.1,
+    "p50": 2.0,
+    "p95": 8.5,
+    "p99": 9.8
+  },
+  "memory": {
+    "heapUsed": 52428800,
+    "heapTotal": 67108864,
+    "rss": 134217728,
+    "external": 1024000,
+    "arrayBuffers": 512000
+  },
+  "gc": {
+    "estimatedCycles": 15,
+    "minorGCCount": 12,
+    "majorGCCount": 3,
+    "gcPressure": 0.45
+  },
+  "threadPool": {
+    "saturationLevel": 0.2,
+    "estimatedQueueSize": 0.8,
+    "avgLatency": 0.5
+  },
+  "cpu": {
+    "user": 125.5,
+    "system": 45.2
+  },
+  "activeRequests": 5,
+  "healthScore": 0.85,
+  "isProtectionActive": false,
+  "timestamp": 1704067200000
+}
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Lint
+npm run lint
+
+# Format code
+npm run format
+```
+
+## Contributing
+
+Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- Built with TypeScript
+- Uses Node.js built-in modules only
+- Inspired by production monitoring needs
+
+---
+
+**If this project helped you or sparked an idea, consider dropping a star or a kind word. It quietly keeps me motivated.**

package/dist/core/EventLoopMonitor.d.ts

@@ -0,0 +1,32 @@
+/// <reference types="node" />
+import { EventEmitter } from 'events';
+import { EventLoopConfig, EventLoopMetrics } from '../types';
+/**
+ * Monitors event loop delay using perf_hooks
+ */
+export declare class EventLoopMonitor extends EventEmitter {
+    private monitor;
+    private interval;
+    private config;
+    private isRunning;
+    constructor(config?: EventLoopConfig);
+    /**
+     * Start monitoring event loop delay
+     */
+    start(): void;
+    /**
+     * Stop monitoring
+     */
+    stop(): void;
+    /**
+     * Collect current metrics
+     */
+    getMetrics(): EventLoopMetrics;
+    /**
+     * Reset monitor statistics
+     */
+    reset(): void;
+    private collectMetrics;
+    private getEmptyMetrics;
+}
+//# sourceMappingURL=EventLoopMonitor.d.ts.map

package/dist/core/EventLoopMonitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventLoopMonitor.d.ts","sourceRoot":"","sources":["../../src/core/EventLoopMonitor.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,EACL,eAAe,EACf,gBAAgB,EAMjB,MAAM,UAAU,CAAC;AAElB;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,YAAY;IAChD,OAAO,CAAC,OAAO,CAAyD;IACxE,OAAO,CAAC,QAAQ,CAA+B;IAC/C,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,SAAS,CAAS;gBAEd,MAAM,GAAE,eAAoB;IASxC;;OAEG;IACH,KAAK,IAAI,IAAI;IAeb;;OAEG;IACH,IAAI,IAAI,IAAI;IAcZ;;OAEG;IACH,UAAU,IAAI,gBAAgB;IAgB9B;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb,OAAO,CAAC,cAAc;IAsDtB,OAAO,CAAC,eAAe;CAUxB"}

package/dist/core/EventLoopMonitor.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventLoopMonitor = void 0;
+const perf_hooks_1 = require("perf_hooks");
+const events_1 = require("events");
+/**
+ * Monitors event loop delay using perf_hooks
+ */
+class EventLoopMonitor extends events_1.EventEmitter {
+    constructor(config = {}) {
+        super();
+        this.monitor = null;
+        this.interval = null;
+        this.isRunning = false;
+        this.config = {
+            enabled: config.enabled ?? true,
+            thresholdMs: config.thresholdMs ?? 100,
+            intervalMs: config.intervalMs ?? 1000,
+        };
+    }
+    /**
+     * Start monitoring event loop delay
+     */
+    start() {
+        if (!this.config.enabled || this.isRunning) {
+            return;
+        }
+        this.monitor = (0, perf_hooks_1.monitorEventLoopDelay)({ resolution: 10 });
+        this.monitor.enable();
+        this.interval = setInterval(() => {
+            this.collectMetrics();
+        }, this.config.intervalMs);
+        this.isRunning = true;
+    }
+    /**
+     * Stop monitoring
+     */
+    stop() {
+        if (this.interval) {
+            clearInterval(this.interval);
+            this.interval = null;
+        }
+        if (this.monitor) {
+            this.monitor.disable();
+            this.monitor = null;
+        }
+        this.isRunning = false;
+    }
+    /**
+     * Collect current metrics
+     */
+    getMetrics() {
+        if (!this.monitor) {
+            return this.getEmptyMetrics();
+        }
+        const stats = this.monitor;
+        return {
+            mean: stats.mean / 1e6, // Convert nanoseconds to milliseconds
+            max: stats.max / 1e6,
+            min: stats.min / 1e6,
+            p50: stats.percentile(50) / 1e6,
+            p95: stats.percentile(95) / 1e6,
+            p99: stats.percentile(99) / 1e6,
+        };
+    }
+    /**
+     * Reset monitor statistics
+     */
+    reset() {
+        if (this.monitor) {
+            this.monitor.reset();
+        }
+    }
+    collectMetrics() {
+        const metrics = this.getMetrics();
+        if (metrics.mean > this.config.thresholdMs) {
+            const emptyMemory = {
+                heapUsed: 0,
+                heapTotal: 0,
+                rss: 0,
+                external: 0,
+                arrayBuffers: 0,
+            };
+            const emptyGC = {
+                estimatedCycles: 0,
+                minorGCCount: 0,
+                majorGCCount: 0,
+                gcPressure: 0,
+            };
+            const emptyThreadPool = {
+                saturationLevel: 0,
+                estimatedQueueSize: 0,
+                avgLatency: 0,
+            };
+            const emptyCPU = {
+                user: 0,
+                system: 0,
+            };
+            const warning = {
+                type: 'eventLoopBlocked',
+                message: `Event loop delay exceeded threshold: ${metrics.mean.toFixed(2)}ms > ${this.config.thresholdMs}ms`,
+                severity: metrics.mean > this.config.thresholdMs * 2 ? 'high' : 'medium',
+                metrics: {
+                    eventLoopDelay: metrics,
+                    memory: emptyMemory,
+                    gc: emptyGC,
+                    threadPool: emptyThreadPool,
+                    cpu: emptyCPU,
+                    activeRequests: 0,
+                    timestamp: Date.now(),
+                },
+                timestamp: Date.now(),
+            };
+            this.emit('warning', warning);
+            this.emit('eventLoopBlocked', metrics);
+        }
+        this.emit('metric', metrics);
+    }
+    getEmptyMetrics() {
+        return {
+            mean: 0,
+            max: 0,
+            min: 0,
+            p50: 0,
+            p95: 0,
+            p99: 0,
+        };
+    }
+}
+exports.EventLoopMonitor = EventLoopMonitor;
+//# sourceMappingURL=EventLoopMonitor.js.map

package/dist/core/EventLoopMonitor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventLoopMonitor.js","sourceRoot":"","sources":["../../src/core/EventLoopMonitor.ts"],"names":[],"mappings":";;;AAAA,2CAAmD;AACnD,mCAAsC;AAWtC;;GAEG;AACH,MAAa,gBAAiB,SAAQ,qBAAY;IAMhD,YAAY,SAA0B,EAAE;QACtC,KAAK,EAAE,CAAC;QANF,YAAO,GAAoD,IAAI,CAAC;QAChE,aAAQ,GAA0B,IAAI,CAAC;QAEvC,cAAS,GAAG,KAAK,CAAC;QAIxB,IAAI,CAAC,MAAM,GAAG;YACZ,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,IAAI;YAC/B,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,GAAG;YACtC,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,IAAI;SACtC,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YAC3C,OAAO;QACT,CAAC;QAED,IAAI,CAAC,OAAO,GAAG,IAAA,kCAAqB,EAAC,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,CAAC;QACzD,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;QAEtB,IAAI,CAAC,QAAQ,GAAG,WAAW,CAAC,GAAG,EAAE;YAC/B,IAAI,CAAC,cAAc,EAAE,CAAC;QACxB,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAE3B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;IACxB,CAAC;IAED;;OAEG;IACH,IAAI;QACF,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC7B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACvB,CAAC;QAED,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;YACvB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACtB,CAAC;QAED,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;IACzB,CAAC;IAED;;OAEG;IACH,UAAU;QACR,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,OAAO,IAAI,CAAC,eAAe,EAAE,CAAC;QAChC,CAAC;QAED,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC;QAC3B,OAAO;YACL,IAAI,EAAE,KAAK,CAAC,IAAI,GAAG,GAAG,EAAE,sCAAsC;YAC9D,GAAG,EAAE,KAAK,CAAC,GAAG,GAAG,GAAG;YACpB,GAAG,EAAE,KAAK,CAAC,GAAG,GAAG,GAAG;YACpB,GAAG,EAAE,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC,GAAG,GAAG;YAC/B,GAAG,EAAE,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC,GAAG,GAAG;YAC/B,GAAG,EAAE,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC,GAAG,GAAG;SAChC,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACvB,CAAC;IACH,CAAC;IAEO,cAAc;QACpB,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;QAElC,IAAI,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;YAC3C,MAAM,WAAW,GAAkB;gBACjC,QAAQ,EAAE,CAAC;gBACX,SAAS,EAAE,CAAC;gBACZ,GAAG,EAAE,CAAC;gBACN,QAAQ,EAAE,CAAC;gBACX,YAAY,EAAE,CAAC;aAChB,CAAC;YAEF,MAAM,OAAO,GAAc;gBACzB,eAAe,EAAE,CAAC;gBAClB,YAAY,EAAE,CAAC;gBACf,YAAY,EAAE,CAAC;gBACf,UAAU,EAAE,CAAC;aACd,CAAC;YAEF,MAAM,eAAe,GAAsB;gBACzC,eAAe,EAAE,CAAC;gBAClB,kBAAkB,EAAE,CAAC;gBACrB,UAAU,EAAE,CAAC;aACd,CAAC;YAEF,MAAM,QAAQ,GAAe;gBAC3B,IAAI,EAAE,CAAC;gBACP,MAAM,EAAE,CAAC;aACV,CAAC;YAEF,MAAM,OAAO,GAAiB;gBAC5B,IAAI,EAAE,kBAAkB;gBACxB,OAAO,EAAE,wCAAwC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,MAAM,CAAC,WAAW,IAAI;gBAC3G,QAAQ,EACN,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ;gBAChE,OAAO,EAAE;oBACP,cAAc,EAAE,OAAO;oBACvB,MAAM,EAAE,WAAW;oBACnB,EAAE,EAAE,OAAO;oBACX,UAAU,EAAE,eAAe;oBAC3B,GAAG,EAAE,QAAQ;oBACb,cAAc,EAAE,CAAC;oBACjB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;iBACtB;gBACD,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;aACtB,CAAC;YAEF,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;YAC9B,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,OAAO,CAAC,CAAC;QACzC,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC/B,CAAC;IAEO,eAAe;QACrB,OAAO;YACL,IAAI,EAAE,CAAC;YACP,GAAG,EAAE,CAAC;YACN,GAAG,EAAE,CAAC;YACN,GAAG,EAAE,CAAC;YACN,GAAG,EAAE,CAAC;YACN,GAAG,EAAE,CAAC;SACP,CAAC;IACJ,CAAC;CACF;AA9ID,4CA8IC"}

package/dist/core/GCMonitor.d.ts

@@ -0,0 +1,32 @@
+/// <reference types="node" />
+import { EventEmitter } from 'events';
+import { GCConfig, GCMetrics } from '../types';
+/**
+ * Monitors GC pressure by observing heap drop patterns
+ */
+export declare class GCMonitor extends EventEmitter {
+    private interval;
+    private config;
+    private isRunning;
+    private heapHistory;
+    private readonly maxHistorySize;
+    private minorGCCount;
+    private majorGCCount;
+    private lastHeapSize;
+    constructor(config?: GCConfig);
+    /**
+     * Start monitoring GC
+     */
+    start(): void;
+    /**
+     * Stop monitoring
+     */
+    stop(): void;
+    /**
+     * Get current GC metrics
+     */
+    getMetrics(): GCMetrics;
+    private collectMetrics;
+    private calculatePressure;
+}
+//# sourceMappingURL=GCMonitor.d.ts.map

package/dist/core/GCMonitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GCMonitor.d.ts","sourceRoot":"","sources":["../../src/core/GCMonitor.ts"],"names":[],"mappings":";AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,EACL,QAAQ,EACR,SAAS,EAMV,MAAM,UAAU,CAAC;AAElB;;GAEG;AACH,qBAAa,SAAU,SAAQ,YAAY;IACzC,OAAO,CAAC,QAAQ,CAA+B;IAC/C,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,WAAW,CAAgB;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAO;IACtC,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,YAAY,CAAK;gBAEb,MAAM,GAAE,QAAa;IAQjC;;OAEG;IACH,KAAK,IAAI,IAAI;IAcb;;OAEG;IACH,IAAI,IAAI,IAAI;IAYZ;;OAEG;IACH,UAAU,IAAI,SAAS;IAiBvB,OAAO,CAAC,cAAc;IA+EtB,OAAO,CAAC,iBAAiB;CAuB1B"}