transitory
Version:
In-memory cache with high hit rates via LFU eviction. Supports time-based expiration, automatic loading and metrics.
228 lines • 7.2 kB
JavaScript
import { AbstractCache } from '../AbstractCache';
import { RemovalReason } from '../RemovalReason';
import { PARENT, ON_REMOVE, TRIGGER_REMOVE, ON_MAINTENANCE, MAINTENANCE } from '../symbols';
import { TimerWheel } from './TimerWheel';
const DATA = Symbol('expirationData');
/**
* Wrapper for another cache that provides evictions of times based on timers.
*
* Currently supports expiration based on maximum age.
*/
export class ExpirationCache extends AbstractCache {
constructor(options) {
super();
this[PARENT] = options.parent;
this[DATA] = {
maxWriteAge: options.maxWriteAge,
maxNoReadAge: options.maxNoReadAge,
removalListener: options.removalListener || null,
timerWheel: new TimerWheel(keys => {
for (const key of keys) {
this.delete(key);
}
})
};
// Custom onRemove handler for the parent cache
this[PARENT][ON_REMOVE] = (key, node, reason) => {
const actualReason = node.isExpired() ? RemovalReason.EXPIRED : reason;
this[DATA].timerWheel.deschedule(node);
this[TRIGGER_REMOVE](key, node.value, actualReason);
};
// Custom maintenance behaviour to advance the wheel
this[PARENT][ON_MAINTENANCE] = this[MAINTENANCE].bind(this);
}
/**
* The maximum size the cache can be. Will be -1 if the cache is unbounded.
*
* @returns
* maximum size
*/
get maxSize() {
return this[PARENT].maxSize;
}
/**
* The current size of the cache.
*
* @returns
* current size
*/
get size() {
return this[PARENT].size;
}
/**
* The size of the cache weighted via the activate estimator.
*
* @returns
* weighted size
*/
get weightedSize() {
return this[PARENT].weightedSize;
}
/**
* Store a value tied to the specified key. Returns the previous value or
* `null` if no value currently exists for the given key.
*
* @param key -
* key to store value under
* @param value -
* value to store
* @returns
* current value or `null`
*/
set(key, value) {
const data = this[DATA];
const timerWheel = data.timerWheel;
const node = timerWheel.node(key, value);
let age = null;
if (data.maxWriteAge) {
age = data.maxWriteAge(key, value) || 0;
}
else if (data.maxNoReadAge) {
age = data.maxNoReadAge(key, value) || 0;
}
if (age !== null && !data.timerWheel.schedule(node, age)) {
// Age was not accepted by wheel, delete any previous value
return this.delete(key);
}
try {
const replaced = this[PARENT].set(key, node);
return replaced ? replaced.value : null;
}
catch (ex) {
timerWheel.deschedule(node);
throw ex;
}
}
/**
* Get the cached value for the specified key if it exists. Will return
* the value or `null` if no cached value exist. Updates the usage of the
* key.
*
* @param key -
* key to get
* @returns
* current value or `null`
*/
getIfPresent(key) {
const node = this[PARENT].getIfPresent(key);
if (node) {
if (node.isExpired()) {
// Check if the node is expired and return null if so
return null;
}
// Reschedule if we have a maximum age between reads
const data = this[DATA];
if (data.maxNoReadAge) {
const age = data.maxNoReadAge(key, node.value);
if (!data.timerWheel.schedule(node, age)) {
// Age was not accepted by wheel, expire it directly
this.delete(key);
}
}
return node.value;
}
return null;
}
/**
* Peek to see if a key is present without updating the usage of the
* key. Returns the value associated with the key or `null` if the key
* is not present.
*
* In many cases `has(key)` is a better option to see if a key is present.
*
* @param key -
* the key to check
* @returns
* value associated with key or `null`
*/
peek(key) {
const node = this[PARENT].peek(key);
return node && !node.isExpired() ? node.value : null;
}
/**
* Check if the given key exists in the cache.
*
* @param key -
* key to check
* @returns
* `true` if value currently exists, `false` otherwise
*/
has(key) {
const node = this[PARENT].peek(key);
return (node && !node.isExpired()) || false;
}
/**
* Delete a value in the cache. Returns the deleted value or `null` if
* there was no value associated with the key in the cache.
*
* @param key -
* the key to delete
* @returns
* deleted value or `null`
*/
delete(key) {
const node = this[PARENT].delete(key);
return node ? node.value : null;
}
/**
* Clear the cache removing all of the entries cached.
*/
clear() {
this[PARENT].clear();
}
/**
* Get all of the keys in the cache as an array. Can be used to iterate
* over all of the values in the cache, but be sure to protect against
* values being removed during iteration due to time-based expiration if
* used.
*
* @returns
* snapshot of keys
*/
keys() {
return this[PARENT].keys();
}
/**
* Request clean up of the cache by removing expired entries and
* old data. Clean up is done automatically a short time after sets and
* deletes, but if your cache uses time-based expiration and has very
* sporadic updates it might be a good idea to call `cleanUp()` at times.
*
* A good starting point would be to call `cleanUp()` in a `setInterval`
* with a delay of at least a few minutes.
*/
cleanUp() {
this[PARENT].cleanUp();
}
/**
* Get metrics for this cache. Returns an object with the keys `hits`,
* `misses` and `hitRate`. For caches that do not have metrics enabled
* trying to access metrics will throw an error.
*
* @returns
* metrics if available via the parent cache
*/
get metrics() {
return this[PARENT].metrics;
}
[MAINTENANCE]() {
this[DATA].timerWheel.advance();
const onMaintenance = this[ON_MAINTENANCE];
if (onMaintenance) {
onMaintenance();
}
}
[TRIGGER_REMOVE](key, value, reason) {
// Trigger any extended remove listeners
const onRemove = this[ON_REMOVE];
if (onRemove) {
onRemove(key, value, reason);
}
const data = this[DATA];
// Trigger the removal listener
if (data.removalListener) {
data.removalListener(key, value, reason);
}
}
}
//# sourceMappingURL=ExpirationCache.js.map