nextlimiter 1.0.0

package/src/core/config.js

@@ -0,0 +1,127 @@
+'use strict';
+
+/**
+ * Built-in SaaS plan definitions.
+ * These can be overridden by passing `plans` in createLimiter options.
+ */
+const DEFAULT_PLANS = {
+  free: {
+    windowMs: 60_000,     // 1 minute
+    max: 60,              // 60 req/min
+    burstMax: 10,         // allow short burst of 10 extra
+    description: 'Free tier — 60 requests per minute',
+  },
+  pro: {
+    windowMs: 60_000,
+    max: 600,
+    burstMax: 100,
+    description: 'Pro tier — 600 requests per minute',
+  },
+  enterprise: {
+    windowMs: 60_000,
+    max: 6000,
+    burstMax: 1000,
+    description: 'Enterprise tier — 6000 requests per minute',
+  },
+};
+
+/**
+ * Named presets for quick configuration.
+ *
+ * @example
+ * createLimiter({ preset: 'strict' })
+ */
+const PRESETS = {
+  strict: {
+    windowMs: 60_000,
+    max: 30,
+    strategy: 'sliding-window',
+    smart: true,
+  },
+  relaxed: {
+    windowMs: 60_000,
+    max: 300,
+    strategy: 'token-bucket',
+    smart: false,
+  },
+  api: {
+    windowMs: 60_000,
+    max: 100,
+    strategy: 'sliding-window',
+    smart: true,
+    keyBy: 'api-key',
+  },
+  auth: {
+    windowMs: 15 * 60_000,  // 15 minutes
+    max: 10,                 // only 10 attempts per 15 min
+    strategy: 'fixed-window',
+    smart: true,
+    message: 'Too many authentication attempts. Please try again in 15 minutes.',
+  },
+};
+
+/**
+ * Default configuration merged with user options.
+ */
+const DEFAULT_CONFIG = {
+  windowMs: 60_000,
+  max: 100,
+  strategy: 'sliding-window',
+  keyBy: 'ip',
+  keyPrefix: 'nexlimit:',
+  message: 'Too many requests, please try again later.',
+  statusCode: 429,
+  headers: true,
+  smart: false,
+  smartThreshold: 2.0,     // trigger smart limiting at 2x normal rate
+  smartCooldownMs: 60_000, // how long smart penalty lasts
+  smartPenaltyFactor: 0.5, // reduce limit to 50% for suspicious keys
+  logging: false,
+  logPrefix: '[NexLimit]',
+  skip: null,               // (req) => bool — skip rate limiting
+  onLimitReached: null,     // (req, res, info) => void
+  store: null,              // custom store instance
+  plan: null,               // 'free' | 'pro' | 'enterprise' | null
+  plans: DEFAULT_PLANS,     // plan map — override to define custom plans
+  preset: null,             // 'strict' | 'relaxed' | 'api' | 'auth'
+  keyGenerator: null,       // (req) => string — custom key fn
+};
+
+/**
+ * Resolve final config by merging preset → plan → user options → defaults.
+ * @param {object} userOptions
+ * @returns {object}
+ */
+function resolveConfig(userOptions = {}) {
+  let base = { ...DEFAULT_CONFIG };
+
+  // Apply named preset first (lowest priority)
+  if (userOptions.preset && PRESETS[userOptions.preset]) {
+    base = { ...base, ...PRESETS[userOptions.preset] };
+  }
+
+  // Merge user options
+  base = { ...base, ...userOptions };
+
+  // Apply plan limits (overrides windowMs and max if plan is set)
+  if (base.plan) {
+    const planDefs = base.plans || DEFAULT_PLANS;
+    const planCfg = planDefs[base.plan];
+    if (!planCfg) {
+      throw new Error(
+        `[NexLimit] Unknown plan "${base.plan}". Available: ${Object.keys(planDefs).join(', ')}`
+      );
+    }
+    base.windowMs = planCfg.windowMs;
+    base.max      = planCfg.max;
+    base._burstMax = planCfg.burstMax;
+  }
+
+  // Validate
+  if (base.max <= 0) throw new Error('[NexLimit] config.max must be greater than 0');
+  if (base.windowMs <= 0) throw new Error('[NexLimit] config.windowMs must be greater than 0');
+
+  return base;
+}
+
+module.exports = { DEFAULT_CONFIG, DEFAULT_PLANS, PRESETS, resolveConfig };

package/src/core/limiter.js

