ioredis-toolkit 0.0.8 → 0.0.10

package/dist/cache.d.ts

@@ -1,6 +1,6 @@
-import { RedisClientWrapper } from './client.js';
-import { CacheOptions, CacheInputConfig } from './types.js';
-import { LoggerLike } from './logger.js';
+import { RedisClientWrapper } from "./client.js";
+import { CacheOptions, CacheInputConfig } from "./types.js";
+import { LoggerLike } from "./logger.js";
 /**
  * Cache layer on top of {@link RedisClientWrapper} with JSON serialization,
  * optional gzip compression and namespace support.
@@ -20,6 +20,7 @@ export declare class Cache {
     private logger;
     private defaultTTL;
     private compressionThreshold;
+    private namespace;
     /**
      * Creates a cache bound to a Redis client.
      *
@@ -31,6 +32,7 @@ export declare class Cache {
      *     applied when no per-call TTL is specified.
      *   - `compressionThreshold` (number, optional, default: `1024`) - Byte threshold
      *     above which values are gzip-compressed transparently.
+     *   - `namespace` (string, optional, default: `''`) - Namespace prefix for all keys.
      * - `logger` - Optional pino-compatible logger. Supports `trace/debug/info/warn/error/fatal`
      *   levels and `child()` for namespace logging. Defaults to `console`.
      *
@@ -39,12 +41,13 @@ export declare class Cache {
      *
      * **Example:**
      * ```ts
-     * const cache = new Cache(client, { defaultTTL: 600, compressionThreshold: 2048 });
+     * const cache = new Cache(client, { defaultTTL: 600, compressionThreshold: 2048, namespace: 'myapp' });
      * ```
      */
     constructor(client: RedisClientWrapper, config: CacheInputConfig, logger?: LoggerLike);
     private serialize;
     private deserialize;
