KeyValueStore
KeyValueStore:
object
KeyValueStore is a key-value storage mechanism. It provides an asynchronous API for storing, retrieving, updating,
and deleting key-value pairs. The store is persistent; the data is stored in a SQLite database that's
automatically backed up and restored by Root.
The key is a string and the value is generic type parameter. When loading data into the key-value store,
Root uses JSON.stringify to convert the value into a string for storage. On the way out, Root uses JSON.parse
to convert back to the type-parameter type.
Root automatically creates an instance of KeyValueStore and exposes it via the rootServer.dataStore.appData property.
Type declaration
delete()
Deletes a key-value pair from the store by key.
Parameters
| Parameter | Type | Description |
|---|---|---|
key | string | The key to delete. |
Returns
Promise<void>
A promise that resolves when the key is deleted.
Example
import { rootServer } from '@rootsdk/server-app';
await rootServer.dataStore.appData.delete("myKey");
deleteLike()
Deletes key-value pairs from the store that match a pattern.
Parameters
| Parameter | Type | Description |
|---|---|---|
keyPattern | string | The pattern to match keys against ('_' matches a single character, '%' matches any sequence of zero or more characters, use '\' to escape the special characters '_' and '%'). |
Returns
Promise<void>
A promise that resolves when the matching keys are deleted.
Example
import { rootServer } from '@rootsdk/server-app';
await rootServer.dataStore.appData.deleteLike("user%");
get()
Retrieves a stored value associated with the given key.
Type Parameters
| Type Parameter | Description |
|---|---|
T | The expected type of the stored value. |
Parameters
| Parameter | Type | Description |
|---|---|---|
key | string | The key associated with the stored value. |
Returns
Promise<undefined | T>
A promise that resolves to the stored value or undefined if not found.
Example
import { rootServer } from '@rootsdk/server-app';
const value = await rootServer.dataStore.appData.get<string>("myKey");
select()
Selects key-value pairs from the store that match a key pattern.
Type Parameters
| Type Parameter | Description |
|---|---|
T | The type of the values to retrieve. |
Parameters
| Parameter | Type | Description |
|---|---|---|
keyPattern | string | The pattern to match keys against ('_' matches a single character, '%' matches any sequence of zero or more characters, use '\' to escape the special characters '_' and '%'). |
Returns
Promise<KeyValue<T>[]>
A promise that resolves with an array of matching key-value pairs.
Example
import { rootServer, KeyValue } from '@rootsdk/server-app';
const pairs: KeyValue<string>[] = await rootServer.dataStore.appData.select("myKey%");
selectValue()
Selects values from the store that match a key pattern.
Type Parameters
| Type Parameter | Description |
|---|---|
T | The type of the values to retrieve. |
Parameters
| Parameter | Type | Description |
|---|---|---|
keyPattern | string | The pattern to match keys against ('_' matches a single character, '%' matches any sequence of zero or more characters, use '\' to escape the special characters '_' and '%'). |
Returns
Promise<T[]>
A promise that resolves with an array of matching values.
Example
import { rootServer } from '@rootsdk/server-app';
const values: string[] = await rootServer.dataStore.appData.selectValue("myKey%");
set()
Sets a key-value pair in the store. If the key already exists, it updates the value.
Type Parameters
| Type Parameter | Description |
|---|---|
T | The type of the value to store. |
Parameters
| Parameter | Type | Description |
|---|---|---|
values | KeyValue<T> | KeyValue<T>[] | The key-value pair or an array of key-value pairs to store. Each key-value pair can optionally contain an expiration Date. If you provide an expiration date, that entry will stop being visible in the store when the expiration date passes. Eventually, it will be automatically deleted. |
Returns
Promise<void>
A promise that resolves when the operation is complete.
Example
import { rootServer, KeyValue } from '@rootsdk/server-app';
// set a single key-value pair
await rootServer.dataStore.appData.set({ key: "myKey", value: "myValue" });
// set an array of key-value pairs.
await rootServer.dataStore.appData.set([{ key: 'key1', value: 'value1' }, { key: 'key2', value: 'value2' } ]);
// include an expiration date
const expiresAt = new Date();
expiresAt.setDate(expiresAt.getDate() + 30); // 30 days from now
const keyValue: KeyValue<string> =
{
key: "myKey",
value: "myValue",
expires_at: expiresAt
};
await rootServer.dataStore.appData.set(keyValue);
update()
Updates a value associated with a key. You must include a transformation function to perform the update:
the old value is retrieved, the function is called with the old value, the function's return value is
used as the new value in the key-value store. If the key does not exist, this conceptually becomes a set
operation. The transformation function is applied to the default and the result becomes the value in the set operation.
Type Parameters
| Type Parameter | Description |
|---|---|
T | The type of the value to update. |
Parameters
| Parameter | Type | Description |
|---|---|---|
key | string | The key of the value to update. |
updateFunc | (data: T) => T | A function to apply to the current value. |
defaultValue | T | The default value to use if the key does not exist. |
expires_at? | Date | Optional expiration date for the updated value. |
Returns
Promise<T>
A promise that resolves with the updated value.
Example
import { rootServer } from '@rootsdk/server-app';
// update the value for the key "counter" by applying the passed function
// the last argument in the call is the default value
await rootServer.dataStore.appData.update("counter", (val) => val + 1, 0);