@forklaunch/core 0.6.6 → 0.7.0

package/lib/src/cache/index.d.ts

@@ -1,8 +1,19 @@
 import { RedisClientOptions } from 'redis';
-import { O as OpenTelemetryCollector, M as MetricsDefinition } from '../../openTelemetryCollector-CWrfzmmW.js';
+import { O as OpenTelemetryCollector, M as MetricsDefinition, T as TelemetryOptions } from '../../openTelemetryCollector-CmZ3T_2T.js';
 import '@opentelemetry/api';
 import 'pino';
 
+/**
+ * Creates a function that generates cache keys with a given prefix.
+ *
+ * @param {string} cacheKeyPrefix - The prefix to use for all cache keys
+ * @returns {Function} A function that takes an ID and returns a formatted cache key
+ * @example
+ * const createUserCacheKey = createCacheKey('user');
+ * const key = createUserCacheKey('123'); // Returns 'user:123'
+ */
+declare const createCacheKey: (cacheKeyPrefix: string) => (id: string) => string;
+
 /**
  * Type representing a TTL (Time-To-Live) cache record.
  *
@@ -28,6 +39,28 @@ interface TtlCache {
      * @returns {Promise<void>} - A promise that resolves when the record is put into the cache.
      */
     putRecord<T>(cacheRecord: TtlCacheRecord<T>): Promise<void>;
+    /**
+     * Puts a batch of records into the cache.
+     *
+     * @param {TtlCacheRecord<T>[]} cacheRecords - The cache records to put into the cache.
+     * @returns {Promise<void>} - A promise that resolves when the records are put into the cache.
+     */
+    putBatchRecords<T>(cacheRecords: TtlCacheRecord<T>[]): Promise<void>;
+    /**
+     * Enqueues a record into the cache.
+     *
+     * @param {string} cacheRecordKey - The key of the cache record to enqueue.
+     * @returns {Promise<void>} - A promise that resolves when the record is enqueued into the cache.
+     */
+    enqueueRecord<T>(queueName: string, cacheRecord: T): Promise<void>;
+    /**
+     *
+     * Enqueues a batch of records into the cache.
+     *
+     * @param {string[]} cacheRecordKeys - The keys of the cache records to enqueue.
+     * @returns {Promise<void>} - A promise that resolves when the records are enqueued into the cache.
+     */
+    enqueueBatchRecords<T>(queueName: string, cacheRecords: T[]): Promise<void>;
     /**
      * Deletes a record from the cache.
      *
@@ -35,6 +68,27 @@ interface TtlCache {
      * @returns {Promise<void>} - A promise that resolves when the record is deleted from the cache.
      */
     deleteRecord(cacheRecordKey: string): Promise<void>;
+    /**
+     * Deletes a batch of records from the cache.
+     *
+     * @param {string[]} cacheRecordKeys - The keys of the cache records to delete.
+     * @returns {Promise<void>} - A promise that resolves when the records are deleted from the cache.
+     */
+    deleteBatchRecords(cacheRecordKeys: string[]): Promise<void>;
+    /**
+     * Dequeues a record from the cache.
+     *
+     * @param {string} cacheRecordKey - The key of the cache record to dequeue.
+     * @returns {Promise<void>} - A promise that resolves when the record is dequeued from the cache.
+     */
+    dequeueRecord<T>(queueName: string): Promise<T>;
+    /**
+     * Dequeues a batch of records from the cache.
+     *
+     * @param {string[]} cacheRecordKeys - The keys of the cache records to dequeue.
+     * @returns {Promise<void>} - A promise that resolves when the records are dequeued from the cache.
+     */
+    dequeueBatchRecords<T>(queueName: string, pageSize: number): Promise<T[]>;
     /**
      * Reads a record from the cache.
      *
@@ -42,6 +96,13 @@ interface TtlCache {
      * @returns {Promise<TtlCacheRecord>} - A promise that resolves with the cache record.
      */
     readRecord<T>(cacheRecordKey: string): Promise<TtlCacheRecord<T>>;
