@lindeneg/cache
Utility class for caching data.
Installation
yarn add @lindeneg/cache
Usage
import Cache from '@lindeneg/cache';
const cache = new Cache(optionalConfig);
// set item
cache.set('id', 5);
// or with async
await cache.setAsync('id', 5);
// listen to events
cache.on('trim', (removed) => {
console.log(removed);
});
// and so on..
Config
type Config = {
/* object with initial cache data
default: {} */
data?: Record<
string | number | symbol,
// this type is referred to as a: CacheEntry
{ expires: number; value: unknown }
>;
/* trimming interval in seconds
default: 600 */
trim?: number;
/* time-to-live in seconds
default: 3600 */
ttl?: number;
};
Methods
Shared
This cache instance is used in the below examples:
type T = {
id: number;
username: string;
};
const cache = new Cache<T>();
value, valueAsync
These methods returns the value
of a desired CacheEntry
. If an entry is found but it has expired, then it will be removed from cache and the function call will return null
.
function value<K extends keyof T>(key: K): T[K] | null;
function valueAsync<K extends keyof T>(key: K): Promise<T[K] | null>;
// type: string | null
const username = cache.value('username');
// type: number | null
const id = await cache.value('id');
get, getAsync
These methods returns the entire CacheEntry
, with both the value
and expires
properties. If an entry is found but it has expired, then it will be removed from cache and the function call will return null
.
function get<K extends keyof T>(key: K): CacheEntry<T[K]> | null;
function getAsync<K extends keyof T>(key: K): Promise<CacheEntry<T[K]> | null>;
// type: { expires: number; value: string } | null
const username = cache.get('username');
// type: { expires: number; value: number } | null
const id = await cache.getAsync('id');
set, setAsync
These methods always returns the created CacheEntry
. The expires
value is deduced from the ttl
property in the cache config
, which defaults to 3600 seconds.
function set<K extends keyof T>(key: K, value: T[K]): CacheEntry<T[K]>;
function setAsync<K extends keyof T>(
key: K,
value: T[K]
): Promise<CacheEntry<T[K]>>;
// type: { expires: number; value: string }
const username = cache.set('username', 'miles');
// type: { expires: number; value: number }
const id = await cache.setAsync('id', 1);
createEntry, Cache.createEntry
There are two methods available to create a CacheEntry
without saving it in the cache. This can be useful for creating initial cache data compatible with the type constraint of config.data
.
// instance method
function createEntry<T>(value: T): CacheEntry<T>;
// static method
function Cache.createEntry<T>(value: T, ttl = 3600): CacheEntry<T>;
remove, removeAsync
These methods returns the removed CacheEntry
or null
if nothing was removed.
function remove<K extends keyof T>(key: K): CacheEntry<T[K]> | null;
function removeAsync<K extends keyof T>(
key: K
): Promise<CacheEntry<T[K]> | null>;
// type: { expires: number; value: string } | null
const username = cache.remove('username');
// type: { expires: number; value: number } | null
const id = await cache.removeAsync('id');
on
This method allows you to attach callbacks to be executed on certain events.
type ListenerConstraint =
| 'remove'
| 'clear'
| 'clearTrimListener'
| 'trim'
| 'set';
function on<K extends ListenerConstraint>(
event: K,
callback: ListenerCallback<T, K>
): void;
The ListenerCallback
type is generic because, for example, set
will provide different arguments than remove
. We can think about it like so:
type ListenerCallback<K extends ListenerConstraint> = K extends 'trim'
? (removed: Array<keyof T>) => void
: K extends 'set'
? (key: keyof T, entry: CacheEntry<T[keyof T]>) => void
: K extends 'remove'
? (key: keyof T) => void
: () => void;
For example, it can be used like so with types inferred from the event
argument:
cache.on('set', (key, entry) => {
// do something
});
cache.on('trim', (removed) => {
// do something
});
cache.on('clear', () => {
// do something
});
has
Check if an entry exists. If an entry is found but it has expired, then it will be removed from cache and the function call will return false
.
function has(key: keyof T): boolean;
const hasId = cache.has('id');
size
Get the current size of cache.
function size(): number;
const cacheSize = cache.size();
keys
Get the keys of the cache.
function keys(): Array<keyof T>;
const keys = cache.keys();
clear, clearAsync
Clear the cache.
function clear(): void;
function clearAsync(): Promise<void>;
cache.clear();
await cache.clearAsync();
clearTrimListener
Removes the trim
event listener.
function clearTrimListener(): void;
cache.clearTrimListener();
Type Safety
Do note, that in order to have type-safety, you either need to pass in a data
object in the config
where the types can be inferred from or pass in a generic type argument that describes what you want to cache.
const cache = new Cache({ id: 1, username: 'christian' });
/* now cache keys 'id' and 'username' are inferred as having types 'number' and 'string', respectively.
however, this is only really useful if the object you pass in, always describes the entire cache. */
// passing in a generic type argument ensures type-safety in all cache methods
type SomeCacheData = { id: number; username: string };
const cache = new Cache<SomeCacheData>();
/* for example, the first arg in 'cache.set', is now constrained to a union of 'id' | 'username',
or K, and the values are constrained to SomeCacheData[K] */
// OK
cache.set('id', 1);
cache.set('username', 'miles');
// TS error
cache.set('id', 'davis');
cache.set('username', 1);
// and so on