cache

↓ Classes.

↓ Members.

↓ Methods.

module:cache

Description:

  • Cache module for shared cache and subscriptions.

    Some drivers (Redis) may support TTL so global options.ttl or local options.ttl can be used for put/incr operations and it will be honored if it is suported.

    For caches that support maps, like Redis the 8options.mapName* can be used with get/put/incr/del to work with maps and individual keys inside maps.

    All methods use options.cacheName for non-default cache. If it is an array then a client will be picked sequentially by maintaining internal sequence number.

    Empty default client always exists, it can be overridden to make default some other driver

    To enable stats collection for a cache it must be enabled with config: cache-redis-options-metrics=1

    The class module:cache.CacheClient defines the methods that a driver may or may not implement.

    The url query parameters that start with bk- will be extracted from the url and placed in the class *options object, this is a way to pass special properties without using cache-options, the rest of the url parameters will be passed to the driver.

Source:
Example
cache-default=redis://
cache-redis=redis://?bk-enable_offline_queue=1
cache-config={ "limiter": "local://", "redis": "redis://" }

Classes
CacheClient
LocalClient
RedisClient
WorkerClient

Members

(inner) args :Array.<ConfigOptions>

Source:

Methods

(async, static) aclear(pattern, optionsopt)

Description:
Source:
Parameters:
Name Type Attributes Description
pattern string
options object <optional>
Example
const { err, data } = await cache.aclear("key:*");

(async, static) adel(key, optionsopt)

Description:
Source:
Parameters:
Name Type Attributes Description
key string
options object <optional>
Example
const { err, data } = await cache.adel("key");

(async, static) aget(key, optionsopt)

Description:
Source:
Parameters:
Name Type Attributes Description
key string | Array.<string>
options object <optional>
Example
const { err, data } = await cache.aget("key");

(async, static) aincr(key, val, optionsopt)

Description:
Source:
Parameters:
Name Type Attributes Description
key string
val number
options object <optional>
Example
const { err, data } = await cache.aincr("key", 10);

(async, static) alock(name, optionsopt)

Description:
Source:
Parameters:
Name Type Attributes Description
name string
options object <optional>
Example
const { err, locked } = await cache.alock("key", { ttl: 1000 });

(async, static) aput(key, val, optionsopt)

Description:
Source:
Parameters:
Name Type Attributes Description
key string
val string | object
options object <optional>
Example
const { err, data } = await cache.aput("key", { ... });

(async, static) astats(optionsopt)

Description:
Source:
Parameters:
Name Type Attributes Description
options object <optional>
Example
const { err, data } = await cache.astats();

(async, static) aunlock(name, optionsopt)

Description:
Source:
Parameters:
Name Type Attributes Description
name string
options object <optional>
Example
const { err, data } = await cache.aunlock("key");

(static) checkConfig()

Description:

  • Initialize missing or new clients, existing clients stay the same

Source:

(static) checkLimiter(options)

Description:

  • Keep checking the limiter until it is clear to proceed with the operation, if there is no available tokens in the bucket it will wait and try again until the bucket is filled.

    The callback will receive the same arguments as module:cache.limiter. options._retries will be set to how many times it tried.

Source:
Parameters:
Name Type Description
options object

same as in module:cache.limiter

Properties
Name Type Attributes Description
retry int <optional>

To never retry pass -1 or number of loops to run before exiting

(static) clear(pattern, optionsopt, callbackopt)

Description:

  • Clear all or only items that match the given pattern

Source:
Parameters:
Name Type Attributes Description
pattern string
options object <optional>
callback function <optional>

(static) createClient()

Description:

  • Return a new client for the given host or null if not supported

Source:

(static) del(key, optionsopt, callbackopt)

Description:

  • Delete an item by key(s), if key is an array all keys will be deleted at once atomically if supported

Source:
Parameters:
Name Type Attributes Description
key string
options object <optional>
Properties
Name Type Attributes Description
mapName string <optional>

defines a map from which the counter will be deleted if the cache supports maps, to delete the whole map the key must be set to *
listName string <optional>

