reminisce v0.1.0
reminisce
Simple Node.js caching module with promises.
Installation
npm i --save reminisce
Example Usage
const Reminisce = require('reminisce');
const cache = new Reminisce();
return cache.set({ key: 'example', value: 1, ttl: 10000 })
// a 10ms delay just for example purposes
.delay(10);
.then(() => cache.get('example'))
.spread((memory) => {
// memory = { key: 'example', value: 1, expires: timestamp, lifespan: 10000, ttl: 9990 }
});
Options
An options object can be passed in when creating a new reminisce instance like so:
const cache = new Reminisce({ memories: [], ttl: 60000 });
memories
(default:[]
) can be a single memory object or an array of memory objects that will be storedttl
(default:60000
) the defaultttl
for memories before they are forgotten (in milliseconds)
Memories
When passing memory objects to the different reminisce functions, they should look like this:
{
key: 'example', // the String to use as a key that can be used to reference this memory later
value: 1, // the value being stored in memory
ttl: 10000 // (optional) the time to live for a memory before it is forgotten (in milliseconds)
}
The ttl
property is optional and will default to the ttl
used when reminisce was initialized.
When memory objects are returned they will have key
, value
, and the following properties:
ttl
the remaining time to live for the memory before it is forgotten (in milliseconds)expires
a UTC timestamp for when the memory is scheduled to be forgottenlifespan
how long the memory was intended to live when it was created (in milliseconds)
Get memories
return cache.get('someKey')
.spread((memory) => {
// memory = { key: 'example', value: 1, expires: timestamp, lifespan: 10000, ttl: 9990 }
});
return cache.get('forgottenKey')
.spread((memory) => {
// memory = undefined
});
return cache.get([ 'someKey', 'someOtherKey', 'forgottenKey' ])
.then((memories) => {
// memories = [{ someMemory }, { someOtherMemory }, undefined]
});
Takes a String key
or an array of key
's, returns a promise that resolves to an array of memory objects. If a memory isn't associated with a given key, undefined
will be returned in its place.
Set memories
return cache.set({ key: 'someKey', value: 1, ttl: 10000 })
.spread((memory) => {
// memory = { key: 'example', value: 1, expires: timestamp, lifespan: 10000, ttl: 10000 }
});
const cache = new Reminisce({ ttl: 60000 });
return cache.set({ key: 'someKey', value: 1 })
.spread((memory) => {
// memory = { key: 'example', value: 1, expires: timestamp, lifespan: 60000, ttl: 60000 }
});
return cache.set([{ someMemory }, { someOtherMemory }])
.then((memories) => {
// memories = [{ someMemory }, { someOtherMemory }]
});
Takes a memory object or an array of memory objects, returns a promise that resolves to an array of memory objects. If there is already a memory associated with a given key, then this function will override that memory.
Update memories
const cache = new Reminisce({
memories: { key: 'existingKey', value: 2, ttl: 30000 }
});
return cache.update({ key: 'existingKey', value: 5 })
.spread((memory) => {
// memory = { key: 'existingKey', value: 5, expires: timestamp, lifespan: 30000, ttl: unaffectedRemainingTTL }
});
const cache = new Reminisce({
memories: [{ key: 'existingKey', value: 5, ttl: 30000 }, { key: 'otherExistingKey', value: 6 }]
});
return cache.update([{ key: 'existingKey', value: 7 }, { key: 'otherExistingKey', value: 8 }])
.then((memories) => {
/*
memories = [{
key: 'existingKey',
value: 7,
expires: timestamp,
lifespan: 30000,
ttl: unaffectedRemainingTTL
}, {
key: 'otherExistingKey',
value: 8,
expires: timestamp,
lifespan: 60000,
ttl: unaffectedRemainingTTL
}]
*/
});
return cache.update({ forgottenMemory })
.spread((memory) => {
// memory = undefined
});
Takes a memory object or an array of memory objects, returns a promise that resolves to an array of memory objects. If a memory isn't associated with a given key, undefined
will be returned in its place. This function can be used to update memory value
s without changing when memories are scheduled to be forgotten.
Delete memories
return cache.delete('someKey')
.then((result) => {
// result = true
});
return cache.delete('forgottenKey')
.then((result) => {
// result = true
});
return cache.delete([ 'someKey', 'someOtherKey', 'forgottenKey' ])
.then((result) => {
// result = true
});
Takes a String key
or an array of key
's, returns a promise that resolves to true
if deletions were successful. If a memory isn't associated with a given key, a promise that resolves to true
will still be returned.
Flush memories
return cache.flush()
.then((result) => {
// result = true
});
Flushes all memories and returns a promise that resolves to true
if successful.
Keys
const cache = new Reminisce({
memories: [{ key: 'someKey', ... }, { key: 'someOtherKey', ... }]
});
console.log(cache.keys);
// -> [ 'someKey', 'someOtherKey' ]
Returns an array of keys associated with current memories.