nextlimiter 1.0.0 → 1.0.2

package/src/strategies/tokenBucket.js

@@ -1,85 +1,85 @@
-'use strict';
-
-const { RateLimitResult } = require('../core/result');
-
-/**
- * Token Bucket strategy.
- *
- * Tokens refill continuously at a steady rate. Each request consumes one
- * token. Allows controlled bursts up to `capacity` tokens while enforcing
- * a long-term average rate of `max` requests per `windowMs`.
- *
- * State per key: { tokens: float, lastRefill: timestamp }
- *
- * Refill rate = config.max / config.windowMs  (tokens per millisecond)
- * Capacity    = config.max  (maximum accumulated tokens)
- *
- * This is the algorithm used by Stripe for their API rate limiting.
- * It feels more "fair" to clients than window-based approaches because
- * occasional bursts are explicitly allowed.
- *
- * @param {string} key      - Rate limit key
- * @param {object} config   - Resolved NexLimit config
- * @param {object} store    - Store instance
- * @returns {RateLimitResult}
- */
-function tokenBucketCheck(key, config, store) {
-  const now        = Date.now();
-  const capacity   = config.max;
-  const refillRate = config.max / config.windowMs; // tokens per ms
-  const storeKey   = `${key}:tb`;
-
-  let bucket = store.get(storeKey);
-
-  if (!bucket) {
-    // First request: full bucket, consume one token
-    bucket = { tokens: capacity - 1, lastRefill: now };
-    store.set(storeKey, bucket, config.windowMs * 2);
-    return new RateLimitResult({
-      allowed:   true,
-      limit:     capacity,
-      remaining: Math.floor(bucket.tokens),
-      resetAt:   now + config.windowMs,
-      retryAfter: 0,
-      key,
-      strategy: 'token-bucket',
-    });
-  }
-
-  // Refill tokens proportional to elapsed time
-  const elapsed = now - bucket.lastRefill;
-  bucket.tokens = Math.min(capacity, bucket.tokens + elapsed * refillRate);
-  bucket.lastRefill = now;
-
-  if (bucket.tokens < 1) {
-    // Not enough tokens: calculate when one token will be available
-    const msUntilToken = Math.ceil((1 - bucket.tokens) / refillRate);
-    store.set(storeKey, bucket, config.windowMs * 2);
-
-    return new RateLimitResult({
-      allowed:   false,
-      limit:     capacity,
-      remaining: 0,
-      resetAt:   now + msUntilToken,
-      retryAfter: Math.ceil(msUntilToken / 1000),
-      key,
-      strategy: 'token-bucket',
-    });
-  }
-
-  // Consume one token
-  bucket.tokens -= 1;
-  store.set(storeKey, bucket, config.windowMs * 2);
-
-  return new RateLimitResult({
-    allowed:   true,
-    limit:     capacity,
-    remaining: Math.floor(bucket.tokens),
-    resetAt:   now + Math.ceil((capacity - bucket.tokens) / refillRate),
-    retryAfter: 0,
-    key,
-    strategy: 'token-bucket',
-  });
-}
-
-module.exports = { tokenBucketCheck };
+'use strict';
+
+const { RateLimitResult } = require('../core/result');
+
+/**
+ * Token Bucket strategy.
+ *
+ * Tokens refill continuously at a steady rate. Each request consumes one
+ * token. Allows controlled bursts up to `capacity` tokens while enforcing
+ * a long-term average rate of `max` requests per `windowMs`.
+ *
+ * State per key: { tokens: float, lastRefill: timestamp }
+ *
+ * Refill rate = config.max / config.windowMs  (tokens per millisecond)
+ * Capacity    = config.max  (maximum accumulated tokens)
+ *
+ * This is the algorithm used by Stripe for their API rate limiting.
+ * It feels more "fair" to clients than window-based approaches because
+ * occasional bursts are explicitly allowed.
+ *
+ * @param {string} key      - Rate limit key
+ * @param {object} config   - Resolved NextLimiter config
+ * @param {object} store    - Store instance
+ * @returns {RateLimitResult}
+ */
+function tokenBucketCheck(key, config, store) {
+  const now        = Date.now();
+  const capacity   = config.max;
+  const refillRate = config.max / config.windowMs; // tokens per ms
+  const storeKey   = `${key}:tb`;
+
+  let bucket = store.get(storeKey);
+
+  if (!bucket) {
+    // First request: full bucket, consume one token
+    bucket = { tokens: capacity - 1, lastRefill: now };
+    store.set(storeKey, bucket, config.windowMs * 2);
+    return new RateLimitResult({
+      allowed:   true,
+      limit:     capacity,
+      remaining: Math.floor(bucket.tokens),
+      resetAt:   now + config.windowMs,
+      retryAfter: 0,
+      key,
+      strategy: 'token-bucket',
+    });
+  }
+
+  // Refill tokens proportional to elapsed time
+  const elapsed = now - bucket.lastRefill;
+  bucket.tokens = Math.min(capacity, bucket.tokens + elapsed * refillRate);
+  bucket.lastRefill = now;
+
+  if (bucket.tokens < 1) {
+    // Not enough tokens: calculate when one token will be available
+    const msUntilToken = Math.ceil((1 - bucket.tokens) / refillRate);
+    store.set(storeKey, bucket, config.windowMs * 2);
+
+    return new RateLimitResult({
+      allowed:   false,
+      limit:     capacity,
+      remaining: 0,
+      resetAt:   now + msUntilToken,
+      retryAfter: Math.ceil(msUntilToken / 1000),
+      key,
+      strategy: 'token-bucket',
+    });
+  }
+
+  // Consume one token
+  bucket.tokens -= 1;
+  store.set(storeKey, bucket, config.windowMs * 2);
+
+  return new RateLimitResult({
+    allowed:   true,
+    limit:     capacity,
+    remaining: Math.floor(bucket.tokens),
+    resetAt:   now + Math.ceil((capacity - bucket.tokens) / refillRate),
+    retryAfter: 0,
+    key,
+    strategy: 'token-bucket',
+  });
+}
+
+module.exports = { tokenBucketCheck };

