ioredis-toolkit 0.0.5 → 0.0.7

package/dist/ratelimiter.js

@@ -41,6 +41,23 @@ if count >= limit then
 end
 return { count, retryAfter }
 `;
+/**
+ * Generates a "fail-open" result when Redis is unavailable.
+ *
+ * **Behavior:**
+ * - When Redis errors occur during rate limit operations, the limiter "fails open"
+ *   (allows the request) to prevent an outage from taking down the whole application.
+ * - This helper creates the result structure that would be returned in a fail-open scenario.
+ *
+ **Returns:**
+ * - A {@link RateLimitResult} with `allowed: true` and default values.
+ *
+ * **Parameters:**
+ * - `limit` - The configured maximum request count.
+ * - `duration` - The window length in seconds.
+ *
+ * @internal
+ */
 function failOpenResult(limit, duration) {
     return {
         allowed: true,
@@ -99,6 +116,31 @@ export class RateLimiter {
         this.defaultAlgorithm = options.algorithm ?? 'sliding';
         this.defaultNamespace = options.namespace ?? 'ratelimit';
     }
+    /**
+     * Creates a rate limiter bound to a Redis client.
+     *
+     * **Default Configuration:**
+     * - `limit`: `100` requests per window
+     * - `duration`: `60` seconds per window
+     * - `algorithm`: `'sliding'` (precise rolling window)
+     * - `namespace`: `'ratelimit'` key prefix
+     *
+     * **Example:**
+     * ```ts
+     * // Rate limit per route, per IP, 100 requests per 60 seconds (sliding window)
+     * const limiter = new RateLimiter(client, { limit: 100, duration: 60 });
+     *
+     * // Fixed window: 10 requests per 1 second
+     * const fixed = new RateLimiter(client, { limit: 10, duration: 1, algorithm: 'fixed' });
+     * ```
+     *
+     * **Parameters:**
+     * - `client` - The underlying {@link RedisClientWrapper}. All rate limit operations
+   *   delegate to this client.
+     * - `options` - Default rate limit settings. Overridden per-call via the `consume`
+   *   and `check` methods.
+     * - `logger` - Optional pino-compatible logger. Defaults to `console`.
+     */
     /**
      * Builds the Redis key for a resource + identifier combination.
      *
@@ -114,6 +156,27 @@ export class RateLimiter {
      * // 'ratelimit:/api/login:ip-10.0.0.1'
      * ```
      */
+    /**
+     * Builds the Redis key for a resource + identifier combination.
+     *
+     * **Key Format:**
+     * The generated key follows the pattern: `${namespace}:${resource}:${identifier}`
+     * For example: `ratelimit:/api/login:ip-10.0.0.1`
+     *
+     * **Example:**
+     * ```ts
+     * const key = limiter.makeKey('/api/login', 'ip-10.0.0.1');
+     * // key === 'ratelimit:/api/login:ip-10.0.0.1'
+     * ```
+     *
+     * **Parameters:**
+     * - `resource` - The rate-limited resource, e.g. a route `'/api/login'` or
+   *   a resource name `'email:send'`.
+     * - `identifier` - The caller identity, e.g. an IP, user id or API key.
+     * - `namespace` - Key prefix. Defaults to the limiter's configured namespace.
+     *
+     * @returns The full key, e.g. `'ratelimit:/api/login:ip-10.0.0.1'`.
+     */
     makeKey(resource, identifier, namespace = this.defaultNamespace) {
         return `${namespace}:${resource}:${identifier}`;
     }
