te.js 2.1.0 → 2.1.2

package/rate-limit/storage/base.js

@@ -1,104 +1,104 @@
-import TejError from '../../server/error.js';
-
-/**
- * Abstract base class for rate limiter storage backends
- *
- * @abstract
- * @description
- * Defines the interface that all storage implementations must follow.
- * Storage backends are responsible for persisting rate limit data and handling
- * data expiration. Two implementations are provided out of the box:
- * - MemoryStorage: For single-instance applications and testing
- * - RedisStorage: For distributed applications
- *
- * Custom storage implementations can be created by extending this class
- * and implementing all required methods.
- *
- * @example
- * // Custom storage implementation
- * class MyCustomStorage extends RateLimitStorage {
- *   async get(key) {
- *     // Implementation
- *   }
- *   async set(key, value, ttl) {
- *     // Implementation
- *   }
- *   async increment(key) {
- *     // Implementation
- *   }
- *   async delete(key) {
- *     // Implementation
- *   }
- * }
- */
-class RateLimitStorage {
-  /**
-   * Retrieve rate limit data for a given key
-   *
-   * @abstract
-   * @param {string} key - The storage key to retrieve data for
-   * @returns {Promise<Object|null>} The stored data, or null if not found
-   * @throws {Error} If not implemented by child class
-   *
-   * @example
-   * const data = await storage.get('rl:127.0.0.1');
-   * if (data) {
-   *   console.log('Found rate limit data:', data);
-   * }
-   */
-  async get(key) {
-    throw new TejError(500, 'Not implemented');
-  }
-
-  /**
-   * Store rate limit data with optional expiration
-   *
-   * @abstract
-   * @param {string} key - The storage key to store data under
-   * @param {Object} value - The data to store
-   * @param {number} ttl - Time-to-live in seconds
-   * @returns {Promise<void>}
-   * @throws {Error} If not implemented by child class
-   *
-   * @example
-   * await storage.set('rl:127.0.0.1', { counter: 5 }, 60);
-   */
-  async set(key, value, ttl) {
-    throw new TejError(500, 'Not implemented');
-  }
-
-  /**
-   * Increment a numeric value in storage
-   *
-   * @abstract
-   * @param {string} key - The storage key to increment
-   * @returns {Promise<number|null>} The new value after increment, or null if key not found
-   * @throws {Error} If not implemented by child class
-   *
-   * @example
-   * const newValue = await storage.increment('rl:127.0.0.1');
-   * if (newValue !== null) {
-   *   console.log('New counter value:', newValue);
-   * }
-   */
-  async increment(key) {
-    throw new TejError(500, 'Not implemented');
-  }
-
-  /**
-   * Delete data for a given key
-   *
-   * @abstract
-   * @param {string} key - The storage key to delete
-   * @returns {Promise<void>}
-   * @throws {Error} If not implemented by child class
-   *
-   * @example
-   * await storage.delete('rl:127.0.0.1');
-   */
-  async delete(key) {
-    throw new TejError(500, 'Not implemented');
-  }
-}
-
-export default RateLimitStorage;
+import TejError from '../../server/error.js';
+
+/**
+ * Abstract base class for rate limiter storage backends
+ *
+ * @abstract
+ * @description
+ * Defines the interface that all storage implementations must follow.
+ * Storage backends are responsible for persisting rate limit data and handling
+ * data expiration. Two implementations are provided out of the box:
+ * - MemoryStorage: For single-instance applications and testing
+ * - RedisStorage: For distributed applications
+ *
+ * Custom storage implementations can be created by extending this class
+ * and implementing all required methods.
+ *
+ * @example
+ * // Custom storage implementation
+ * class MyCustomStorage extends RateLimitStorage {
+ *   async get(key) {
+ *     // Implementation
+ *   }
+ *   async set(key, value, ttl) {
+ *     // Implementation
+ *   }
+ *   async increment(key) {
+ *     // Implementation
+ *   }
+ *   async delete(key) {
+ *     // Implementation
+ *   }
+ * }
+ */
+class RateLimitStorage {
+  /**
+   * Retrieve rate limit data for a given key
+   *
+   * @abstract
+   * @param {string} key - The storage key to retrieve data for
+   * @returns {Promise<Object|null>} The stored data, or null if not found
+   * @throws {Error} If not implemented by child class
+   *
+   * @example
+   * const data = await storage.get('rl:127.0.0.1');
+   * if (data) {
+   *   console.log('Found rate limit data:', data);
+   * }
+   */
+  async get(key) {
+    throw new TejError(500, 'Not implemented');
+  }
+
+  /**
+   * Store rate limit data with optional expiration
+   *
+   * @abstract
+   * @param {string} key - The storage key to store data under
+   * @param {Object} value - The data to store
+   * @param {number} ttl - Time-to-live in seconds
+   * @returns {Promise<void>}
+   * @throws {Error} If not implemented by child class
+   *
+   * @example
+   * await storage.set('rl:127.0.0.1', { counter: 5 }, 60);
+   */
+  async set(key, value, ttl) {
+    throw new TejError(500, 'Not implemented');
+  }
+
+  /**
+   * Increment a numeric value in storage
+   *
+   * @abstract
+   * @param {string} key - The storage key to increment
+   * @returns {Promise<number|null>} The new value after increment, or null if key not found
+   * @throws {Error} If not implemented by child class
+   *
+   * @example
+   * const newValue = await storage.increment('rl:127.0.0.1');
+   * if (newValue !== null) {
+   *   console.log('New counter value:', newValue);
+   * }
+   */
+  async increment(key) {
+    throw new TejError(500, 'Not implemented');
+  }
+
+  /**
+   * Delete data for a given key
+   *
+   * @abstract
+   * @param {string} key - The storage key to delete
+   * @returns {Promise<void>}
+   * @throws {Error} If not implemented by child class
+   *
+   * @example
+   * await storage.delete('rl:127.0.0.1');
+   */
+  async delete(key) {
+    throw new TejError(500, 'Not implemented');
+  }
+}
+
+export default RateLimitStorage;

