Describes utilities in the Javascript API to manage the temporary storage.

sys.storage

This package contains methods to work with the storage. The storage is a temporary key-value data structure you can use to save information for things that span multiple user requests or threads.

It is a temporary data structure because when the app is restarted information could be lost, so you shouldn’t rely on data being available between restarts or upgrades of the app.

get(key, options)

Returns the value stored at the given key.

Parameters

Name Type Required Default Description

key

string

yes

The key of the value to retrieve.

options

object

no

This is a map with options for getting a value. Available option is:

  • decrypt: if true it will decrypt the entry value.

Returns

any - The value at the given key or null if there isn’t any value.

Samples

// puts something in the storage and retrives it

sys.storage.put('key1', 'a');
log('key1: '+sys.storage.get('key1'));


// retrieve sensitive data

sys.storage.put('apiKey', 'd4j6Ls83ndIw2JdnuwUj3bz');
log('apiKey: ' + sys.storage.get('token')); // display api key encrypted
log('apiKey: ' + sys.storage.get('token', {decrypt: true})); // display plain api key

put(key, value, options)

Stores an object or primitive value in the storage.

Parameters

Name Type Required Default Description

key

string

yes

The key used to store the value.

value

any

yes

The value to store. It could be a primitive or an object.

options

object

no

This is a map with options for setting a value. Available options are:

  • ttl: indicates the time to live for that key. It requires to be expressed in milliseconds.
  • encrypt: if true it will encrypt the entry value. This can be useful for storing sensitive data.

Returns

any - The previous value associated with the given key or null if there wasn’t a value associated to it.

Samples

// puts a string and an object in the storage

sys.storage.put('key1', 'a');
log('key1: '+sys.storage.get('key1'));
var obj = {prop1: 'a', prop2: 'b'};
sys.storage.put('key2', obj);
log('key2: '+JSON.stringify(sys.storage.get('key2')));


// puts a key that will live for 1 hours

sys.storage.put('key1', 'a', {ttl: 60 * 60 * 1000});


// encrypts and decrypts a token

sys.storage.put('token', 'Okd4j6', {encrypt: true});
log('token: ' + sys.storage.get('token')); // display token encrypted
log('token: ' + sys.storage.get('token', {decrypt: true})); // display plain token

putIfAbsent(key, value, options)

Stores an object or primitive value in the storage at the given key if it hasn’t been set already.

Parameters

Name Type Required Default Description

key

string

yes

The key used to store the value.

value

any

yes

The value to store. It could be a primitive or an object.

options

object

no

This is a map with options for setting a value. Available options are:

  • ttl: indicates the time to live for that key. It requires to be expressed in milliseconds.
  • encrypt: if true it will encrypt the entry value. This can be useful for storing sensitive data.

Returns

boolean - true if the value was effectively set or false otherwise.

Samples

// puts a value twice over the same key, but second time it shouldn't be stored

sys.storage.put('key1', 'a');
sys.storage.putIfAbsent('key1', 'b');
log('key1: '+sys.storage.get('key1'));

replace(key, value, options)

Replaces the value at the given key. If no value was set at that key, the new value won’t be stored.

Parameters

Name Type Required Default Description

key

string

yes

The key used to store the value.

value

any

yes

The value to store. It could be a primitive or an object.

options

object

no

This is a map with options for setting a value. Available options are:

  • ttl: indicates the time to live for that key. It requires to be expressed in milliseconds.
  • encrypt: if true it will encrypt the entry value. This can be useful for storing sensitive data.

Returns

boolean - true if the value was effectively set or false otherwise.

Samples

// tries to replace the value in two different keys

sys.storage.put('key1', 'a');
sys.storage.replace('key1', 'b');
sys.storage.replace('keyThatDoesNotExist', 'c');
log('key1: '+sys.storage.get('key1'));
log('keyThatDoesNotExist: '+sys.storage.get('keyThatDoesNotExist'));

remove(key)

Removes the value at the given key.

Parameters

Name Type Required Default Description

key

string

yes

The key of the value to remove.

Returns

any - The value at the given key or null if there isn’t any value.

Samples

// puts and remove a value

sys.storage.put('key1', 'a');
log('key1: '+sys.storage.get('key1'));
sys.storage.remove('key1');
log('key1: '+sys.storage.get('key1'));

clear()

Removes all values in the storage.

Samples

// puts and remove a value

sys.storage.put('key1', 'a');
sys.storage.put('key2', 'b');
log('key1: '+sys.storage.get('key1'));
log('key2: '+sys.storage.get('key2'));
sys.storage.clear();
log('key1: '+sys.storage.get('key1'));
log('key2: '+sys.storage.get('key2'));
Back to top