ioredis-toolkit 0.0.9 → 0.5.0

package/dist/pubsub.d.ts

@@ -1,423 +0,0 @@
-import { RedisClientWrapper } from './client.js';
-import { EventEmitter } from 'node:events';
-import { RedisConfig } from './types.js';
-import { LoggerLike } from './logger.js';
-/**
- * Redis Pub/Sub with a dedicated publisher and subscriber connection.
- *
- * **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
- *
- * **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.
- *
- * **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({ mode: 'standalone', host: 'localhost', port: 6379 });
- *
- * // Subscribe to a channel
- * await pubsub.subscribe('orders:created', (message) => {
- *   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);
- * });
- * ```
- *
- * **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;
-    private subscriber;
-    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.
-     *
-     * @param publisher - A {@link RedisClientWrapper} used for publishing.
-     * @param logger - Optional pino-compatible logger; defaults to `console`.
-     *
-     * @example
-     * ```ts
-     * const pubsub = new PubSub(client);
-     * ```
-     */
-    constructor(publisher: RedisClientWrapper, logger?: LoggerLike);
-    /**
-     * Opens a dedicated subscriber connection.
-     *
-     * Idempotent: a second call is a no-op while a subscriber is connected.
-     * Subscriber errors are emitted as `'error'` events on the instance.
-     *
-     * @param config - Redis config for the subscriber connection (any mode).
-     *
-     * @example
-     * ```ts
-     * 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.
-     *
-     * Non-string values are JSON-serialized.
-     *
-     * @param channel - The channel name.
-     * @param message - The message payload (string or any JSON-serializable value).
-     * @returns The number of subscribers that received the message.
-     *
-     * @example
-     * ```ts
-     * 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.
-     *
-     * Multiple handlers per channel are supported; the channel is subscribed on
-     * Redis only once. Delivered payloads are JSON-parsed when possible.
-     *
-     * @param channel - The channel name.
-     * @param handler - Callback receiving the (parsed) message.
-     * @throws `Error` if the subscriber connection is not open.
-     *
-     * @example
-     * ```ts
-     * await pubsub.subscribe('orders:created', (order) => {
-     *   console.log(order.id);
-     * });
-     * ```
-     */
-    /**
-     * 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.
-     *
-     * The Redis subscription is dropped once the last handler for the channel is
-     * removed. Without a handler, the whole channel is unsubscribed.
-     *
-     * @param channel - The channel name.
-     * @param handler - Optional specific handler to remove; when omitted all
-     *   handlers for the channel are removed.
-     *
-     * @example
-     * ```ts
-     * await pubsub.unsubscribe('orders:created', myHandler);
-     * 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.
-     *
-     * Pattern handlers receive `{ channel, message }` (message JSON-parsed).
-     *
-     * @param pattern - Glob pattern, e.g. `'orders:*'`.
-     * @param handler - Callback receiving `{ channel, message }`.
-     * @throws `Error` if the subscriber connection is not open.
-     *
-     * @example
-     * ```ts
-     * await pubsub.psubscribe('orders:*', ({ channel, message }) => {
-     *   console.log(channel, message);
-     * });
-     * ```
-     */
-    /**
-       * 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;
-    }) => void): Promise<void>;
-    /**
-     * Removes a handler (or all handlers) from a pattern subscription.
-     *
-     * @param pattern - The glob pattern.
-     * @param handler - Optional specific handler to remove; when omitted all
-     *   handlers for the pattern are removed.
-     *
-     * @example
-     * ```ts
-     * await pubsub.punsubscribe('orders:*', myHandler);
-     * 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.
-     *
-     * The publisher client is not closed (it is owned by the caller).
-     *
-     * @example
-     * ```ts
-     * 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.
-     *
-     * @returns `{ subscriptions, patternSubscriptions, connected }`.
-     *
-     * @example
-     * ```ts
-     * const stats = pubsub.getStats();
-     * // { 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;
-        connected: boolean;
-    };
-}