ioredis-toolkit 0.0.1

package/dist/pubsub.d.ts

@@ -0,0 +1,171 @@
+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.
+ *
+ * Messages are JSON-serialized on publish and auto-parsed on delivery.
+ * Extends `EventEmitter` and emits `'error'` on subscriber failures.
+ *
+ * Works in all three modes (standalone, sentinel, cluster).
+ *
+ * @example
+ * ```ts
+ * const pubsub = new PubSub(client);
+ * await pubsub.connectSubscriber(redisConfig);
+ *
+ * await pubsub.subscribe('orders:created', (message) => {
+ *   console.log(message); // { id: 1 }
+ * });
+ * await pubsub.publish('orders:created', { id: 1 });
+ * ```
+ */
+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);
+     * ```
+     */
+    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 });
+     * ```
+     */
+    connectSubscriber(config: RedisConfig): Promise<void>;
+    private setupSubscriber;
+    private handleMessage;
+    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 });
+     * ```
+     */
+    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);
+     * });
+     * ```
+     */
+    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
+     * ```
+     */
+    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);
+     * });
+     * ```
+     */
+    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:*');
+     * ```
+     */
+    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();
+     * ```
+     */
+    close(): Promise<void>;
+    /**
+     * Returns subscription statistics.
+     *
+     * @returns `{ subscriptions, patternSubscriptions, connected }`.
+     *
+     * @example
+     * ```ts
+     * const stats = pubsub.getStats();
+     * // { subscriptions: 2, patternSubscriptions: 1, connected: true }
+     * ```
+     */
+    getStats(): {
+        subscriptions: number;
+        patternSubscriptions: number;
+        connected: boolean;
+    };
+}

package/dist/pubsub.js