package/rate-limit/storage/memory.js

@@ -1,102 +1,102 @@
-import RateLimitStorage from './base.js';
-
-/**
- * In-memory storage implementation for rate limiting
- * 
- * @extends RateLimitStorage
- * @description
- * This storage backend uses a JavaScript Map to store rate limit data in memory.
- * It's suitable for single-instance applications or testing environments, but not 
- * recommended for production use in distributed systems as data is not shared
- * between instances.
- * 
- * Key features:
- * - Fast access (all data in memory)
- * - Automatic cleanup of expired entries
- * - No external dependencies
- * - Data is lost on process restart
- * - Not suitable for distributed systems
- * 
- * @example
- * import { TokenBucketRateLimiter, MemoryStorage } from 'te.js/rate-limit';
- * 
- * // Memory storage is used by default if no redis config is provided
- * const limiter = new TokenBucketRateLimiter({
- *   maxRequests: 60,
- *   timeWindowSeconds: 60,
- *   tokenBucketConfig: {
- *     refillRate: 1,
- *     burstSize: 60
- *   }
- * });
- * 
- * // Or create storage instance explicitly
- * const storage = new MemoryStorage();
- * await storage.set('key', { counter: 5 }, 60); // Store for 60 seconds
- */
-class MemoryStorage extends RateLimitStorage {
-  /**
-   * Initialize a new memory storage instance
-   */
-  constructor() {
-    super();
-    this.store = new Map();
-  }
-
-  /**
-   * Get stored data for a key, handling expiration
-   * 
-   * @param {string} key - The storage key to retrieve data for
-   * @returns {Promise<Object|null>} The stored data, or null if not found or expired
-   */
-  async get(key) {
-    const item = this.store.get(key);
-    if (!item) return null;
-    if (item.expireAt < Date.now()) {
-      this.store.delete(key);
-      return null;
-    }
-    return item.value;
-  }
-
-  /**
-   * Store data with expiration time
-   * 
-   * @param {string} key - The storage key
-   * @param {Object} value - The data to store
-   * @param {number} ttl - Time-to-live in seconds
-   * @returns {Promise<void>}
-   */
-  async set(key, value, ttl) {
-    this.store.set(key, {
-      value,
-      expireAt: Date.now() + ttl * 1000
-    });
-  }
-
-  /**
-   * Increment a numeric value in storage
-   * 
-   * @param {string} key - The storage key to increment
-   * @returns {Promise<number|null>} New value after increment, or null if key not found/expired
-   */
-  async increment(key) {
-    const item = await this.get(key);
-    if (!item) return null;
-    item.counter = (item.counter || 0) + 1;
-    await this.set(key, item, (item.expireAt - Date.now()) / 1000);
-    return item.counter;
-  }
-
-  /**
-   * Delete data for a key
-   * 
-   * @param {string} key - The storage key to delete
-   * @returns {Promise<void>}
-   */
-  async delete(key) {
-    this.store.delete(key);
-  }
-}
-
+import RateLimitStorage from './base.js';
+
+/**
+ * In-memory storage implementation for rate limiting
+ * 
+ * @extends RateLimitStorage
+ * @description
+ * This storage backend uses a JavaScript Map to store rate limit data in memory.
+ * It's suitable for single-instance applications or testing environments, but not 
+ * recommended for production use in distributed systems as data is not shared
+ * between instances.
+ * 
+ * Key features:
+ * - Fast access (all data in memory)
+ * - Automatic cleanup of expired entries
+ * - No external dependencies
+ * - Data is lost on process restart
+ * - Not suitable for distributed systems
+ * 
+ * @example
+ * import { TokenBucketRateLimiter, MemoryStorage } from 'te.js/rate-limit';
+ * 
+ * // Memory storage is used by default if no redis config is provided
+ * const limiter = new TokenBucketRateLimiter({
+ *   maxRequests: 60,
+ *   timeWindowSeconds: 60,
+ *   tokenBucketConfig: {
+ *     refillRate: 1,
+ *     burstSize: 60
+ *   }
+ * });
+ * 
+ * // Or create storage instance explicitly
+ * const storage = new MemoryStorage();
+ * await storage.set('key', { counter: 5 }, 60); // Store for 60 seconds
+ */
+class MemoryStorage extends RateLimitStorage {
+  /**
+   * Initialize a new memory storage instance
+   */
+  constructor() {
+    super();
+    this.store = new Map();
+  }
+
+  /**
+   * Get stored data for a key, handling expiration
+   * 
+   * @param {string} key - The storage key to retrieve data for
+   * @returns {Promise<Object|null>} The stored data, or null if not found or expired
+   */
+  async get(key) {
+    const item = this.store.get(key);
+    if (!item) return null;
+    if (item.expireAt < Date.now()) {
+      this.store.delete(key);
+      return null;
+    }
+    return item.value;
+  }
+
+  /**
+   * Store data with expiration time
+   * 
+   * @param {string} key - The storage key
+   * @param {Object} value - The data to store
+   * @param {number} ttl - Time-to-live in seconds
+   * @returns {Promise<void>}
+   */
+  async set(key, value, ttl) {
+    this.store.set(key, {
+      value,
+      expireAt: Date.now() + ttl * 1000
+    });
+  }
+
+  /**
+   * Increment a numeric value in storage
+   * 
+   * @param {string} key - The storage key to increment
+   * @returns {Promise<number|null>} New value after increment, or null if key not found/expired
+   */
+  async increment(key) {
+    const item = await this.get(key);
+    if (!item) return null;
+    item.counter = (item.counter || 0) + 1;
+    await this.set(key, item, (item.expireAt - Date.now()) / 1000);
+    return item.counter;
+  }
+
+  /**
+   * Delete data for a key
+   * 
+   * @param {string} key - The storage key to delete
+   * @returns {Promise<void>}
+   */
+  async delete(key) {
+    this.store.delete(key);
+  }
+}
+
 export default MemoryStorage;

