@sebspark/promise-cache 3.5.0 → 3.7.0

package/dist/index.d.ts

@@ -102,6 +102,9 @@ declare class PromiseCache<U> {
     wrap(key: string, delegate: () => Promise<U>, ttlInSeconds?: number, ttlKeyInSeconds?: string): Promise<U>;
 }
 
+type Client = ReturnType<typeof createClient>;
+type Multi = ReturnType<Client['multi']>;
+type MultiExecReturnTypes = Awaited<ReturnType<Multi['exec']>>[number] | boolean;
 /**
  * Defines the expiration strategy for cached values.
  *
@@ -149,45 +152,406 @@ type Cache = {
      */
     wrap: <A extends unknown[], R>(delegate: (...args: A) => Promise<R>, options: CachingOptions<A, R>) => (...args: A) => Promise<R>;
 };
+/**
+ * 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.
-     * @returns Resolves to `"OK"` if successful.
+     * @param options - Expiration options (TTL, absolute expiration, etc.).
+     * @returns Resolves to `"OK"` if successful, otherwise `null` if the operation fails.
      */
     set: (key: string, value: string, options?: SetOptions) => Promise<string | null>;
     /**
      * Retrieves a value from Redis or Memory.
      * @param key - The storage key.
-     * @returns Resolves to the stored value or `null` if not found.
+     * @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 not found).
+     * @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 successful, false if key does not exist.
+     * @returns Resolves to `true` if the expiration was successfully set, `false` if the key does not exist.
      */
     expire: (key: string, seconds: number) => Promise<boolean>;
     /**
-     * Gets the remaining TTL of a key in seconds.
+     * Gets the remaining TTL (time-to-live) of a key.
      * @param key - The storage key.
-     * @returns Remaining TTL in seconds, `-1` if no TTL is set, or `-2` if key does not exist.
+     * @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 in Redis or Memory.
-     * @returns Resolves to `"OK"` when complete.
+     * 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<boolean>;
+    /**
+     * 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: string) => Promise<number>;
+    /**
+     * Retrieves a field from a hash.
+     * @param key - The hash key.
+     * @param field - The field name.
+     * @returns Resolves to the value, or `undefined` if the field does not exist.
+     */
+    hGet: (key: string, field: string) => Promise<string | undefined>;
+    /**
+     * 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>;
+}
+/**
+ * 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: string, 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: string) => IPersistorMulti;
+    /**
+     * Retrieves a field from a hash.
+     * @param key - The hash key.
+     * @param field - The field name.
+     * @returns The multi-instance for chaining.
+     */
+    hGet: (key: string, field: 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[]>;
 }
 
 /**
@@ -236,6 +600,35 @@ declare class InMemoryPersistor implements IPersistor {
      * @returns {Promise<'OK' | null>} Resolves to `'OK'` on success, or `null` if a conditional set (`NX`) fails.
      */
     set(key: string, value: string, 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<boolean>;
     /**
      * Retrieves the value associated with a key.
      *
@@ -270,12 +663,168 @@ declare class InMemoryPersistor implements IPersistor {
      *   - `-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, field: string, value: string): 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 `undefined` if the field does not exist.
+     */
+    hGet(key: string, field: string): Promise<string | undefined>;
+    /**
+     * 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.
@@ -325,4 +874,13 @@ declare namespace time {
   export { time_DAY as DAY, time_HOUR as HOUR, time_MINUTE as MINUTE, time_SECOND as SECOND, time_WEEK as WEEK, time_add as add, time_days as days, time_hours as hours, time_minutes as minutes, time_seconds as seconds, time_sub as sub, time_today as today, time_tomorrow as tomorrow, time_weeks as weeks };
 }
 
-export { type Cache, type CachingOptions, type IPersistor, InMemoryPersistor, Persistor, type PersistorConstructorType, PromiseCache, type PromiseCacheOptions, createCache, time };
+declare const serialize: <T>(data: T) => string;
+declare const deserialize: <T>(serialized: string) => T;
+
+declare const serializer_deserialize: typeof deserialize;
+declare const serializer_serialize: typeof serialize;
+declare namespace serializer {
+  export { serializer_deserialize as deserialize, serializer_serialize as serialize };
+}
+
+export { type Cache, type CachingOptions, type IPersistor, InMemoryPersistor, Persistor, type PersistorConstructorType, PromiseCache, type PromiseCacheOptions, createCache, serializer, time };