Cache List

Install

$ npm install cache-list

How to use

import { MemoryCache } from 'cache-list';

const cache = new MemoryCache({
    defaultDuration: 600, // 10 min
});

const data = [
    {
        name: 'Tom',
        age: 35
    },
    {
        name: 'Emma',
        age: 29
    }
];

cache.set('users', data, 3600); // 60 min

if (cache.exists('users')) {
    return cache.get('users');
}

List:

• MemoryCache
• RedisCache

Properties

• defaultDuration [integer] - Default duration in seconds before a cache entry will expire.
• keyPrefix [string] - A string prefixed to every cache key so that it is unique globally in the whole cache storage.
• serialization [boolean] - Store serialized or unserialized cached data.

Methods

• buildKey - Builds a normalized cache key from a given key.
• exists - Checks whether a specified key exists in the cache.
• get - Retrieves a value from cache with a specified key.
• multiGet - Retrieves multiple values from cache with the specified keys.
• set - Stores a value identified by a key into cache.
• multiSet - Stores multiple items in cache. Each item contains a value identified by a key.
• add - Stores a value identified by a key into cache if the cache does not contain this key.
• multiAdd - Stores multiple items in cache. Each item contains a value identified by a key.
• delete - Deletes a value with the specified key from cache.
• flush - Deletes all values from cache.

Property Details

defaultDuration

Default duration in seconds before a cache entry will expire. Default value is 0, meaning infinity. This value is used by set() if the duration is not explicitly given.

keyPrefix

A string prefixed to every cache key so that it is unique globally in the whole cache storage. It is recommended that you set a unique cache key prefix for each application if the same cache storage is being used by different applications.

To ensure interoperability, only alphanumeric characters should be used.

serialization

If this property is set false, data will be directly sent to and retrieved from the cache component without any serialization or deserialization.

Method Details

buildKey

Builds a normalized cache key from a given key.

If the given key is a string containing alphanumeric characters only and no more than 32 characters, then the key will be returned back prefixed with keyPrefix. Otherwise, a normalized key is generated by serializing the given key, applying MD5 hashing, and prefixing with keyPrefix.

buildKey(key)
key	mixed	The key to be normalized
return	string	The generated cache key

exists

Checks whether a specified key exists in the cache.

This can be faster than getting the value from the cache if the data is big.

exists(key)
key	mixed	A key identifying the cached value. This can be a simple string or a complex data structure consisting of factors representing the key.
return	boolean	True if a value exists in cache, false if the value is not in the cache or expired.

get

Retrieves a value from cache with a specified key.

get(key)
key	mixed	A key identifying the cached value. This can be a simple string or a complex data structure consisting of factors representing the key.
return	mixed	The value stored in cache, false if the value is not in the cache, expired, or the dependency associated with the cached data has changed.

multiGet

Retrieves multiple values from cache with the specified keys.

Some caches allow retrieving multiple cached values at the same time, which may improve the performance. In case a cache does not support this feature natively, this method will try to simulate it.

multiGet(key)
key	string[]	List of string keys identifying the cached values
return	mixed	List of cached values corresponding to the specified keys. The array is returned in terms of (key, value) pairs. If a value is not cached or expired, the corresponding array value will be false.

set

Stores a value identified by a key into cache.

If the cache already contains such a key, the existing value and expiration time will be replaced with the new ones, respectively.

set(key, value, duration)
key	mixed	A key identifying the value to be cached. This can be a simple string or a complex data structure consisting of factors representing the key.
value	mixed	The value to be cached
duration	integer	The number of seconds in which the cached value will expire. 0 means never expire. If not set, default defaultDuration value is used.
return	string	Whether the value is successfully stored into cache

multiSet

Stores multiple items in cache. Each item contains a value identified by a key.

If the cache already contains such a key, the existing value and expiration time will be replaced with the new ones, respectively.

multiSet(items, duration)
items	mixed	The items to be cached, as key-value pairs.
duration	integer	Default number of seconds in which the cached values will expire. 0 means never expire.
return	string	Array of failed keys

add

Stores a value identified by a key into cache if the cache does not contain this key.

Nothing will be done if the cache already contains the key.

add(key, value, duration)
key	mixed	A key identifying the value to be cached. This can be a simple string or a complex data structure consisting of factors representing the key.
value	mixed	The value to be cached
duration	integer	The number of seconds in which the cached value will expire. 0 means never expire. If not set, default defaultDuration§ value is used.
return	string	Whether the value is successfully stored into cache

multiAdd

Stores multiple items in cache. Each item contains a value identified by a key.

If the cache already contains such a key, the existing value and expiration time will be preserved.

multiAdd(items, duration)
items	mixed	The items to be cached, as key-value pairs.
duration	integer	Default number of seconds in which the cached values will expire. 0 means never expire.
return	string	Array of failed keys

delete

Deletes a value with the specified key from cache.

delete(key)
key	mixed	A key identifying the value to be deleted from cache. This can be a simple string or a complex data structure consisting of factors representing the key.
return	boolean	If no error happens during deletion

flush

Deletes all values from cache.

Be careful of performing this operation if the cache is shared among multiple applications.

flush()
return	boolean	Whether the flush operation was successful.

MemoryCache

Use memory as a storage.

RedisCache

Use Redis as a storage.

Properties

• isSharedDatabase [boolean] - If you use a separated database to store a cache, set keyPrefix
• clientOptions [object] - Config for redis connections. You can find a full list of redis client options here.

const cache = new RedisCache();

const cache = new RedisCache({
    clientOptions: {
        db: 2
    }
});

const cache = new RedisCache(
    {
        isSharedDatabase: true,
        keyPrefix: 'active_users',
        clientOptions: {
            db: 1
        }
    }
);

Redis Client Options

Property	Default	Description
host	127.0.0.1	IP address of the Redis server
port	6379	Port of the Redis server
path	null	The UNIX socket string of the Redis server
url	null	The URL of the Redis server. Format: [redis[s]:]//[[user][:password@]][host][:port][/db-number][?db=db-number[&password=bar[&option=value]]] (More info avaliable at IANA).
family	IPv4	You can force using IPv6 if you set the family to 'IPv6'. See Node.js net or dns modules on how to use the family type.
db	null	If set, client will run Redis select command on connect.
password	null	If set, client will run Redis auth command on connect. Alias auth_pass Note Node Redis < 2.5 must use auth_pass
socket_keepalive	true	If set to true, the keep-alive functionality is enabled on the underlying socket.
socket_initial_delay	0	Initial Delay in milliseconds, and this will also behave the interval keep alive message sending to Redis.
enable_offline_queue	true	By default, if there is no active connection to the Redis server, commands are added to a queue and are executed once the connection has been established. Setting enable_offline_queue to false will disable this feature and the callback will be executed immediately with an error, or an error will be emitted if no callback is specified.
retry_unfulfilled_commands	false	If set to true, all commands that were unfulfilled while the connection is lost will be retried after the connection has been reestablished. Use this with caution if you use state altering commands (e.g. incr). This is especially useful if you use blocking commands.
disable_resubscribing	false	If set to true, a client won't resubscribe after disconnecting.