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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.medable.com/cortex-api/scripting/modules-1/cache-module.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.