@@ -142,6 +205,50 @@ export class RateLimiter {
      * }
      * ```
      */
+    /**
+     * Consumes one unit of capacity for a resource + identifier and returns the
+     * resulting limit state.
+     *
+     * **Behavior:**
+     * - When the limit is reached, the request is not recorded and `allowed` is `false`
+   *   with `retryAfter` (seconds) and `resetAt` (epoch ms) hints.
+     * - Fails open (allows the request) if Redis errors occur, so an outage cannot take
+   *   down the whole app.
+     * - Two algorithm modes are available: `sliding` (default, precise rolling window)
+   *   and `fixed` (simple counter-based).
+     *
+     * **Type Parameters:**
+     * - The return type is {@link RateLimitResult}.
+     *
+     * **Returns:**
+     * - A {@link RateLimitResult} object containing:
+     *   - `allowed`: whether the request may proceed
+     *   - `limit`: the configured max
+     *   - `used`: requests in current window
+     *   - `remaining`: left in the window
+     *   - `resetAt`: epoch ms when window resets
+     *   - `retryAfter`: seconds to wait (0 when allowed)
+     *
+     * **Example:**
+     * ```ts
+     * const result = await limiter.consume('/api/login', 'ip-10.0.0.1');
+     * if (!result.allowed) {
+     *   // HTTP 429, set Retry-After: result.retryAfter
+     *   res.setHeader('Retry-After', String(result.retryAfter));
+     *   return res.status(429).json({ error: 'Too many requests' });
+     * }
+     * // allowed === true, request may proceed
+     * ```
+     *
+     * **Parameters:**
+     * - `resource` - The rate-limited resource, e.g. a route `'/api/login'` or
+   *   a resource name `'email:send'`.
+     * - `identifier` - The caller identity, e.g. an IP, user id or API key.
+     * - `options` - Per-call overrides for `limit`, `duration`, `algorithm`, and `namespace`.
+     *
+     * @returns The limit state: `allowed`, `limit`, `used`, `remaining`,
+     *   `resetAt` (epoch ms), `retryAfter` (seconds).
+     */
     async consume(resource, identifier, options = {}) {
         const limit = options.limit ?? this.defaultLimit;
         const duration = options.duration ?? this.defaultDuration;
@@ -179,6 +286,37 @@ export class RateLimiter {
      * }
      * ```
      */