@@ -0,0 +1,229 @@
+'use strict';
+
+const { resolveConfig }           = require('./config');
+const { MemoryStore }             = require('../store/memoryStore');
+const { fixedWindowCheck }        = require('../strategies/fixedWindow');
+const { slidingWindowCheck }      = require('../strategies/slidingWindow');
+const { tokenBucketCheck }        = require('../strategies/tokenBucket');
+const { resolveKeyGenerator }     = require('../utils/keyGenerator');
+const { createLogger }            = require('../utils/logger');
+const { AnalyticsTracker }        = require('../analytics/tracker');
+const { SmartDetector }           = require('../smart/detector');
+const { setHeaders }              = require('../middleware/headers');
+
+const STRATEGY_MAP = {
+  'fixed-window':   fixedWindowCheck,
+  'sliding-window': slidingWindowCheck,
+  'token-bucket':   tokenBucketCheck,
+};
+
+/**
+ * NexLimit — the main Limiter class.
+ *
+ * Instantiate via `createLimiter(options)` or `autoLimit()`.
+ * Do not call `new Limiter()` directly in application code.
+ *
+ * @example
+ * const limiter = createLimiter({ windowMs: 60_000, max: 100 });
+ * app.use(limiter.middleware());
+ *
+ * // Programmatic check
+ * const result = await limiter.check('user:42');
+ */
+class Limiter {
+  /**
+   * @param {object} options - NexLimit configuration (see config.js for defaults)
+   */
+  constructor(options = {}) {
+    this._config = resolveConfig(options);
+
+    // Storage backend
+    this._store = this._config.store || new MemoryStore();
+
+    // Strategy function
+    const strategyFn = STRATEGY_MAP[this._config.strategy];
+    if (!strategyFn) {
+      throw new Error(
+        `[NexLimit] Unknown strategy "${this._config.strategy}". ` +
+        `Valid options: ${Object.keys(STRATEGY_MAP).join(', ')}`
+      );
+    }
+    this._strategy = strategyFn;
+
+    // Key generator
+    const keyByFn = this._config.keyGenerator || resolveKeyGenerator(this._config.keyBy);
+    this._keyGenerator = keyByFn;
+
+    // Logger
+    this._log = createLogger(this._config.logPrefix, this._config.logging);
+
+    // Analytics
+    this._analytics = new AnalyticsTracker();
+
+    // Smart detector
+    this._smart = this._config.smart ? new SmartDetector(this._config) : null;
+  }
+
+  // ── Public API ─────────────────────────────────────────────────────────────
+
+  /**
+   * Returns an Express middleware function.
+   *
+   * @returns {function} (req, res, next) => void
+   *
+   * @example
+   * app.use('/api', limiter.middleware());
+   */
+  middleware() {
+    return async (req, res, next) => {
+      try {
+        // Skip check if skip() returns true
+        if (this._config.skip && this._config.skip(req)) {
+          return next();
+        }
+
+        const rawKey = this._keyGenerator(req);
+        const key    = `${this._config.keyPrefix}${rawKey}`;
+
+        const result = await this._runCheck(key);
+
+        // Record analytics
+        this._analytics.record(key, result.allowed);
+
+        // Set headers
+        if (this._config.headers) {
+          setHeaders(res, result, !result.allowed);
+        }
+
+        if (!result.allowed) {
+          this._log.blocked(
+            rawKey,
+            result.limit - result.remaining,
+            result.limit,
+            result.strategy,
+            result.smartBlocked
+          );
+
+          // Custom handler
+          if (this._config.onLimitReached) {
+            return this._config.onLimitReached(req, res, result);
+          }
+
+          return res.status(this._config.statusCode).json({
+            error:      'Too Many Requests',
+            message:    this._config.message,
+            retryAfter: result.retryAfter,
+            limit:      result.limit,
+            resetAt:    new Date(result.resetAt).toISOString(),
+          });
+        }
+
+        next();
+      } catch (err) {
+        // Never let rate limiter errors take down the application
+        this._log.warn(`Error in rate limiter: ${err.message}. Failing open.`);
+        next();
+      }
+    };
+  }
+
+  /**
+   * Programmatic rate limit check — use outside of HTTP middleware context.
+   *
+   * @param {string} key - The rate limit key to check
+   * @returns {Promise<import('../core/result').RateLimitResult>}
+   *
+   * @example
+   * const result = await limiter.check('user:42');
+   * if (!result.allowed) throw new Error('Rate limit exceeded');
+   */
+  async check(key) {
+    const fullKey = `${this._config.keyPrefix}${key}`;
+    const result  = await this._runCheck(fullKey);
+    this._analytics.record(fullKey, result.allowed);
+    return result;
+  }
+
+  /**
+   * Manually reset the rate limit for a specific key.
+   * Useful after a user upgrades their plan, or for admin overrides.
+   *
+   * @param {string} key
+   */
+  async reset(key) {
+    const fullKey = `${this._config.keyPrefix}${key}`;
+    await this._store.delete(fullKey);
+    if (this._smart) this._smart.reset();
+    this._log.info(`Reset key: ${fullKey}`);
+  }
+
+  /**
+   * Get analytics snapshot.
+   *
+   * @returns {object}
+   *
+   * @example
+   * const stats = limiter.getStats();
+   * console.log(stats.totalRequests, stats.blockRate);
+   */
+  getStats() {
+    const stats = this._analytics.getStats();
+
+    if (this._smart) {
+      stats.smartLimiting = {
+        enabled:       true,
+        penalizedKeys: this._smart.getPenalizedKeys(),
+      };
+    }
+
+    stats.config = {
+      strategy: this._config.strategy,
+      windowMs: this._config.windowMs,
+      max:      this._config.max,
+      keyBy:    this._config.keyBy,
+      plan:     this._config.plan || 'custom',
+      smart:    this._config.smart,
+    };
+
+    return stats;
+  }
+
+  /**
+   * Reset all analytics counters.
+   */
+  resetStats() {
+    this._analytics.reset();
+  }
+
+  /**
+   * Expose the resolved configuration (read-only).
+   * @returns {object}
+   */
+  get config() {
+    return Object.freeze({ ...this._config });
+  }
+
+  // ── Private ────────────────────────────────────────────────────────────────
+
+  /**
+   * Run the strategy check, applying smart penalty if enabled.
+   * @param {string} key - Fully-prefixed key
+   * @returns {import('../core/result').RateLimitResult}
+   */
+  _runCheck(key) {
+    let effectiveConfig = this._config;
+
+    // Apply smart penalty if relevant
+    if (this._smart) {
+      const { penalized, effectiveMax } = this._smart.check(key);
+      if (penalized) {
+        // Create a shallow config override with reduced max
+        effectiveConfig = { ...this._config, max: effectiveMax };
+      }
+    }
+
+    return this._strategy(key, effectiveConfig, this._store);
+  }
+}
+
+module.exports = { Limiter };

