nextlimiter 1.0.5 → 1.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nextlimiter",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "Production-ready rate limiting for Node.js — sliding window, token bucket, SaaS plans, smart limiting, and built-in analytics.",
   "main": "src/index.js",
   "types": "types/index.d.ts",

package/src/analytics/prometheus.js

@@ -0,0 +1,122 @@
+'use strict';
+
+/**
+ * Pure Node.js Prometheus Exposition Formatter
+ * Zero dependencies. Converts limiter stats to valid Prometheus text format.
+ */
+
+class PrometheusFormatter {
+  constructor(limiter) {
+    this.limiter = limiter;
+  }
+
+  contentType() {
+    return 'text/plain; version=0.0.4; charset=utf-8';
+  }
+
+  /**
+   * Escape label values according to Prometheus rules:
+   * \ -> \\
+   * " -> \"
+   * \n -> \n
+   */
+  _escapeLabel(str) {
+    return String(str)
+      .replace(/\\/g, '\\\\')
+      .replace(/"/g, '\\"')
+      .replace(/\n/g, '\\n');
+  }
+
+  /**
+   * Format a single metric block (help, type, and samples).
+   */
+  _metricBlock(name, help, type, samples) {
+    if (!samples || samples.length === 0) return '';
+    let block = `# HELP ${name} ${help}\n`;
+    block += `# TYPE ${name} ${type}\n`;
+
+    for (const sample of samples) {
+      const labelEntries = Object.entries(sample.labels || {});
+      if (labelEntries.length > 0) {
+        const labelStrs = labelEntries.map(([k, v]) => `${k}="${this._escapeLabel(v)}"`);
+        block += `${name}{${labelStrs.join(',')}} ${sample.value}\n`;
+      } else {
+        block += `${name} ${sample.value}\n`;
+      }
+    }
+    return block + '\n';
+  }
+
+  format() {
+    const stats = this.limiter.getStats();
+    let output = '';
+
+    // 1. Total requests (Counter)
+    output += this._metricBlock(
+      'nextlimiter_requests_total',
+      'Total requests processed by nextlimiter',
+      'counter',
+      [
+        { labels: { status: 'allowed' }, value: stats.allowedRequests },
+        { labels: { status: 'blocked' }, value: stats.blockedRequests }
+      ]
+    );
+
+    // 2. Block rate (Gauge)
+    output += this._metricBlock(
+      'nextlimiter_block_rate',
+      'Ratio of blocked to total requests (0.0 to 1.0)',
+      'gauge',
+      [{ labels: {}, value: isNaN(stats.blockRate) ? 0 : stats.blockRate }]
+    );
+
+    // 3. Top blocked IPs (Gauge)
+    const topBlockedSamples = (stats.topBlocked || []).slice(0, 10).map((item) => {
+      // Clean up IP label
+      let ip = item.key.replace(/^nextlimiter:(ip:)?/, '');
+      return { labels: { ip }, value: item.count };
+    });
+    if (topBlockedSamples.length > 0) {
+      output += this._metricBlock(
+        'nextlimiter_top_blocked_ip',
+        'Block count per offending IP',
+        'gauge',
+        topBlockedSamples
+      );
+    }
+
+    // 4. Top keys by volume (Gauge)
+    const topKeysSamples = (stats.topKeys || []).slice(0, 10).map((item) => {
+      return { labels: { key: item.key }, value: item.count };
+    });
+    if (topKeysSamples.length > 0) {
+      output += this._metricBlock(
+        'nextlimiter_top_keys_total',
+        'Total request count per key',
+        'gauge',
+        topKeysSamples
+      );
+    }
+
+    // 5. Uptime seconds (Gauge)
+    output += this._metricBlock(
+      'nextlimiter_uptime_seconds',
+      'Seconds since limiter was created',
+      'gauge',
+      [{ labels: {}, value: stats.uptimeMs / 1000 }]
+    );
+
+    // 6. Info (Gauge = 1)
+    const version = '1.0.5'; // Current pkg version
+    output += this._metricBlock(
+      'nextlimiter_info',
+      'Static info about the limiter instance',
+      'gauge',
+      [{ labels: { strategy: stats.config.strategy, version }, value: 1 }]
+    );
+
+    return output;
+  }
+}
+
+module.exports = { PrometheusFormatter };

package/src/core/limiter.js

@@ -12,6 +12,7 @@ const { AnalyticsTracker }        = require('../analytics/tracker');
 const { SmartDetector }           = require('../smart/detector');
 const { setHeaders }              = require('../middleware/headers');
 const { checkAccess }             = require('./accessControl');
+const { PrometheusFormatter }     = require('../analytics/prometheus');
 
 const STRATEGY_MAP = {
   'fixed-window':   fixedWindowCheck,
@@ -146,6 +147,41 @@ class Limiter {
     };
   }
 
+  /**
+   * Express route handler for serving Prometheus metrics.
+   * Exposes getStats() data in plain text format (version=0.0.4).
+   *
+   * @example
+   * app.get('/metrics', limiter.metricsHandler());
+   */
+  metricsHandler() {
+    return (req, res) => {
+      try {
+        const formatter = new PrometheusFormatter(this);
+        res.set('Content-Type', formatter.contentType());
+        res.send(formatter.format());
+      } catch (err) {
+        res.status(500).type('text/plain').send(`Error generating metrics: ${err.message}`);
+      }
+    };
+  }
+
+  /**
+   * Global middleware that automatically intercepts GET /metrics requests
+   * and serves the Prometheus exposition format. Passes through all other routes.
+   *
+   * @example
+   * app.use(limiter.metricsMiddleware());
+   */
+  metricsMiddleware() {
+    return (req, res, next) => {
+      if (req.method === 'GET' && req.path === '/metrics') {
+        return this.metricsHandler()(req, res);
+      }
+      next();
+    };
+  }
+
   /**
    * Programmatic rate limit check — use outside of HTTP middleware context.
    *

package/src/index.js

@@ -5,6 +5,7 @@ const { PRESETS, DEFAULT_PLANS } = require('./core/config');
 const { MemoryStore } = require('./store/memoryStore');
 const { RedisStore }  = require('./store/redisStore');
 const { ipMatchesCidr, ipMatchesList } = require('./utils/cidr');
+const { PrometheusFormatter } = require('./analytics/prometheus');
 
 /**
  * Create a fully configured rate limiter instance.
@@ -107,6 +108,9 @@ module.exports = {
   ipMatchesCidr,
   ipMatchesList,
 
+  // Analytics export
+  PrometheusFormatter,
+
   // Constants
   PRESETS,
   DEFAULT_PLANS,

package/types/index.d.ts

@@ -139,6 +139,12 @@ export interface RateLimitResult {
 
 // ── Analytics ────────────────────────────────────────────────────────────────
 
+export declare class PrometheusFormatter {
+  constructor(limiter: Limiter);
+  format(): string;
+  contentType(): string;
+}
+
 export interface KeyCount {
   key: string;
   count: number;
@@ -181,6 +187,18 @@ export declare class Limiter {
   /** Returns an Express-compatible middleware function */
   middleware(): (req: Request, res: Response, next: NextFunction) => Promise<void>;
 
+  /**
+   * Express route handler for serving Prometheus metrics.
+   * Exposes getStats() data in plain text format (version=0.0.4).
+   */
+  metricsHandler(): (req: any, res: any) => void;
+
+  /**
+   * Global middleware that automatically intercepts GET /metrics requests.
+   * Passes through all other routes.
+   */
+  metricsMiddleware(): (req: any, res: any, next: any) => void;
+
   /** Programmatic rate limit check by key string */
   check(key: string): Promise<RateLimitResult>;