@ardrive/ardrive-promise-cache
@ardrive/ardrive-promise-cache
is a caching library designed to cache promises, enabling faster subsequent retrievals of data. It includes two types of caching implementations:
- PromiseCache - a simple cache that stores promises in memory
- ReadThroughPromiseCache - a wrapper of
PromiseCache
that allows providing an async readThroughFunction
that is called when the cache does contain the requested key
Installation
You can install the library using npm or yarn:
npm i @ardrive/ardrive-promise-cache
yarn add @ardrive/ardrive-promise-cache
Usage
PromiseCache
Example
import { PromiseCache, CacheParams } from '@ardrive/ardrive-promise-cache';
const params: CacheParams = {
cacheCapacity: 100,
cacheTTL: 60_000,
};
const cache = new PromiseCache<string, number>(params);
const promise1 = new Promise<number>((resolve) => resolve(42));
cache.put('answer', promise1);
await cache.get('answer');
const promise2 = new Promise<number>((resolve) => resolve(100));
cache.put('answer', promise2);
await cache.get('answer');
cache.remove('answer');
await cache.get('answer');
cache.clear();
const size = cache.size();
API
constructor({ cacheCapacity, cacheTTL }: CacheParams)
Creates a new PromiseCache
instance with the specified capacity and time-to-live (TTL) for cached items.
put(key: K, value: Promise<V>): Promise<V>
Stores a promise with the specified key in the cache.
get(key: K): Promise<V> | undefined
Retrieves a promise from the cache using the specified key. Returns undefined
if the key is not found.
remove(key: K): void
Removes a promise from the cache using the specified key.
clear(): void
Clears the entire cache.
size(): number
Returns the current number of items in the cache.
ReadThroughPromiseCache
A Read Through Cache is useful for high throughput systems. If the cache contains the requested data, it is immediately returned. If the data does not exist (or has expired), the cache will fetch and place resulting promise in the cache for future requests. Some examples and use cases for Read Through Caching (and other caching patterns) can be found here.
Example
import { ReadThroughPromiseCache, CacheParams } from '@ardrive/ardrive-promise-cache';
const params: CacheParams = {
cacheCapacity: 100,
cacheTTL: 60_000,
};
const readThroughCacheParams: ReadThroughPromiseCacheParams<string,AxiosResponse> = {
cacheParams: params,
readThroughFunction: async (key: K) => {
return axios.get(`https://example.com/api/${key}`);
}
};
const readThroughCache = new ReadThroughPromiseCache<string, AxiosResponse>(readThroughCacheParams);
const { status, data } = await readThroughCache.get('example')
const { status: cachedStatus, data: cacheData } = await readThroughCache.get('example')
await new Promise((res) => setTimeout(() => res, 60_000);
const { status: refreshedStatus, data:refreshedData } = await readThroughCache.get('example')
API
constructor({ cacheParams: { cacheCapacity, cacheTTL }, readThroughFunction: (key: string) => Promise<V>: ReadThroughPromiseCacheParams)
Creates a new ReadThroughPromiseCache
instance with the specified capacity and time-to-live (TTL) for cached items and readThroughFunction
that will be called when the cache does not contain the key.
getWithStatus(key: K): Promise<{status: 'hit' | 'miss', data: V}>
Returns a Promise'd object, with the key 'data' pre-awaited and 'status' key indicating if it was a hit or a miss.
Note
The method cacheKeyString(key: K): string
is used internally to create cache keys. The default implementation may not sufficiently differentiate keys for certain object types, depending on their toJSON
implementation. You may need to override this method if you encounter issues.