package/src/core/result.js

@@ -0,0 +1,49 @@
+'use strict';
+
+/**
+ * Immutable result object returned by every strategy check.
+ * Passed to middleware for header generation and response decisions.
+ */
+class RateLimitResult {
+  /**
+   * @param {object} params
+   * @param {boolean} params.allowed      - Whether the request should proceed
+   * @param {number}  params.limit        - Max requests allowed in window
+   * @param {number}  params.remaining    - Remaining requests in current window
+   * @param {number}  params.resetAt      - Unix timestamp (ms) when window resets
+   * @param {number}  params.retryAfter   - Seconds until next request allowed (0 if allowed)
+   * @param {string}  params.key          - The resolved rate limit key
+   * @param {string}  params.strategy     - Strategy name used
+   * @param {boolean} params.smartBlocked - True if blocked by smart limiting
+   */
+  constructor({ allowed, limit, remaining, resetAt, retryAfter = 0, key, strategy, smartBlocked = false }) {
+    this.allowed      = allowed;
+    this.limit        = limit;
+    this.remaining    = Math.max(0, remaining);
+    this.resetAt      = resetAt;
+    this.retryAfter   = retryAfter;
+    this.key          = key;
+    this.strategy     = strategy;
+    this.smartBlocked = smartBlocked;
+
+    // Freeze so nothing accidentally mutates the result downstream
+    Object.freeze(this);
+  }
+
+  /** Seconds until window resets (for Retry-After header) */
+  get retryAfterSeconds() {
+    return Math.ceil((this.resetAt - Date.now()) / 1000);
+  }
+
+  toJSON() {
+    return {
+      allowed:   this.allowed,
+      limit:     this.limit,
+      remaining: this.remaining,
+      resetAt:   this.resetAt,
+      retryAfter: this.retryAfter,
+    };
+  }
+}
+
+module.exports = { RateLimitResult };

package/src/index.js