@@ -0,0 +1,285 @@
+import { RedisClientWrapper } from './client.js';
+import { EventEmitter } from 'node:events';
+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.
+ *
+ * Works in all three modes (standalone, sentinel, cluster).
+ *
+ * @example
+ * ```ts
+ * const pubsub = new PubSub(client);
+ * await pubsub.connectSubscriber(redisConfig);
+ *
+ * await pubsub.subscribe('orders:created', (message) => {
+ *   console.log(message); // { id: 1 }
+ * });
+ * await pubsub.publish('orders:created', { id: 1 });
+ * ```
+ */
+export class PubSub extends EventEmitter {
+    publisher;
+    subscriber = null;
+    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);
+     * ```
+     */
+    constructor(publisher, logger = defaultLogger) {
+        super();
+        this.publisher = publisher;
+        this.logger = logger.child({ component: 'PubSub' });
+    }
+    /**
+     * 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 });
+     * ```
+     */
+    async connectSubscriber(config) {
+        if (this.subscriber)
+            return;
+        this.subscriber = new RedisClientWrapper(config, this.logger);
+        this.setupSubscriber();
+    }
+    setupSubscriber() {
+        if (!this.subscriber)
+            return;
+        const raw = this.subscriber.raw;
+        raw.on('message', (channel, message) => {
+            this.handleMessage(channel, message);
+        });
+        raw.on('pmessage', (pattern, channel, message) => {
+            this.handlePatternMessage(pattern, channel, message);
+        });
+        raw.on('error', (error) => {
+            this.logger.error('Subscriber error:', error);
+            this.emit('error', error);
+        });
+    }
+    handleMessage(channel, message) {
+        const handlers = this.subscriptions.get(channel);
+        if (!handlers)
+            return;
+        let parsed = message;
+        try {
+            parsed = JSON.parse(message);
+        }
+        catch { }
+        for (const handler of handlers) {
+            try {
+                handler(parsed);
+            }
+            catch (error) {
+                this.logger.error('Handler error:', error);
+            }
+        }
+    }
+    handlePatternMessage(pattern, channel, message) {
+        const handlers = this.patternSubscriptions.get(pattern);
+        if (!handlers)
+            return;
+        let parsed = message;
+        try {
+            parsed = JSON.parse(message);
+        }
+        catch { }
+        for (const handler of handlers) {
+            try {
+                handler({ channel, message: parsed });
+            }
+            catch (error) {
+                this.logger.error('Handler error:', error);
+            }
+        }
+    }
+    /**
+     * 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 });
+     * ```
+     */
+    async publish(channel, message) {
+        const raw = typeof message === 'string' ? message : JSON.stringify(message);
+        return this.publisher.raw.publish(channel, raw);
+    }
+    /**
+     * 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);
+     * });
+     * ```
+     */
+    async subscribe(channel, handler) {
+        if (!this.subscriber) {
+            throw new Error('Subscriber not connected');
+        }
+        if (!this.subscriptions.has(channel)) {
+            this.subscriptions.set(channel, new Set());
+            await this.subscriber.raw.subscribe(channel);
+        }
+        this.subscriptions.get(channel).add(handler);
+        this.logger.debug('Subscribed to channel', { channel });
+    }
+    /**
+     * 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
+     * ```
+     */
+    async unsubscribe(channel, handler) {
+        if (!this.subscriber)
+            return;
+        if (handler && this.subscriptions.has(channel)) {
+            const handlers = this.subscriptions.get(channel);
+            handlers.delete(handler);
+            if (handlers.size === 0) {
+                this.subscriptions.delete(channel);
+                await this.subscriber.raw.unsubscribe(channel);
+            }
+        }
+        else {
+            this.subscriptions.delete(channel);
+            await this.subscriber.raw.unsubscribe(channel);
+        }
+    }
+    /**
+     * 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);
+     * });
+     * ```
+     */
+    async psubscribe(pattern, handler) {
+        if (!this.subscriber) {
+            throw new Error('Subscriber not connected');
+        }
+        if (!this.patternSubscriptions.has(pattern)) {
+            this.patternSubscriptions.set(pattern, new Set());
+            await this.subscriber.raw.psubscribe(pattern);
+        }
+        this.patternSubscriptions.get(pattern).add(handler);
+    }
+    /**
+     * 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:*');
+     * ```
+     */
+    async punsubscribe(pattern, handler) {
+        if (!this.subscriber)
+            return;
+        if (handler && this.patternSubscriptions.has(pattern)) {
+            const handlers = this.patternSubscriptions.get(pattern);
+            handlers.delete(handler);
+            if (handlers.size === 0) {
+                this.patternSubscriptions.delete(pattern);
+                await this.subscriber.raw.punsubscribe(pattern);
+            }
+        }
+        else {
+            this.patternSubscriptions.delete(pattern);
+            await this.subscriber.raw.punsubscribe(pattern);
+        }
+    }
+    /**
+     * 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();
+     * ```
+     */
+    async close() {
+        if (this.subscriber) {
+            await this.subscriber.close();
+            this.subscriber = null;
+        }
+        this.subscriptions.clear();
+        this.patternSubscriptions.clear();
+    }
+    /**
+     * Returns subscription statistics.
+     *
+     * @returns `{ subscriptions, patternSubscriptions, connected }`.
+     *
+     * @example
+     * ```ts
+     * const stats = pubsub.getStats();
+     * // { subscriptions: 2, patternSubscriptions: 1, connected: true }
+     * ```
+     */
+    getStats() {
+        return {
+            subscriptions: this.subscriptions.size,
+            patternSubscriptions: this.patternSubscriptions.size,
+            connected: this.subscriber !== null,
+        };
+    }
+}

package/dist/ratelimiter.d.ts