defines a list from which an item should be removed
callback function <optional>
Example
cache.del("my:key")
cache.del("key1", { mapName: "my:map" })
cache.del("*", { mapName: "my:map" })
cache.del("1", { listName: "my:list" })

(static) get(key, optionsopt, callback)

Description:

  • Retrieve an item from the cache by key.

Source:
Parameters:
Name Type Attributes Description
key string | Array.<string>

If the key is an array then it returns an array with values for each key, for non existent keys an empty string will be returned. For maps only if the key is * it will return the whole object, otherwise only value(s) are returned.
options object <optional>
Properties
Name Type Attributes Description
del boolean <optional>

is given then it will delete the key after returning, i.e. Redis GETDEL op
set any <optional>

if given and no value exists in the cache it will be set as the initial value, still nothing will be returned to signify that a new value assigned.
mapName string <optional>

defines a map from which the key will be retrieved if the cache supports maps, to get the whole map the key must be set to *
listName string <optional>

defines a map from which to get items, if a key is given it will return 1 if it belongs to the list, if no key is provided it will return an array with 2 elements: [a random key, the length of the list], to get the whole list specify * as the key. Specifying del in the options will delete returned items from the list.
ttl int <optional>

can be used with lists with del and empty key, in such case all popped up keys will be saved in the cache with specified time to live, when being popped up every key is checked if it has been served already, i.e. it exists in the cache and not expired yet, such keys are ignored and only never seen keys are returned
datatype string <optional>

specifies that the returned value must be converted into the specified type using lib.toValue
callback function
Example
cache.get(["my:key1", "my:key2"], function(err, data) { console.log(data) });
cache.get("my:key", function(err, data) { console.log(data) });
cache.get("my:counter", { set: 10 }, function(err, data) { console.log(data) });
cache.get("*", { mapName: "my:map" }, function(err, data) { console.log(data) });
cache.get("key1", { mapName: "my:map" }, function(err, data) { console.log(data) });
cache.get(["key1", "key2"], { mapName: "my:map" }, function(err, data) { console.log(data) });
cache.get(["key1", "key2"], { listName: "my:list" }, function(err, data) { console.log(data) });
cache.get("", { listName: "my:list", del: 1 }, function(err, data) { console.log(data) });
cache.get("", { listName: "my:list", del: 1, ttl: 30000 }, function(err, data) { console.log(data) });

(static) getClient(optionsopt) → {module:cache.CacheClient}

Description:

  • Return a cache client by name if specified in the options or use default client which always exists, use cacheName to specify a specific driver. If it is an array it will rotate items sequentially.

Source:
Parameters:
Name Type Attributes Description
options object <optional>
Returns:
Type Description
module:cache.CacheClient

(static) incr(key, val, optionsopt, callbackopt)

Description:

  • Increase/decrease a counter in the cache by val, non existent items are treated as 0, if a callback is given an error and the new value will be returned.

Source:
Parameters:
Name Type Attributes Description
key string | Array.<string>
  • if key is an array then increment each item in the list with given val number, in this case ttl can be an array as well with specific ttl per key
val int | object
  • if val is an object then all numeric properties will be incremented, other properties just set.
  • if val is an object then either mapName or non empty key is used for map
  • if val is an object and the key is empty then all properties are treated as standalone items
options object <optional>
Properties
Name Type Attributes Description
ttl int <optional>

in milliseconds can be used if the driver supports it
mapName string <optional>

defines a map where the counter will be stored if the cache supports maps
returning string <optional>

return old or new map object, if new or * it will be the first item in the result array, if old the last, to return all values for multi updates it must be provided, otherwise only first result by default.
callback function <optional>
Example
cache.incr("my:key", 1)
cache.incr("counter", 1, { mapName: "my:map" })
cache.incr("my:map", { count: 1, name: "aaa", mtime: Date.now().toString() })
cache.incr("", { count: 1, name: "bbb", mtime: Date.now().toString() }, { mapName: "my:map" })
cache.incr("", { "my-key": 1, counter2: 2 })
cache.incr([ "my:key", "my:counter"], 1 }, { ttl: [1000, 30000] })

(static) initClients()

Description:

  • Reinitialize a client for cache purposes, previous client will be closed.

