ioredis-toolkit 0.0.4 → 0.0.6

package/dist/pubsub.js

@@ -4,21 +4,50 @@ import { defaultLogger } from './logger.js';
 /**
  * Redis Pub/Sub with a dedicated publisher and subscriber connection.
  *
- * Messages are JSON-serialized on publish and auto-parsed on delivery.
- * Extends `EventEmitter` and emits `'error'` on subscriber failures.
+ * **Description:**
+ * Provides a higher-level interface over native Redis Pub/Sub with the following features:
+ * - Dedicated publisher connection (configured at construction)
+ * - Dedicated subscriber connection (opened via {@link connectSubscriber})
+ * - JSON serialization on publish, auto-parsing on delivery
+ * - Pattern subscription support (`psubscribe`, `punsubscribe`)
+ * - Extends Node.js `EventEmitter` for event-based handling
+ * - Emits `'error'` events on subscriber failures
  *
- * Works in all three modes (standalone, sentinel, cluster).
+ * **Type Parameters:**
+ * - `T` - The type of message payload. When publishing non-string values, they are
+ *   JSON-serialized. When subscribing, messages are auto-parsed from JSON when possible.
  *
- * @example
+ * **Mode Support:**
+ * - Standalone, Sentinel, and Cluster modes are all supported.
+ * - The subscriber connection is created per the configured mode.
+ *
+ * **Example:**
  * ```ts
  * const pubsub = new PubSub(client);
- * await pubsub.connectSubscriber(redisConfig);
+ * await pubsub.connectSubscriber({ mode: 'standalone', host: 'localhost', port: 6379 });
  *
+ * // Subscribe to a channel
  * await pubsub.subscribe('orders:created', (message) => {
- *   console.log(message); // { id: 1 }
+ *   console.log(message); // { id: 1 } - JSON-parsed
+ * });
+ *
+ * // Publish a message
+ * const receivers = await pubsub.publish('orders:created', { id: 1 });
+ * // receivers === number of subscribers that received the message
+ *
+ * // Pattern subscription
+ * await pubsub.psubscribe('orders:*', ({ channel, message }) => {
+ *   console.log(channel, message);
  * });
- * await pubsub.publish('orders:created', { id: 1 });
  * ```
+ *
+ * **Event Emissions:**
+ * - `message`: Emitted when a message is received on a subscribed channel.
+ *   Payload: `{ channel: string, message: string }`
+ * - `pmessage`: Emitted when a pattern message is received.
+ *   Payload: `{ pattern: string, channel: string, message: string }`
+ * - `error`: Emitted on subscriber errors.
+ *   Payload: `Error`
  */
 export class PubSub extends EventEmitter {
     publisher;
@@ -26,6 +55,18 @@ export class PubSub extends EventEmitter {
     logger;
     subscriptions = new Map();
     patternSubscriptions = new Map();
+    /**
+     * Creates a pub/sub instance. Publishing works immediately; subscribing
+     * requires calling {@link connectSubscriber} first.
+     *
+     * @param publisher - A {@link RedisClientWrapper} used for publishing.
+     * @param logger - Optional pino-compatible logger; defaults to `console`.
+     *
+     * @example
+     * ```ts
+     * const pubsub = new PubSub(client);
+     * ```
+     */
     /**
      * Creates a pub/sub instance. Publishing works immediately; subscribing
      * requires calling {@link connectSubscriber} first.
@@ -56,12 +97,46 @@ export class PubSub extends EventEmitter {
      * await pubsub.connectSubscriber({ mode: 'standalone', host: 'localhost', port: 6379 });
      * ```
      */
+    /**
+     * Opens a dedicated subscriber connection.
+     *
+     * **Behavior:**
+     * - Idempotent: a second call is a no-op while a subscriber is connected.
+     * - Subscriber errors are emitted as `'error'` events on the instance.
+     *
+     * **Parameters:**
+     * - `config` - Redis config for the subscriber connection (any mode: standalone, sentinel, or cluster).
+     *
+     * **Example:**
+     * ```ts
+     * // Connect with standalone configuration
+     * await pubsub.connectSubscriber({ mode: 'standalone', host: 'localhost', port: 6379 });
+     *
+     * // Connect with cluster configuration
+     * await pubsub.connectSubscriber({
+     *   mode: 'cluster',
+     *   clusterNodes: [{ host: 'redis1', port: 7000 }, { host: 'redis2', port: 7001 }],
+     * });
+     * ```
+     *
+     * @returns `Promise<void>` that resolves when the subscriber connection is established.
+     */
     async connectSubscriber(config) {
         if (this.subscriber)
             return;
         this.subscriber = new RedisClientWrapper(config, this.logger);
         this.setupSubscriber();
     }
+    /**
+     * Sets up event listeners on the subscriber connection.
+     *
+     * **Behavior:**
+     * - Listens for `message` events and dispatches to {@link handleMessage}.
+     * - Listens for `pmessage` events (pattern subscriptions) and dispatches to {@link handlePatternMessage}.
+     * - Listens for `error` events and emits them on the instance.
+     *
+     * @internal
+     */
     setupSubscriber() {
         if (!this.subscriber)
             return;
@@ -77,6 +152,20 @@ export class PubSub extends EventEmitter {
             this.emit('error', error);
         });
     }
+    /**
+     * Handles a standard message event from the subscriber.
+     *
+     * **Behavior:**
+     * - Parses the message payload as JSON when possible.
+     * - Invokes all registered handlers for the channel.
+     * - Catches and logs handler errors without crashing.
+     *
+     * **Parameters:**
+     * - `channel` - The Redis channel name.
+     * - `message` - The raw message string from Redis (JSON-encoded).
+     *
+     * @internal
+     */
     handleMessage(channel, message) {
         const handlers = this.subscriptions.get(channel);
         if (!handlers)
@@ -95,6 +184,22 @@ export class PubSub extends EventEmitter {
             }
         }
     }
