Local Storage Agent

import { LocalStorageAgent } from "@fstnetwork/loc-logic-sdk";

For sharing data between tasks of one data process, which can stay persistent for a period of time.

This is similar to session storage, except that "local" data would be stored in etcd key-value store and won't be lost before timeout, even after the original data process task is done.

note

To preserve data permanently, use file storages or database agent instead or use HTTP agent to pass it to another API.

Availability

• ✓ Generic logic
• ✗ Aggregator logic

Write to Local Storage

JSON

async LocalStorageAgent.putJson(key: string, value: any, timeout?: number): Promise<boolean>

Parameter	Description
key	Key of session data
value	Valid JSON data (JavaScript object)
timeout	(Optional) data persistent time (seconds); default 300s

If value is not valid JSON, the agent will throw an error.

tip

value can be a single number (which is also valid for JSON).

String

async LocalStorageAgent.putString(key: string, value: string, timeout?: number): Promise<boolean>

Parameter	Description
key	Key of session data
value	string data
timeout	(Optional) data persistent time (seconds); default 300s

Uint8Array

async LocalStorageAgent.putByteArray(key: string, value: Uint8Array | string, timeout?: number): Promise<boolean>

Parameter	Description
key	Key of session data
value	Uint8Array or string data
timeout	(Optional) data persistent time (seconds); default 300s

Write a value into session storage. The key/value pair will be created if not exist.

The functions return a boolean to indicate if the write action is successful.

info

The data persistent time's upper limit is 86400 seconds (= 1 day).

Example: write JSON object to local storage

const data = {
    name: "Arthur Dent",
    age: 42,
};

await LocalStorageAgent.putJson("data", data);
await LocalStorageAgent.putJson("age", data.age); // single number is valid JSON

warning

The data may not be properly written into local storage without using await.

Example: write string to local storage

await LocalStorageAgent.putString("name", "Arthur Dent"");
await LocalStorageAgent.putString("age", String(age));  // convert a single number to string

Example: write Uint8Array to local storage

await LocalStorageAgent.putByteArray(
    "payload",
    new Uint8Array(ctx.payload.http.body),
);

Read from Local Storage

async LocalStorageAgent.get(key: string): Promise<string | number | object | Uint8Array>

Read a local storage data. The type depends on how the data was written into session storage. If the data is a single number stored with putJson, the return type will be number as well.

If the key is not exist, the agent will return null.

Example

const name = await LocalStorageAgent.get("name"); // returns a string
const data = await LocalStorageAgent.get("data"); // returns a JSON object

const name_in_data = data?.name;
const age_in_data = data?.age;

tip

If you are using TypeScript, you can use type assertions to enforce typeing in your editor:

const name = (await LocalStorageAgent.get("name")) as string;
const age = (await LocalStorageAgent.get("age")) as number;
const data = (await LocalStorageAgent.get("data")) as {
    name: string;
    age: number;
};

Remove from Local Storage

async LocalStorageAgent.delete(key: string): Promise<void>

// or
async LocalStorageAgent.remove(key: string): Promise<void>

Example

await LocalStorageAgent.remove("data");