cacheable
Table of Contents
Cacheable
Simple Caching Engine using Keyv
cacheable
is a high performance layer 1 / layer 2 caching engine that is focused on distributed caching with enterprise features such as CacheSync
(coming soon). It is built on top of the robust storage engine Keyv and provides a simple API to cache and retrieve data.
- Simple to use with robust API
- Not bloated with additional modules
- Scalable and trusted storage engine by Keyv
- Memory Caching with LRU and Expiration
CacheableMemory
- Resilient to failures with try/catch and offline
- Wrap / Memoization for Sync and Async Functions
- Hooks and Events to extend functionality
- Shorthand for ttl in milliseconds
(1m = 60000) (1h = 3600000) (1d = 86400000)
- Non-blocking operations for layer 2 caching
- Distributed Caching Sync via Pub/Sub (coming soon)
- Comprehensive testing and code coverage
- ESM and CommonJS support with Typescript
- Maintained and supported regularly
Table of Contents
Getting Started
cacheable
is primarily used as an extension to you caching engine with a robust storage backend Keyv, Memonization (Wrap), Hooks, Events, and Statistics.
npm install cacheable
Basic Usage
import { Cacheable } from 'cacheable';
const cacheable = new Cacheable();
await cacheable.set('key', 'value', 1000);
const value = await cacheable.get('key');
This is a basic example where you are only using the in-memory storage engine. To enable layer 1 and layer 2 caching you can use the secondary
property in the options:
import { Cacheable } from 'cacheable';
import KeyvRedis from '@keyv/redis';
const secondary = new KeyvRedis('redis://user:pass@localhost:6379');
const cache = new Cacheable({secondary});
In this example, the primary store we will use lru-cache
and the secondary store is Redis. You can also set multiple stores in the options:
import { Cacheable } from 'cacheable';
import { Keyv } from 'keyv';
import KeyvRedis from '@keyv/redis';
import { LRUCache } from 'lru-cache'
const primary = new Keyv({store: new LRUCache()});
const secondary = new KeyvRedis('redis://user:pass@localhost:6379');
const cache = new Cacheable({primary, secondary});
This is a more advanced example and not needed for most use cases.
Hooks and Events
The following hooks are available for you to extend the functionality of cacheable
via CacheableHooks
enum:
BEFORE_SET
: This is called before theset()
method is called.AFTER_SET
: This is called after theset()
method is called.BEFORE_SET_MANY
: This is called before thesetMany()
method is called.AFTER_SET_MANY
: This is called after thesetMany()
method is called.BEFORE_GET
: This is called before theget()
method is called.AFTER_GET
: This is called after theget()
method is called.BEFORE_GET_MANY
: This is called before thegetMany()
method is called.AFTER_GET_MANY
: This is called after thegetMany()
method is called.
An example of how to use these hooks:
import { Cacheable, CacheableHooks } from 'cacheable';
const cacheable = new Cacheable();
cacheable.onHook(CacheableHooks.BEFORE_SET, (data) => {
console.log(`before set: ${data.key} ${data.value}`);
});
Storage Tiering and Caching
cacheable
is built as a layer 1 and layer 2 caching engine by default. The purpose is to have your layer 1 be fast and your layer 2 be more persistent. The primary store is the layer 1 cache and the secondary store is the layer 2 cache. By adding the secondary store you are enabling layer 2 caching. By default the operations are blocking but fault tolerant:
Setting Data
: Sets the value in the primary store and then the secondary store.Getting Data
: Gets the value from the primary if the value does not exist it will get it from the secondary store and set it in the primary store.Deleting Data
: Deletes the value from the primary store and secondary store at the same time waiting for both to respond.Clearing Data
: Clears the primary store and secondary store at the same time waiting for both to respond.
Shorthand for Time to Live (ttl)
By default Cacheable
and CacheableMemory
the ttl
is in milliseconds but you can use shorthand for the time to live. Here are the following shorthand values:
ms
: Milliseconds such as (1ms = 1)s
: Seconds such as (1s = 1000)m
: Minutes such as (1m = 60000)h
orhr
: Hours such as (1h = 3600000)d
: Days such as (1d = 86400000)
Here is an example of how to use the shorthand for the ttl
:
import { Cacheable } from 'cacheable';
const cache = new Cacheable({ ttl: '15m' }); //sets the default ttl to 15 minutes (900000 ms)
cache.set('key', 'value', '1h'); //sets the ttl to 1 hour (3600000 ms) and overrides the default
if you want to disable the ttl
you can set it to 0
or undefined
:
import { Cacheable } from 'cacheable';
const cache = new Cacheable({ ttl: 0 }); //sets the default ttl to 0 which is disabled
cache.set('key', 'value', 0); //sets the ttl to 0 which is disabled
If you set the ttl to anything below 0
or undefined
it will disable the ttl for the cache and the value that returns will be undefined
. With no ttl set the value will be stored indefinitely
.
import { Cacheable } from 'cacheable';
const cache = new Cacheable({ ttl: 0 }); //sets the default ttl to 0 which is disabled
console.log(cache.ttl); // undefined
cache.ttl = '1h'; // sets the default ttl to 1 hour (3600000 ms)
console.log(cache.ttl); // '1h'
cache.ttl = -1; // sets the default ttl to 0 which is disabled
console.log(cache.ttl); // undefined
Non-Blocking Operations
If you want your layer 2 (secondary) store to be non-blocking you can set the nonBlocking
property to true
in the options. This will make the secondary store non-blocking and will not wait for the secondary store to respond on setting data
, deleting data
, or clearing data
. This is useful if you want to have a faster response time and not wait for the secondary store to respond.
import { Cacheable } from 'cacheable';
import {KeyvRedis} from '@keyv/redis';
const secondary = new KeyvRedis('redis://user:pass@localhost:6379');
const cache = new Cacheable({secondary, nonBlocking: true});
CacheSync - Distributed Updates
cacheable
has a feature called CacheSync
that is coming soon. This feature will allow you to have distributed caching with Pub/Sub. This will allow you to have multiple instances of cacheable
running and when a value is set, deleted, or cleared it will update all instances of cacheable
with the same value. Current plan is to support the following:
This feature should be live by end of year.
Cacheable Options
The following options are available for you to configure cacheable
:
primary
: The primary store for the cache (layer 1) defaults to in-memory by Keyv.secondary
: The secondary store for the cache (layer 2) usually a persistent cache by Keyv.nonBlocking
: If the secondary store is non-blocking. Default isfalse
.stats
: To enable statistics for this instance. Default isfalse
.ttl
: The default time to live for the cache in milliseconds. Default isundefined
which is disabled.
Cacheable Statistics (Instance Only)
If you want to enable statistics for your instance you can set the .stats.enabled
property to true
in the options. This will enable statistics for your instance and you can get the statistics by calling the stats
property. Here are the following property statistics:
hits
: The number of hits in the cache.misses
: The number of misses in the cache.sets
: The number of sets in the cache.deletes
: The number of deletes in the cache.clears
: The number of clears in the cache.errors
: The number of errors in the cache.count
: The number of keys in the cache.vsize
: The estimated byte size of the values in the cache.ksize
: The estimated byte size of the keys in the cache.
You can clear / reset the stats by calling the .stats.reset()
method.
This does not enable statistics for your layer 2 cache as that is a distributed cache.
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.getMany([keys])
: Gets multiple values from the cache.has(key)
: Checks if a value exists in the cache.hasMany([keys])
: Checks if multiple values exist in the cache.take(key)
: Takes a value from the cache and deletes it.takeMany([keys])
: Takes multiple values from the cache and deletes them.delete(key)
: Deletes a value from the cache.deleteMany([keys])
: Deletes multiple values from the cache.clear()
: Clears the cache stores. Be careful with this as it will clear both layer 1 and layer 2.wrap(function, WrapOptions)
: Wraps anasync
function in a cache.disconnect()
: Disconnects from the cache stores.onHook(hook, callback)
: Sets a hook.removeHook(hook)
: Removes a hook.on(event, callback)
: Listens for an event.removeListener(event, callback)
: Removes a listener.hash(object: any, algorithm = 'sha256'): string
: Hashes an object with the algorithm. Default issha256
.primary
: The primary store for the cache (layer 1) defaults to in-memory by Keyv.secondary
: The secondary store for the cache (layer 2) usually a persistent cache by Keyv.nonBlocking
: If the secondary store is non-blocking. Default isfalse
.stats
: The statistics for this instance which includeshits
,misses
,sets
,deletes
,clears
,errors
,count
,vsize
,ksize
.
CacheableMemory - In-Memory Cache
cacheable
comes with a built-in in-memory cache called CacheableMemory
. This is a simple in-memory cache that is used as the primary store for cacheable
. You can use this as a standalone cache or as a primary store for cacheable
. Here is an example of how to use CacheableMemory
:
import { CacheableMemory } from 'cacheable';
const options = {
ttl: '1h', // 1 hour
useClones: true, // use clones for the values (default is true)
lruSize: 1000, // the size of the LRU cache (default is 0 which is unlimited)
}
const cache = new CacheableMemory(options);
cache.set('key', 'value');
const value = cache.get('key'); // value
You can use CacheableMemory
as a standalone cache or as a primary store for cacheable
. You can also set the useClones
property to false
if you want to use the same reference for the values. This is useful if you are using large objects and want to save memory. The lruSize
property is the size of the LRU cache and is set to 0
by default which is unlimited. When setting the lruSize
property it will limit the number of keys in the cache.
This simple in-memory cache uses multiple Map objects and a with expiration
and lru
policies if set to manage the in memory cache at scale.
By default we use lazy expiration deletion which means on get
and getMany
type functions we look if it is expired and then delete it. If you want to have a more aggressive expiration policy you can set the checkInterval
property to a value greater than 0
which will check for expired keys at the interval you set.
CacheableMemory Options
ttl
: The time to live for the cache in milliseconds. Default isundefined
which is means indefinitely.useClones
: If the cache should use clones for the values. Default istrue
.lruSize
: The size of the LRU cache. Default is0
which is unlimited.checkInterval
: The interval to check for expired keys in milliseconds. Default is0
which is disabled.
CacheableMemory API
set(key, value, ttl?)
: Sets a value in the cache.setMany([{key, value, ttl?}])
: Sets multiple values in the cache fromCachableItem
.get(key)
: Gets a value from the cache.getMany([keys])
: Gets multiple values from the cache.getRaw(key)
: Gets a value from the cache asCacheableStoreItem
.getManyRaw([keys])
: Gets multiple values from the cache asCacheableStoreItem
.has(key)
: Checks if a value exists in the cache.delete(key)
: Deletes a value from the cache.deleteMany([keys])
: Deletes multiple values from the cache.take(key)
: Takes a value from the cache and deletes it.takeMany([keys])
: Takes multiple values from the cache and deletes them.wrap(function, WrapSyncOptions)
: Wraps async
function in a cache.clear()
: Clears the cache.size()
: The number of keys in the cache.keys()
: The keys in the cache.items()
: The items in the cache asCacheableStoreItem
example{ key, value, expires? }
.checkExpired()
: Checks for expired keys in the cache. This is used by thecheckInterval
property.startIntervalCheck()
: Starts the interval check for expired keys ifcheckInterval
is above 0 ms.stopIntervalCheck()
: Stops the interval check for expired keys.hash(object: any, algorithm = 'sha256'): string
: Hashes an object with the algorithm. Default issha256
.
Wrap / Memoization for Sync and Async Functions
Cacheable
and CacheableMemory
has a feature called wrap
that allows you to wrap a function in a cache. This is useful for memoization and caching the results of a function. You can wrap a sync
or async
function in a cache. Here is an example of how to use the wrap
function:
import { Cacheable } from 'cacheable';
const asyncFunction = async (value: number) => {
return value * 2;
};
const cache = new Cacheable();
const wrappedFunction = cache.wrap(asyncFunction, { ttl: '1h' });
console.log(await wrappedFunction(2)); // 4
console.log(await wrappedFunction(2)); // 4 from cache
In this example we are wrapping an async
function in a cache with a ttl
of 1 hour
. This will cache the result of the function for 1 hour
and then expire the value. You can also wrap a sync
function in a cache:
import { CacheableMemory } from 'cacheable';
const syncFunction = (value: number) => {
return value * 2;
};
const cache = new CacheableMemory();
const wrappedFunction = cache.wrap(syncFunction, { ttl: '1h', key: 'syncFunction' });
console.log(wrappedFunction(2)); // 4
console.log(wrappedFunction(2)); // 4 from cache
console.log(cache.get('syncFunction')); // 4
In this example we are wrapping a sync
function in a cache with a ttl
of 1 hour
. This will cache the result of the function for 1 hour
and then expire the value. You can also set the key
property in the wrap()
options to set a custom key for the cache.
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
.