ioredis-toolkit 0.0.1

package/dist/cache.d.ts

@@ -0,0 +1,298 @@
+import { RedisClientWrapper } from './client.js';
+import { RedisConfig, CacheOptions } from './types.js';
+import { LoggerLike } from './logger.js';
+/**
+ * Cache layer on top of {@link RedisClientWrapper} with JSON serialization,
+ * optional gzip compression and namespace support.
+ *
+ * Works in all three modes (standalone, sentinel, cluster): multi-key operations
+ * are slot-aware and pattern scans cover every cluster node.
+ *
+ * @example
+ * ```ts
+ * const cache = new Cache(client, { defaultTTL: 3600, compressionThreshold: 1024 });
+ * await cache.set('user:1', { name: 'alice' });
+ * const user = await cache.get('user:1');
+ * ```
+ */
+export declare class Cache {
+    private client;
+    private logger;
+    private defaultTTL;
+    private compressionThreshold;
+    /**
+     * 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`.
+     *
+     * @example
+     * ```ts
+     * const cache = new Cache(client, { defaultTTL: 600, compressionThreshold: 2048 });
+     * ```
+     */
+    constructor(client: RedisClientWrapper, config: RedisConfig, logger?: LoggerLike);
+    private serialize;
+    private deserialize;
+    private getKey;
+    /**
+     * Reads a cached value.
+     *
+     * Objects are parsed from JSON and compressed values are transparently
+     * decompressed. Strings that are not JSON are returned as-is.
+     *
+     * @param key - Cache key.
+     * @param namespace - Optional namespace prefix (`namespace:key`).
+     * @returns The stored value, or `null` when missing.
+     *
+     * @example
+     * ```ts
+     * const user = await cache.get<User>('user:1');
+     * const token = await cache.get('token', 'auth');
+     * ```
+     */
+    get<T = any>(key: string, namespace?: string): Promise<T | null>;
+    /**
+     * Stores a value in the cache.
+     *
+     * @param key - Cache key.
+     * @param value - Any serializable value (string, number, boolean, Buffer, object).
+     * @param options - `ttl` in seconds (defaults to `defaultTTL`), `namespace`,
+     *   and `compress` (default `true`). Values larger than `compressionThreshold`
+     *   bytes are gzip-compressed.
+     * @returns `true` when stored successfully.
+     *
+     * @example
+     * ```ts
+     * await cache.set('user:1', user, { ttl: 300 });
+     * await cache.set('token', 'abc', { namespace: 'auth', compress: false });
+     * ```
+     */
+    set<T>(key: string, value: T, options?: CacheOptions): Promise<boolean>;
+    /**
+     * Stores a value only if the key does not exist yet (`SETNX`).
+     *
+     * @param key - Cache key.
+     * @param value - The value to store.
+     * @param options - `ttl` in seconds and `namespace`.
+     * @returns `true` only when the value was actually stored.
+     *
+     * @example
+     * ```ts
+     * const claimed = await cache.setNX('job:1', 'worker-1', { ttl: 60 });
+     * ```
+     */
+    setNX<T>(key: string, value: T, options?: CacheOptions): Promise<boolean>;
+    /**
+     * Stores a value only if the key does not exist yet, atomically with the TTL
+     * (`SET ... EX NX`).
+     *
+     * @param key - Cache key.
+     * @param value - The value to store.
+     * @param options - `ttl` in seconds and `namespace`.
+     * @returns `true` only when the value was actually stored.
+     *
+     * @example
+     * ```ts
+     * const locked = await cache.setEXNX('lock:order:42', 'txn-id', { ttl: 30 });
+     * ```
+     */
+    setEXNX<T>(key: string, value: T, options?: CacheOptions): Promise<boolean>;
+    /**
+     * Reads multiple cache keys in one call.
+     *
+     * Cluster-safe: keys are grouped by hash slot under the hood.
+     *
+     * @param keys - Cache keys to read.
+     * @param namespace - Optional namespace prefix applied to every key.
+     * @returns Values in input order; `null` for missing keys.
+     *
+     * @example
+     * ```ts
+     * const [a, b] = await cache.mget(['user:1', 'user:2']);
+     * ```
+     */
+    mget<T = any>(keys: string[], namespace?: string): Promise<(T | null)[]>;
+    /**
+     * Stores multiple key/value entries in one call.
+     *
+     * Cluster-safe: entries are grouped by hash slot, one pipeline per slot.
+     *
+     * @param entries - Object mapping cache keys to values.
+     * @param options - `ttl` in seconds (defaults to `defaultTTL`) and `namespace`.
+     * @returns `true` when every entry was stored.
+     *
+     * @example
+     * ```ts
+     * await cache.mset({ 'user:1': alice, 'user:2': bob }, { ttl: 300 });
+     * ```
+     */
+    mset<T>(entries: Record<string, T>, options?: CacheOptions): Promise<boolean>;
+    /**
+     * Deletes a cache key.
+     *
+     * @param key - Cache key.
+     * @param namespace - Optional namespace prefix.
+     * @returns `true` if the key existed and was deleted.
+     *
+     * @example
+     * ```ts
+     * const removed = await cache.delete('user:1');
+     * ```
+     */
+    delete(key: string, namespace?: string): Promise<boolean>;
+    /**
+     * Checks whether a cache key exists.
+     *
+     * @param key - Cache key.
+     * @param namespace - Optional namespace prefix.
+     * @returns `true` if the key exists.
+     *
+     * @example
+     * ```ts
+     * const cached = await cache.exists('user:1');
+     * ```
+     */
+    exists(key: string, namespace?: string): Promise<boolean>;
+    /**
+     * Sets the TTL of an existing cache key.
+     *
+     * @param key - Cache key.
+     * @param ttl - TTL in seconds.
+     * @param namespace - Optional namespace prefix.
+     * @returns `true` if the TTL was applied.
+     *
+     * @example
+     * ```ts
+     * const extended = await cache.expire('session:42', 3600);
+     * ```
+     */
+    expire(key: string, ttl: number, namespace?: string): Promise<boolean>;
+    /**
+     * Returns the remaining TTL of a cache key in seconds.
+     *
+     * @param key - Cache key.
+     * @param namespace - Optional namespace prefix.
+     * @returns Remaining TTL in seconds (`-2` if missing, `-1` if no TTL).
+     *
+     * @example
+     * ```ts
+     * const secondsLeft = await cache.ttl('session:42');
+     * ```
+     */
+    ttl(key: string, namespace?: string): Promise<number>;
+    /**
+     * Atomically increments a cache counter.
+     *
+     * @param key - Counter key.
+     * @param by - Amount to increment by (default `1`; ignored by Redis, kept for API parity).
+     * @param namespace - Optional namespace prefix.
+     * @returns The new counter value.
+     *
+     * @example
+     * ```ts
+     * const visits = await cache.increment('stats:visits');
+     * ```
+     */
+    increment(key: string, by?: number, namespace?: string): Promise<number>;
+    /**
+     * Atomically decrements a cache counter.
+     *
+     * @param key - Counter key.
+     * @param by - Amount to decrement by (default `1`; ignored by Redis, kept for API parity).
+     * @param namespace - Optional namespace prefix.
+     * @returns The new counter value.
+     *
+     * @example
+     * ```ts
+     * const stock = await cache.decrement('inventory:sku-1');
+     * ```
+     */
+    decrement(key: string, by?: number, namespace?: string): Promise<number>;
+    /**
+     * Reads a field from a hash-style cache key.
+     *
+     * @param key - Cache key.
+     * @param field - Hash field.
+     * @param namespace - Optional namespace prefix.
+     * @returns The field value (JSON-parsed when possible), or `null`.
+     *
+     * @example
+     * ```ts
+     * const name = await cache.hget('user:1', 'name');
+     * ```
+     */
+    hget<T = any>(key: string, field: string, namespace?: string): Promise<T | null>;
+    /**
+     * Writes a field into a hash-style cache key.
+     *
+     * @param key - Cache key.
+     * @param field - Hash field.
+     * @param value - Any serializable value (JSON-stringified unless it is a string).
+     * @param namespace - Optional namespace prefix.
+     * @returns `true` if a new field was created.
+     *
+     * @example
+     * ```ts
+     * await cache.hset('user:1', 'age', 30);
+     * ```
+     */
+    hset(key: string, field: string, value: any, namespace?: string): Promise<boolean>;
+    /**
+     * Returns every field of a hash-style cache key.
+     *
+     * @param key - Cache key.
+     * @param namespace - Optional namespace prefix.
+     * @returns Object mapping fields to values (JSON-parsed when possible).
+     *
+     * @example
+     * ```ts
+     * const profile = await cache.hgetall('user:1');
+     * ```
+     */
+    hgetall<T = any>(key: string, namespace?: string): Promise<Record<string, T>>;
+    /**
+     * Deletes every cache key matching a glob pattern.
+     *
+     * Cluster-safe: scans every node before deleting.
+     *
+     * @param pattern - Glob pattern, e.g. `'user:*'`.
+     * @param namespace - Optional namespace prefix (`namespace:pattern`).
+     * @returns The number of deleted keys.
+     *
+     * @example
+     * ```ts
+     * const removed = await cache.deletePattern('temp:*');
+     * ```
+     */
+    deletePattern(pattern: string, namespace?: string): Promise<number>;
+    /**
+     * Lists every cache key matching a glob pattern.
+     *
+     * Cluster-safe: scans every node.
+     *
+     * @param pattern - Glob pattern, e.g. `'session:*'`.
+     * @param namespace - Optional namespace prefix (`namespace:pattern`).
+     * @returns Matching keys.
+     *
+     * @example
+     * ```ts
+     * const sessions = await cache.keys('session:*');
+     * ```
+     */
+    keys(pattern: string, namespace?: string): Promise<string[]>;
+    /**
+     * Deletes every key inside a namespace.
+     *
+     * @param namespace - Namespace to wipe (`namespace:*`).
+     * @returns The number of deleted keys.
+     *
+     * @example
+     * ```ts
+     * const cleared = await cache.clearNamespace('sessions');
+     * ```
+     */
+    clearNamespace(namespace: string): Promise<number>;
+}