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) clear(search='') count(search='') del(key) find(search='', skip=0, limit=100) get(key) has(key) list(search='', skip=0, limit=100) set(key, val, ttl=null)

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;
    }
}