@@ -0,0 +1,106 @@
+'use strict';
+
+const { Limiter }     = require('./core/limiter');
+const { PRESETS, DEFAULT_PLANS } = require('./core/config');
+const { MemoryStore } = require('./store/memoryStore');
+
+/**
+ * Create a fully configured rate limiter instance.
+ *
+ * @param {object} [options]
+ * @param {number}  [options.windowMs=60000]      - Time window in ms
+ * @param {number}  [options.max=100]             - Max requests per window
+ * @param {string}  [options.strategy='sliding-window'] - 'fixed-window' | 'sliding-window' | 'token-bucket'
+ * @param {string}  [options.keyBy='ip']          - 'ip' | 'user-id' | 'api-key' | function
+ * @param {string}  [options.plan]                - 'free' | 'pro' | 'enterprise'
+ * @param {string}  [options.preset]              - 'strict' | 'relaxed' | 'api' | 'auth'
+ * @param {boolean} [options.smart=false]         - Enable behavior-based smart limiting
+ * @param {boolean} [options.logging=false]       - Enable request logging
+ * @param {boolean} [options.headers=true]        - Send X-RateLimit-* headers
+ * @param {string}  [options.message]             - Custom 429 message
+ * @param {number}  [options.statusCode=429]      - HTTP status for blocked requests
+ * @param {object}  [options.store]               - Custom store instance
+ * @param {function} [options.skip]               - (req) => bool — skip rate limiting
+ * @param {function} [options.onLimitReached]     - (req, res, result) => void
+ * @param {function} [options.keyGenerator]       - (req) => string — custom key function
+ * @param {object}  [options.plans]               - Custom plan definitions
+ *
+ * @returns {Limiter}
+ *
+ * @example
+ * const limiter = createLimiter({ windowMs: 60_000, max: 100 });
+ * app.use(limiter.middleware());
+ */
+function createLimiter(options = {}) {
+  return new Limiter(options);
+}
+
+/**
+ * Zero-config rate limiter.
+ * Returns an Express middleware directly — no .middleware() call needed.
+ *
+ * Defaults: 100 requests per minute, sliding window, IP-based, no logging.
+ *
+ * @param {object} [options] - Optional overrides
+ * @returns {function} Express middleware
+ *
+ * @example
+ * app.use(autoLimit());
+ * app.use(autoLimit({ max: 50, logging: true }));
+ */
+function autoLimit(options = {}) {
+  const limiter = new Limiter({ logging: true, ...options });
+  return limiter.middleware();
+}
+
+/**
+ * Create a rate limiter pre-configured for a SaaS plan.
+ *
+ * @param {string} planName - 'free' | 'pro' | 'enterprise'
+ * @param {object} [options] - Additional options to merge
+ * @returns {Limiter}
+ *
+ * @example
+ * const limiter = createPlanLimiter('pro', { keyBy: 'api-key', logging: true });
+ * app.use('/api', limiter.middleware());
+ */
+function createPlanLimiter(planName, options = {}) {
+  return new Limiter({ ...options, plan: planName });
+}
+
+/**
+ * Create a rate limiter from a named preset.
+ *
+ * @param {string} presetName - 'strict' | 'relaxed' | 'api' | 'auth'
+ * @param {object} [options]  - Overrides applied on top of the preset
+ * @returns {Limiter}
+ *
+ * @example
+ * app.post('/login', createPresetLimiter('auth').middleware());
+ */
+function createPresetLimiter(presetName, options = {}) {
+  if (!PRESETS[presetName]) {
+    throw new Error(
+      `[NexLimit] Unknown preset "${presetName}". Available: ${Object.keys(PRESETS).join(', ')}`
+    );
+  }
+  return new Limiter({ ...options, preset: presetName });
+}
+
+module.exports = {
+  // Core factory functions
+  createLimiter,
+  autoLimit,
+  createPlanLimiter,
+  createPresetLimiter,
+
+  // Class — for advanced usage / subclassing
+  Limiter,
+
+  // Storage
+  MemoryStore,
+
+  // Constants
+  PRESETS,
+  DEFAULT_PLANS,
+};

package/src/middleware/headers.js

