Cache Module

General purpose key/value storage with searchable keys.

The cache module serves as general purpose key/value storage, accessible from scripts for all principals and for developers from the REST API, using /cache routes.

🚧No ACL
There are no access controls surrounding cache data. Users should keep PHI and PII out of the cache or otherwise ensure only valid principals are pulling out entries.

📘Metered
Cache storage is metered at the same rate as Documents and Media storage.

Import

import cache from 'cache';

Methods

cas(key, chk, val, ttl = null)

Atomic compare and swap.

Arguments

key (String) The cache key to compare and swap.
chk (Object) The value to compare. the update only occurs if chk matches the value in the cache.
val (Object) The value to set.
ttl (Number) Optional time-to-live for cache entry, in seconds.

Returns

updated (Boolean) true if the value was set, or false if the cache value did not initially equal chk.

clear(search='')

Clears cache values starting with search (or the entire cache).

Arguments

search (String) Any keys starting with search are removed. To avoid inadvertently clearing keys, adopt a key naming strategy that guarantees key domains remain segregated. For example, prefix all cache keys involving single sign-on with sso.. Leaving this argument blank will delete the entire cache.

Returns

removed (Number) the number of keys removed.

count(search='')

Returns a count of cache entries starting with search (or the entire cache).

Arguments

search (String) Any keys starting with search are counted.

Returns

count (Number) the number of matching keys.

del(key)

Removes the cache entries with a key matching key.

Arguments

key (String) The key to remove.

Returns

removed (Boolean) true if the value was removed.

find(search='', skip=0, limit=100)

Returns an array of matching entry key/value pairs, sorted by key.

Arguments

search (String) The key filter. All entries starting with search are returned.
skip (Number) The number of entries to skip. Useful for paging.
limit (Number) The maximum number of entries to return, from 1 to 1000.

Returns

entries (Object[]) A list of matching entries.
- key (String) The entry key.
- val (String) The entry value.

get(key)

Returns the value of a cache entry matching key.

Arguments

key (String) The key to match.

Returns

value (Object) Returns the value of the entry, or null if not found.

has(key)

Returns true if a cache entry matching key exists. For use in cases where null is a valid entry value.

Arguments

key (String) The key to match.

Returns

exists (Boolean) Returns true if the entry exists in the cache.

list(search='', skip=0, limit=100)

Returns an array of matching entry metadata, sorted by key. List results may include recently expired keys.

Arguments

search (String) The key filter. All entries starting with search are returned.
skip (Number) The number of entries to skip. Useful for paging.
limit (Number) The maximum number of entries to return, from 1 to 1000.

Returns

entries (Object[]) A list of matching entry metadata.
- key (String) The entry key.
- created (Date) The time the entry was initially created.
- sz (Number) The total size of the cache entry, including overhead.
- exp (Date) For keys with a ttl, the time the entry expires.

set(key, val, ttl = null)

Set or update a cache entry.

Arguments

key (String) The key to set.
val (Object) The value to set.
ttl (Number) Optional time-to-live for cache entry, in seconds.

Examples

slow process ttl caching

import cache from 'cache';
import http from 'http';

let data = cache.get('sites:example.com');
if (!data) {
  data = http.get('https://www.example.com/').body;
  cache.set('sites:example.com', data, 86400); // cache for a day
}
return data;

Atomic increment

import cache from 'cache';

while (1) {
    const curr = cache.get('increment.foo'),
          next = curr + 1;
    if (cache.cas('increment.foo', curr, next)) {
        return next;
    }
}

Last updated 3 years ago

Was this helpful?

import cache from 'cache'; import http from 'http'; let data = cache.get('sites:example.com'); if (!data) { data = http.get('https://www.example.com/').body; cache.set('sites:example.com', data, 86400); // cache for a day } return data;