ioredis-toolkit 0.0.4 → 0.0.6

package/dist/lock.d.ts

@@ -1,6 +1,48 @@
 import { RedisClientWrapper } from './client.js';
 import { LoggerLike } from './logger.js';
-import { DistributedLockOptions, LockInfo } from './types.js';
+/**
+ * Information about a distributed lock.
+ *
+ * **Fields:**
+ * - `locked`: Whether the lock is currently held.
+ * - `ttl`: Remaining TTL in seconds (when held and TTL set).
+ * - `lockId`: Unique owner id of the lock.
+ *
+ * **Example:**
+ * ```ts
+ * const info = await lock.getLockInfo('order:42');
+ * // { locked: true, ttl: 29, lockId: 'a1b2c3...' }
+ * ```
+ */
+export type LockInfo = {
+    /** Whether the lock is currently held. */
+    locked: boolean;
+    /** Remaining TTL in seconds (when held and TTL set). */
+    ttl?: number;
+    /** Unique owner id of the lock. */
+    lockId?: string;
+};
+/**
+ * Options for the distributed lock.
+ *
+ * **Fields:**
+ * - `ttl`: Lock TTL in milliseconds. Default: `30000`.
+ * - `retryCount`: Number of acquisition attempts. Default: `3`.
+ * - `retryDelay`: Base delay between retries in ms (grows exponentially). Default: `200`.
+ *
+ * **Example:**
+ * ```ts
+ * const lock = new DistributedLock(client, { ttl: 10000, retryCount: 5 });
+ * ```
+ */
+export interface DistributedLockOptions {
+    /** Lock TTL in milliseconds. Default: `30000`. */
+    ttl?: number;
+    /** Number of acquisition attempts. Default: `3`. */
+    retryCount?: number;
+    /** Base delay between retries in ms (grows exponentially). Default: `200`. */
+    retryDelay?: number;
+}
 /**
  * Distributed mutual-exclusion lock backed by Redis.
  *
@@ -53,11 +95,13 @@ export declare class DistributedLock {
      *
      * @param key - The resource to lock, e.g. `'order:42'` (stored as `lock:order:42`).
      * @param ttl - Lock TTL in milliseconds (default: `30000`).
+     *
      * @returns `true` when the lock was acquired.
      *
      * @example
      * ```ts
      * const acquired = await lock.acquire('order:42', 10000);
+     * // acquired === true when lock was successfully acquired
      * ```
      */
     acquire(key: string, ttl?: number): Promise<boolean>;
@@ -68,6 +112,7 @@ export declare class DistributedLock {
      * re-acquired by someone else) is never removed by the old owner.
      *
      * @param key - The locked resource.
+     *
      * @returns `true` if the lock was released, `false` if not owned or missing.
      *
      * @example