package/src/utils/keyGenerator.js

@@ -1,95 +1,95 @@
-'use strict';
-
-/**
- * Built-in key generators.
- * Each returns a string that uniquely identifies the rate-limit subject.
- */
-
-/**
- * Extract real client IP, respecting common proxy headers.
- * Order: X-Forwarded-For → X-Real-IP → req.ip → req.socket.remoteAddress
- *
- * @param {object} req - Express request
- * @returns {string}
- */
-function getIP(req) {
-  const forwarded = req.headers['x-forwarded-for'];
-  if (forwarded) {
-    // X-Forwarded-For can be a comma-separated list; first entry is client IP
-    return forwarded.split(',')[0].trim();
-  }
-  return (
-    req.headers['x-real-ip'] ||
-    req.ip ||
-    (req.socket && req.socket.remoteAddress) ||
-    'unknown'
-  );
-}
-
-/**
- * Rate limit by authenticated user ID.
- * Looks for userId in: req.user.id → req.user._id → req.userId → req.auth.userId
- *
- * Falls back to IP if no user is found (unauthenticated requests).
- *
- * @param {object} req
- * @returns {string}
- */
-function getUserId(req) {
-  const userId =
-    (req.user && (req.user.id || req.user._id || req.user.userId)) ||
-    req.userId ||
-    (req.auth && req.auth.userId);
-
-  return userId ? `user:${userId}` : `ip:${getIP(req)}`;
-}
-
-/**
- * Rate limit by API key.
- * Looks for key in: Authorization header (Bearer) → X-API-Key header → query.apiKey
- *
- * Falls back to IP if no API key found.
- *
- * @param {object} req
- * @returns {string}
- */
-function getApiKey(req) {
-  // Bearer token in Authorization header
-  const auth = req.headers['authorization'];
-  if (auth && auth.startsWith('Bearer ')) {
-    return `apikey:${auth.slice(7)}`;
-  }
-
-  // X-API-Key custom header
-  const headerKey = req.headers['x-api-key'];
-  if (headerKey) return `apikey:${headerKey}`;
-
-  // Query parameter fallback
-  const queryKey = req.query && req.query.apiKey;
-  if (queryKey) return `apikey:${queryKey}`;
-
-  // Final fallback: IP
-  return `ip:${getIP(req)}`;
-}
-
-/**
- * Resolve a key generator function from the `keyBy` config value.
- *
- * @param {string|function} keyBy - 'ip' | 'user-id' | 'api-key' | custom fn
- * @returns {function}
- */
-function resolveKeyGenerator(keyBy) {
-  if (typeof keyBy === 'function') return keyBy;
-
-  switch (keyBy) {
-    case 'ip':      return getIP;
-    case 'user-id': return getUserId;
-    case 'api-key': return getApiKey;
-    default:
-      throw new Error(
-        `[NexLimit] Unknown keyBy value: "${keyBy}". Use 'ip', 'user-id', 'api-key', or a custom function.`
-      );
-  }
-}
-
-module.exports = { getIP, getUserId, getApiKey, resolveKeyGenerator };
+'use strict';
+
+/**
+ * Built-in key generators.
+ * Each returns a string that uniquely identifies the rate-limit subject.
+ */
+
+/**
+ * Extract real client IP, respecting common proxy headers.
+ * Order: X-Forwarded-For → X-Real-IP → req.ip → req.socket.remoteAddress
+ *
+ * @param {object} req - Express request
+ * @returns {string}
+ */
+function getIP(req) {
+  const forwarded = req.headers['x-forwarded-for'];
+  if (forwarded) {
+    // X-Forwarded-For can be a comma-separated list; first entry is client IP
+    return forwarded.split(',')[0].trim();
+  }
+  return (
+    req.headers['x-real-ip'] ||
+    req.ip ||
+    (req.socket && req.socket.remoteAddress) ||
+    'unknown'
+  );
+}
+
+/**
+ * Rate limit by authenticated user ID.
+ * Looks for userId in: req.user.id → req.user._id → req.userId → req.auth.userId
+ *
+ * Falls back to IP if no user is found (unauthenticated requests).
+ *
+ * @param {object} req
+ * @returns {string}
+ */
+function getUserId(req) {
+  const userId =
+    (req.user && (req.user.id || req.user._id || req.user.userId)) ||
+    req.userId ||
+    (req.auth && req.auth.userId);
+
+  return userId ? `user:${userId}` : `ip:${getIP(req)}`;
+}
+
+/**
+ * Rate limit by API key.
+ * Looks for key in: Authorization header (Bearer) → X-API-Key header → query.apiKey
+ *
+ * Falls back to IP if no API key found.
+ *
+ * @param {object} req
+ * @returns {string}
+ */
+function getApiKey(req) {
+  // Bearer token in Authorization header
+  const auth = req.headers['authorization'];
+  if (auth && auth.startsWith('Bearer ')) {
+    return `apikey:${auth.slice(7)}`;
+  }
+
+  // X-API-Key custom header
+  const headerKey = req.headers['x-api-key'];
+  if (headerKey) return `apikey:${headerKey}`;
+
+  // Query parameter fallback
+  const queryKey = req.query && req.query.apiKey;
+  if (queryKey) return `apikey:${queryKey}`;
+
+  // Final fallback: IP
+  return `ip:${getIP(req)}`;
+}
+
+/**
+ * Resolve a key generator function from the `keyBy` config value.
+ *
+ * @param {string|function} keyBy - 'ip' | 'user-id' | 'api-key' | custom fn
+ * @returns {function}
+ */
+function resolveKeyGenerator(keyBy) {
+  if (typeof keyBy === 'function') return keyBy;
+
+  switch (keyBy) {
+    case 'ip':      return getIP;
+    case 'user-id': return getUserId;
+    case 'api-key': return getApiKey;
+    default:
+      throw new Error(
+        `[NextLimiter] Unknown keyBy value: "${keyBy}". Use 'ip', 'user-id', 'api-key', or a custom function.`
+      );
+  }
+}
+
+module.exports = { getIP, getUserId, getApiKey, resolveKeyGenerator };