+    /**
+     * Peeks at the current limit state without consuming capacity.
+     *
+     * **Behavior:**
+     * - Useful for pre-flight checks (e.g. showing "limit reached" in a UI before
+   *   the actual request).
+     * - Does not increment the counter; only reads the current state.
+     * - Fails open (allows the request) if Redis errors occur.
+     *
+     * **Type Parameters:**
+     * - The return type is {@link RateLimitResult}.
+     *
+     * **Returns:**
+     * - A {@link RateLimitResult} object representing the current state.
+     *   `used` is not incremented.
+     *
+     * **Example:**
+     * ```ts
+     * const state = await limiter.check('/api/search', 'user-1');
+     * if (state.remaining === 0) {
+     *   // disable the search button
+     * }
+   * ```
+     *
+     * **Parameters:**
+     * - `resource` - The rate-limited resource.
+     * - `identifier` - The caller identity.
+     * - `options` - Per-call overrides for `limit`, `duration`, `algorithm`, and `namespace`.
+     *
+     * @returns The current limit state; `used` is not incremented.
+     */
     async check(resource, identifier, options = {}) {
         const limit = options.limit ?? this.defaultLimit;
         const duration = options.duration ?? this.defaultDuration;
@@ -210,6 +348,30 @@ export class RateLimiter {
      * await limiter.reset('/api/export', 'user-7');
      * ```
      */
+    /**
+     * Resets the counter for a resource + identifier, granting full capacity again.
+     *
+     * **Behavior:**
+     * - Deletes the rate limit key from Redis, resetting the counter to zero.
+     * - After reset, the next request will be allowed (full capacity available).
+     *
+     * **Returns:**
+     * - `true` if a counter existed and was removed.
+     * - `false` if no counter existed (key already deleted).
+     *
+     * **Example:**
+     * ```ts
+     * // User upgraded to a premium plan, lift their limits
+     * await limiter.reset('/api/export', 'user-7');
+     * ```
+     *
+     * **Parameters:**
+     * - `resource` - The rate-limited resource.
+     * - `identifier` - The caller identity.
+     * - `namespace` - Key prefix. Defaults to the limiter's configured namespace.
+     *
+     * @returns `true` if a counter existed and was removed.
+     */
     async reset(resource, identifier, namespace = this.defaultNamespace) {
         const key = this.makeKey(resource, identifier, namespace);
         try {
@@ -221,6 +383,25 @@ export class RateLimiter {
             return false;
         }
     }
+    /**
+     * Consumes one unit of capacity using the fixed-window algorithm.
+     *
+     * **Behavior:**
+     * - Uses Redis `INCR` to increment a counter key.
+     * - If the counter was `1` (first request in the window), sets a TTL via `EXPIRE`.
+     * - The window resets at fixed boundaries determined by the TTL.
+     * - Returns `allowed: true` as long as `count <= limit`.
+     *
+     * **Returns:**
+     * - A {@link RateLimitResult} with the current window state.
+     *
+     * **Parameters:**
+     * - `key` - The Redis key for this resource + identifier combination.
+     * - `limit` - The maximum allowed requests within the window.
+     * - `duration` - The TTL in seconds for the key (also the window length).
+     *
+     * @internal
+     */
     async consumeFixed(key, limit, duration) {
         const now = Date.now();
         const count = await this.client.incr(key);
@@ -239,6 +420,32 @@ export class RateLimiter {
             retryAfter: allowed ? 0 : ttlSeconds,
         };
     }
+    /**
+     * Consumes one unit of capacity using the sliding-window algorithm.
+     *
+     * **Behavior:**
+     * - Uses an atomic Lua script over a sorted set for a precise rolling window.
+     * - Old entries outside the window are purged before counting.
+     * - A unique member (timestamp + UUID) is added for each request.
+     * - The `PEXPIRE` command ensures the key expires after the window duration.
+     * - Returns `allowed: true` as long as the count of entries within the window is < limit.
+     *
+     * **The Lua script** (see {@link CONSUME_SCRIPT}) performs these operations atomically:
+     * 1. Remove entries with scores older than `now - window`
+     * 2. Count remaining entries (`ZCARD`)
+     * 3. If count >= limit, return `allowed: false` with `retryAfter`
+     * 4. Otherwise, add the new entry (`ZADD`) and return `allowed: true`
+     *
+     * **Returns:**
+     * - A {@link RateLimitResult} with the current window state.
+     *
+     * **Parameters:**
+     * - `key` - The Redis key for this resource + identifier combination.
+     * - `limit` - The maximum allowed requests within the window.
+     * - `duration` - The window length in seconds.
+     *
+     * @internal
+     */
     async consumeSliding(key, limit, duration) {
         const now = Date.now();
         const member = `${now}:${randomUUID()}`;
@@ -256,6 +463,24 @@ export class RateLimiter {
             retryAfter,
         };
     }
+    /**
+     * Peeks at the current limit using the fixed-window algorithm.
+     *
+     * **Behavior:**
+     * - Reads the current counter value from Redis via `GET`.
+     * - If the key does not exist, `used` is `0`.
+     * - Returns `allowed: true` when `used < limit`.
+     *
+     * **Returns:**
+     * - A {@link RateLimitResult} with the current window state.
+     *
+     * **Parameters:**
+     * - `key` - The Redis key for this resource + identifier combination.
+     * - `limit` - The maximum allowed requests within the window.
+     * - `duration` - The TTL/window length in seconds.
+     *
+     * @internal
+     */
     async checkFixed(key, limit, duration) {
         const now = Date.now();
         const raw = await this.client.get(key);
@@ -272,6 +497,31 @@ export class RateLimiter {
             retryAfter: allowed ? 0 : ttlSeconds,
         };
     }
+    /**
+     * Peeks at the current limit using the sliding-window algorithm.
+     *
+     * **Behavior:**
+     * - Uses an atomic Lua script (see {@link PEEK_SCRIPT}) to count entries within
+   *   the rolling window without consuming capacity.
+     * - Old entries outside the window are purged before counting.
+     * - Returns `allowed: true` when the count of entries within the window is < limit.
+     *
+     * **The Lua script** (see {@link PEEK_SCRIPT}) performs:
+     * 1. Remove entries with scores older than `now - window`
+     * 2. Count remaining entries (`ZCARD`)
+     * 3. Return the count and optional `retryAfter`
+     *
+     * **Returns:**
+     * - A {@link RateLimitResult} with the current window state.
+     *   `used` is the count of entries in the window; not incremented.
+     *
+     * **Parameters:**
+     * - `key` - The Redis key for this resource + identifier combination.
+     * - `limit` - The maximum allowed requests within the window.
+     * - `duration` - The window length in seconds.
+     *
+     * @internal
+     */
     async checkSliding(key, limit, duration) {
         const now = Date.now();
         const result = (await this.client.raw.eval(PEEK_SCRIPT, 1, key, now, duration * 1000, limit));

package/dist/session/scripts/create.lua

@@ -1,7 +1,8 @@
 -- create.lua (version 1)
 -- Atomically creates a session record, registers it in the user index
--- (ZSET, score = createdAt), optionally claims an idempotency key, and
--- enforces maxSessionsPerUser with bounded oldest-first eviction.
+-- (ZSET, score = microsecond-resolution Redis server time, used purely
+-- for eviction ordering - see below), optionally claims an idempotency
+-- key, and enforces maxSessionsPerUser with bounded oldest-first eviction.
 --
 -- KEYS[1] = session record key
 -- KEYS[2] = user session index key (ZSET)
@@ -44,7 +45,21 @@ if redis.call('EXISTS', key) == 1 then
 end
 
 redis.call('SET', key, ARGV[1], 'EX', tonumber(ARGV[4]))
-redis.call('ZADD', index, tonumber(ARGV[3]), ARGV[2])
+
+-- The user index score is used purely for oldest-first eviction ordering
+-- (never as the record's createdAt, which is app-stamped seconds inside the
+-- envelope). Redis breaks equal ZSET scores by lexicographic member order,
+-- not insertion order, so scoring by second-granularity createdAt would
+-- make eviction pick an arbitrary (jti-lexicographic) session rather than
+-- the actual oldest one whenever a user creates more than one session in
+-- the same wall-clock second - a realistic case under normal traffic, not
+-- just a burst edge case. Redis is single-threaded, so two scripts touching
+-- the same user slot never observe the same TIME() reading in practice;
+-- microsecond-resolution server time therefore gives a strictly monotonic,
+-- clock-skew-free ordering key for this user's index.
+local t = redis.call('TIME')
+local orderScore = tonumber(t[1]) + (tonumber(t[2]) / 1000000)
+redis.call('ZADD', index, orderScore, ARGV[2])
 
 local evicted = {}
 local limit = tonumber(ARGV[5])

package/dist/session/scripts/rotate-encrypted.lua

@@ -37,7 +37,8 @@ if env.v ~= 2 then
   return 6
 end
 
-local now = tonumber(redis.call('TIME')[1])
+local t = redis.call('TIME')
+local now = tonumber(t[1])
 
 -- Retry-safe replay detection BEFORE rejecting consumed records.
 -- The rotation nonce uniquely identifies the rotation: when the consumed
@@ -102,6 +103,8 @@ end
 
 redis.call('SET', KEYS[2], cjson.encode(nextEnv), 'EX', nextTtl)
 redis.call('ZREM', KEYS[3], ARGV[7])
-redis.call('ZADD', KEYS[3], now, ARGV[3])
+-- Microsecond-resolution ordering score - see create.lua for why
+-- second-granularity scores break oldest-first eviction ordering.
+redis.call('ZADD', KEYS[3], tonumber(t[1]) + (tonumber(t[2]) / 1000000), ARGV[3])
 
 return { 1, ARGV[3] }

package/dist/session/scripts/rotate.lua

@@ -44,7 +44,8 @@ if env.v ~= 1 then
 end
 
 local s = env.s
-local now = tonumber(redis.call('TIME')[1])
+local t = redis.call('TIME')
+local now = tonumber(t[1])
 
 -- Retry-safe replay detection BEFORE rejecting consumed records.
 -- The rotation nonce uniquely identifies the rotation: when the consumed
@@ -114,6 +115,8 @@ end
 
 redis.call('SET', KEYS[2], cjson.encode(nextEnv), 'EX', nextTtl)
 redis.call('ZREM', KEYS[3], ARGV[6])
-redis.call('ZADD', KEYS[3], now, ARGV[2])
+-- Microsecond-resolution ordering score - see create.lua for why
+-- second-granularity scores break oldest-first eviction ordering.
+redis.call('ZADD', KEYS[3], tonumber(t[1]) + (tonumber(t[2]) / 1000000), ARGV[2])
 
 return { 1, ARGV[2] }

package/dist/types.js

@@ -67,8 +67,6 @@ export const BaseRedisConfigSchema = z
     maxFanOutConcurrency: z.number().int().min(1).max(128).default(8),
     maxBatchSize: z.number().int().min(1).max(10_000).default(500),
     lockOptions: DistributedLockOptionsSchema.optional(),
-    // defaultTTL: z.number().int().min(0).default(3_600),
-    // compressionThreshold: z.number().int().min(1).default(1_024),
     cacheOptions: CacheOptionsSchema.optional(),
     slowCommandThreshold: z.number().int().min(0).default(1_000),
     rateLimit: RateLimitOptionsSchema.optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ioredis-toolkit",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "Production-grade, type-safe Redis infrastructure for standalone, Sentinel, and Cluster deployments",
   "type": "module",
   "main": "./dist/index.js",