@sebspark/promise-cache 3.3.3 → 3.4.0

package/README.md

@@ -2,6 +2,8 @@
 
 Simple caching wrapper
 
+# PromiseCache implementation
+
 ## **Features**
 
 - **PromiseCache**: Simple caching wraper for promises
@@ -18,14 +20,14 @@ yarn install @sebspark/promise-cache
 
 ### **PromiseCache Class**
 
-| Params        | Type     | Default |Description                                  |
-|---------------|----------|---------|---------------------------------------------|
-| redis         | RedisClientOptions   |    undefined     |Redis instance url, skip if use local memory |
-| ttlInSeconds  | number   |   undefined      |Persist time in Seconds                      |
-| caseSensituve | boolean  |   false    |Retrieving cache with case sensitive         |
-| onSuccess     | function |    undefined     |Callback function if connection is success   |
-| onError       | function |    undefined     |Callback function if there is an error       |
-| logger        | winston Logger |    undefined     |Logger                                 |
+| Params        | Type                | Default   | Description                                   |
+|---------------|---------------------|-----------|-----------------------------------------------|
+| redis         | RedisClientOptions  | undefined | Redis instance url, skip if use local memory  |
+| ttlInSeconds  | number              | undefined | Persist time in Seconds                       |
+| caseSensituve | boolean             | false     | Retrieving cache with case sensitive          |
+| onSuccess     | function            | undefined | Callback function if connection is success    |
+| onError       | function            | undefined | Callback function if there is an error        |
+| logger        | winston Logger      | undefined | Logger                                        |
 
 ```typescript
 import { PromiseCache } from '@sebspark/promise-cache'
@@ -161,3 +163,119 @@ expect(cached).toBe({
 await store.delete('MyKey')
 expect(await store.get('MyKey').toBe(null)
 ```
+
+# Cache implementation
+
+The basic functionality of this new implementation is:
+
+1. You create a persistor to store your cached data. This can be the built in `InMemoryPersistor` or a `Redis` client
+2. You create a cache by calling `createCache(persistor, 'optional-prefix')`
+3. You call the cache's wrap function to wrap your original function(s)
+4. You call the wrapped function(s) instead of the originals
+
+** Why the change? **
+
+When trying to add support for caching _to_ a specified time in addition to _for_ a specified time, it tuyrned out to be hard given the original implementation. Changing the implementation proved hard without breaking changes. So a new implementation is is.
+
+## How to use it
+
+```typescript
+import { createClient } from 'redis'
+import { createCache } from '@sebspark/promise-cache'
+import { myFunction } from './some_function'
+
+const run = async () => {
+  // Create your persistor
+  const persistor = createClient({ url: 'redis' })
+  await persistor.connect() // This is not handled by the cache
+
+  // Create your cache and give it a prefix
+  const cache = createCache(persistor, 'my-prefix')
+  
+  // wrap your function
+  const myCachedFunction = cache.wrap(myFunction, {
+    key: 'my-function', // cached data will be stored with the key 'my-prefix:my-function'
+    expiry: 100, // ttl will be 100 ms
+  })
+
+  // call the wrapped function
+  const response = await myCachedFunction() // the wrapped function will have the same signature as the original
+}
+
+run()
+```
+
+### Keys
+
+Keys can be constructed in two ways: as a fixed string or as a function that generates a string. The generator will accept the arguments of the wrapped function.
+
+```typescript
+const cache = createCache(persistor, 'api')
+
+const getById = async (id: string): Promise<Data> => {
+  // Something gets called
+}
+
+const cachedGetById = cache.wrap(myApiCall, {
+  key: (id) => `getById:${id}`
+})
+
+const result = await cachedGetById('foo')
+
+// key will be 'api:getById:foo'
+```
+
+### Expiry
+
+Expiration can be set as either a number (number of milliseconds from now) or a Date (exact expiry time). It can be set either as a value (`number | Date`) or as a function that generates a value (`number | Date`). The generator will accept the arguments _and_ the response of the wrapped function.
+
+```typescript
+const cache = createCache(persistor, 'api')
+
+type Data = {
+  value: number
+  expires: string // ISO6501 date time string
+}
+
+const getById = async (id: string): Promise<Data> => {
+  // Something gets called
+}
+
+const cachedGetById = cache.wrap(myApiCall, {
+  key: (id) => `getById:${id}`,
+  expires: ([id], data) => new Date(data.expires),
+})
+
+const result = await cachedGetById('foo')
+```
+
+There are also helpers for setting time or manipulating dates
+
+```typescript
+import { createCache, time } from '@sebspark/promise-cache'
+
+const cache = createCache(persistor, 'api')
+
+type Data = {
+  value: number
+  lastUpdated: string // ISO6501 date time string. Data is updated every 30 minutes.
+}
+
+const getById = async (id: string): Promise<Data> => {
+  // Something gets called
+}
+
+// Computed from response
+const cachedGetById = cache.wrap(myApiCall, {
+  key: (id) => `getById:${id}`,
+  expires: ([id], data) => time.add(new Date(data.lastUpdated), { minutes: 30 })
+})
+
+// Fixed at 20 seconds
+const cachedGetById = cache.wrap(myApiCall, {
+  key: (id) => `getById:${id}`,
+  expires: time.seconds(100),
+})
+```
+
+If expiry is not set or yields an unusable value, it will default to 1 sec.