Source:

(static) limiter(options, callback)

Description:

  • Check for rate limit using the default or specific cache, by default TokenBucket using local LRU cache is used unless a client provides its own implementation.

Source:
Parameters:
Name Type Description
options object
Properties
Name Type Attributes Description
name string

unique id, can be IP address, account id, etc...
max int

the maximum burst capacity
rate int

the rate to refill tokens
interval int

interval for the bucket refills, default 1000 ms
ttl int <optional>

auto expire after specified ms since last use
reset boolean <optional>

if true reset the token bucket if not consumed or the total reached this value if it is a number greater than 1
multiplier int <optional>

multiply the interval after it consumed all tokens, subsequent checks use the increased interval, fractions supported, if the multiplier is positive then the interval will keep increasing indefinitely, if it is negative the interval will reset to the default value on first successful consumption
callback function

takes 2 arguments:

  • delay is a number of milliseconds till the bucket can be used again if not consumed, i.e. 0 means consumed.
  • info is an object with info about the state of the token bucket after the operation with properties: delay, count, total, elapsed

(static) localLimiter(msg) → {object}

Description:

  • Uses local limiter returns the same message with consumed set to 1 or 0

Source:
Parameters:
Name Type Description
msg object
Properties
Name Type Description
name string
Returns:
Type Description
object

(static) lock(name, optionsopt, callbackopt)

Description:

  • Implementation of a lock with optional ttl, only one instance can lock it, can be for some period of time and will expire after timeout.

    This is intended to be used for background job processing or something similar when only one instance is needed to run. At the end of the processing module.cache.unlock must be called to enable another instance immediately, otherwise it will be available after the ttl only.

    The callback must be passed which will take an error and a boolean value, if true is returned it means the timer has been locked by the caller, otherwise it is already locked by other instance. In case of an error the lock is not supposed to be locked by the caller.

Source:
Parameters:
Name Type Attributes Description
name string

unique lock name
options object <optional>
Properties
Name Type Attributes Description
ttl int <optional>

ttl period in milliseconds.
timeout int <optional>

if given the function will keep trying to lock for the timeout milliseconds.
set boolean <optional>

if given it will unconditionally set the lock for the specified ttl, this is for cases when the lock must be active for longer because of the long running task
callback function <optional>
Example
cache.lock("my-lock", { ttl: 60000, timeout: 30000 }, (err, locked) => {
  if (locked) {
      ...
      cache.unlock("my-lock");
  }
});

(static) put(key, val, optionsopt, callbackopt)

Description:

  • Replace or put a new item in the cache.

Source:
Parameters:
Name Type Attributes Description
key string
val string | object
options object <optional>
Properties
Name Type Attributes Description
ttl int <optional>

can be passed in milliseconds if the driver supports it
mapName string <optional>

defines a map where the counter will be stored if the cache supports maps, to store the whole map in one operation the key must be empty or * and the val must be an object
setmax boolean <optional>

if not empty tell the driver to set this new number only if there is no existing value or it is less that the new number, only works for numeric values
listName string <optional>

defines a list where to add items, val can be a value or an array of values, key is ignored in this case. Returns an array with 2 items: [added, total] where added is how many iterms just added and the total number of items in the list after the operation.
callback function <optional>
Example
cache.put("my:key", 2)
cache.put("my:key", 1, { setmax: 1 })
cache.put("key1", 1, { mapName: "my:map" })
cache.put("*", { key1: 1, key2: 2 }, { mapName: "my:map" })
cache.put("", [1,2,3], { listName: "my:list" }, (err, rc) => { })

(static) shutdown()

Description:

  • Close all existing clients except empty local client

Source:

(static) stats(optionsopt, callbackopt)

Description:

  • Returns the cache statistics, the format depends on the cache type used

Source:
Parameters:
Name Type Attributes Description
options object <optional>
callback function <optional>

(static) unlock(name, optionsopt, callbackopt)

Description:

  • Unconditionally unlock the lock by key, any client can unlock any lock.

Source:
Parameters:
Name Type Attributes Description
name string
options object <optional>
callback function <optional>