Caching data

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.

Much like our other storage offerings, storage is isolated per installation.

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();

Each installation of your app is subject to the Cache API's limits. See Cache limits for more details.

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: string, value: string, { ttlSeconds: number }): 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: string, value: string, { ttlSeconds: number }): 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. If the value at the key is not an integer, an error will be returned. After the increment operation, it returns the value of the key after the increment. TTL is optional and will only be set when the key is created; it will not be updated by subsequent increment calls.

Method signature

1
2
cacheClient.incrementAndGet(key: string, { ttlSeconds: number }): 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. 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. TTL is optional and will only be set when the key is created; it will not be updated by subsequent decrement calls.

Method signature

1
2
cacheClient.decrementAndGet(key: string, { ttlSeconds: number }): 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: string, value: string, { ttlSeconds: number }): Promise<null | string>;

Example

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