package/rate-limit/storage/redis.js

@@ -1,88 +1,88 @@
-import RateLimitStorage from './base.js';
-
-/**
- * Redis storage implementation for rate limiting
- *
- * @extends RateLimitStorage
- * @description
- * This storage backend uses Redis for distributed rate limiting across multiple application instances.
- * It's the recommended storage backend for production use in distributed systems as it provides
- * reliable rate limiting across all application instances.
- *
- * Key features:
- * - Distributed rate limiting (works across multiple app instances)
- * - Atomic operations for race condition prevention
- * - Automatic key expiration using Redis TTL
- * - Persistence options available through Redis configuration
- * - Clustering support for high availability
- *
- * @example
- * import { TokenBucketRateLimiter } from 'te.js/rate-limit';
- *
- * // Use Redis storage for distributed rate limiting
- * const limiter = new TokenBucketRateLimiter({
- *   maxRequests: 100,
- *   timeWindowSeconds: 60,
- *   store: 'redis', // Use Redis storage
- *   tokenBucketConfig: {
- *     refillRate: 2,
- *     burstSize: 100
- *   }
- * });
- */
-class RedisStorage extends RateLimitStorage {
-  /**
-   * Initialize Redis storage with client
-   *
-   * @param {RedisClient} client - Connected Redis client instance
-   */
-  constructor(client) {
-    super();
-    this.client = client;
-  }
-
-  /**
-   * Get stored data for a key
-   *
-   * @param {string} key - The storage key to retrieve
-   * @returns {Promise<Object|null>} Stored value if found, null otherwise
-   */
-  async get(key) {
-    const value = await this.client.get(key);
-    return value ? JSON.parse(value) : null;
-  }
-
-  /**
-   * Store data with expiration time
-   *
-   * @param {string} key - The storage key
-   * @param {Object} value - The data to store
-   * @param {number} ttl - Time-to-live in seconds
-   * @returns {Promise<void>}
-   */
-  async set(key, value, ttl) {
-    await this.client.set(key, JSON.stringify(value), { EX: ttl });
-  }
-
-  /**
-   * Increment a counter value atomically
-   *
-   * @param {string} key - The storage key to increment
-   * @returns {Promise<number>} New value after increment
-   */
-  async increment(key) {
-    return await this.client.incr(key);
-  }
-
-  /**
-   * Delete data for a key
-   *
-   * @param {string} key - The storage key to delete
-   * @returns {Promise<void>}
-   */
-  async delete(key) {
-    await this.client.del(key);
-  }
-}
-
-export default RedisStorage;
+import RateLimitStorage from './base.js';
+
+/**
+ * Redis storage implementation for rate limiting
+ *
+ * @extends RateLimitStorage
+ * @description
+ * This storage backend uses Redis for distributed rate limiting across multiple application instances.
+ * It's the recommended storage backend for production use in distributed systems as it provides
+ * reliable rate limiting across all application instances.
+ *
+ * Key features:
+ * - Distributed rate limiting (works across multiple app instances)
+ * - Atomic operations for race condition prevention
+ * - Automatic key expiration using Redis TTL
+ * - Persistence options available through Redis configuration
+ * - Clustering support for high availability
+ *
+ * @example
+ * import { TokenBucketRateLimiter } from 'te.js/rate-limit';
+ *
+ * // Use Redis storage for distributed rate limiting
+ * const limiter = new TokenBucketRateLimiter({
+ *   maxRequests: 100,
+ *   timeWindowSeconds: 60,
+ *   store: 'redis', // Use Redis storage
+ *   tokenBucketConfig: {
+ *     refillRate: 2,
+ *     burstSize: 100
+ *   }
+ * });
+ */
+class RedisStorage extends RateLimitStorage {
+  /**
+   * Initialize Redis storage with client
+   *
+   * @param {RedisClient} client - Connected Redis client instance
+   */
+  constructor(client) {
+    super();
+    this.client = client;
+  }
+
+  /**
+   * Get stored data for a key
+   *
+   * @param {string} key - The storage key to retrieve
+   * @returns {Promise<Object|null>} Stored value if found, null otherwise
+   */
+  async get(key) {
+    const value = await this.client.get(key);
+    return value ? JSON.parse(value) : null;
+  }
+
+  /**
+   * Store data with expiration time
+   *
+   * @param {string} key - The storage key
+   * @param {Object} value - The data to store
+   * @param {number} ttl - Time-to-live in seconds
+   * @returns {Promise<void>}
+   */
+  async set(key, value, ttl) {
+    await this.client.set(key, JSON.stringify(value), { EX: ttl });
+  }
+
+  /**
+   * Increment a counter value atomically
+   *
+   * @param {string} key - The storage key to increment
+   * @returns {Promise<number>} New value after increment
+   */
+  async increment(key) {
+    return await this.client.incr(key);
+  }
+
+  /**
+   * Delete data for a key
+   *
+   * @param {string} key - The storage key to delete
+   * @returns {Promise<void>}
+   */
+  async delete(key) {
+    await this.client.del(key);
+  }
+}
+
+export default RedisStorage;