Cache (EAP)

You can use the Cache API to store temporary, ephemeral data for fast access. Data stored through this API automatically expires based on the time to live (TTL) setting. For persistent hosted storage, use the Key-Value Store or Custom Entity Store instead.

To start using the Cache API, install the package in your project by running:

1
2
npm install @forge/cache

Next, import the package into your app:

1
2
import cache from '@forge/cache';

// ...
const App = () => {
  // ...
  const cacheClient = cache.connect();

Limitations

Each installation of your app is subject to the limits of Cache API.

TTL recommendations

We’re currently evaluating a suitable minimum and maximum TTL. These values may change partly based on the data collected during the EAP. As such, we strongly suggest that you set appropriate TTL values based on your app’s needs.

If your app requires a higher limit, request a TTL increase through this form. We will review each request and adjust the limit based on demand, available resources, and use case validity.

Tunneling limitation and workaround

During EAP, forge tunnel will not correctly work with the cache.

Meanwhile, if you need to use the tunnel, you can work around this by emulating the Cache API locally. Refer to this snippet for an example. A secondary function in the getClient will automatically detect when used in the tunnel. This function only works with the New native Node.js runtime.

set

Sets a key to a specific string value in the cache. This method replaces any existing value the key currently holds and discards any previous TTL associated with the key.

Method signature

1
2
cacheClient.set(key, value, { ttlSeconds }): Promise<void>;

Example

1
2
await cacheClient.set('example-key', 'example-value');

setIfNotExists

Set a key to hold a string value only if the key does not already exist. It will return null if the key already exists and OK if the key does not exist and has now been overwritten.

Method signature

1
2
cacheClient.setIfNotExists(key, value, { ttlSeconds }): Promise<null | 'OK'>;

Example

1
2
const response = await cacheClient.setIfNotExists('example-key', 'example-value');

get

Get the value of a key. If the key does not exist, null is returned. If the key does exist, it will return the string value.

Method signature

1
2
cacheClient.get(key): Promise<value>;

Example

1
2
const value = await cacheClient.get('example-key');

incrementAndGet

Increments the integer value stored at the specified string key by one. If the key does not exist, it is set to 0 before performing the operation and uses the default value (600s) for TTL. If the value at the key is not an integer, the system will return an error. After the increment operation, it returns the value of the key after the increment.

Method signature

1
2
cacheClient.incrementAndGet(key): Promise<value>;

Example

1
2
const value = await cacheClient.incrementAndGet('example-key');

delete

Removes the specified key and its corresponding value. If the operation is successful, it will return 1 and if it can't find the key, it will return 0.

Method signature

1
2
cacheClient.delete(key): Promise<numberOfKeyDeleted>;

Example

1
2
const numberOfKeysDeleted = await cacheClient.delete('example-key');

decrementAndGet

Decrements the number stored at key by one. If the key does not exist, it is set to 0 before performing the operation and will use the default value (600s) for TTL. If the value at the key is not an integer, an error will be returned. After the decrement operation, it returns the value of key after the decrement.

Method signature

1
2
cacheClient.decrementAndGet(key): Promise<value>;

Example

1
2
const value = await cacheClient.decrementAndGet('example-key');

getAndSet

Gets and returns the old value of the specified key, then sets the new value. If the key does not exist, null is returned.

Method signature

1
2
cacheClient.getAndSet(key, value, { ttlSeconds }): Promise<null | string>;

Example

1
2
const response = await cacheClient.getAndSet('example-key', 'example-value');