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. |