@@ -0,0 +1,29 @@
+'use strict';
+
+/**
+ * Apply standard rate limit headers to an Express response.
+ *
+ * Headers set:
+ *   X-RateLimit-Limit     — max requests per window
+ *   X-RateLimit-Remaining — remaining requests in current window
+ *   X-RateLimit-Reset     — Unix timestamp (seconds) when window resets
+ *   X-RateLimit-Strategy  — algorithm name (informational)
+ *   Retry-After           — seconds to wait (only on 429 responses)
+ *
+ * @param {object} res           - Express response object
+ * @param {object} result        - RateLimitResult instance
+ * @param {boolean} includeRetry - Whether to add Retry-After header
+ */
+function setHeaders(res, result, includeRetry = false) {
+  res.setHeader('X-RateLimit-Limit',     result.limit);
+  res.setHeader('X-RateLimit-Remaining', result.remaining);
+  res.setHeader('X-RateLimit-Reset',     Math.ceil(result.resetAt / 1000));
+  res.setHeader('X-RateLimit-Strategy',  result.strategy);
+
+  if (includeRetry && !result.allowed) {
+    const retrySeconds = Math.max(1, Math.ceil((result.resetAt - Date.now()) / 1000));
+    res.setHeader('Retry-After', retrySeconds);
+  }
+}
+
+module.exports = { setHeaders };

package/src/smart/detector.js

@@ -0,0 +1,117 @@
+'use strict';
+
+/**
+ * SmartDetector — behavior-based dynamic rate limiting.
+ *
+ * Detects anomalous traffic patterns and temporarily reduces the limit
+ * for flagged keys without blocking them entirely.
+ *
+ * Detection logic:
+ *   1. Track request rate for each key over a short observation window
+ *   2. If the observed rate exceeds (normalRate × smartThreshold), flag the key
+ *   3. Flagged keys get a reduced limit: floor(max × smartPenaltyFactor)
+ *   4. The penalty expires after smartCooldownMs
+ *
+ * This lets legitimate burst-y users (e.g. someone running a data export)
+ * slow down gracefully rather than hitting a hard wall.
+ */
+class SmartDetector {
+  /**
+   * @param {object} config - Resolved NexLimit config
+   */
+  constructor(config) {
+    this._config = config;
+
+    // Map: key → { windowStart, count, penalized, penaltyExpires }
+    /** @type {Map<string, object>} */
+    this._state = new Map();
+
+    // Observation window = 10% of the rate limit window (min 1s, max 30s)
+    this._observationMs = Math.min(
+      30_000,
+      Math.max(1_000, Math.floor(config.windowMs * 0.1))
+    );
+  }
+
+  /**
+   * Check whether a key should be penalized and what its effective limit is.
+   *
+   * @param {string} key
+   * @returns {{ penalized: boolean, effectiveMax: number }}
+   */
+  check(key) {
+    const now    = Date.now();
+    const config = this._config;
+    let state  = this._state.get(key);
+
+    if (!state) {
+      state = {
+        windowStart:    now,
+        count:          0,
+        penalized:      false,
+        penaltyExpires: 0,
+      };
+      this._state.set(key, state);
+    }
+
+    // --- Record this request in the observation window ---
+    if (now - state.windowStart > this._observationMs) {
+      // Slide the window
+      const normalRatePerObsWindow =
+        (config.max / config.windowMs) * this._observationMs;
+
+      // Was the previous window anomalous?
+      if (state.count > normalRatePerObsWindow * config.smartThreshold) {
+        state.penalized      = true;
+        state.penaltyExpires = now + config.smartCooldownMs;
+      }
+
+      // Reset observation window
+      state.windowStart = now;
+      state.count       = 0;
+    }
+
+    state.count++;
+
+    // --- Check if currently under penalty ---
+    if (state.penalized && now < state.penaltyExpires) {
+      return {
+        penalized:    true,
+        effectiveMax: Math.max(1, Math.floor(config.max * config.smartPenaltyFactor)),
+      };
+    }
+
+    // Penalty expired — lift it
+    if (state.penalized && now >= state.penaltyExpires) {
+      state.penalized = false;
+    }
+
+    return { penalized: false, effectiveMax: config.max };
+  }
+
+  /**
+   * Return a snapshot of currently penalized keys.
+   * @returns {Array<{key: string, expiresAt: number, remainingMs: number}>}
+   */
+  getPenalizedKeys() {
+    const now = Date.now();
+    const result = [];
+    for (const [key, state] of this._state) {
+      if (state.penalized && now < state.penaltyExpires) {
+        result.push({
+          key,
+          expiresAt:   state.penaltyExpires,
+          remainingMs: state.penaltyExpires - now,
+        });
+      }
+    }
+    return result;
+  }
+
+  /** Clear all tracking state. */
+  reset() {
+    this._state.clear();
+  }
+}
+
+module.exports = { SmartDetector };