+    private get getNamespace();
     private getKey;
     /**
      * Reads a cached value.
@@ -132,7 +135,7 @@ export declare class Cache {
      *
      * **Type Parameters:**
      * - `T` - The type of the value being stored. Can be any serializable JavaScript value.
-   *
+     *
      * **Returns:**
      * - `true` when the value was stored successfully (`result === 'OK'`).
      *
@@ -266,36 +269,36 @@ export declare class Cache {
      * ```
      */
     /**
-       * Reads multiple cache keys in one call.
-       *
-       * **Behavior:**
-       * - Cluster-safe: keys are grouped by hash slot under the hood, avoiding CROSS-SLOT errors.
-       * - Values are deserialized from JSON when stored as JSON. Strings/numbers/buffers
-       *   are returned as-is.
-       * - Missing keys return `null` in the corresponding position.
-       *
-       * **Type Parameters:**
-       * - `T` - The expected type of each returned value. When the stored value is JSON,
-       *   it will be parsed and coerced to `T`.
-       *
-       * **Returns:**
-       * - An array of values in the same order as the input `keys`. Each element is `T | null`.
-       *   `null` indicates the key did not exist.
-     *
-       * **Example:**
-       * ```ts
-       * const [a, b] = await cache.mget(['user:1', 'user:2']);
-       * // a === { name: 'alice' }, b === { name: 'bob' }
-       * ```
-       *
-       * **Parameters:**
-       * - `keys` - Cache keys to read. Will have the namespace prefix applied automatically
-       *   if a namespace is configured.
-       * - `namespace` - Optional namespace prefix applied to every key. When provided,
-       *   each key is internally transformed to `${namespace}:${key}`.
-       *
-       * @returns Values in input order; `null` for missing keys.
-       */
+     * Reads multiple cache keys in one call.
+     *
+     * **Behavior:**
+     * - Cluster-safe: keys are grouped by hash slot under the hood, avoiding CROSS-SLOT errors.
+     * - Values are deserialized from JSON when stored as JSON. Strings/numbers/buffers
+     *   are returned as-is.
+     * - Missing keys return `null` in the corresponding position.
+     *
+     * **Type Parameters:**
+     * - `T` - The expected type of each returned value. When the stored value is JSON,
+     *   it will be parsed and coerced to `T`.
+     *
+     * **Returns:**
+     * - An array of values in the same order as the input `keys`. Each element is `T | null`.
+     *   `null` indicates the key did not exist.
+     *
+     * **Example:**
+     * ```ts
+     * const [a, b] = await cache.mget(['user:1', 'user:2']);
+     * // a === { name: 'alice' }, b === { name: 'bob' }
+     * ```
+     *
+     * **Parameters:**
+     * - `keys` - Cache keys to read. Will have the namespace prefix applied automatically
+     *   if a namespace is configured.
+     * - `namespace` - Optional namespace prefix applied to every key. When provided,
+     *   each key is internally transformed to `${namespace}:${key}`.
+     *
+     * @returns Values in input order; `null` for missing keys.
+     */
     mget<T = any>(keys: string[], namespace?: string): Promise<(T | null)[]>;
     /**
      * Stores multiple key/value entries in one call.
@@ -366,7 +369,7 @@ export declare class Cache {
      *
      * **Returns:**
      * - `true` if the key existed and was deleted.
-   *
+     *
      * **Example:**
      * ```ts
      * const removed = await cache.delete('user:1');

package/dist/cache.js

@@ -1,6 +1,6 @@
-import zlib from 'node:zlib';
-import { promisify } from 'node:util';
-import { defaultLogger } from './logger.js';
+import zlib from "node:zlib";
+import { promisify } from "node:util";
+import { defaultLogger } from "./logger.js";
 const gzip = promisify(zlib.gzip);
 const gunzip = promisify(zlib.gunzip);
 /**
@@ -23,6 +23,7 @@ export class Cache {
     // private config: RedisConfig;
     defaultTTL;
     compressionThreshold;
+    namespace;
     /**
      * Creates a cache bound to a Redis client.
      *
@@ -34,6 +35,7 @@ export class Cache {
      *     applied when no per-call TTL is specified.
      *   - `compressionThreshold` (number, optional, default: `1024`) - Byte threshold
      *     above which values are gzip-compressed transparently.
+     *   - `namespace` (string, optional, default: `''`) - Namespace prefix for all keys.
      * - `logger` - Optional pino-compatible logger. Supports `trace/debug/info/warn/error/fatal`
      *   levels and `child()` for namespace logging. Defaults to `console`.
      *
@@ -42,15 +44,16 @@ export class Cache {
      *
      * **Example:**
      * ```ts
-     * const cache = new Cache(client, { defaultTTL: 600, compressionThreshold: 2048 });
+     * const cache = new Cache(client, { defaultTTL: 600, compressionThreshold: 2048, namespace: 'myapp' });
      * ```
      */
     constructor(client, config, logger = defaultLogger) {
         this.client = client;
-        this.logger = logger.child({ component: 'Cache' });
+        this.logger = logger.child({ component: "Cache" });
         // this.config = config;
         this.defaultTTL = config.defaultTTL || 3600;
         this.compressionThreshold = config.compressionThreshold || 1024;
+        this.namespace = config.namespace || "";
     }
     async serialize(value) {
         // Convert to Buffer
@@ -58,10 +61,10 @@ export class Cache {
         if (Buffer.isBuffer(value)) {
             data = value;
         }
-        else if (typeof value === 'string') {
+        else if (typeof value === "string") {
             data = Buffer.from(value);
         }
-        else if (typeof value === 'number' || typeof value === 'boolean') {
+        else if (typeof value === "number" || typeof value === "boolean") {
             data = Buffer.from(String(value));
         }
         else {
@@ -75,7 +78,7 @@ export class Cache {
                 return { data: compressed, compressed: true };
             }
             catch (error) {
-                this.logger.warn('Compression failed, storing uncompressed');
+                this.logger.warn("Compression failed, storing uncompressed");
                 return { data, compressed: false };
             }
         }
@@ -88,14 +91,14 @@ export class Cache {
                 buffer = await gunzip(data);
             }
             catch (error) {
-                this.logger.warn('Decompression failed, trying raw data');
+                this.logger.warn("Decompression failed, trying raw data");
                 // Attempt to use raw data if decompression fails
             }
         }
         // Try to parse as JSON if it looks like JSON
         const str = buffer.toString();
         try {
-            if (str.startsWith('{') || str.startsWith('[')) {
+            if (str.startsWith("{") || str.startsWith("[")) {
                 return JSON.parse(str);
             }
         }
@@ -104,8 +107,14 @@ export class Cache {
         }
         return str;
     }
+    get getNamespace() {
+        return this.namespace?.trim() ? `${this.namespace}:` : "";
+    }
     getKey(key, namespace) {
-        return namespace ? `${namespace}:${key}` : key;
+        if (namespace?.trim()) {
+            return `${this.getNamespace}${namespace.trim()}:${key}`;
+        }
+        return `${this.getNamespace}${key}`;
     }
     /**
      * Reads a cached value.
@@ -170,7 +179,7 @@ export class Cache {
             // Check if stored with metadata
             const parsed = JSON.parse(raw);
             if (parsed._compressed && parsed._data) {
-                const data = Buffer.from(parsed._data, 'base64');
+                const data = Buffer.from(parsed._data, "base64");
                 return this.deserialize(data, parsed._compressed);
             }
             // Legacy format - try to parse as JSON
@@ -212,7 +221,7 @@ export class Cache {
      *
      * **Type Parameters:**
      * - `T` - The type of the value being stored. Can be any serializable JavaScript value.
-   *
+     *
      * **Returns:**
      * - `true` when the value was stored successfully (`result === 'OK'`).
      *
@@ -250,7 +259,7 @@ export class Cache {
                     // Store with metadata
                     rawValue = JSON.stringify({
                         _compressed: true,
-                        _data: data.toString('base64'),
+                        _data: data.toString("base64"),
                     });
                 }
                 else {
@@ -258,7 +267,7 @@ export class Cache {
                 }
             }
             else {
-                if (typeof value === 'string') {
+                if (typeof value === "string") {
                     rawValue = value;
                 }
                 else if (Buffer.isBuffer(value)) {
@@ -269,11 +278,15 @@ export class Cache {
                 }
             }
             const result = await this.client.set(fullKey, rawValue, ttl);
-            this.logger.debug('Cache set', { key: fullKey, ttl, compressed: shouldCompress });
-            return result === 'OK';
+            this.logger.debug("Cache set", {
+                key: fullKey,
+                ttl,
+                compressed: shouldCompress,
+            });
+            return result === "OK";
         }
         catch (error) {
-            this.logger.error('Cache set failed:', error);
+            this.logger.error("Cache set failed:", error);
             return false;
         }
     }
@@ -324,12 +337,12 @@ export class Cache {
         const fullKey = this.getKey(key, options.namespace);
         const ttl = options.ttl || this.defaultTTL;
         try {
-            const rawValue = typeof value === 'string' ? value : JSON.stringify(value);
+            const rawValue = typeof value === "string" ? value : JSON.stringify(value);
             const result = await this.client.setnx(fullKey, rawValue, ttl);
             return result === 1;
         }
         catch (error) {
-            this.logger.error('Cache setNX failed:', error);
+            this.logger.error("Cache setNX failed:", error);
             return false;
         }
     }
@@ -384,12 +397,12 @@ export class Cache {
         const fullKey = this.getKey(key, options.namespace);
         const ttl = options.ttl || this.defaultTTL;
         try {
-            const rawValue = typeof value === 'string' ? value : JSON.stringify(value);
+            const rawValue = typeof value === "string" ? value : JSON.stringify(value);
             const result = await this.client.setexnx(fullKey, rawValue, ttl);
-            return result === 'OK';
+            return result === "OK";
         }
         catch (error) {
-            this.logger.error('Cache setEXNX failed:', error);
+            this.logger.error("Cache setEXNX failed:", error);
             return false;
         }
     }
@@ -430,38 +443,38 @@ export class Cache {
      * ```
      */
     /**
-       * Reads multiple cache keys in one call.
-       *
-       * **Behavior:**
-       * - Cluster-safe: keys are grouped by hash slot under the hood, avoiding CROSS-SLOT errors.
-       * - Values are deserialized from JSON when stored as JSON. Strings/numbers/buffers
-       *   are returned as-is.
-       * - Missing keys return `null` in the corresponding position.
-       *
-       * **Type Parameters:**
-       * - `T` - The expected type of each returned value. When the stored value is JSON,
-       *   it will be parsed and coerced to `T`.
-       *
-       * **Returns:**
-       * - An array of values in the same order as the input `keys`. Each element is `T | null`.
-       *   `null` indicates the key did not exist.
-     *
-       * **Example:**
-       * ```ts
-       * const [a, b] = await cache.mget(['user:1', 'user:2']);
-       * // a === { name: 'alice' }, b === { name: 'bob' }
-       * ```
-       *
-       * **Parameters:**
-       * - `keys` - Cache keys to read. Will have the namespace prefix applied automatically
-       *   if a namespace is configured.
-       * - `namespace` - Optional namespace prefix applied to every key. When provided,
-       *   each key is internally transformed to `${namespace}:${key}`.
-       *
-       * @returns Values in input order; `null` for missing keys.
-       */
+     * Reads multiple cache keys in one call.
+     *
+     * **Behavior:**
+     * - Cluster-safe: keys are grouped by hash slot under the hood, avoiding CROSS-SLOT errors.
+     * - Values are deserialized from JSON when stored as JSON. Strings/numbers/buffers
+     *   are returned as-is.
+     * - Missing keys return `null` in the corresponding position.
+     *
+     * **Type Parameters:**
+     * - `T` - The expected type of each returned value. When the stored value is JSON,
+     *   it will be parsed and coerced to `T`.
+     *
+     * **Returns:**
+     * - An array of values in the same order as the input `keys`. Each element is `T | null`.
+     *   `null` indicates the key did not exist.
+     *
+     * **Example:**
+     * ```ts
+     * const [a, b] = await cache.mget(['user:1', 'user:2']);
+     * // a === { name: 'alice' }, b === { name: 'bob' }
+     * ```
+     *
+     * **Parameters:**
+     * - `keys` - Cache keys to read. Will have the namespace prefix applied automatically
+     *   if a namespace is configured.
+     * - `namespace` - Optional namespace prefix applied to every key. When provided,
+     *   each key is internally transformed to `${namespace}:${key}`.
+     *
+     * @returns Values in input order; `null` for missing keys.
+     */
     async mget(keys, namespace) {
-        const fullKeys = keys.map(k => this.getKey(k, namespace));
+        const fullKeys = keys.map((k) => this.getKey(k, namespace));
         const raw = await this.client.mgetClusterAware(fullKeys);
         return Promise.all(raw.map(async (item) => {
             if (!item)
@@ -469,7 +482,7 @@ export class Cache {
             try {
                 const parsed = JSON.parse(item);
                 if (parsed._compressed && parsed._data) {
-                    const data = Buffer.from(parsed._data, 'base64');
+                    const data = Buffer.from(parsed._data, "base64");
                     return this.deserialize(data, parsed._compressed);
                 }
                 return parsed;
@@ -558,7 +571,7 @@ export class Cache {
             const groups = new Map();
             for (const [key, value] of Object.entries(entries)) {
                 const fullKey = this.getKey(key, namespace);
-                const rawValue = typeof value === 'string' ? value : JSON.stringify(value);
+                const rawValue = typeof value === "string" ? value : JSON.stringify(value);
                 const slot = this.client.calculateSlot(fullKey);
                 if (!groups.has(slot)) {
                     groups.set(slot, []);
@@ -568,17 +581,17 @@ export class Cache {
             for (const group of groups.values()) {
                 const pipeline = this.client.pipeline();
                 for (const [fullKey, rawValue] of group) {
-                    pipeline.set(fullKey, rawValue, 'EX', ttl);
+                    pipeline.set(fullKey, rawValue, "EX", ttl);
                 }
                 const results = await pipeline.exec();
-                if (!results?.every((result) => result[1] === 'OK')) {
+                if (!results?.every((result) => result[1] === "OK")) {
                     return false;
                 }
             }
             return true;
         }
         catch (error) {
-            this.logger.error('Cache mset failed:', error);
+            this.logger.error("Cache mset failed:", error);
             return false;
         }
     }
@@ -603,7 +616,7 @@ export class Cache {
      *
      * **Returns:**
      * - `true` if the key existed and was deleted.
-   *
+     *
      * **Example:**
      * ```ts
      * const removed = await cache.delete('user:1');
@@ -912,7 +925,7 @@ export class Cache {
      */
     async hset(key, field, value, namespace) {
         const fullKey = this.getKey(key, namespace);
-        const rawValue = typeof value === 'string' ? value : JSON.stringify(value);
+        const rawValue = typeof value === "string" ? value : JSON.stringify(value);
         const result = await this.client.hset(fullKey, field, rawValue);
         return result === 1;
     }
@@ -1006,7 +1019,7 @@ export class Cache {
      * @returns The number of deleted keys.
      */
     async deletePattern(pattern, namespace) {
-        const fullPattern = namespace ? `${namespace}:${pattern}` : pattern;
+        const fullPattern = this.getKey(pattern, namespace);
         let deleted = 0;
         for await (const key of this.client.scanIterator(fullPattern)) {
             const result = await this.client.del(key);
@@ -1055,7 +1068,7 @@ export class Cache {
      * @returns Matching keys.
      */
     async keys(pattern, namespace) {
-        const fullPattern = namespace ? `${namespace}:${pattern}` : pattern;
+        const fullPattern = this.getKey(pattern, namespace);
         const keys = [];
         for await (const key of this.client.scanIterator(fullPattern)) {
             keys.push(key);
@@ -1097,6 +1110,6 @@ export class Cache {
      * @returns The number of deleted keys.
      */
     async clearNamespace(namespace) {
-        return this.deletePattern('*', namespace);
+        return this.deletePattern("*", namespace);
     }
 }

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import { Cluster, Redis as RedisClient } from "ioredis";
-import { RateLimitOptionsInput, type ClusterInfo, type ClusterSlotRange, type ConnectionStatus, type RedisConfigInput, type RedisMode, DistributedLockInputOptions, CacheInputConfig } from "./types.js";
+import { RateLimitOptionsInput, type ClusterInfo, type ClusterRedisConfig, type ClusterSlotRange, type ConnectionStatus, type RedisConfig, type RedisConfigInput, type RedisMode, type SentinelRedisConfig, type StandaloneRedisConfig, DistributedLockInputOptions, CacheInputConfig } from "./types.js";
 import { type LoggerLike } from "./logger.js";
 import { Cache } from "./cache.js";
 import { PubSub } from "./pubsub.js";
@@ -48,6 +48,9 @@ type DeletePatternOptions = {
     batchSize?: number;
     scanCount?: number;
 };
+export declare function isClusterConfig(config: RedisConfig): config is ClusterRedisConfig;
+export declare function isSentinelConfig(config: RedisConfig): config is SentinelRedisConfig;
+export declare function isStandaloneConfig(config: RedisConfig): config is StandaloneRedisConfig;
 /**
  * Production-grade Redis client wrapper supporting:
  *

package/dist/client.js

@@ -15,13 +15,13 @@ import { deepMerge } from "./utils/deepmerge.js";
 // ============================================================================
 // Type Guards
 // ============================================================================
-function isClusterConfig(config) {
+export function isClusterConfig(config) {
     return config.mode === "cluster";
 }
-function isSentinelConfig(config) {
+export function isSentinelConfig(config) {
     return config.mode === "sentinel";
 }
-function isStandaloneConfig(config) {
+export function isStandaloneConfig(config) {
     return config.mode === "standalone";
 }
 // ============================================================================
@@ -295,7 +295,6 @@ export class RedisClientWrapper {
                 revocationStore: options.revocationStore ?? this.revocationStore,
             };
             this._session = createSessionManager(params);
-            void this._session.init();
             this.config.sessionOptions = params;
         }
         return this._session;

package/dist/lock.d.ts

@@ -1,5 +1,6 @@
 import { RedisClientWrapper } from './client.js';
 import { LoggerLike } from './logger.js';
+import { DistributedLockOptions, LockInfo } from './types.js';
 /**
  * Information about a distributed lock.
  *
@@ -14,14 +15,6 @@ import { LoggerLike } from './logger.js';
  * // { 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.
  *
@@ -35,14 +28,6 @@ export type LockInfo = {
  * 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.
  *

package/dist/lock.js

@@ -1,6 +1,49 @@
 import { RedisError } from './errors.js';
 import { randomBytes } from 'node:crypto';
 import { defaultLogger } from './logger.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.
  *