Search
⌃K
Comment on page

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.
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.
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;
}
}
Previous
Base64 Module
Next
Connections Module
Last modified 2yr ago