@sebspark/promise-cache 6.1.2 → 6.2.0

package/dist/index.d.mts

@@ -0,0 +1,940 @@
+import { RedisClientOptions, RedisClientOptions as RedisClientOptions$1, SetOptions, createClient } from "redis";
+import { UUID } from "node:crypto";
+import { add, sub } from "date-fns";
+
+//#region src/types.d.ts
+type MultiExecReturnTypes = string[] | string | {
+  [x: string]: string;
+} | number | boolean | null | undefined;
+/**
+ * Defines the expiration strategy for cached values.
+ *
+ * - A `number` is interpreted as a TTL (time-to-live) in **milliseconds**.
+ * - A `Date` represents an **exact expiration timestamp**.
+ * - If omitted, the cache entry **never expires**.
+ */
+type Expiry = number | Date;
+/**
+ * Options for caching a function's result.
+ * @template A - Argument types of the function.
+ */
+type CachingOptions<A extends unknown[], R> = {
+  /**
+   * A fixed key or a function that generates a key based on function arguments.
+   */
+  key: string | ((...args: A) => string);
+  /**
+   * Defines how long the cached value remains valid before expiring.
+   *
+   * - A **number** is treated as a TTL (time-to-live) in **milliseconds**.
+   * - A **Date** sets an **exact expiration timestamp**.
+   * - A **function** dynamically determines the expiration based on:
+   *   - `args` - The function arguments.
+   *   - `response` - The function result.
+   * - If omitted, the cache entry **does not expire**.
+   */
+  expiry?: Expiry | ((args: A, response: R) => Expiry);
+};
+/**
+ * Represents a caching system that wraps asynchronous functions.
+ */
+type Cache = {
+  /**
+   * The underlying persistor used for caching.
+   */
+  persistor: IPersistor;
+  /**
+   * Wraps an asynchronous function to enable caching.
+   * @template A - Argument types.
+   * @template R - Return type.
+   * @param {Delegate<A, R>} delegate - The function to wrap.
+   * @param {CachingOptions<A>} options - Caching options, including key strategy.
+   * @returns {Delegate<A, R>} A new function that caches results.
+   */
+  wrap<A extends unknown[], R>(delegate: (...args: A) => Promise<R>, options: CachingOptions<A, R>): (...args: A) => Promise<R>;
+};
+type HashTypes = string | number;
+type HashValue = {
+  [x: string]: HashTypes;
+  [x: number]: HashTypes;
+} | Map<HashTypes, HashTypes>;
+/**
+ * Interface for a key-value storage system that supports Redis-like commands.
+ * Provides methods for storing, retrieving, and managing data with optional expiration.
+ */
+interface IPersistor {
+  /**
+   * Stores a value in Redis or Memory with an optional expiration.
+   * @param key - The storage key.
+   * @param value - The string value to store.
+   * @param options - Expiration options (TTL, absolute expiration, etc.).
+   * @returns Resolves to `"OK"` if successful, otherwise `null` if the operation fails.
+   */
+  set(key: string, value: HashTypes, options?: SetOptions): Promise<string | null>;
+  /**
+   * Retrieves a value from Redis or Memory.
+   * @param key - The storage key.
+   * @returns Resolves to the stored value as a string, or `null` if the key does not exist.
+   */
+  get(key: string): Promise<string | null>;
+  /**
+   * Deletes a key from Redis or Memory.
+   * @param key - The storage key.
+   * @returns Resolves to the number of keys removed (`1` if deleted, `0` if the key was not found).
+   */
+  del(key: string): Promise<number>;
+  /**
+   * Sets a time-to-live (TTL) in seconds for a key.
+   * @param key - The storage key.
+   * @param seconds - TTL in seconds.
+   * @returns Resolves to `true` if the expiration was successfully set, `false` if the key does not exist.
+   */
+  expire(key: string, seconds: number): Promise<number>;
+  /**
+   * Gets the remaining TTL (time-to-live) of a key.
+   * @param key - The storage key.
+   * @returns
+   * - The remaining TTL in seconds.
+   * - `-1` if the key exists but has no expiration.
+   * - `-2` if the key does not exist.
+   */
+  ttl(key: string): Promise<number>;
+  /**
+   * Clears all keys from the storage system.
+   * @returns Resolves to `"OK"` when the operation completes successfully.
+   */
+  flushAll(): Promise<string>;
+  /**
+   * Stores a value and sets an expiration time in seconds.
+   * @param key - The storage key.
+   * @param seconds - Expiration time in seconds.
+   * @param value - The string value to store.
+   * @returns Resolves to `"OK"` if successful, otherwise `null` if the operation fails.
+   */
+  setEx(key: string, seconds: number, value: string): Promise<string | null>;
+  /**
+   * Stores a value and sets an expiration time in milliseconds.
+   * @param key - The storage key.
+   * @param milliseconds - Expiration time in milliseconds.
+   * @param value - The string value to store.
+   * @returns Resolves to `"OK"` if successful, otherwise `null` if the operation fails.
+   */
+  pSetEx(key: string, milliseconds: number, value: string): Promise<string | null>;
+  /**
+   * Stores a value **only if the key does not already exist**.
+   * @param key - The storage key.
+   * @param value - The string value to store.
+   * @returns Resolves to `true` if the key was set, or `false` if the key already exists.
+   */
+  setNX(key: string, value: string): Promise<number>;
+  /**
+   * Creates a multi-command batch operation.
+   * This allows multiple commands to be executed in a batch, improving performance.
+   * @returns An instance of `IPersistorMulti` to queue multiple commands.
+   */
+  multi(): IPersistorMulti;
+  /**
+   * Checks if keys exist in storage.
+   * @param keys - One or more keys to check.
+   * @returns Resolves to the number of keys that exist.
+   */
+  exists(key: string | string[]): Promise<number>;
+  /**
+   * Increments a key by 1.
+   * @param key - The key to increment.
+   * @returns Resolves to the new value after increment.
+   */
+  incr(key: string): Promise<number>;
+  /**
+   * Decrements a key by 1.
+   * @param key - The key to decrement.
+   * @returns Resolves to the new value after decrement.
+   */
+  decr(key: string): Promise<number>;
+  /**
+   * Increments a key by a specified amount.
+   * @param key - The key to increment.
+   * @param increment - The amount to increase by.
+   * @returns Resolves to the new value after increment.
+   */
+  incrBy(key: string, increment: number): Promise<number>;
+  /**
+   * Decrements a key by a specified amount.
+   * @param key - The key to decrement.
+   * @param decrement - The amount to decrease by.
+   * @returns Resolves to the new value after decrement.
+   */
+  decrBy(key: string, decrement: number): Promise<number>;
+  /**
+   * Sets a field in a hash.
+   * @param key - The hash key.
+   * @param field - The field name.
+   * @param value - The value to store.
+   * @returns Resolves to `1` if the field was added, or `0` if updated.
+   */
+  hSet(key: string, field: string, value: HashTypes): Promise<number>;
+  /**
+   * Sets a (partial) hash.
+   * @param key - The hash key.
+   * @param value - The (partial) value to store.
+   * @returns Resolves to `1` if a field was added, or `0` if updated.
+   */
+  hSet(key: string, value: HashValue): Promise<number>;
+  /**
+   * Retrieves a field from a hash.
+   * @param key - The hash key.
+   * @param field - The field name.
+   * @returns Resolves to the value, or null if the field does not exist.
+   */
+  hGet(key: string, field: string): Promise<string | null>;
+  /**
+   * Retrieves a hash value.
+   * @param key - The hash key.
+   * @returns Resolves to the value, or null if the hash does not exist.
+   */
+  hGetAll(key: string): Promise<{
+    [x: string]: string;
+  }>;
+  /**
+   * Pushes values to the left (head) of a list.
+   * @param key - The list key.
+   * @param values - The values to add.
+   * @returns Resolves to the length of the list after the operation.
+   */
+  lPush(key: string, values: string | string[]): Promise<number>;
+  /**
+   * Pushes values to the right (tail) of a list.
+   * @param key - The list key.
+   * @param values - The values to add.
+   * @returns Resolves to the length of the list after the operation.
+   */
+  rPush(key: string, values: string | string[]): Promise<number>;
+  /**
+   * Removes and returns the first element from a list.
+   * @param key - The list key.
+   * @returns Resolves to the removed element, or `null` if the list is empty.
+   */
+  lPop(key: string): Promise<string | null>;
+  /**
+   * Removes and returns the last element from a list.
+   * @param key - The list key.
+   * @returns Resolves to the removed element, or `null` if the list is empty.
+   */
+  rPop(key: string): Promise<string | null>;
+  /**
+   * Retrieves a range of elements from a list.
+   * @param key - The list key.
+   * @param start - The start index.
+   * @param stop - The stop index (inclusive).
+   * @returns Resolves to an array of elements in the range.
+   */
+  lRange(key: string, start: number, stop: number): Promise<string[]>;
+  /**
+   * Adds members to a set.
+   * @param key - The set key.
+   * @param values - The values to add.
+   * @returns Resolves to the number of elements successfully added.
+   */
+  sAdd(key: string, values: string | string[]): Promise<number>;
+  /**
+   * Removes members from a set.
+   * @param key - The set key.
+   * @param values - The values to remove.
+   * @returns Resolves to the number of elements removed.
+   */
+  sRem(key: string, values: string | string[]): Promise<number>;
+  /**
+   * Retrieves all members of a set.
+   * @param key - The set key.
+   * @returns Resolves to an array of all members in the set.
+   */
+  sMembers(key: string): Promise<string[]>;
+  /**
+   * Adds members to a sorted set with scores.
+   * @param key - The sorted set key.
+   * @param members - An array of objects with `score` and `value`.
+   * @returns Resolves to the number of elements successfully added.
+   */
+  zAdd(key: string, members: {
+    score: number;
+    value: string;
+  }[]): Promise<number>;
+  /**
+   * Retrieves a range of members from a sorted set.
+   * @param key - The sorted set key.
+   * @param start - The start index.
+   * @param stop - The stop index (inclusive).
+   * @returns Resolves to an array of member values in the range.
+   */
+  zRange(key: string, start: number, stop: number): Promise<string[]>;
+  /**
+   * Removes members from a sorted set.
+   * @param key - The sorted set key.
+   * @param members - The members to remove.
+   * @returns Resolves to the number of elements removed.
+   */
+  zRem(key: string, members: string | string[]): Promise<number>;
+  isReady: boolean;
+  isOpen: boolean;
+  connect(): Promise<IPersistor>;
+  once(event: IPersistorEvent, cb: EventCallback): IPersistor;
+}
+type IPersistorEvent = 'ready' | 'connect' | 'reconnecting';
+type EventCallback = () => void;
+/**
+ * Interface for executing multiple storage commands in a batch operation.
+ * All commands are queued and executed when `exec()` is called.
+ */
+interface IPersistorMulti {
+  /**
+   * Stores a value in Redis or Memory with an optional expiration.
+   * @param key - The storage key.
+   * @param value - The string value to store.
+   * @param options - Expiration options (TTL, absolute expiration, etc.).
+   * @returns The same `IPersistorMulti` instance, enabling method chaining.
+   */
+  set(key: string, value: HashTypes, options?: SetOptions): IPersistorMulti;
+  /**
+   * Stores a value and sets an expiration time in seconds.
+   * @param key - The storage key.
+   * @param seconds - Expiration time in seconds.
+   * @param value - The string value to store.
+   * @returns The same `IPersistorMulti` instance, enabling method chaining.
+   */
+  setEx(key: string, seconds: number, value: string): IPersistorMulti;
+  /**
+   * Stores a value and sets an expiration time in milliseconds.
+   * @param key - The storage key.
+   * @param milliseconds - Expiration time in milliseconds.
+   * @param value - The string value to store.
+   * @returns The same `IPersistorMulti` instance, enabling method chaining.
+   */
+  pSetEx(key: string, milliseconds: number, value: string): IPersistorMulti;
+  /**
+   * Stores a value **only if the key does not already exist**.
+   * @param key - The storage key.
+   * @param value - The string value to store.
+   * @returns The same `IPersistorMulti` instance, enabling method chaining.
+   */
+  setNX(key: string, value: string): IPersistorMulti;
+  /**
+   * Retrieves a value from Redis or Memory.
+   * @param key - The storage key.
+   * @returns The same `IPersistorMulti` instance, enabling method chaining.
+   */
+  get(key: string): IPersistorMulti;
+  /**
+   * Deletes a key from Redis or Memory.
+   * @param key - The storage key.
+   * @returns The same `IPersistorMulti` instance, enabling method chaining.
+   */
+  del(key: string): IPersistorMulti;
+  /**
+   * Sets a time-to-live (TTL) in seconds for a key.
+   * @param key - The storage key.
+   * @param seconds - TTL in seconds.
+   * @returns The same `IPersistorMulti` instance, enabling method chaining.
+   */
+  expire(key: string, seconds: number): IPersistorMulti;
+  /**
+   * Gets the remaining TTL (time-to-live) of a key.
+   * @param key - The storage key.
+   * @returns The same `IPersistorMulti` instance, enabling method chaining.
+   */
+  ttl(key: string): IPersistorMulti;
+  /**
+   * Clears all keys from the storage system.
+   * @returns The same `IPersistorMulti` instance, enabling method chaining.
+   */
+  flushAll(): IPersistorMulti;
+  /**
+   * Queues an `exists` operation in the transaction.
+   * @param key - The storage key or an array of keys.
+   * @returns The `IPersistorMulti` instance for method chaining.
+   */
+  exists(key: string | string[]): IPersistorMulti;
+  /**
+   * Queues an `incr` operation in the transaction.
+   * @param key - The storage key.
+   * @returns The `IPersistorMulti` instance for method chaining.
+   */
+  incr(key: string): IPersistorMulti;
+  /**
+   * Queues an `incrBy` operation in the transaction.
+   * @param key - The storage key.
+   * @param increment - The amount to increment by.
+   * @returns The `IPersistorMulti` instance for method chaining.
+   */
+  incrBy(key: string, increment: number): IPersistorMulti;
+  /**
+   * Queues a `decr` operation in the transaction.
+   * @param key - The storage key.
+   * @returns The `IPersistorMulti` instance for method chaining.
+   */
+  decr(key: string): IPersistorMulti;
+  /**
+   * Queues a `decrBy` operation in the transaction.
+   * @param key - The storage key.
+   * @param decrement - The amount to decrement by.
+   * @returns The `IPersistorMulti` instance for method chaining.
+   */
+  decrBy(key: string, decrement: number): IPersistorMulti;
+  /**
+   * Sets a field in a hash.
+   * @param key - The hash key.
+   * @param field - The field name.
+   * @param value - The value to store.
+   * @returns The multi-instance for chaining.
+   */
+  hSet(key: string, field: string, value: HashTypes): IPersistorMulti;
+  /**
+   * Sets a (partial) hash.
+   * @param key - The hash key.
+   * @param value - The (partial) value to store.
+   * @returns Resolves to `1` if a field was added, or `0` if updated.
+   */
+  hSet(key: string, value: HashValue): IPersistorMulti;
+  /**
+   * Retrieves a field from a hash.
+   * @param key - The hash key.
+   * @param field - The field name.
+   * @returns Resolves to the value, or null if the field does not exist.
+   */
+  hGet(key: string, field: string): IPersistorMulti;
+  /**
+   * Retrieves a hash value.
+   * @param key - The hash key.
+   * @returns Resolves to the value, or null if the hash does not exist.
+   */
+  hGetAll(key: string): IPersistorMulti;
+  /**
+   * Pushes values to the left (head) of a list.
+   * @param key - The list key.
+   * @param values - The values to add.
+   * @returns The multi-instance for chaining.
+   */
+  lPush(key: string, values: string | string[]): IPersistorMulti;
+  /**
+   * Pushes values to the right (tail) of a list.
+   * @param key - The list key.
+   * @param values - The values to add.
+   * @returns The multi-instance for chaining.
+   */
+  rPush(key: string, values: string | string[]): IPersistorMulti;
+  /**
+   * Removes and returns the first element from a list.
+   * @param key - The list key.
+   * @returns The multi-instance for chaining.
+   */
+  lPop(key: string): IPersistorMulti;
+  /**
+   * Removes and returns the last element from a list.
+   * @param key - The list key.
+   * @returns The multi-instance for chaining.
+   */
+  rPop(key: string): IPersistorMulti;
+  /**
+   * Retrieves a range of elements from a list.
+   * @param key - The list key.
+   * @param start - The start index.
+   * @param stop - The stop index (inclusive).
+   * @returns The multi-instance for chaining.
+   */
+  lRange(key: string, start: number, stop: number): IPersistorMulti;
+  /**
+   * Adds members to a set.
+   * @param key - The set key.
+   * @param values - The values to add.
+   * @returns The multi-instance for chaining.
+   */
+  sAdd(key: string, values: string | string[]): IPersistorMulti;
+  /**
+   * Removes members from a set.
+   * @param key - The set key.
+   * @param values - The values to remove.
+   * @returns The multi-instance for chaining.
+   */
+  sRem(key: string, values: string | string[]): IPersistorMulti;
+  /**
+   * Retrieves all members of a set.
+   * @param key - The set key.
+   * @returns The multi-instance for chaining.
+   */
+  sMembers(key: string): IPersistorMulti;
+  /**
+   * Adds members to a sorted set with scores.
+   * @param key - The sorted set key.
+   * @param members - An array of objects with `score` and `value`.
+   * @returns The multi-instance for chaining.
+   */
+  zAdd(key: string, members: {
+    score: number;
+    value: string;
+  }[]): IPersistorMulti;
+  /**
+   * Retrieves a range of members from a sorted set.
+   * @param key - The sorted set key.
+   * @param start - The start index.
+   * @param stop - The stop index (inclusive).
+   * @returns The multi-instance for chaining.
+   */
+  zRange(key: string, start: number, stop: number): IPersistorMulti;
+  /**
+   * Removes members from a sorted set.
+   * @param key - The sorted set key.
+   * @param members - The members to remove.
+   * @returns The multi-instance for chaining.
+   */
+  zRem(key: string, members: string | string[]): IPersistorMulti;
+  /**
+   * Executes all queued commands and returns their results.
+   * @returns A promise resolving to an array of results for each command.
+   * The result type can be `string | number | boolean | null`, depending on the command.
+   */
+  exec(): Promise<MultiExecReturnTypes[] | unknown>;
+}
+//#endregion
+//#region src/cache.d.ts
+/**
+ * Creates a cache instance using a given persistor.
+ * @param {IPersistor} persistor - The underlying storage for caching.
+ * @param {string?} prefix - An optional prefix that will be prepended to the key, formatted as `prefix:key`.
+ * @returns {Cache} A cache instance.
+ */
+declare const createCache: (persistor: IPersistor, prefix?: string) => Cache;
+//#endregion
+//#region src/inMemoryPersistor.d.ts
+/**
+ * An in-memory key-value store with Redis-like behavior.
+ * Supports basic operations like `set`, `get`, `del`, `expire`, `ttl`, and `flushAll`.
+ * Implements expiration using `setTimeout` for automatic key deletion.
+ */
+declare class InMemoryPersistor implements IPersistor {
+  /**
+   * Internal key-value store for caching string values.
+   * @private
+   */
+  private readonly store;
+  /**
+   * Tracks active timeouts for expiring keys.
+   * Each key maps to a `setTimeout` reference that deletes the key when triggered.
+   * @private
+   */
+  private readonly expirations;
+  /**
+   * Stores absolute expiration timestamps (in milliseconds since epoch) for each key.
+   * Used to compute remaining TTL.
+   * @private
+   */
+  private readonly expiryTimestamps;
+  /**
+   * Creates a new instance of `InMemoryPersistor`.
+   * Initializes an empty store, expiration map, and TTL tracker.
+   */
+  constructor();
+  connect(): Promise<this>;
+  get isReady(): boolean;
+  get isOpen(): boolean;
+  once(): this;
+  /**
+   * Stores a key-value pair with optional expiration settings.
+   * If an expiration is provided (`EX`, `PX`, `EXAT`, `PXAT`), the key is automatically removed when TTL expires.
+   *
+   * @param {string} key - The key to store.
+   * @param {string} value - The string value to associate with the key.
+   * @param {SetOptions} [options] - Optional Redis-style expiration settings.
+   * @returns {Promise<'OK' | null>} Resolves to `'OK'` on success, or `null` if a conditional set (`NX`) fails.
+   */
+  set(key: string, value: HashTypes, options?: SetOptions): Promise<'OK' | null>;
+  /**
+   * Stores a key-value pair with an expiration time in seconds.
+   * If the key already exists, it will be overwritten.
+   *
+   * @param key - The storage key.
+   * @param seconds - Expiration time in seconds.
+   * @param value - The string value to store.
+   * @returns Resolves to `'OK'` on success.
+   */
+  setEx(key: string, seconds: number, value: string): Promise<string | null>;
+  /**
+   * Stores a key-value pair with an expiration time in milliseconds.
+   * If the key already exists, it will be overwritten.
+   *
+   * @param key - The storage key.
+   * @param milliseconds - Expiration time in milliseconds.
+   * @param value - The string value to store.
+   * @returns Resolves to `'OK'` on success.
+   */
+  pSetEx(key: string, milliseconds: number, value: string): Promise<string | null>;
+  /**
+   * Stores a key-value pair **only if the key does not already exist**.
+   * If the key exists, the operation fails and returns `false`.
+   *
+   * @param key - The storage key.
+   * @param value - The string value to store.
+   * @returns Resolves to `true` if the key was set, or `false` if the key already exists.
+   */
+  setNX(key: string, value: string): Promise<number>;
+  /**
+   * Retrieves the value associated with a key.
+   *
+   * @param {string} key - The key to retrieve.
+   * @returns {Promise<string | null>} Resolves to the string value, or `null` if the key does not exist.
+   */
+  get(key: string): Promise<string | null>;
+  /**
+   * Deletes a key from the store.
+   * If the key exists, it is removed along with any associated expiration.
+   *
+   * @param {string} key - The key to delete.
+   * @returns {Promise<number>} Resolves to `1` if the key was deleted, or `0` if the key did not exist.
+   */
+  del(key: string): Promise<number>;
+  /**
+   * Sets a time-to-live (TTL) in seconds for a key.
+   * If the key exists, it will be deleted after the specified duration.
+   *
+   * @param {string} key - The key to set an expiration on.
+   * @param {number} seconds - The TTL in seconds.
+   * @returns {Promise<number>} Resolves to `1` if the TTL was set, or `0` if the key does not exist.
+   */
+  expire(key: string, seconds: number): Promise<number>;
+  /**
+   * Retrieves the remaining time-to-live (TTL) of a key in seconds.
+   *
+   * @param {string} key - The key to check.
+   * @returns {Promise<number>} Resolves to:
+   *   - Remaining TTL in **seconds** if the key exists and has an expiration.
+   *   - `-1` if the key exists but has no expiration.
+   *   - `-2` if the key does not exist.
+   */
+  ttl(key: string): Promise<number>;
+  /**
+   * Checks if one or more keys exist in the store.
+   *
+   * @param {string | string[]} keys - A single key or an array of keys to check.
+   * @returns {Promise<number>} Resolves to the number of keys that exist.
+   */
+  exists(keys: string | string[]): Promise<number>;
+  /**
+   * Increments a numeric value stored at a key by 1.
+   * If the key does not exist, it is set to `1`.
+   *
+   * @param {string} key - The key to increment.
+   * @returns {Promise<number>} Resolves to the new value after increment.
+   */
+  incr(key: string): Promise<number>;
+  /**
+   * Increments a numeric value stored at a key by a specified amount.
+   * If the key does not exist, it is set to the increment value.
+   *
+   * @param {string} key - The key to increment.
+   * @param {number} increment - The amount to increase by.
+   * @returns {Promise<number>} Resolves to the new value after increment.
+   */
+  incrBy(key: string, increment: number): Promise<number>;
+  /**
+   * Decrements a numeric value stored at a key by 1.
+   * If the key does not exist, it is set to `-1`.
+   *
+   * @param {string} key - The key to decrement.
+   * @returns {Promise<number>} Resolves to the new value after decrement.
+   */
+  decr(key: string): Promise<number>;
+  /**
+   * Decrements a numeric value stored at a key by a specified amount.
+   * If the key does not exist, it is set to the negative decrement value.
+   *
+   * @param {string} key - The key to decrement.
+   * @param {number} decrement - The amount to decrease by.
+   * @returns {Promise<number>} Resolves to the new value after decrement.
+   */
+  decrBy(key: string, decrement: number): Promise<number>;
+  /**
+   * Sets a field in a hash.
+   * If the field already exists, its value is updated.
+   *
+   * @param key - The hash key.
+   * @param field - The field name.
+   * @param value - The value to store.
+   * @returns Resolves to `1` if a new field was added, `0` if an existing field was updated.
+   */
+  hSet(key: string, fieldOrValue: string | HashValue, value?: HashTypes): Promise<number>;
+  /**
+   * Retrieves a field from a hash.
+   *
+   * @param key - The hash key.
+   * @param field - The field name to retrieve.
+   * @returns Resolves to the field value, or `null` if the field does not exist.
+   */
+  hGet(key: string, field: string): Promise<string | null>;
+  /**
+   * Retrieves a hash value.
+   * @param key - The hash key.
+   * @returns Resolves to the value, or null if the hash does not exist.
+   */
+  hGetAll(key: string): Promise<{
+    [x: string]: string;
+  }>;
+  /**
+   * Pushes elements to the left (head) of a list.
+   *
+   * @param key - The list key.
+   * @param values - One or more values to add.
+   * @returns Resolves to the length of the list after the operation.
+   */
+  lPush(key: string, values: string | string[]): Promise<number>;
+  /**
+   * Pushes elements to the right (tail) of a list.
+   *
+   * @param key - The list key.
+   * @param values - One or more values to add.
+   * @returns Resolves to the length of the list after the operation.
+   */
+  rPush(key: string, values: string | string[]): Promise<number>;
+  /**
+   * Removes and returns the first element from a list.
+   *
+   * @param key - The list key.
+   * @returns Resolves to the removed element, or `null` if the list is empty.
+   */
+  lPop(key: string): Promise<string | null>;
+  /**
+   * Removes and returns the last element from a list.
+   *
+   * @param key - The list key.
+   * @returns Resolves to the removed element, or `null` if the list is empty.
+   */
+  rPop(key: string): Promise<string | null>;
+  /**
+   * Retrieves a range of elements from a list.
+   *
+   * @param key - The list key.
+   * @param start - The starting index.
+   * @param stop - The stopping index.
+   * @returns Resolves to an array containing the requested range.
+   */
+  lRange(key: string, start: number, stop: number): Promise<string[]>;
+  /**
+   * Adds elements to a set.
+   *
+   * @param key - The set key.
+   * @param values - One or more values to add.
+   * @returns Resolves to the number of new elements added.
+   */
+  sAdd(key: string, values: string | string[]): Promise<number>;
+  /**
+   * Removes elements from a set.
+   *
+   * @param key - The set key.
+   * @param values - One or more values to remove.
+   * @returns Resolves to the number of elements removed.
+   */
+  sRem(key: string, values: string | string[]): Promise<number>;
+  /**
+   * Retrieves all elements from a set.
+   *
+   * @param key - The set key.
+   * @returns Resolves to an array of all set members.
+   */
+  sMembers(key: string): Promise<string[]>;
+  /**
+   * Adds members to a sorted set with scores.
+   *
+   * @param key - The sorted set key.
+   * @param members - An array of objects containing `{ score, value }`.
+   * @returns Resolves to the number of new elements added.
+   */
+  zAdd(key: string, members: {
+    score: number;
+    value: string;
+  }[]): Promise<number>;
+  /**
+   * Retrieves a range of elements from a sorted set.
+   *
+   * @param key - The sorted set key.
+   * @param start - The starting index.
+   * @param stop - The stopping index.
+   * @returns Resolves to an array of sorted set values in the range.
+   */
+  zRange(key: string, start: number, stop: number): Promise<string[]>;
+  /**
+   * Removes elements from a sorted set.
+   *
+   * @param key - The sorted set key.
+   * @param members - One or more values to remove.
+   * @returns Resolves to the number of elements removed.
+   */
+  zRem(key: string, members: string | string[]): Promise<number>;
+  /**
+   * Removes all keys from the store and clears all active expirations.
+   *
+   * @returns {Promise<'OK'>} Resolves to `'OK'` after all data is cleared.
+   */
+  flushAll(): Promise<'OK'>;
+  /**
+   * Creates a new multi-command batch instance.
+   * Commands queued in this batch will be executed together when `exec()` is called.
+   *
+   * @returns A new `IPersistorMulti` instance for batching commands.
+   */
+  multi(): IPersistorMulti;
+  /**
+   * Sets an expiration timeout for a key.
+   * Cancels any existing expiration before setting a new one.
+   *
+   * @private
+   * @param {string} key - The key to expire.
+   * @param {number} ttlMs - Time-to-live in milliseconds.
+   */
+  private setExpiration;
+  /**
+   * Cancels an active expiration timeout for a key and removes its TTL record.
+   *
+   * @private
+   * @param {string} key - The key whose expiration should be cleared.
+   */
+  private clearExpiration;
+}
+//#endregion
+//#region src/persistor.d.ts
+type GetType<T> = {
+  value: T;
+  ttl?: number;
+  timestamp: number;
+};
+type SetParams<T> = {
+  value: T;
+  timestamp?: number;
+  ttl?: number;
+};
+type PersistorConstructorType = {
+  redis?: RedisClientOptions$1;
+  redisClient?: ReturnType<typeof createClient>;
+  clientId?: UUID;
+  onError?: (error: string) => void;
+  onSuccess?: () => void;
+};
+declare class Persistor {
+  client: ReturnType<typeof createClient> | null;
+  private readonly clientId?;
+  private readonly onError;
+  private readonly onSuccess;
+  private readonly logger;
+  private readonly redis?;
+  constructor({
+    redis,
+    redisClient,
+    clientId,
+    onSuccess,
+    onError
+  }: PersistorConstructorType);
+  startConnection(): Promise<void>;
+  size(): Promise<number>;
+  getClientId(): UUID | undefined;
+  getIsClientConnected(): boolean;
+  private createOptions;
+  /**
+   * Set a value in the cache.
+   * @param key Cache key.
+   * @param object.value Value to set in the cache.
+   * @param object.ttl Time to live in seconds.
+   * @param object.timestamp Timestamp
+   */
+  set<T>(key: string, {
+    value,
+    timestamp,
+    ttl
+  }: SetParams<T>): Promise<void>;
+  /**
+   * Get a value from the cache.
+   * @param key Cache key.
+   * @returns GetType<T> value
+   */
+  get<T>(key: string): Promise<GetType<T> | null>;
+  /**
+   * Delete a value from the cache.
+   * @param key Cache key
+   */
+  delete(key: string): Promise<void>;
+}
+//#endregion
+//#region src/promiseCache.d.ts
+type PromiseCacheOptions = {
+  ttlInSeconds?: number;
+  caseSensitive?: boolean;
+  redis?: RedisClientOptions;
+  fallbackToFunction?: boolean;
+  onError?: (error: string) => void;
+  onSuccess?: () => void;
+};
+declare class PromiseCache<U> {
+  persistor: Persistor;
+  private readonly clientId;
+  private readonly caseSensitive;
+  private readonly fallbackToFunction;
+  private readonly ttl?;
+  private readonly logger;
+  /**
+   * Initialize a new PromiseCache.
+   * @param ttlInSeconds Default cache TTL.
+   * @param caseSensitive Set to true if you want to differentiate between keys with different casing.
+   */
+  constructor({
+    ttlInSeconds,
+    caseSensitive,
+    redis,
+    fallbackToFunction,
+    onSuccess,
+    onError
+  }: PromiseCacheOptions);
+  /**
+   * Cache size.
+   * @returns The number of entries in the cache.
+   */
+  size(): Promise<number>;
+  /**
+   * Override a value in the cache.
+   * @param key Cache key.
+   * @param value Cache value.
+   * @param ttlInSeconds Time to live in seconds.
+   */
+  override<U>(key: string, value: U, ttlInSeconds?: number): Promise<void>;
+  /**
+   * Get a value from the cache.
+   * @param key Cache key.
+   */
+  find<U>(key: string): Promise<U | null>;
+  /**
+   * A simple promise cache wrapper.
+   * @param key Cache key.
+   * @param delegate The function to execute if the key is not in the cache.
+   * @param ttlInSeconds Time to live in seconds.
+   * @param ttlKeyInSeconds The key in the response object that contains the TTL.
+   * @returns The result of the delegate function.
+   */
+  wrap(key: string, delegate: () => Promise<U>, ttlInSeconds?: number, ttlKeyInSeconds?: string): Promise<U>;
+}
+declare namespace serializer_d_exports {
+  export { deserialize, serialize };
+}
+declare const serialize: <T>(data: T) => string;
+declare const deserialize: <T>(serialized: string | null) => T | null;
+declare namespace time_d_exports {
+  export { DAY, HOUR, MINUTE, SECOND, WEEK, add, days, hours, minutes, seconds, sub, today, tomorrow, weeks };
+}
+declare const SECOND = 1000;
+declare const MINUTE: number;
+declare const HOUR: number;
+declare const DAY: number;
+declare const WEEK: number;
+declare const seconds: (num: number) => number;
+declare const minutes: (num: number) => number;
+declare const hours: (num: number) => number;
+declare const days: (num: number) => number;
+declare const weeks: (num: number) => number;
+declare const today: (hours?: number, minutes?: number, seconds?: number) => Date;
+declare const tomorrow: (hours?: number, minutes?: number, seconds?: number) => Date;
+//#endregion
+export { type Cache, type CachingOptions, type IPersistor, InMemoryPersistor, Persistor, PersistorConstructorType, PromiseCache, PromiseCacheOptions, type RedisClientOptions, createCache, serializer_d_exports as serializer, time_d_exports as time };
+//# sourceMappingURL=index.d.mts.map