# 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)](https://docs.medable.com/reference#section-cas-key-chk-val-ttl-null-)\
[clear(search='')](https://docs.medable.com/reference#section-clear-search-)\
[count(search='')](https://docs.medable.com/reference#section-count-search-)\
[del(key)](https://docs.medable.com/reference#section-del-key-)\
[find(search='', skip=0, limit=100)](https://docs.medable.com/reference#section-find-search-skip-0-limit-100-)\
[get(key)](https://docs.medable.com/reference#section-get-key-)\
[has(key)](https://docs.medable.com/reference#section-has-key-)\
[list(search='', skip=0, limit=100)](https://docs.medable.com/reference#section-list-search-skip-0-limit-100-)\
[set(key, val, ttl=null)](https://docs.medable.com/reference#section-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;
    }
}
```