ioredis-toolkit 0.0.5 → 0.0.7

package/dist/cache.js

@@ -26,12 +26,21 @@ export class Cache {
     /**
      * Creates a cache bound to a Redis client.
      *
-     * @param client - The underlying {@link RedisClientWrapper}.
-     * @param config - Redis config; `defaultTTL` (seconds) and `compressionThreshold` (bytes)
-     *   control cache behavior.
-     * @param logger - Optional pino-compatible logger; defaults to `console`.
+     * **Parameters:**
+     * - `client` - The underlying {@link RedisClientWrapper}. All cache operations
+     *   delegate to this client.
+     * - `config` - Configuration object with the following fields:
+     *   - `defaultTTL` (number, optional, default: `3600`) - Default TTL in seconds
+     *     applied when no per-call TTL is specified.
+     *   - `compressionThreshold` (number, optional, default: `1024`) - Byte threshold
+     *     above which values are gzip-compressed transparently.
+     * - `logger` - Optional pino-compatible logger. Supports `trace/debug/info/warn/error/fatal`
+     *   levels and `child()` for namespace logging. Defaults to `console`.
      *
-     * @example
+     * **Type Parameters:**
+     * - `T` - The type of values stored/retrieved from the cache.
+     *
+     * **Example:**
      * ```ts
      * const cache = new Cache(client, { defaultTTL: 600, compressionThreshold: 2048 });
      * ```
@@ -114,6 +123,44 @@ export class Cache {
      * const token = await cache.get('token', 'auth');
      * ```
      */
+    /**
+     * Reads a cached value.
+     *
+     * **Behavior:**
+     * - Objects are parsed from JSON when stored as JSON.
+     * - Values larger than `compressionThreshold` bytes are transparently
+     *   decompressed (gzip) when reading.
+     * - Strings that are not JSON are returned as-is.
+     * - If the key does not exist, returns `null`.
+     *
+     * **Type Parameters:**
+     * - `T` - The expected return type. When the stored value is a JSON object/array,
+     *   it will be parsed and returned as `T`. When it's a primitive (string/number/bool),
+     *   it is returned as-is and typed as `T`.
+     *
+     * **Returns:**
+     * - The stored value, parsed as `T` when possible, or `null` when the key is missing.
+     *
+     * **Example:**
+     * ```ts
+     * // Store an object
+     * await cache.set('user:1', { name: 'alice', age: 30 });
+     *
+     * // Read it back with type coercion
+     * const user: { name: string; age: number } | null = await cache.get<UserProfile>('user:1');
+     * // user === { name: 'alice', age: 30 }
+     *
+     * // Read a string value
+     * const token = await cache.get('token'); // 'abc' | null
+     * ```
+     *
+     * **Parameters:**
+     * - `key` - Cache key.
+     * - `namespace` - Optional namespace prefix (`namespace:key`). When provided,
+     *   the key is internally transformed to `${namespace}:${key}`.
+     *
+     * @returns The stored value, or `null` when missing.
+     */
     async get(key, namespace) {
         const fullKey = this.getKey(key, namespace);
         const raw = await this.client.get(fullKey);
@@ -150,6 +197,47 @@ export class Cache {
      * await cache.set('token', 'abc', { namespace: 'auth', compress: false });
      * ```
      */
+    /**
+     * Stores a value in the cache.
+     *
+     * **Behavior:**
+     * - Values are JSON-serialized when they are objects, arrays, or booleans/strings/numbers
+     *   are stored as-is.
+     * - Values larger than `compressionThreshold` bytes are gzip-compressed transparently.
+     *   The compressed form is stored with metadata (`_compressed: true`, `_data: base64`) so
+     *   it is transparently decompressed on read.
+     * - Set `compress: false` to disable compression for a single write, regardless of size.
+     * - Per-call TTL overrides the cache's `defaultTTL`.
+     * - Per-call `namespace` overrides the cache's configured namespace for that operation.
+     *
+     * **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'`).
+     *
+     * **Example:**
+     * ```ts
+     * // Store an object with a custom TTL
+     * await cache.set('user:1', { name: 'alice' }, { ttl: 300 });
+     *
+     * // Store with compression disabled
+     * await cache.set('token', 'abc123', { compress: false });
+     *
+     * // Store with a namespace
+     * await cache.set('token', 'abc', { namespace: 'auth' });
+     * ```
+     *
+     * **Parameters:**
+     * - `key` - Cache key.
+     * - `value` - Any serializable value (string, number, boolean, Buffer, or object).
+     * - `options` - Optional configuration:
+     *   - `ttl` (number, optional) - TTL in seconds. Falls back to `defaultTTL`.
+     *   - `namespace` (string, optional) - Namespace prefix. Falls back to cache config.
+     *   - `compress` (boolean, optional) - Force compression or disable it. Defaults to `true`.
+     *
+     * @returns `true` when stored successfully.
+     */
     async set(key, value, options = {}) {
         const fullKey = this.getKey(key, options.namespace);
         const ttl = options.ttl || this.defaultTTL;
@@ -202,6 +290,36 @@ export class Cache {
      * const claimed = await cache.setNX('job:1', 'worker-1', { ttl: 60 });
      * ```
      */
+    /**
+     * Stores a value only if the key does not exist yet (`SETNX`).
+     *
+     * **Behavior:**
+     * - The value is stored atomically using Redis `SET key value EX ttl NX`.
+     * - Returns `true` only when the key did not exist and the value was set.
+     * - Per-call TTL overrides the cache's `defaultTTL`.
+     * - Per-call `namespace` is applied to the key.
+     *
+     * **Type Parameters:**
+     * - `T` - The type of the value being stored. Will be JSON-stringified if not a string.
+     *
+     * **Returns:**
+     * - `true` only when the value was actually stored (Redis SETNX returned `1`).
+     *
+     * **Example:**
+     * ```ts
+     * const claimed = await cache.setNX('job:1', 'worker-1', { ttl: 60 });
+     * // claimed === true (job was claimed by this worker)
+     * ```
+     *
+     * **Parameters:**
+     * - `key` - Cache key.
+     * - `value` - The value to store. String stored as-is; objects are JSON-stringified.
+     * - `options` - Optional configuration:
+     *   - `ttl` (number, optional) - TTL in seconds. Falls back to `defaultTTL`.
+     *   - `namespace` (string, optional) - Namespace prefix.
+     *
+     * @returns `true` only when the value was actually stored.
+     */
     async setNX(key, value, options = {}) {
         const fullKey = this.getKey(key, options.namespace);
         const ttl = options.ttl || this.defaultTTL;
@@ -229,6 +347,39 @@ export class Cache {
      * const locked = await cache.setEXNX('lock:order:42', 'txn-id', { ttl: 30 });
      * ```
      */
+    /**
+     * Stores a value only if the key does not exist yet, atomically with the TTL
+     * (`SET ... EX NX`).
+     *
+     * **Behavior:**
+     * - The value is stored atomically using Redis `SET key value EX ttl NX`.
+     * - This is the atomic equivalent of calling `SET key value EX ttl` followed by
+     *   `SET key value NX` - but done in a single Redis call.
+     * - Returns `true` only when the key did not exist and the value was set with TTL.
+     * - Per-call TTL overrides the cache's `defaultTTL`.
+     * - Per-call `namespace` is applied to the key.
+     *
+     * **Type Parameters:**
+     * - `T` - The type of the value being stored. Will be JSON-stringified if not a string.
+     *
+     * **Returns:**
+     * - `true` only when the value was actually stored (Redis SET returned `OK`).
+     *
+     * **Example:**
+     * ```ts
+     * const locked = await cache.setEXNX('lock:order:42', 'txn-id', { ttl: 30 });
+     * // locked === true (lock was acquired with 30s TTL)
+     * ```
+     *
+     * **Parameters:**
+     * - `key` - Cache key.
+     * - `value` - The value to store. String stored as-is; objects are JSON-stringified.
+     * - `options` - Optional configuration:
+     *   - `ttl` (number, optional) - TTL in seconds. Falls back to `defaultTTL`.
+     *   - `namespace` (string, optional) - Namespace prefix.
+     *
+     * @returns `true` only when the value was actually stored.
+     */
     async setEXNX(key, value, options = {}) {
         const fullKey = this.getKey(key, options.namespace);
         const ttl = options.ttl || this.defaultTTL;
@@ -278,6 +429,37 @@ export class Cache {
      * const [a, b] = await cache.mget(['user:1', 'user:2']);
      * ```
      */
+    /**
+       * 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 raw = await this.client.mgetClusterAware(fullKeys);
@@ -336,6 +518,39 @@ export class Cache {
      * await cache.mset({ 'user:1': alice, 'user:2': bob }, { ttl: 300 });
      * ```
      */
+    /**
+     * Stores multiple key/value entries in one call.
+     *
+     * **Behavior:**
+     * - Cluster-safe: entries are grouped by hash slot, one pipeline per slot.
+     *   This avoids CROSS-SLOT errors that would occur if keys spanned multiple slots in a
+     *   single pipeline.
+     * - Values are JSON-serialized when they are objects; strings/buffers are stored as-is.
+     * - Per-call TTL overrides the cache's `defaultTTL`.
+     * - Per-call `namespace` is applied to all keys.
+     *
+     * **Type Parameters:**
+     * - `T` - The type of values being stored. Objects are JSON-stringified; strings/buffers
+     *   are stored as-is.
+     *
+     * **Returns:**
+     * - `true` when every entry was stored successfully.
+     * - `false` if any entry failed to store.
+     *
+     * **Example:**
+     * ```ts
+     * await cache.mset({ 'user:1': alice, 'user:2': bob }, { ttl: 300 });
+     * // Both entries stored with a 5-minute TTL
+     * ```
+     *
+     * **Parameters:**
+     * - `entries` - Object mapping cache keys to values.
+     * - `options` - Optional configuration:
+     *   - `ttl` (number, optional) - TTL in seconds. Falls back to `defaultTTL`.
+     *   - `namespace` (string, optional) - Namespace prefix. Applied to all keys.
+     *
+     * @returns `true` when every entry was stored.
+     */
     async mset(entries, options = {}) {
         const ttl = options.ttl || this.defaultTTL;
         const namespace = options.namespace;
@@ -379,6 +594,28 @@ export class Cache {
      * const removed = await cache.delete('user:1');
      * ```
      */
+    /**
+     * Deletes a cache key.
+     *
+     * **Behavior:**
+     * - Deletes the full key (including any namespace prefix).
+     * - Returns `true` only when the key existed and was deleted (Redis DEL returned `1`).
+     *
+     * **Returns:**
+     * - `true` if the key existed and was deleted.
+   *
+     * **Example:**
+     * ```ts
+     * const removed = await cache.delete('user:1');
+     * // removed === true
+     * ```
+     *
+     * **Parameters:**
+     * - `key` - Cache key.
+     * - `namespace` - Optional namespace prefix.
+     *
+     * @returns `true` if the key existed and was deleted.
+     */
     async delete(key, namespace) {
         const fullKey = this.getKey(key, namespace);
         const result = await this.client.del(fullKey);
@@ -396,6 +633,25 @@ export class Cache {
      * const cached = await cache.exists('user:1');
      * ```
      */
+    /**
+     * Checks whether a cache key exists.
+     *
+     * **Returns:**
+     * - `true` if the key exists in Redis.
+     * - `false` if the key does not exist.
+     *
+     * **Example:**
+     * ```ts
+     * const cached = await cache.exists('user:1');
+     * // cached === true when 'user:1' has been set
+     * ```
+     *
+     * **Parameters:**
+     * - `key` - Cache key.
+     * - `namespace` - Optional namespace prefix.
+     *
+     * @returns `true` if the key exists.
+     */
     async exists(key, namespace) {
         const fullKey = this.getKey(key, namespace);
         const result = await this.client.exists(fullKey);
@@ -414,6 +670,26 @@ export class Cache {
      * const extended = await cache.expire('session:42', 3600);
      * ```
      */
+    /**
+     * Sets the TTL of an existing cache key.
+     *
+     * **Returns:**
+     * - `true` if the TTL was applied (Redis EXPIRE returned `1`).
+     * - `false` if the key did not exist.
+     *
+     * **Example:**
+     * ```ts
+     * const extended = await cache.expire('session:42', 3600);
+     * // extended === true (TTL was set to 1 hour)
+     * ```
+     *
+     * **Parameters:**
+     * - `key` - Cache key.
+     * - `ttl` - TTL in seconds.
+     * - `namespace` - Optional namespace prefix.
+     *
+     * @returns `true` if the TTL was applied.
+     */
     async expire(key, ttl, namespace) {
         const fullKey = this.getKey(key, namespace);
         const result = await this.client.expire(fullKey, ttl);
@@ -431,6 +707,26 @@ export class Cache {
      * const secondsLeft = await cache.ttl('session:42');
      * ```
      */
+    /**
+     * Returns the remaining TTL of a cache key in seconds.
+     *
+     * **Returns:**
+     * - The remaining TTL in seconds.
+     * - `-2` if the key does not exist.
+     * - `-1` if the key exists but has no TTL set.
+     *
+     * **Example:**
+     * ```ts
+     * const secondsLeft = await cache.ttl('session:42');
+     * // secondsLeft === 2500 (approximately 42 minutes remaining)
+     * ```
+     *
+     * **Parameters:**
+     * - `key` - Cache key.
+     * - `namespace` - Optional namespace prefix.
+     *
+     * @returns Remaining TTL in seconds (`-2` if missing, `-1` if no TTL).
+     */
     async ttl(key, namespace) {
         const fullKey = this.getKey(key, namespace);
         return this.client.ttl(fullKey);
@@ -448,6 +744,35 @@ export class Cache {
      * const visits = await cache.increment('stats:visits');
      * ```
      */
+    /**
+     * Atomically increments a cache counter.
+     *
+     * **Behavior:**
+     * - Uses Redis `INCR` command on the full key (including namespace if set).
+     * - The counter starts at `0` if the key does not exist, then increments to `1`.
+     * - The `by` parameter is passed to Redis but note: Redis `INCR` always increments
+     *   by `1`. The `by` parameter is kept for API parity with other cache implementations
+     *   but has no effect on the actual Redis command result.
+     *
+     * **Returns:**
+     * - The new counter value (the value after incrementing).
+     *
+     * **Example:**
+     * ```ts
+     * const visits = await cache.increment('stats:visits');
+     * // visits === 1 (first increment)
+     * const more = await cache.increment('stats:visits', 5); // by parameter ignored
+     * // more === 2
+     * ```
+     *
+     * **Parameters:**
+     * - `key` - Counter key.
+     * - `by` - Amount to increment by (default `1`). Note: Redis `INCR` always increments
+     *   by `1`; this parameter is kept for API parity.
+     * - `namespace` - Optional namespace prefix.
+     *
+     * @returns The new counter value.
+     */
     async increment(key, by = 1, namespace) {
         const fullKey = this.getKey(key, namespace);
         return this.client.incr(fullKey);
@@ -465,6 +790,32 @@ export class Cache {
      * const stock = await cache.decrement('inventory:sku-1');
      * ```
      */
+    /**
+     * Atomically decrements a cache counter.
+     *
+     * **Behavior:**
+     * - Uses Redis `DECR` command on the full key (including namespace if set).
+     * - The `by` parameter is passed to Redis but note: Redis `DECR` always decrements
+     *   by `1`. The `by` parameter is kept for API parity with other cache implementations
+     *   but has no effect on the actual Redis command result.
+     *
+     * **Returns:**
+     * - The new counter value (the value after decrementing).
+     *
+     * **Example:**
+     * ```ts
+     * const stock = await cache.decrement('inventory:sku-1');
+     * // stock === 99 (started at 100, decremented by 1)
+     * ```
+     *
+     * **Parameters:**
+     * - `key` - Counter key.
+     * - `by` - Amount to decrement by (default `1`). Note: Redis `DECR` always decrements
+     *   by `1`; this parameter is kept for API parity.
+     * - `namespace` - Optional namespace prefix.
+     *
+     * @returns The new counter value.
+     */
     async decrement(key, by = 1, namespace) {
         const fullKey = this.getKey(key, namespace);
         return this.client.decr(fullKey);
@@ -483,6 +834,30 @@ export class Cache {
      * const name = await cache.hget('user:1', 'name');
      * ```
      */
+    /**
+     * Reads a field from a hash-style cache key.
+     *
+     * **Behavior:**
+     * - The field value is retrieved from the Redis hash.
+     * - When the stored value is a JSON string, it is parsed and returned as the typed result.
+     * - When the stored value is not JSON, it is returned as a raw string, typed as `T`.
+     *
+     * **Returns:**
+     * - The field value, parsed as `T` when possible, or `null` when the key or field does not exist.
+     *
+     * **Example:**
+     * ```ts
+     * const name = await cache.hget('user:1', 'name');
+     * // name === 'alice' | null
+     * ```
+     *
+     * **Parameters:**
+     * - `key` - Cache key (hash key in Redis).
+     * - `field` - Hash field to read.
+     * - `namespace` - Optional namespace prefix. Applied to the key.
+     *
+     * @returns The field value, or `null`.
+     */
     async hget(key, field, namespace) {
         const fullKey = this.getKey(key, namespace);
         const result = await this.client.hget(fullKey, field);
@@ -509,6 +884,32 @@ export class Cache {
      * await cache.hset('user:1', 'age', 30);
      * ```
      */
+    /**
+     * Writes a field into a hash-style cache key.
+     *
+     * **Behavior:**
+     * - The value is JSON-stringified when it is not a string (objects, arrays, etc.).
+     *   Strings are stored as-is.
+     * - Returns `true` only when a new field was created (Redis HSET returned `1`).
+     *   If the field already exists, its value is overwritten and `true` is still returned.
+     *
+     * **Returns:**
+     * - `true` if a new field was created.
+     *
+     * **Example:**
+     * ```ts
+     * await cache.hset('user:1', 'age', 30);
+     * // Field 'age' set to '30' (stringified) in hash 'user:1'
+     * ```
+     *
+     * **Parameters:**
+     * - `key` - Cache key (hash key in Redis).
+     * - `field` - Hash field to write.
+     * - `value` - Any serializable value. Strings stored as-is; objects are JSON-stringified.
+     * - `namespace` - Optional namespace prefix. Applied to the key.
+     *
+     * @returns `true` if a new field was created.
+     */
     async hset(key, field, value, namespace) {
         const fullKey = this.getKey(key, namespace);
         const rawValue = typeof value === 'string' ? value : JSON.stringify(value);
@@ -527,6 +928,29 @@ export class Cache {
      * const profile = await cache.hgetall('user:1');
      * ```
      */
+    /**
+     * Returns every field of a hash-style cache key.
+     *
+     * **Behavior:**
+     * - Retrieves all fields and values from the Redis hash.
+     * - Each value is parsed from JSON when possible. Non-JSON values are returned as raw strings.
+     * - Returns an empty object `{}` when the key does not exist or has no fields.
+     *
+     * **Returns:**
+     * - An object mapping field names to their values, with values parsed as `T` when possible.
+     *
+     * **Example:**
+     * ```ts
+     * const profile = await cache.hgetall('user:1');
+     * // profile === { age: 30, name: 'alice' }
+     * ```
+     *
+     * **Parameters:**
+     * - `key` - Cache key (hash key in Redis).
+     * - `namespace` - Optional namespace prefix. Applied to the key.
+     *
+     * @returns Object mapping fields to values (JSON-parsed when possible).
+     */
     async hgetall(key, namespace) {
         const fullKey = this.getKey(key, namespace);
         const result = await this.client.hgetall(fullKey);
@@ -556,6 +980,31 @@ export class Cache {
      * const removed = await cache.deletePattern('temp:*');
      * ```
      */
+    /**
+     * Deletes every cache key matching a glob pattern.
+     *
+     * **Behavior:**
+     * - Cluster-safe: scans every node before deleting.
+     * - Uses `SCAN` iteratively to avoid blocking the Redis server on large datasets.
+     * - Each matching key is individually deleted via `DEL`.
+     * - The `batchSize` and `scanCount` options control the scan batching.
+     *
+     * **Returns:**
+     * - The number of deleted keys.
+     *
+     * **Example:**
+     * ```ts
+     * const removed = await cache.deletePattern('temp:*');
+     * // removed === number of keys matching 'temp:*' that were deleted
+     * ```
+     *
+     * **Parameters:**
+     * - `pattern` - Glob pattern, e.g. `'temp:*'`.
+     * - `namespace` - Optional namespace prefix. The pattern is transformed to
+     *   `${namespace}:${pattern}` before scanning.
+     *
+     * @returns The number of deleted keys.
+     */
     async deletePattern(pattern, namespace) {
         const fullPattern = namespace ? `${namespace}:${pattern}` : pattern;
         let deleted = 0;
@@ -580,6 +1029,31 @@ export class Cache {
      * const sessions = await cache.keys('session:*');
      * ```
      */
+    /**
+     * Lists every cache key matching a glob pattern.
+     *
+     * **Behavior:**
+     * - Cluster-safe: scans every node.
+     * - Uses `SCAN` iteratively to avoid blocking the Redis server on large datasets.
+     * - Returns all keys matching the glob pattern across all nodes (in cluster mode).
+     *
+     * **Returns:**
+     * - An array of matching keys (relative format, without namespace prefix unless
+     *   one was provided in the options).
+     *
+     * **Example:**
+     * ```ts
+     * const sessions = await cache.keys('session:*');
+     * // sessions === ['session:1', 'session:2', ...]
+     * ```
+     *
+     * **Parameters:**
+     * - `pattern` - Glob pattern, e.g. `'session:*'`.
+     * - `namespace` - Optional namespace prefix. The pattern is transformed to
+     *   `${namespace}:${pattern}` before scanning.
+     *
+     * @returns Matching keys.
+     */
     async keys(pattern, namespace) {
         const fullPattern = namespace ? `${namespace}:${pattern}` : pattern;
         const keys = [];
@@ -600,6 +1074,28 @@ export class Cache {
      * const cleared = await cache.clearNamespace('sessions');
      * ```
      */
+    /**
+     * Deletes every key inside a namespace.
+     *
+     * **Behavior:**
+     * - Deletes all keys matching the pattern `*` within the specified namespace.
+     * - Internally calls {@link deletePattern} with the pattern `*` and the given namespace.
+     *
+     * **Returns:**
+     * - The number of deleted keys.
+     *
+     * **Example:**
+     * ```ts
+     * const cleared = await cache.clearNamespace('sessions');
+     * // cleared === number of keys deleted in the 'sessions' namespace
+     * ```
+     *
+     * **Parameters:**
+     * - `namespace` - Namespace to wipe (e.g. `'sessions'`). Every key of the form
+     *   `namespace:*` will be deleted.
+     *
+     * @returns The number of deleted keys.
+     */
     async clearNamespace(namespace) {
         return this.deletePattern('*', namespace);
     }