cacheable
On this page
cacheable
Simple Caching Engine using Keyv
cacheable
is a simple caching engine that uses Keyv as the storage engine. It is designed to be simple to use and extend. Here are some of the features:
- Simple to use with robust API
- Not bloated with additional modules
- Extendable to your own caching engine
- Scalable and trusted storage engine by Keyv
- Statistics built in by default
- Hooks and Events to extend functionality
- Comprehensive testing and code coverage
- Maintained and supported
Getting Started
cacheable
is primarily used as an extension to you caching engine with a robust storage backend Keyv, Memonization, Hooks, Events, and Statistics.
npm install cacheable
Extending Your own Caching Engine
import { Cacheable } from 'cacheable';
export class MyCache extends Cacheable {
constructor() {
super();
}
}
From here you now how the ability to use the cacheable
API. You can also extend the API to add your own functionality.
Storage Adapters and Keyv
To set Keyv as the storage engine, you can do the following:
import { Cacheable } from 'cacheable';
import Keyv from 'keyv';
export class MyCache extends Cacheable {
constructor() {
super(new Keyv('redis://user:pass@localhost:6379'));
}
}
or you can do it at the property level:
import { Cacheable } from 'cacheable';
import Keyv from 'keyv';
export class MyCache extends Cacheable {
constructor() {
super();
this.store = new Keyv('redis://user:pass@localhost:6379');
}
}
Statistics
To get statistics on your cache, you can do the following:
import { Cacheable } from 'cacheable';
export class MyCache extends Cacheable {
constructor() {
super();
}
async getStats() {
return this.stats.getReport();
}
}
This will generate the following json object:
{
"cacheSize": 100,
"currentSize": 80,
"hits": 500,
"misses": 200,
"hitRate": 0.71,
"evictions": 50,
"averageLoadPenalty": 0.05,
"loadSuccessCount": 700,
"loadExceptionCount": 10,
"totalLoadTime": 3500,
"topHits": [
{
"key": "key1",
"value": "value1",
"lastAccessed": 1627593600000,
"accessCount": 50
},
{
"key": "key2",
"value": "value2",
"lastAccessed": 1627593600000,
"accessCount": 45
}
// More items...
],
"leastUsed": [
{
"key": "key3",
"value": "value3",
"lastAccessed": 1627593600000,
"accessCount": 5
},
{
"key": "key4",
"value": "value4",
"lastAccessed": 1627593600000,
"accessCount": 4
}
// More items...
]
}
cacheSize
: The maximum number of items that can be stored in the cache.currentSize
: The current number of items in the cache. hits: The number of cache hits. A cache hit occurs when the requested data is found in the cache.misses
: The number of cache misses. A cache miss occurs when the requested data is not found in the cache and needs to be loaded.hitRate
: The ratio of cache hits to the total number of cache lookups. This is a measure of the cache's effectiveness.evictions
: The number of items that have been evicted from the cache, typically because the cache is full.averageLoadPenalty
: The average time spent loading new values into the cache, typically measured in milliseconds. This could be calculated as totalLoadTime / (hits + misses).loadSuccessCount
: The number of times cache loading has succeeded.loadExceptionCount
: The number of times cache loading has failed due to exceptions.totalLoadTime
: The total time spent loading new values into the cache, typically measured in milliseconds.
Hooks and Events
The following hooks are available for you to extend the functionality of cacheable
:
preSet
: This is called before theset
method is called.postSet
: This is called after theset
method is called.preSetMany
: This is called before thesetMany
method is called.postSetMany
: This is called after thesetMany
method is called.preGet
: This is called before theget
method is called.postGet
: This is called after theget
method is called.preGetMany
: This is called before thegetMany
method is called.postGetMany
: This is called after thegetMany
method is called.
An example of how to use these hooks:
import { Cacheable } from 'cacheable';
const cacheable = new Cacheable();
cacheable.hooks.setHook('preSet', (key, value) => {
console.log(`preSet: ${key} ${value}`);
});
The following events are available for you to extend the functionality of cacheable
:
set
: This is called when theset
method is called.setMany
: This is called when thesetMany
method is called.get
: This is called when theget
method is called.getMany
: This is called when thegetMany
method is called.clear
: This is called when theclear
method is called.has
: This is called when thehas
method is called.disconnect
: This is called when thedisconnect
method is called.error
: This is called when an error occurs.
API
set(key, value, ttl?)
: Sets a value in the cache.setMany([{key, value, ttl?}])
: Sets multiple values in the cache.get(key)
: Gets a value from the cache.has(key)
: Checks if a value exists in the cache.getMany([keys])
: Gets multiple values from the cache.delete(key)
: Deletes a value from the cache.clear()
: Clears the cache.disconnect()
: Disconnects from the cache.getStats()
: Gets statistics from the cache.setHook(hook, callback)
: Sets a hook.deleteHook(hook)
: Removes a hook.emitEvent(event, data)
: Emits an event.on(event, callback)
: Listens for an event.removeListener(event, callback)
: Removes a listener.store
: The Keyv storage engine.
How to Contribute
You can contribute by forking the repo and submitting a pull request. Please make sure to add tests and update the documentation. To learn more about how to contribute go to our main README https://github.com/jaredwray/cacheable. This will talk about how to Open a Pull Request
, Ask a Question
, or Post an Issue
.
License and Copyright
MIT © Jared Wray - https://github.com/jaredwray/cacheable/blob/main/LICENSE