+    /**
+     * Reads a batch of records from the cache.
+     *
+     * @param {string[] | string} cacheRecordKeysOrPrefix - The keys of the cache records to read or a prefix to match.
+     * @returns {Promise<TtlCacheRecord<T>[]>} - A promise that resolves with the cache records.
+     */
+    readBatchRecords<T>(cacheRecordKeysOrPrefix: string[] | string): Promise<TtlCacheRecord<T>[]>;
     /**
      * Peeks at a record in the cache to check if it exists.
      *
@@ -49,6 +110,27 @@ interface TtlCache {
      * @returns {Promise<boolean>} - A promise that resolves with a boolean indicating if the record exists.
      */
     peekRecord(cacheRecordKey: string): Promise<boolean>;
+    /**
+     * Peeks at a batch of records in the cache to check if they exist.
+     *
+     * @param {string[] | string} cacheRecordKeysOrPrefix - The keys of the cache records to peek at or a prefix to match.
+     * @returns {Promise<boolean[]>} - A promise that resolves with an array of booleans indicating if the records exist.
+     */
+    peekBatchRecords(cacheRecordKeysOrPrefix: string[] | string): Promise<boolean[]>;
+    /**
+     * Peeks at a record in the cache to check if it exists.
+     *
+     * @param {string} queueName - The name of the queue to peek at.
+     * @returns {Promise<T>} - A promise that resolves with the record.
+     */
+    peekQueueRecord<T>(queueName: string): Promise<T>;
+    /**
+     * Peeks at a batch of records in the cache to check if they exist.
+     *
+     * @param {string} queueName - The name of the queue to peek at.
+     * @returns {Promise<T[]>} - A promise that resolves with the records.
+     */
+    peekQueueRecords<T>(queueName: string, pageSize: number): Promise<T[]>;
     /**
      * Gets the TTL (Time-To-Live) in milliseconds.
      *
@@ -66,69 +148,173 @@ interface TtlCache {
 
 /**
  * Class representing a Redis-based TTL (Time-To-Live) cache.
- * Implements the TtlCache interface.
+ * Implements the TtlCache interface to provide caching functionality with automatic expiration.
  */
 declare class RedisTtlCache implements TtlCache {
     private ttlMilliseconds;
     private openTelemetryCollector;
     private client;
+    private telemetryOptions;
     /**
      * Creates an instance of RedisTtlCache.
      *
-     * @param {number} ttlMilliseconds - The default TTL in milliseconds.
-     * @param {RedisClientOptions} [hostingOptions] - The Redis client options.
+     * @param {number} ttlMilliseconds - The default Time-To-Live in milliseconds for cache entries
+     * @param {OpenTelemetryCollector<MetricsDefinition>} openTelemetryCollector - Collector for OpenTelemetry metrics
+     * @param {RedisClientOptions} hostingOptions - Configuration options for the Redis client
+     * @param {TelemetryOptions} telemetryOptions - Configuration options for telemetry
+     */
+    constructor(ttlMilliseconds: number, openTelemetryCollector: OpenTelemetryCollector<MetricsDefinition>, hostingOptions: RedisClientOptions, telemetryOptions: TelemetryOptions);
+    /**
+     * Parses a raw Redis reply into the expected type.
+     * Handles null values, arrays, buffers, and JSON strings.
+     *
+     * @template T - The expected type of the parsed value
+     * @param {RedisCommandRawReply} value - The raw value from Redis to parse
+     * @returns {T} The parsed value cast to type T
      */
-    constructor(ttlMilliseconds: number, openTelemetryCollector: OpenTelemetryCollector<MetricsDefinition>, hostingOptions?: RedisClientOptions);
+    private parseValue;
     /**
      * Puts a record into the Redis cache.
      *
-     * @param {TtlCacheRecord} param0 - The cache record to put into the cache.
-     * @returns {Promise<void>} - A promise that resolves when the record is put into the cache.
+     * @template T - The type of value being cached
+     * @param {TtlCacheRecord<T>} param0 - The cache record containing key, value and optional TTL
+     * @param {string} param0.key - The key to store the value under
+     * @param {T} param0.value - The value to cache
+     * @param {number} [param0.ttlMilliseconds] - Optional TTL in milliseconds, defaults to constructor value
+     * @returns {Promise<void>} A promise that resolves when the value is cached
      */
     putRecord<T>({ key, value, ttlMilliseconds }: TtlCacheRecord<T>): Promise<void>;
+    /**
+     * Puts multiple records into the Redis cache in a single transaction.
+     *
+     * @template T - The type of values being cached
+     * @param {TtlCacheRecord<T>[]} cacheRecords - Array of cache records to store
+     * @returns {Promise<void>} A promise that resolves when all values are cached
+     */
+    putBatchRecords<T>(cacheRecords: TtlCacheRecord<T>[]): Promise<void>;
+    /**
+     * Adds a value to the left end of a Redis list.
+     *
+     * @template T - The type of value being enqueued
+     * @param {string} queueName - The name of the Redis list
+     * @param {T} value - The value to add to the list
+     * @returns {Promise<void>} A promise that resolves when the value is enqueued
+     */
+    enqueueRecord<T>(queueName: string, value: T): Promise<void>;
+    /**
+     * Adds multiple values to the left end of a Redis list in a single transaction.
+     *
+     * @template T - The type of values being enqueued
+     * @param {string} queueName - The name of the Redis list
+     * @param {T[]} values - Array of values to add to the list
+     * @returns {Promise<void>} A promise that resolves when all values are enqueued
+     */
+    enqueueBatchRecords<T>(queueName: string, values: T[]): Promise<void>;
     /**
      * Deletes a record from the Redis cache.
      *
-     * @param {string} cacheRecordKey - The key of the cache record to delete.
-     * @returns {Promise<void>} - A promise that resolves when the record is deleted from the cache.
+     * @param {string} cacheRecordKey - The key of the record to delete
+     * @returns {Promise<void>} A promise that resolves when the record is deleted
      */
     deleteRecord(cacheRecordKey: string): Promise<void>;
+    /**
+     * Deletes multiple records from the Redis cache in a single transaction.
+     *
+     * @param {string[]} cacheRecordKeys - Array of keys to delete
+     * @returns {Promise<void>} A promise that resolves when all records are deleted
+     */
+    deleteBatchRecords(cacheRecordKeys: string[]): Promise<void>;
+    /**
+     * Removes and returns the rightmost element from a Redis list.
+     *
+     * @template T - The type of value being dequeued
+     * @param {string} queueName - The name of the Redis list
+     * @returns {Promise<T>} A promise that resolves with the dequeued value
+     * @throws {Error} If the queue is empty
+     */
+    dequeueRecord<T>(queueName: string): Promise<T>;
+    /**
+     * Removes and returns multiple elements from the right end of a Redis list.
+     *
+     * @template T - The type of values being dequeued
+     * @param {string} queueName - The name of the Redis list
+     * @param {number} pageSize - Maximum number of elements to dequeue
+     * @returns {Promise<T[]>} A promise that resolves with an array of dequeued values
+     */
+    dequeueBatchRecords<T>(queueName: string, pageSize: number): Promise<T[]>;
     /**
      * Reads a record from the Redis cache.
      *
-     * @param {string} cacheRecordKey - The key of the cache record to read.
-     * @returns {Promise<TtlCacheRecord>} - A promise that resolves with the cache record.
-     * @throws {Error} - Throws an error if the record is not found.
+     * @template T - The type of value being read
+     * @param {string} cacheRecordKey - The key of the record to read
+     * @returns {Promise<TtlCacheRecord<T>>} A promise that resolves with the cache record
+     * @throws {Error} If the record is not found
      */
     readRecord<T>(cacheRecordKey: string): Promise<TtlCacheRecord<T>>;
     /**
-     * Lists the keys in the Redis cache that match a pattern prefix.
+     * Reads multiple records from the Redis cache.
      *
-     * @param {string} pattern_prefix - The pattern prefix to match.
-     * @returns {Promise<string[]>} - A promise that resolves with an array of keys matching the pattern prefix.
+     * @template T - The type of values being read
+     * @param {string[] | string} cacheRecordKeysOrPrefix - Array of keys to read, or a prefix pattern
+     * @returns {Promise<TtlCacheRecord<T>[]>} A promise that resolves with an array of cache records
+     */
+    readBatchRecords<T>(cacheRecordKeysOrPrefix: string[] | string): Promise<TtlCacheRecord<T>[]>;
+    /**
+     * Lists all keys in the Redis cache that match a pattern prefix.
+     *
+     * @param {string} pattern_prefix - The prefix pattern to match keys against
+     * @returns {Promise<string[]>} A promise that resolves with an array of matching keys
      */
     listKeys(pattern_prefix: string): Promise<string[]>;
     /**
-     * Peeks at a record in the Redis cache to check if it exists.
+     * Checks if a record exists in the Redis cache.
      *
-     * @param {string} cacheRecordKey - The key of the cache record to peek at.
-     * @returns {Promise<boolean>} - A promise that resolves with a boolean indicating if the record exists.
+     * @param {string} cacheRecordKey - The key to check
+     * @returns {Promise<boolean>} A promise that resolves with true if the record exists, false otherwise
      */
     peekRecord(cacheRecordKey: string): Promise<boolean>;
     /**
-     * Disconnects the Redis client.
+     * Checks if multiple records exist in the Redis cache.
      *
-     * @returns {Promise<void>} - A promise that resolves when the client is disconnected.
+     * @param {string[] | string} cacheRecordKeysOrPrefix - Array of keys to check, or a prefix pattern
+     * @returns {Promise<boolean[]>} A promise that resolves with an array of existence booleans
+     */
+    peekBatchRecords(cacheRecordKeysOrPrefix: string[] | string): Promise<boolean[]>;
+    /**
+     * Peeks at a record in the Redis cache.
+     *
+     * @template T - The type of value being peeked at
+     * @param {string} queueName - The name of the Redis queue
+     * @returns {Promise<T>} A promise that resolves with the peeked value
+     */
+    peekQueueRecord<T>(queueName: string): Promise<T>;
+    /**
+     * Peeks at multiple records in the Redis cache.
+     *
+     * @template T - The type of values being peeked at
+     * @param {string} queueName - The name of the Redis queue
+     * @param {number} pageSize - The number of records to peek at
+     * @returns {Promise<T[]>} A promise that resolves with an array of peeked values
+     */
+    peekQueueRecords<T>(queueName: string, pageSize: number): Promise<T[]>;
+    /**
+     * Gracefully disconnects from the Redis server.
+     *
+     * @returns {Promise<void>} A promise that resolves when the connection is closed
      */
     disconnect(): Promise<void>;
     /**
-     * Gets the default TTL (Time-To-Live) in milliseconds.
+     * Gets the default Time-To-Live value in milliseconds.
      *
-     * @returns {number} - The TTL in milliseconds.
+     * @returns {number} The default TTL in milliseconds
      */
     getTtlMilliseconds(): number;
+    /**
+     * Gets the underlying Redis client instance.
+     *
+     * @returns {typeof this.client} The Redis client instance
+     */
+    getClient(): typeof this.client;
 }
 
-declare const createCacheKey: (cacheKeyPrefix: string) => (id: string) => string;
-
 export { RedisTtlCache, type TtlCache, type TtlCacheRecord, createCacheKey };