Vault 🔒

The Vault System provides robust mechanisms for secure data storage and management within the mobile app.

Custom Block Code Editor version: 1.8+

Functions

initialize

Description

Initializes a new Vault instance using the provided vaultKey and scope. This method returns a promise that resolves to a vault object with various methods for interacting with the Vault. This method can throw an VaultUserException or any of its children.

Parameters

ParameterTypeDescription
vaultKeystringThe key used to identify the Vault.
scopestringThe scope of the Vault. This can either be "user" or "global" (defaults to "user")

Returns

A Promise that resolves to a Vault Object with the following methods or throws:

MethodDescription
get(key):PromiseRetrieves the value associated with the given key.
set(key, value):PromiseSets the value associated with the given key.
clear():PromiseClears all values from the Vault.
remove(key):PromiseRemoves the value associated with the given key.
keys():PromiseRetrieves a list of all keys in the Vault.
observe(key, observer, errorHandler):PromiseObserves changes to the value associated with the given key.

Scoping

The scope defines who should have access to the data stored within the vault.

ScopeDescription
"user"Vault is accessible only to the currently logged in user.
"global"Vault is available to unauthenticated users and same data is available multiple users.

For safety, if a vault is created with a "user" scope, when the user logs out all interactions with the vault from that moment forward will throw a VaultAccessException

Example
const vault = await Tapcart.actions.vault.initialize("test", "user");
vault.get('myKey')
    .then(value => console.log(value))
    .catch((error)=>{console.log(error)});

Vault Object

Description
The vault object returned by the initialize method provides the following methods for interacting with the Vault.

Get

get(key)

Gets the value associated with the given key.
Returns a promise that resolves to the associated value.

Example
const vault = await Tapcart.actions.vault.initialize("test", "user");
vault.get('myKey')
    .then(value => console.log(value))
    .catch((error)=>{console.log(error)});
const vault = await Tapcart.actions.vault.initialize("test", "user");
vault.get('myKey')
    .then(value => console.log(value))
    .catch((error)=>{console.log(error)});

Set

set(key, value)

Sets the value associated with the given key. Calling set with a null value is the same as calling remove(key)

Params
ParameterTypeDescription
keystringThe key to set.
valuestringThe value to set.
Return

A Promise that resolves true when the action was succesful.

Example
const vault = await Tapcart.actions.vault.initialize("test", "user");
await vault.set('myKey','foo') 
console.log(await vault.get('myKey')) //will print 'foo'

Clear

clear()

Clears all values from the Vault.

Return

Returns a Promise that resolves true when the action was succesful.

Example
const vault = await Tapcart.actions.vault.initialize("test", "user");
await vault.set('myKey','foo') 
console.log(await vault.get('myKey')) //will print 'foo'
await vault.clear()
console.log(await vault.get('myKey')) //will return undefined

Remove

remove(key)

Removes the value associated with the given key.

Params
MethodTypeDescription
keystringThe key to set.
Return

A Promise that resolves true when the action was succesful.

Example
const vault = await Tapcart.actions.vault.initialize("test", "user");
await vault.set('myKey','foo') 
console.log(await vault.get('myKey')) //will print 'foo'
await vault.remove('myKey')
console.log(await vault.get('myKey')) //will return undefined

Keys

keys()

Retrieves a list of all keys in the Vault.

Return

Returns a promise that resolves to an array of key values.

Example
const vault = await Tapcart.actions.vault.initialize("test", "user");
await vault.set('myKey','foo') 
await vault.set('myKey2','bar') 
console.log(await vault.keys()) //will return ['foo','bar']

Observe

observe(key, observer, errorHandler)

Observes changes to the value associated with the given key.

MethodTypeDescription
keystringThe key to observe.
observerfunctionA function to call when the value changes. Will receive the current value upon registration.
errorHandlerfunctionA function to call when an error occurs.
Return

Returns a promise that resolves when the observer is fully registered and can begin listening for updates.

Example
const vault = await Tapcart.actions.vault.initialize("test", "user");
await vault.set('myKey','foo') 
await vault.observe('myKey',(value)=>{console.log(value}),(error)=>{console.log(error)}}
await vault.set('myKey','bar')  //    ^ the observer will log 'bar'

Error Handling

The Vault System introduces various classes for handling different types of errors:
These are availble for use with instanceof under

Tapcart.actions.vault.errorTypes //returns an array of the possible Exception types
ExceptionDescription
VaultUserExceptionThrown when there is a general error related to the Vault.
VaultAccessExceptionThrown when there is an access-related error.
VaultBuildExceptionThrown when there is a Vault construction-related error.
VaultInvalidArgumentExceptionThrown when an invalid argument is passed.
VaultInvalidScopeExceptionThrown when there is an error related to the scope.
VaultScopeModificationExceptionThrown when a vault is already loaded with a different scope.
VaultUserIdentifierExceptionThrown when there is an identifier-related error.