+    /**
+     * Handles a pattern message event from the subscriber.
+     *
+     * **Behavior:**
+     * - Parses the message payload as JSON when possible.
+     * - Invokes all registered handlers for the pattern.
+     * - Each handler receives an object with `channel` and `message` properties.
+     * - Catches and logs handler errors without crashing.
+     *
+     * **Parameters:**
+     * - `pattern` - The pattern that matched.
+     * - `channel` - The specific channel that was matched.
+     * - `message` - The raw message string from Redis (JSON-encoded).
+     *
+     * @internal
+     */
     handlePatternMessage(pattern, channel, message) {
         const handlers = this.patternSubscriptions.get(pattern);
         if (!handlers)
@@ -127,6 +232,32 @@ export class PubSub extends EventEmitter {
      * const receivers = await pubsub.publish('orders:created', { id: 1, total: 99 });
      * ```
      */
+    /**
+     * Publishes a message to a channel.
+     *
+     * **Behavior:**
+     * - Non-string values are JSON-serialized automatically.
+     * - The raw message is published to the Redis channel.
+     * - Returns the number of subscribers that received the message.
+     *
+     * **Type Parameters:**
+     * - `T` - The type of the message payload. Non-string values are JSON-serialized.
+     *
+     * **Returns:**
+     * - The number of subscribers that received the message.
+     *
+     * **Example:**
+     * ```ts
+     * const receivers = await pubsub.publish('orders:created', { id: 1, total: 99 });
+     * // receivers === number of subscribed clients
+     * ```
+     *
+     * **Parameters:**
+     * - `channel` - The channel name.
+     * - `message` - The message payload (string or any JSON-serializable value).
+     *
+     * @returns The number of subscribers that received the message.
+     */
     async publish(channel, message) {
         const raw = typeof message === 'string' ? message : JSON.stringify(message);
         return this.publisher.raw.publish(channel, raw);
@@ -148,6 +279,34 @@ export class PubSub extends EventEmitter {
      * });
      * ```
      */
+    /**
+     * Subscribes a handler to a channel.
+     *
+     * **Behavior:**
+     * - Multiple handlers per channel are supported; the channel is subscribed on
+     *   Redis only once.
+     * - Delivered payloads are JSON-parsed when possible.
+     * - Throws an error if the subscriber connection is not open.
+     *
+     * **Type Parameters:**
+     * - `T` - The type of the message data received in the handler.
+     *
+     * **Returns:**
+     * - `Promise<void>` that resolves when the subscription is established.
+   *
+     * **Example:**
+     * ```ts
+     * await pubsub.subscribe('orders:created', (order) => {
+     *   console.log(order.id);
+     * });
+     * ```
+     *
+     * **Parameters:**
+     * - `channel` - The channel name.
+     * - `handler` - Callback receiving the (parsed) message.
+     *
+     * @throws `Error` if the subscriber connection is not open.
+     */
     async subscribe(channel, handler) {
         if (!this.subscriber) {
             throw new Error('Subscriber not connected');
@@ -175,6 +334,28 @@ export class PubSub extends EventEmitter {
      * await pubsub.unsubscribe('orders:created'); // remove everything
      * ```
      */
+    /**
+     * Removes a handler (or all handlers) from a channel.
+     *
+     * **Behavior:**
+     * - The Redis subscription is dropped once the last handler for the channel is
+     *   removed.
+     * - Without a handler, the whole channel is unsubscribed.
+     *
+     * **Returns:**
+     * - `Promise<void>` that resolves when the unsubscription is complete.
+   *
+     * **Example:**
+     * ```ts
+     * await pubsub.unsubscribe('orders:created', myHandler);
+     * await pubsub.unsubscribe('orders:created'); // remove everything
+     * ```
+     *
+     * **Parameters:**
+     * - `channel` - The channel name.
+     * - `handler` - Optional specific handler to remove; when omitted all
+     *   handlers for the channel are removed.
+     */
     async unsubscribe(channel, handler) {
         if (!this.subscriber)
             return;
@@ -207,6 +388,32 @@ export class PubSub extends EventEmitter {
      * });
      * ```
      */
+    /**
+       * Subscribes a handler to all channels matching a glob pattern.
+       *
+       * **Behavior:**
+       * - Pattern handlers receive `{ channel, message }` (message JSON-parsed).
+       * - The Redis subscription is set up once per pattern.
+       *
+       * **Type Parameters:**
+       * - `T` - The type of the message data received in the handler.
+       *
+       * **Returns:**
+       * - `Promise<void>` that resolves when the pattern subscription is established.
+     *
+       * **Example:**
+       * ```ts
+       * await pubsub.psubscribe('orders:*', ({ channel, message }) => {
+       *   console.log(channel, message);
+       * });
+       * ```
+       *
+       * **Parameters:**
+       * - `pattern` - Glob pattern, e.g. `'orders:*'`.
+       * - `handler` - Callback receiving `{ channel, message }`.
+       *
+       * @throws `Error` if the subscriber connection is not open.
+       */
     async psubscribe(pattern, handler) {
         if (!this.subscriber) {
             throw new Error('Subscriber not connected');
@@ -230,6 +437,23 @@ export class PubSub extends EventEmitter {
      * await pubsub.punsubscribe('orders:*');
      * ```
      */
+    /**
+     * Removes a handler (or all handlers) from a pattern subscription.
+     *
+     * **Returns:**
+     * - `Promise<void>` that resolves when the punsubscription is complete.
+     *
+     * **Example:**
+     * ```ts
+     * await pubsub.punsubscribe('orders:*', myHandler);
+     * await pubsub.punsubscribe('orders:*');
+     * ```
+     *
+     * **Parameters:**
+     * - `pattern` - The glob pattern.
+     * - `handler` - Optional specific handler to remove; when omitted all
+     *   handlers for the pattern are removed.
+     */
     async punsubscribe(pattern, handler) {
         if (!this.subscriber)
             return;
@@ -256,6 +480,20 @@ export class PubSub extends EventEmitter {
      * await pubsub.close();
      * ```
      */
+    /**
+     * Closes the subscriber connection and clears all subscriptions.
+     *
+     * **Behavior:**
+     * - The publisher client is not closed (it is owned by the caller).
+     * - All subscriptions are cleared from memory.
+     *
+     * **Example:**
+     * ```ts
+     * await pubsub.close();
+     * ```
+     *
+     * @returns `Promise<void>` that resolves when the subscriber is closed.
+     */
     async close() {
         if (this.subscriber) {
             await this.subscriber.close();
@@ -275,6 +513,20 @@ export class PubSub extends EventEmitter {
      * // { subscriptions: 2, patternSubscriptions: 1, connected: true }
      * ```
      */
+    /**
+     * Returns subscription statistics.
+     *
+     * **Returns:**
+     * - A {@link PubSubStats} object with the current subscription state.
+     *
+     * **Example:**
+     * ```ts
+     * const stats = pubsub.getStats();
+     * // { subscriptions: 2, patternSubscriptions: 1, connected: true }
+     * ```
+     *
+     * @returns `{ subscriptions, patternSubscriptions, connected }`.
+     */
     getStats() {
         return {
             subscriptions: this.subscriptions.size,

package/dist/ratelimiter.d.ts

@@ -6,10 +6,32 @@ import { RateLimitOptionsInput } from './types.js';
  * - `fixed` - fixed window via `INCR`/`EXPIRE` (simple, cheapest)
  * - `sliding` - sliding window via an atomic Lua script over a sorted set (smoothest)
  */
+/**
+ * Window algorithm used by the rate limiter.
+ *
+ * - `fixed` - Fixed window via `INCR`/`EXPIRE` (simple, cheapest).
+ * - `sliding` - Sliding window via an atomic Lua script over a sorted set (smoothest,
+ *   precise rolling window).
+ */
 export type RateLimitAlgorithm = 'fixed' | 'sliding';
 /**
  * Options for a rate limiter instance or an individual call.
  */
+/**
+ * Options for a rate limiter instance or an individual call.
+ *
+ * **Algorithm Details:**
+ * - `sliding` (default): Uses a sorted set with a Lua script for a precise rolling window.
+ *   New entries are added with the current timestamp, and old entries outside the window
+ *   are purged before counting. This provides the smoothest rate limiting experience.
+ * - `fixed`: Uses a simple counter with `INCR`/`EXPIRE`. The window resets at fixed
+ *   boundaries (e.g., every 60 seconds from the start). This is the cheapest algorithm
+ *   but has slightly less precise rate limiting.
+ *
+ * **Key Naming:**
+ * Keys are namespaced as `ratelimit:{namespace}:{resource}:{identifier}` so each
+ * resource + identifier pair is tracked independently.
+ */
 export interface RateLimitOptions {
     /** Maximum allowed requests within `duration`. Default: `100`. */
     limit?: number;
@@ -23,6 +45,29 @@ export interface RateLimitOptions {
 /**
  * Result of a rate limit `consume`/`check` call.
  */
+/**
+ * Result of a rate limit `consume`/`check` call.
+ *
+ * **Fields:**
+ * - `allowed`: `true` when the request is within the rate limit and may proceed.
+ * - `limit`: The configured maximum number of requests within the window.
+ * - `used`: The number of requests already counted in the current window.
+ * - `remaining`: The number of requests still available (`limit - used`, floored at `0`).
+ * - `resetAt`: Epoch milliseconds when the current window resets. `0` when the request
+ *   is allowed (indicating the window is still open).
+ * - `retryAfter`: Seconds to wait before retrying the request. `0` when the request
+ *   is allowed.
+ *
+ * **Example:**
+ * ```ts
+ * const result = await limiter.consume('/api/login', 'ip-10.0.0.1');
+ * if (!result.allowed) {
+ *   // result.retryAfter tells you how many seconds to wait before retrying
+ *   console.log(`Retry after ${result.retryAfter}s`);
+ *   console.log(`Window resets at ${new Date(result.resetAt)}`);
+ * }
+ * ```
+ */
 export interface RateLimitResult {
     /** `true` when the request is within the limit. */
     allowed: boolean;
@@ -32,7 +77,7 @@ export interface RateLimitResult {
     used: number;
     /** Requests still available (`limit - used`, floored at `0`). */
     remaining: number;
-    /** Epoch milliseconds when the window resets (0 retry hint when allowed). */
+    /** Epoch milliseconds when the window resets. */
     resetAt: number;
     /** Seconds to wait before retrying; `0` when allowed. */
     retryAfter: number;
@@ -78,6 +123,31 @@ export declare class RateLimiter {
      * ```
      */
     constructor(client: RedisClientWrapper, options?: RateLimitOptionsInput, logger?: LoggerLike);
+    /**
+     * 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.
      *
@@ -93,6 +163,27 @@ export declare 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: string, identifier: string, namespace?: string): string;
     /**
      * Consumes one unit of capacity for a resource + identifier and returns the
@@ -119,6 +210,50 @@ export declare 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).
+     */
     consume(resource: string, identifier: string, options?: RateLimitOptions): Promise<RateLimitResult>;
     /**
      * Peeks at the current limit state without consuming capacity.
@@ -140,6 +275,37 @@ export declare 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.
+     */
     check(resource: string, identifier: string, options?: RateLimitOptions): Promise<RateLimitResult>;
     /**
      * Resets the counter for a resource + identifier, granting full capacity again.
@@ -155,9 +321,121 @@ export declare 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.
+     */
     reset(resource: string, identifier: string, namespace?: string): Promise<boolean>;
+    /**
+     * 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
+     */
     private consumeFixed;
+    /**
+     * 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
+     */
     private consumeSliding;
+    /**
+     * 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
+     */
     private checkFixed;
+    /**
+     * 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
+     */
     private checkSliding;
 }