package/src/utils/logger.js

@@ -1,76 +1,76 @@
-'use strict';
-
-// ANSI color codes — auto-disabled on non-TTY environments
-const isTTY = process.stdout && process.stdout.isTTY;
-const c = {
-  reset:  isTTY ? '\x1b[0m'  : '',
-  bold:   isTTY ? '\x1b[1m'  : '',
-  dim:    isTTY ? '\x1b[2m'  : '',
-  red:    isTTY ? '\x1b[31m' : '',
-  green:  isTTY ? '\x1b[32m' : '',
-  yellow: isTTY ? '\x1b[33m' : '',
-  cyan:   isTTY ? '\x1b[36m' : '',
-  gray:   isTTY ? '\x1b[90m' : '',
-};
-
-/**
- * Create a logger bound to a specific prefix and enabled flag.
- *
- * @param {string}  prefix  - e.g. '[NexLimit]'
- * @param {boolean} enabled - logging on/off
- * @returns {{ blocked, allowed, warn, info }}
- */
-function createLogger(prefix, enabled) {
-  if (!enabled) {
-    return {
-      blocked: () => {},
-      allowed: () => {},
-      warn:    () => {},
-      info:    () => {},
-    };
-  }
-
-  const tag = `${c.bold}${c.cyan}${prefix}${c.reset}`;
-  const ts  = () => `${c.gray}${new Date().toISOString()}${c.reset}`;
-
-  return {
-    /**
-     * Log a blocked request.
-     * @param {string} key
-     * @param {number} count
-     * @param {number} limit
-     * @param {string} strategy
-     * @param {boolean} smart
-     */
-    blocked(key, count, limit, strategy, smart = false) {
-      const smartTag = smart ? ` ${c.yellow}[smart]${c.reset}` : '';
-      console.log(
-        `${ts()} ${tag} ${c.red}BLOCKED${c.reset}${smartTag} ` +
-        `${c.bold}${key}${c.reset} ` +
-        `${c.red}(${count}/${limit})${c.reset} ` +
-        `${c.dim}via ${strategy}${c.reset}`
-      );
-    },
-
-    /**
-     * Log an allowed request (only useful for debugging — off by default).
-     */
-    allowed(key, remaining, limit) {
-      console.log(
-        `${ts()} ${tag} ${c.green}ALLOWED${c.reset} ` +
-        `${c.bold}${key}${c.reset} ` +
-        `${c.dim}(${remaining}/${limit} remaining)${c.reset}`
-      );
-    },
-
-    warn(message) {
-      console.warn(`${ts()} ${tag} ${c.yellow}WARN${c.reset} ${message}`);
-    },
-
-    info(message) {
-      console.log(`${ts()} ${tag} ${c.cyan}INFO${c.reset} ${message}`);
-    },
-  };
-}
-
-module.exports = { createLogger };
+'use strict';
+
+// ANSI color codes — auto-disabled on non-TTY environments
+const isTTY = process.stdout && process.stdout.isTTY;
+const c = {
+  reset:  isTTY ? '\x1b[0m'  : '',
+  bold:   isTTY ? '\x1b[1m'  : '',
+  dim:    isTTY ? '\x1b[2m'  : '',
+  red:    isTTY ? '\x1b[31m' : '',
+  green:  isTTY ? '\x1b[32m' : '',
+  yellow: isTTY ? '\x1b[33m' : '',
+  cyan:   isTTY ? '\x1b[36m' : '',
+  gray:   isTTY ? '\x1b[90m' : '',
+};
+
+/**
+ * Create a logger bound to a specific prefix and enabled flag.
+ *
+ * @param {string}  prefix  - e.g. '[NextLimiter]'
+ * @param {boolean} enabled - logging on/off
+ * @returns {{ blocked, allowed, warn, info }}
+ */
+function createLogger(prefix, enabled) {
+  if (!enabled) {
+    return {
+      blocked: () => {},
+      allowed: () => {},
+      warn:    () => {},
+      info:    () => {},
+    };
+  }
+
+  const tag = `${c.bold}${c.cyan}${prefix}${c.reset}`;
+  const ts  = () => `${c.gray}${new Date().toISOString()}${c.reset}`;
+
+  return {
+    /**
+     * Log a blocked request.
+     * @param {string} key
+     * @param {number} count
+     * @param {number} limit
+     * @param {string} strategy
+     * @param {boolean} smart
+     */
+    blocked(key, count, limit, strategy, smart = false) {
+      const smartTag = smart ? ` ${c.yellow}[smart]${c.reset}` : '';
+      console.log(
+        `${ts()} ${tag} ${c.red}BLOCKED${c.reset}${smartTag} ` +
+        `${c.bold}${key}${c.reset} ` +
+        `${c.red}(${count}/${limit})${c.reset} ` +
+        `${c.dim}via ${strategy}${c.reset}`
+      );
+    },
+
+    /**
+     * Log an allowed request (only useful for debugging — off by default).
+     */
+    allowed(key, remaining, limit) {
+      console.log(
+        `${ts()} ${tag} ${c.green}ALLOWED${c.reset} ` +
+        `${c.bold}${key}${c.reset} ` +
+        `${c.dim}(${remaining}/${limit} remaining)${c.reset}`
+      );
+    },
+
+    warn(message) {
+      console.warn(`${ts()} ${tag} ${c.yellow}WARN${c.reset} ${message}`);
+    },
+
+    info(message) {
+      console.log(`${ts()} ${tag} ${c.cyan}INFO${c.reset} ${message}`);
+    },
+  };
+}
+
+module.exports = { createLogger };