@@ -83,6 +128,7 @@ export declare class DistributedLock {
      * be gone. This is what `withLock` falls back to when a normal release fails.
      *
      * @param key - The locked resource.
+     *
      * @returns `true` if a lock existed and was deleted.
      *
      * @example
@@ -99,11 +145,13 @@ export declare class DistributedLock {
      *
      * @param key - The locked resource.
      * @param ttl - New TTL in milliseconds (default: `30000`).
+     *
      * @returns `true` if the lock was extended.
      *
      * @example
      * ```ts
      * const extended = await lock.extend('order:42', 30000);
+     * // extended === true when lock TTL was renewed
      * ```
      */
     extend(key: string, ttl?: number): Promise<boolean>;
@@ -117,7 +165,9 @@ export declare class DistributedLock {
      * @param key - The resource to lock.
      * @param fn - The critical section to run exclusively.
      * @param options - Per-call `ttl` (ms), `retryCount`, `retryDelay`.
+     *
      * @returns The return value of `fn`.
+     *
      * @throws {@link RedisError} with code `LOCK_ACQUISITION_FAILED` when the lock
      *   cannot be acquired, or `LOCK_LOST` when the lock expired mid-execution.
      *
@@ -133,6 +183,7 @@ export declare class DistributedLock {
      * Checks whether a lock is currently held.
      *
      * @param key - The locked resource.
+     *
      * @returns `true` if the lock exists (held by anyone).
      *
      * @example
@@ -145,6 +196,7 @@ export declare class DistributedLock {
      * Returns details about a lock.
      *
      * @param key - The locked resource.
+     *
      * @returns `{ locked: false }` when not held, otherwise `{ locked: true, ttl, lockId }`.
      *
      * @example
@@ -158,6 +210,7 @@ export declare class DistributedLock {
      * Returns the owner id of a lock.
      *
      * @param key - The locked resource.
+     *
      * @returns The lock id (random hex token), or `null` when not held.
      *
      * @example
@@ -170,6 +223,7 @@ export declare class DistributedLock {
      * Returns the remaining TTL of a lock in seconds.
      *
      * @param key - The locked resource.
+     *
      * @returns Remaining seconds (`0` when not held or expired).
      *
      * @example

package/dist/lock.js

@@ -1,28 +1,6 @@
 import { RedisError } from './errors.js';
 import { randomBytes } from 'node:crypto';
 import { defaultLogger } from './logger.js';
-// /**
-//  * Information about a distributed lock.
-//  */
-// export interface LockInfo {
-//   /** Whether the lock is currently held. */
-//   locked: boolean;
-//   /** Remaining TTL in seconds (when held and TTL set). */
-//   ttl?: number;
-//   /** Unique owner id of the lock. */
-//   lockId?: string;
-// }
-// /**
-//  * Options for the distributed lock.
-//  */
-// export interface DistributedLockOptions {
-//   /** Lock TTL in milliseconds. Default: `30000`. */
-//   ttl?: number;
-//   /** Number of acquisition attempts. Default: `3`. */
-//   retryCount?: number;
-//   /** Base delay between retries in ms (grows exponentially). Default: `200`. */
-//   retryDelay?: number;
-// }
 /**
  * Distributed mutual-exclusion lock backed by Redis.
  *
@@ -100,11 +78,13 @@ export class DistributedLock {
      *
      * @param key - The resource to lock, e.g. `'order:42'` (stored as `lock:order:42`).
      * @param ttl - Lock TTL in milliseconds (default: `30000`).
+     *
      * @returns `true` when the lock was acquired.
      *
      * @example
      * ```ts
      * const acquired = await lock.acquire('order:42', 10000);
+     * // acquired === true when lock was successfully acquired
      * ```
      */
     async acquire(key, ttl = this.defaultTTL) {
@@ -123,6 +103,7 @@ export class DistributedLock {
      * re-acquired by someone else) is never removed by the old owner.
      *
      * @param key - The locked resource.
+     *
      * @returns `true` if the lock was released, `false` if not owned or missing.
      *
      * @example
@@ -161,6 +142,7 @@ export class DistributedLock {
      * be gone. This is what `withLock` falls back to when a normal release fails.
      *
      * @param key - The locked resource.
+     *
      * @returns `true` if a lock existed and was deleted.
      *
      * @example
@@ -181,11 +163,13 @@ export class DistributedLock {
      *
      * @param key - The locked resource.
      * @param ttl - New TTL in milliseconds (default: `30000`).
+     *
      * @returns `true` if the lock was extended.
      *
      * @example
      * ```ts
      * const extended = await lock.extend('order:42', 30000);
+     * // extended === true when lock TTL was renewed
      * ```
      */
     async extend(key, ttl = this.defaultTTL) {
@@ -220,7 +204,9 @@ export class DistributedLock {
      * @param key - The resource to lock.
      * @param fn - The critical section to run exclusively.
      * @param options - Per-call `ttl` (ms), `retryCount`, `retryDelay`.
+     *
      * @returns The return value of `fn`.
+     *
      * @throws {@link RedisError} with code `LOCK_ACQUISITION_FAILED` when the lock
      *   cannot be acquired, or `LOCK_LOST` when the lock expired mid-execution.
      *
@@ -308,6 +294,7 @@ export class DistributedLock {
      * Checks whether a lock is currently held.
      *
      * @param key - The locked resource.
+     *
      * @returns `true` if the lock exists (held by anyone).
      *
      * @example
@@ -324,6 +311,7 @@ export class DistributedLock {
      * Returns details about a lock.
      *
      * @param key - The locked resource.
+     *
      * @returns `{ locked: false }` when not held, otherwise `{ locked: true, ttl, lockId }`.
      *
      * @example
@@ -356,6 +344,7 @@ export class DistributedLock {
      * Returns the owner id of a lock.
      *
      * @param key - The locked resource.
+     *
      * @returns The lock id (random hex token), or `null` when not held.
      *
      * @example
@@ -371,6 +360,7 @@ export class DistributedLock {
      * Returns the remaining TTL of a lock in seconds.
      *
      * @param key - The locked resource.
+     *
      * @returns Remaining seconds (`0` when not held or expired).
      *
      * @example

package/dist/pubsub.d.ts

@@ -5,21 +5,50 @@ import { LoggerLike } 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 declare class PubSub extends EventEmitter {
     private publisher;
@@ -27,6 +56,18 @@ export declare class PubSub extends EventEmitter {
     private logger;
     private subscriptions;
     private patternSubscriptions;
+    /**
+     * 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.
@@ -53,9 +94,73 @@ export declare 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.
+     */
     connectSubscriber(config: RedisConfig): Promise<void>;
+    /**
+     * 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
+     */
     private setupSubscriber;
+    /**
+     * 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
+     */
     private handleMessage;
+    /**
+     * 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
+     */
     private handlePatternMessage;
     /**
      * Publishes a message to a channel.
@@ -71,6 +176,32 @@ export declare 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.
+     */
     publish<T = any>(channel: string, message: T): Promise<number>;
     /**
      * Subscribes a handler to a channel.
@@ -89,6 +220,34 @@ export declare 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.
+     */
     subscribe<T = any>(channel: string, handler: (data: T) => void): Promise<void>;
     /**
      * Removes a handler (or all handlers) from a channel.
@@ -106,6 +265,28 @@ export declare 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.
+     */
     unsubscribe<T = any>(channel: string, handler?: (data: T) => void): Promise<void>;
     /**
      * Subscribes a handler to all channels matching a glob pattern.
@@ -123,6 +304,32 @@ export declare 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.
+       */
     psubscribe<T = any>(pattern: string, handler: (data: {
         channel: string;
         message: T;
@@ -140,6 +347,23 @@ export declare 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.
+     */
     punsubscribe(pattern: string, handler?: (data: any) => void): Promise<void>;
     /**
      * Closes the subscriber connection and clears all subscriptions.
@@ -151,6 +375,20 @@ export declare 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.
+     */
     close(): Promise<void>;
     /**
      * Returns subscription statistics.
@@ -163,6 +401,20 @@ export declare 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(): {
         subscriptions: number;
         patternSubscriptions: number;