package/dist/index.d.mts

@@ -1,7 +1,8 @@
-import { RedisClientOptions, createClient } from 'redis';
+import { RedisClientOptions, createClient, SetOptions } from 'redis';
 export { RedisClientOptions } from 'redis';
 import { Logger } from 'winston';
 import { UUID } from 'node:crypto';
+import { add } from 'date-fns';
 
 type GetType<T> = {
     value: T;
@@ -101,4 +102,222 @@ declare class PromiseCache<U> {
     wrap(key: string, delegate: () => Promise<U>, ttlInSeconds?: number, ttlKeyInSeconds?: string): Promise<U>;
 }
 
-export { Persistor, type PersistorConstructorType, PromiseCache, type PromiseCacheOptions };
+/**
+ * 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>;
+};
+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.
+     */
+    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.
+     */
+    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).
+     */
+    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.
+     */
+    expire: (key: string, seconds: number) => Promise<boolean>;
+    /**
+     * Gets the remaining TTL of a key in seconds.
+     * @param key - The storage key.
+     * @returns Remaining TTL in seconds, `-1` if no TTL is set, or `-2` if key does not exist.
+     */
+    ttl: (key: string) => Promise<number>;
+    /**
+     * Clears all keys in Redis or Memory.
+     * @returns Resolves to `"OK"` when complete.
+     */
+    flushAll: () => Promise<string>;
+}
+
+/**
+ * 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;
+
+/**
+ * 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();
+    /**
+     * 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: string, options?: SetOptions): Promise<'OK' | null>;
+    /**
+     * 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<boolean>;
+    /**
+     * 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>;
+    /**
+     * 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'>;
+    /**
+     * 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;
+}
+
+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 time_DAY: typeof DAY;
+declare const time_HOUR: typeof HOUR;
+declare const time_MINUTE: typeof MINUTE;
+declare const time_SECOND: typeof SECOND;
+declare const time_WEEK: typeof WEEK;
+declare const time_add: typeof add;
+declare const time_days: typeof days;
+declare const time_hours: typeof hours;
+declare const time_minutes: typeof minutes;
+declare const time_seconds: typeof seconds;
+declare const time_weeks: typeof weeks;
+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_weeks as weeks };
+}
+
+export { type Cache, type CachingOptions, type IPersistor, InMemoryPersistor, Persistor, type PersistorConstructorType, PromiseCache, type PromiseCacheOptions, createCache, time };

package/dist/index.d.ts

@@ -1,7 +1,8 @@
-import { RedisClientOptions, createClient } from 'redis';
+import { RedisClientOptions, createClient, SetOptions } from 'redis';
 export { RedisClientOptions } from 'redis';
 import { Logger } from 'winston';
 import { UUID } from 'node:crypto';
+import { add } from 'date-fns';
 
 type GetType<T> = {
     value: T;
@@ -101,4 +102,222 @@ declare class PromiseCache<U> {
     wrap(key: string, delegate: () => Promise<U>, ttlInSeconds?: number, ttlKeyInSeconds?: string): Promise<U>;
 }
 
-export { Persistor, type PersistorConstructorType, PromiseCache, type PromiseCacheOptions };
+/**
+ * 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>;
+};
+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.
+     */
+    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.
+     */
+    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).
+     */
+    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.
+     */
+    expire: (key: string, seconds: number) => Promise<boolean>;
+    /**
+     * Gets the remaining TTL of a key in seconds.
+     * @param key - The storage key.
+     * @returns Remaining TTL in seconds, `-1` if no TTL is set, or `-2` if key does not exist.
+     */
+    ttl: (key: string) => Promise<number>;
+    /**
+     * Clears all keys in Redis or Memory.
+     * @returns Resolves to `"OK"` when complete.
+     */
+    flushAll: () => Promise<string>;
+}
+
+/**
+ * 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;
+
+/**
+ * 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();
+    /**
+     * 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: string, options?: SetOptions): Promise<'OK' | null>;
+    /**
+     * 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<boolean>;
+    /**
+     * 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>;
+    /**
+     * 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'>;
+    /**
+     * 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;
+}
+
+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 time_DAY: typeof DAY;
+declare const time_HOUR: typeof HOUR;
+declare const time_MINUTE: typeof MINUTE;
+declare const time_SECOND: typeof SECOND;
+declare const time_WEEK: typeof WEEK;
+declare const time_add: typeof add;
+declare const time_days: typeof days;
+declare const time_hours: typeof hours;
+declare const time_minutes: typeof minutes;
+declare const time_seconds: typeof seconds;
+declare const time_weeks: typeof weeks;
+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_weeks as weeks };
+}
+
+export { type Cache, type CachingOptions, type IPersistor, InMemoryPersistor, Persistor, type PersistorConstructorType, PromiseCache, type PromiseCacheOptions, createCache, time };