@@ -0,0 +1,162 @@
+import { RedisClientWrapper } from './client.js';
+import { LoggerLike } from './logger.js';
+/**
+ * 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)
+ */
+export type RateLimitAlgorithm = 'fixed' | 'sliding';
+/**
+ * Options for a rate limiter instance or an individual call.
+ */
+export interface RateLimitOptions {
+    /** Maximum allowed requests within `duration`. Default: `100`. */
+    limit?: number;
+    /** Window length in seconds. Default: `60`. */
+    duration?: number;
+    /** Window algorithm. Default: `'sliding'`. */
+    algorithm?: RateLimitAlgorithm;
+    /** Redis key prefix. Default: `'ratelimit'`. */
+    namespace?: string;
+}
+/**
+ * Result of a rate limit `consume`/`check` call.
+ */
+export interface RateLimitResult {
+    /** `true` when the request is within the limit. */
+    allowed: boolean;
+    /** The configured maximum within the window. */
+    limit: number;
+    /** Requests already counted in the current window. */
+    used: number;
+    /** Requests still available (`limit - used`, floored at `0`). */
+    remaining: number;
+    /** Epoch milliseconds when the window resets (0 retry hint when allowed). */
+    resetAt: number;
+    /** Seconds to wait before retrying; `0` when allowed. */
+    retryAfter: number;
+}
+/**
+ * Generic Redis-backed rate limiter that works for any resource: routes, API
+ * endpoints, users, IPs, databases, email sending, etc.
+ *
+ * Keys are namespaced as `ratelimit:{namespace}:{resource}:{identifier}` so each
+ * resource + identifier combination is tracked independently. Supports fixed-window
+ * (`INCR`/`EXPIRE`) and sliding-window (atomic Lua over a sorted set) algorithms.
+ * Fails open when Redis is unavailable.
+ *
+ * @example
+ * ```ts
+ * const limiter = new RateLimiter(client, { limit: 100, duration: 60 });
+ *
+ * const result = await limiter.consume('/api/login', 'ip-10.0.0.1');
+ * if (!result.allowed) {
+ *   throw new Error(`Slow down, retry in ${result.retryAfter}s`);
+ * }
+ * ```
+ */
+export declare class RateLimiter {
+    private client;
+    private logger;
+    private defaultLimit;
+    private defaultDuration;
+    private defaultAlgorithm;
+    private defaultNamespace;
+    /**
+     * Creates a rate limiter bound to a Redis client.
+     *
+     * @param client - The underlying {@link RedisClientWrapper}.
+     * @param options - Defaults applied when a call does not override them:
+     *   `limit` (default `100`), `duration` in seconds (default `60`),
+     *   `algorithm` (default `'sliding'`), `namespace` (default `'ratelimit'`).
+     * @param logger - Optional pino-compatible logger; defaults to `console`.
+     *
+     * @example
+     * ```ts
+     * const limiter = new RateLimiter(client, { limit: 10, duration: 1, algorithm: 'fixed' });
+     * ```
+     */
+    constructor(client: RedisClientWrapper, options?: RateLimitOptions, logger?: LoggerLike);
+    /**
+     * Builds the Redis key for a resource + identifier combination.
+     *
+     * @param resource - The rate-limited resource, e.g. a route `'/api/login'` or
+     *   a resource name `'email:send'`.
+     * @param identifier - The caller identity, e.g. an IP, user id or API key.
+     * @param namespace - Key prefix (defaults to the limiter's namespace).
+     * @returns The full key, e.g. `'ratelimit:/api/login:ip-10.0.0.1'`.
+     *
+     * @example
+     * ```ts
+     * limiter.makeKey('/api/login', 'ip-10.0.0.1');
+     * // '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
+     * resulting limit state.
+     *
+     * 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.
+     *
+     * @param resource - The rate-limited resource, e.g. a route `'/api/login'` or
+     *   a resource name `'db:write'`.
+     * @param identifier - The caller identity, e.g. an IP, user id or API key.
+     * @param options - Per-call overrides for `limit`, `duration`, `algorithm`,
+     *   and `namespace`.
+     * @returns The limit state: `allowed`, `limit`, `used`, `remaining`,
+     *   `resetAt` (epoch ms), `retryAfter` (seconds).
+     *
+     * @example
+     * ```ts
+     * const result = await limiter.consume('/api/orders', 'user-7', { limit: 5, duration: 60 });
+     * if (!result.allowed) {
+     *   res.setHeader('Retry-After', String(result.retryAfter));
+     *   return res.status(429).json({ error: 'Too many requests' });
+     * }
+     * ```
+     */
+    consume(resource: string, identifier: string, options?: RateLimitOptions): Promise<RateLimitResult>;
+    /**
+     * Peeks at the current limit state without consuming capacity.
+     *
+     * Useful for pre-flight checks (e.g. showing "limit reached" in a UI before
+     * the actual request). Also fails open on Redis errors.
+     *
+     * @param resource - The rate-limited resource.
+     * @param identifier - The caller identity.
+     * @param options - Per-call overrides for `limit`, `duration`, `algorithm`,
+     *   and `namespace`.
+     * @returns The current limit state; `used` is not incremented.
+     *
+     * @example
+     * ```ts
+     * const state = await limiter.check('/api/search', 'user-1');
+     * if (state.remaining === 0) {
+     *   // disable the search button
+     * }
+     * ```
+     */
+    check(resource: string, identifier: string, options?: RateLimitOptions): Promise<RateLimitResult>;
+    /**
+     * Resets the counter for a resource + identifier, granting full capacity again.
+     *
+     * @param resource - The rate-limited resource.
+     * @param identifier - The caller identity.
+     * @param namespace - Key prefix (defaults to the limiter's namespace).
+     * @returns `true` if a counter existed and was removed.
+     *
+     * @example
+     * ```ts
+     * // user upgraded to a premium plan, lift their limits
+     * await limiter.reset('/api/export', 'user-7');
+     * ```
+     */
+    reset(resource: string, identifier: string, namespace?: string): Promise<boolean>;
+    private consumeFixed;
+    private consumeSliding;
+    private checkFixed;
+    private checkSliding;
+}