ttl-mem-cache
v4.1.0
Published
A in memory time to live cache with streaming support.
Downloads
3,256
Maintainers
Readme
A in memory time to live cache with streaming support.
Installation
$ npm install ttl-mem-cache
Example
Set an object and retrieve it.
const Cache = require('ttl-mem-cache');
const cache = new Cache();
cache.set('a', {foo: 'bar'});
const obj = cache.get('a'); // returns {foo: 'bar'}
Description
This is a in memory time to live key/value cache with streaming support. Items are
not pro-actively pruned out as they age but expires when they are too old when touched.
In other words; this module does not use setTimeout()
or simmilar methods internally.
There is no restrictions on the values stored in the cache and there is no maximum limit of the amount of items in the cache. Whan that is said, the intention of this module is to act as a simple key/value cache where one need to cache small to medium amounts of data.
Constructor
Create a new Cache instance.
const Cache = require('ttl-mem-cache');
const cache = new Cache(options);
options (optional)
An Object containing misc configuration. The following values can be provided:
- ttl -
Number
- Default time to live in milliseconds all items in the cache should be cached before expiering. - stale -
Boolean
- If expired items in cache should be returned when pruned from the cache. Default:false
. - changelog -
Boolean
- If emittedset
event and stream should contain both old and new value. Default:false
. - id -
String
- Give the instanse a unique identifier. Default:hash
If an option Object with a ttl
is not provided all items in the cache will by default
cached for 5 minutes before they expire.
Items can be cached forever by setting ttl
to Infinity
. Items cached forever can
be overwritten and manually deleted.
Pruning of items from the cache happend when they are touched by one of the methods
for retrieving (.get()
and .entries()
) items from the cache. By default pruning
happens before the method returns a value so if an item have expired, null
will be
returned for expired items. By setting stale
to true
, these methods will return
the pruned item(s) before they are removed from the cache.
Internally the cache has a unique ID created each time its instantiated. This ID is
used to tell the origin of an cached item when streaming. The id
will override
this generated ID. When using this, be carefull to not provide the same ID to multiple
instances of the cache.
The Cache instance inherit from Duplex Stream. Due to this the instance also take all config parameters which the Duplex Stream does. Please see the documentation of Duplex Streams for further documentation.
API
The Cache instance have the following API:
.set(key, value, ttl)
Set an item in the cache on a given key.
const cache = new Cache();
cache.set('a', {foo: 'bar'});
cache.set('b', {foo: 'xyz'}, 20 * 60 * 1000);
This method take the following arguments:
- key - An unique key the value should be stored on in the cache. Required.
- value - The value to store on the key in the cache. Required.
- ttl - Time to live before the item should expire. Uses default if not given. Optional.
An item can be cached forever by setting ttl
to Infinity
.
.get(key)
Get an item on a given key from the cache.
const cache = new Cache();
cache.set('a', {foo: 'bar'});
const obj = cache.get('a'); // returns {foo: 'bar'}
This method take the following arguments:
- key - The unique key for the item in the cache. Required.
Triggering .get()
will check the expire on the item. If the item is older than
the time to live set on it, the item will be removed from the cache and this method
will return null
unless stale
is set to true
on the constructor. Then the
expired item will be returned before its removed from the cache.
.del(key)
Explicitly delete an item on a given key in the cache.
const cache = new Cache();
cache.set('a', {foo: 'bar'});
cache.del('a');
This method take the following arguments:
- key - The unique key for the item in the cache. Required.
.entries(mutator)
Get all items in the cache. Returns an Array with all items.
const cache = new Cache();
cache.set('a', {foo: 'bar'});
cache.set('b', {foo: 'xyz'});
const all = cache.entries(); // returns [{foo: 'bar'}, {foo: 'xyz'}]
Triggering .entries()
will check the expire on the items. If an item is older than
the time to live set on it, the item will be removed from the cache and it will not be
included in the returned value of this methid unless stale
is set to true
on the
constructor. Then the expired item will be included before its removed from the cache.
This method take the following arguments:
- mutator - A function for mutating the items returned. Optional.
The mutator attribute can be used to change the structure of the returned items. It
takes a function which will be called with an Object with the key
and value
. This
function must return a value which then will be the value of the item in the returned
output.
const cache = new Cache();
cache.set('a', {foo: 'bar'});
cache.set('b', {foo: 'xyz'});
const all = cache.entries((item) => {
return item.value.foo;
}); // returns ['bar', 'xyz']
The advantage of using the mutator if one want to mutate the items is that the mutator is applied to each item in the same process as the expire is checked.
.prune()
Iterates over all items in the cache and proactively prunes expired items.
.clear()
Clears the entire cache. All items will be deleted.
.dump()
Returns an Array of all items in the cache ready to be used by .load()
.
.load(dump)
Loads an Array of items, provided by .dump()
, into the cache.
This method take the following arguments:
- dump - Array of items to be imported.
If any of the items in the loaded Array contains a key which already are in the cache the entry in the cache will be overwritten.
If any of the entries in the loaded Array are not compatible with the format
which .dump()
exports, they will not be inserted into the cache.
Returns and Array with the keys which was inserted into the cache.
.length()
The number of items in the cache.
Events
The Cache instance inherit from Duplex Stream. Due to this the instance emits all the events which Duplex Stream does when the streaming feature is used. Please see the documentation of Duplex Streams for further documentation.
In addition to this, the following events are emitted:
set
When an item is set in the cache. Emits an Object with the key
and value
of the item.
const cache = new Cache();
cache.on('set', (key, item) => {
console.log(key, item); // outputs: "a, {foo: 'bar'}"
});
cache.set('a', {foo: 'bar'});
If changefeed
is set to be true
on the constructor, the emitted Object will hold both
old and new value for the key. See "changelog" for further info.
dispose
When an item is disposed (deleted) from the cache. Emits the key
of the item and the item itself.
const cache = new Cache();
cache.on('dispose', (key, item) => {
console.log(key, item); // outputs: "a, {foo: 'bar'}"
});
cache.set('a', {foo: 'bar'});
cache.del('a');
clear
When the cache is cleared.
Streams
The Cache instance is a Duplex Stream. One can stream items in and out of the cache.
Example of streaming into the cache:
const cache = new Cache();
const source = new SomeReadableStream(); // a source streaming an item on key 'a' into the cache
source.pipe(cache);
cache.get('a'); // returns the item for key 'a'
Example of streaming out of the cache:
const cache = new Cache();
const dest = new SomeWritableStream(); // a destination stream recieving items from the cache
cache.pipe(dest);
cache.set('a', {foo: 'bar'}); // pushes {foo: 'bar'} onto the writable stream
Example of streaming through the cache (all items streamed through will be kept in the cache):
const cache = new Cache();
const source = new SomeReadableStream(); // a source streaming items into the cache
const dest = new SomeWritableStream(); // a destination stream recieving items from the cache
source.pipe(cache).pipe(dest);
cache.entries(); // returns all the items streamed through the cache
Linking caches
With the stream API its possible to link caches together and distribute cached items between them.
const Cache = require('../');
const cacheA = new Cache();
const cacheB = new Cache();
const cacheC = new Cache();
// Link all caches together
cacheA.pipe(cacheB).pipe(cacheC).pipe(cacheA);
// Set a value in cache C
cacheC.set('foo', 'bar');
// Retrieve the same value from all caches
console.log(cacheA.get('foo'), cacheB.get('foo'), cacheC.get('foo'));
// Delete the value in cache A
cacheA.del('foo');
// The value is deleted from all caches
console.log(cacheA.get('foo'), cacheB.get('foo'), cacheC.get('foo'));
Streaming Object type
When using the Stream API to write to and read from the cache an Entry Object or an Object of simmilar character is used.
The Entry Object looks like this:
{
key: 'item key',
value: 'item value',
origin: 'cache instance ID',
ttl: 'time to live',
expires: 'time stamp'
}
The Stream API will always emit a full Entry Object. When writing to the Stream API one can provide
a full Entry Object, but a simmilar Object will also be accepted. Only key
and value
are required
properties when writing to the Stream API.
Iow; the following Object will be accepted by the Stream API:
{
key: 'foo',
value: 'bar'
}
key
defines what key the value of value
should be stored on in the cache. key
is required
and if not provided the stream will emit an error.
When writing to the cache and a Object with value
with a value is provided, it will be stored in
the cache on the provided key
. If value
is not provided or null
or undefined
on the
Object when writing to the cache, any item with a matching key
in the cache will be deleted.
When the stream emits objects each object will have a origin
key. The value is the unique ID of
the instance the object first was emitted on the stream. If the construcor was given a value for
the id
argument, this will be used as origin
value.
ttl
is how long the item is set to live in the cache.
expires
is the calculated timestamp for when the item should expire from the cache. This is
calculated when an item is set in the cache. If a value for expires
is provided when writing
to the Stream API this value will be set in the cache.
If the items you want to store in the cache does not fit your data type, its recommended to use a Transform Stream to transform it into the supported Object type.
Example:
const cache = new Cache();
const source = new SomeReadableStream(); // contains Objects like this {id: 'a', item: 'bar'}
const convert = new stream.Transform({
objectMode: true,
transform(obj, encoding, callback) {
this.push({
key: obj.id,
value: obj.item
});
callback();
}
});
source.pipe(convert).pipe(cache);
The Entry Object does
implement .toPrimitive
where a stringified JSON representation of the Object will be returned
when call to the Entry Object with a String hint is done.
This can be used when one want to convert the Entry Object into a Buffer.
const cache = new Cache();
const dest = new SomeWritableStream(); // Some destination supporting Buffers
const convert = new stream.Transform({
writableObjectMode: true,
readableObjectMode: false,
transform(obj, encoding, callback) {
const buff = Buffer.from(obj); // Convert Entry Object to a Buffer
this.push(buff);
callback();
}
});
cache.pipe(convert).pipe(dest);
Object Mode
By default the stream are in object mode. Its also supported to run the stream in non-object
mode. Object mode can be turned off by setting objectMode
to false
as an option to the
constructor.
When using non-object mode the stream will emit Buffers
containing a stringified JSON
representaion of the Entry Object.
Changelog
If the attribute changelog
is set to true
on the constructor, the set
events will emit an
object holding both old and new values for the key.
The emitted object looks like this:
{
oldVal: 'foo',
newVal: 'bar'
}
Example:
const Cache = require('ttl-mem-cache');
const cache = new Cache({ changefeed: true });
cache.on('set', (key, item) => {
// item will be in the format above
});
cache.set('a', 'foo');
cache.set('a', 'bar');
If a key does not hold a value in cache before, oldVal
will be null
.
If a key hold a value which has expired and stale
is false
, oldVal
will be null
.
If a key hold a value which has expired and stale
is true
, oldVal
will be the old value.
node.js compabillity
This module is written in ES6 and uses some functions only found in node.js 8.2 and newer. This module will not function with older than 8.2 versions of node.js.
error handling
This module does not handle errors for you, so you must handle errors on whatever streams you pipe into this module. This is a general rule when programming with node.js streams: always handle errors on each and every stream.
We recommend using end-of-stream
or pump
for writing error tolerant stream code.
License
The MIT License (MIT)
Copyright (c) 2017 - Trygve Lie - [email protected]
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.