nextlimiter 1.0.6 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nextlimiter",
-  "version": "1.0.6",
+  "version": "1.1.0",
   "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/core/accessControl.js

@@ -21,14 +21,16 @@ const { ipMatchesList } = require('../utils/cidr');
  * checkAccess('1.2.3.4', {})
  * // → { action: 'allow', reason: 'proceed' }
  */
-function checkAccess(ip, config) {
+function checkAccess(ip, config, emitter) {
   // Blacklist wins — always checked first regardless of whitelist
   if (config.blacklist && ipMatchesList(ip, config.blacklist)) {
+    if (emitter) emitter.emit('blacklisted', ip);
     return { action: 'block', reason: 'blacklisted' };
   }
 
   // Whitelist — bypass all rate limiting
   if (config.whitelist && ipMatchesList(ip, config.whitelist)) {
+    if (emitter) emitter.emit('whitelisted', ip);
     return { action: 'skip', reason: 'whitelisted' };
   }
 

package/src/core/config.js

@@ -87,6 +87,7 @@ const DEFAULT_CONFIG = {
   keyGenerator: null,       // (req) => string — custom key fn
   whitelist:     null,       // string[] — IPs/CIDRs that bypass rate limiting
   blacklist:     null,       // string[] — IPs/CIDRs that always get 403
+  statsInterval: undefined,  // ms interval to emit 'stats' event
 };
 
 /**
@@ -147,6 +148,17 @@ function resolveConfig(userOptions = {}) {
     base[listName] = valid.length > 0 ? valid : null;
   }
 
+  // Validate statsInterval
+  if (base.statsInterval !== undefined) {
+    if (typeof base.statsInterval !== 'number' || base.statsInterval <= 0) {
+      console.warn('[NextLimiter] config.statsInterval must be a positive number. Disabling.');
+      base.statsInterval = undefined;
+    } else if (base.statsInterval < 1000) {
+      console.warn('[NextLimiter] config.statsInterval must be at least 1000ms. Clamping to 1000ms.');
+      base.statsInterval = 1000;
+    }
+  }
+
   return base;
 }
 

package/src/core/limiter.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const EventEmitter                = require('events');
 const { resolveConfig }           = require('./config');
 const { MemoryStore }             = require('../store/memoryStore');
 const { fixedWindowCheck }        = require('../strategies/fixedWindow');
@@ -33,11 +34,15 @@ const STRATEGY_MAP = {
  * // Programmatic check
  * const result = await limiter.check('user:42');
  */
-class Limiter {
+class Limiter extends EventEmitter {
   /**
    * @param {object} options - NextLimiter configuration (see config.js for defaults)
    */
   constructor(options = {}) {
+    super();
+    this.setMaxListeners(50);
+    this.on('error', () => {}); // default no-op handler prevents crashes
+
     this._config = resolveConfig(options);
 
     // Storage backend
@@ -64,7 +69,14 @@ class Limiter {
     this._analytics = new AnalyticsTracker();
 
     // Smart detector
-    this._smart = this._config.smart ? new SmartDetector(this._config) : null;
+    this._smart = this._config.smart ? new SmartDetector(this._config, this) : null;
+
+    // Stats event interval
+    if (this._config.statsInterval) {
+      this._statsTimer = setInterval(() => {
+        this.emit('stats', this.getStats());
+      }, this._config.statsInterval).unref();
+    }
   }
 
   // ── Public API ─────────────────────────────────────────────────────────────
@@ -87,7 +99,7 @@ class Limiter {
 
         // ── Access control (whitelist / blacklist) ───────────────────────────
         const clientIp = extractIp(req);
-        const access   = checkAccess(clientIp, this._config);
+        const access   = checkAccess(clientIp, this._config, this);
 
         if (access.action === 'block') {
           return res.status(403).json({
@@ -106,13 +118,17 @@ class Limiter {
         const key    = `${this._config.keyPrefix}${rawKey}`;
 
         const result = await this._runCheck(key);
+        
+        // Emit events
+        if (result.allowed) this.emit('allowed', rawKey, result);
+        else this.emit('blocked', rawKey, result);
 
         // Record analytics
         this._analytics.record(key, result.allowed);
 
         // Set headers
         if (this._config.headers) {
-          setHeaders(res, result, !result.allowed);
+          setHeaders(res, result);
         }
 
         if (!result.allowed) {
@@ -140,8 +156,9 @@ class Limiter {
 
         next();
       } catch (err) {
+        this.emit('error', err);
         // Never let rate limiter errors take down the application
-        this._log.warn(`Error in rate limiter: ${err.message}. Failing open.`);
+        this._log.warn(`Middleware error: ${err.message}. Failing open.`);
         next();
       }
     };
@@ -196,7 +213,7 @@ class Limiter {
     // Apply access control if the key looks like a plain IP address
     const looksLikeIp = /^\d{1,3}(\.\d{1,3}){3}$/.test(String(key).trim());
     if (looksLikeIp) {
-      const access = checkAccess(key, this._config);
+      const access = checkAccess(key, this._config, this);
       if (access.action === 'block') {
         return {
           allowed:      false,
@@ -229,9 +246,35 @@ class Limiter {
     const fullKey = `${this._config.keyPrefix}${key}`;
     const result  = await this._runCheck(fullKey);
     this._analytics.record(fullKey, result.allowed);
+
+    if (result.allowed) this.emit('allowed', key, result);
+    else this.emit('blocked', key, result);
+
     return result;
   }
 
+  /**
+   * Reset rate limit state for a key.
+   *
+   * @param {string} key
+   */
+  resetKey(key) {
+    const fullKey = `${this._config.keyPrefix}${key}`;
+    this._store.delete(fullKey);
+    this.emit('reset', key);
+  }
+
+  /**
+   * Cleanly dispose of stats cycles and store buffers.
+   */
+  destroy() {
+    if (this._statsTimer) clearInterval(this._statsTimer);
+    if (this._store && typeof this._store.destroy === 'function') {
+      this._store.destroy();
+    }
+    this.removeAllListeners();
+  }
+
   /**
    * Manually reset the rate limit for a specific key.
    * Useful after a user upgrades their plan, or for admin overrides.

package/src/smart/detector.js

@@ -18,9 +18,12 @@
 class SmartDetector {
   /**
    * @param {object} config - Resolved NextLimiter config
+   * @param {import('events').EventEmitter} [emitter] - Optional event emitter
    */
-  constructor(config) {
+  constructor(config, emitter) {
     this._config = config;
+    this._emitter = emitter;
+    this._penalizedSet = new Set();
 
     // Map: key → { windowStart, count, penalized, penaltyExpires }
     /** @type {Map<string, object>} */
@@ -64,6 +67,17 @@ class SmartDetector {
       if (state.count > normalRatePerObsWindow * config.smartThreshold) {
         state.penalized      = true;
         state.penaltyExpires = now + config.smartCooldownMs;
+
+        if (this._emitter && !this._penalizedSet.has(key)) {
+          this._penalizedSet.add(key);
+          this._emitter.emit('penalized', key, {
+            key,
+            normalLimit: config.max,
+            reducedLimit: Math.floor(config.max * config.smartPenaltyFactor),
+            cooldownMs: config.smartCooldownMs,
+            detectedAt: new Date().toISOString()
+          });
+        }
       }
 
       // Reset observation window
@@ -84,6 +98,7 @@ class SmartDetector {
     // Penalty expired — lift it
     if (state.penalized && now >= state.penaltyExpires) {
       state.penalized = false;
+      this._penalizedSet.delete(key);
     }
 
     return { penalized: false, effectiveMax: config.max };
@@ -111,6 +126,7 @@ class SmartDetector {
   /** Clear all tracking state. */
   reset() {
     this._state.clear();
+    this._penalizedSet.clear();
   }
 }
 

package/types/index.d.ts

@@ -1,7 +1,7 @@
 // NextLimiter — TypeScript type definitions
 // Compatible with @types/node and @types/express
-
 import { Request, Response, NextFunction } from 'express';
+import { EventEmitter } from 'events';
 
 // ── Store interface ──────────────────────────────────────────────────────────
 
@@ -102,6 +102,9 @@ export interface LimiterOptions {
 
   /** Array of IPs or CIDR ranges to block immediately (403) */
   blacklist?: string[];
+
+  /** ms interval to emit 'stats' event. undefined = disabled. */
+  statsInterval?: number;
 }
 
 // ── Rate limit result ────────────────────────────────────────────────────────
@@ -139,6 +142,14 @@ export interface RateLimitResult {
 
 // ── Analytics ────────────────────────────────────────────────────────────────
 
+export interface PenaltyInfo {
+  key: string;
+  normalLimit: number;
+  reducedLimit: number;
+  cooldownMs: number;
+  detectedAt: string;
+}
+
 export declare class PrometheusFormatter {
   constructor(limiter: Limiter);
   format(): string;
@@ -181,7 +192,7 @@ export interface LimiterStats {
 
 // ── Limiter class ────────────────────────────────────────────────────────────
 
-export declare class Limiter {
+export declare class Limiter extends EventEmitter {
   constructor(options?: LimiterOptions);
 
   /** Returns an Express-compatible middleware function */
@@ -205,6 +216,12 @@ export declare class Limiter {
   /** Reset rate limit state for a specific key */
   reset(key: string): Promise<void>;
 
+  /** Reset rate limit state and clear from store immediately */
+  resetKey(key: string): void;
+
+  /** Clean up stores and timers */
+  destroy(): void;
+
   /** Get analytics snapshot */
   getStats(): LimiterStats;
 
@@ -213,6 +230,25 @@ export declare class Limiter {
 
   /** Read-only resolved configuration */
   readonly config: Readonly<Required<LimiterOptions>>;
+
+  // Typed EventEmitter overloads
+  on(event: 'blocked',     listener: (key: string, result: RateLimitResult) => void): this;
+  on(event: 'allowed',     listener: (key: string, result: RateLimitResult) => void): this;
+  on(event: 'penalized',   listener: (key: string, info: PenaltyInfo) => void): this;
+  on(event: 'blacklisted', listener: (ip: string) => void): this;
+  on(event: 'whitelisted', listener: (ip: string) => void): this;
+  on(event: 'reset',       listener: (key: string) => void): this;
+  on(event: 'stats',       listener: (stats: LimiterStats) => void): this;
+  on(event: 'error',       listener: (err: Error) => void): this;
+
+  once(event: 'blocked',     listener: (key: string, result: RateLimitResult) => void): this;
+  once(event: 'allowed',     listener: (key: string, result: RateLimitResult) => void): this;
+  once(event: 'penalized',   listener: (key: string, info: PenaltyInfo) => void): this;
+  once(event: 'blacklisted', listener: (ip: string) => void): this;
+  once(event: 'whitelisted', listener: (ip: string) => void): this;
+  once(event: 'reset',       listener: (key: string) => void): this;
+  once(event: 'stats',       listener: (stats: LimiterStats) => void): this;
+  once(event: 'error',       listener: (err: Error) => void): this;
 }
 
 // ── Factory functions ────────────────────────────────────────────────────────