Class NonLocalStorage

Provides a persistent, optionally encrypted, remote key-value store. Supports atomic operations, TTL, and presence via websockets.

Remarks

Use this class to interact with the Vaultrice API for storing and retrieving data.

Hierarchy

default
- NonLocalStorage

Constructors

constructor

new NonLocalStorage(
    credentials: {
        apiKey?: string;
        apiSecret?: string;
        accessToken?: string;
        projectId: string;
    },
    id?: string,
): NonLocalStorage
Create a NonLocalStorage instance.
Parameters
- credentials: { apiKey?: string; apiSecret?: string; accessToken?: string; projectId: string }
  API credentials.
- Optionalid: string
  Optional ID.
Returns NonLocalStorage
Overrides WebSocketFunctions.constructor
- Defined in NonLocalStorage.ts:28
new NonLocalStorage(
    credentials: {
        apiKey?: string;
        apiSecret?: string;
        accessToken?: string;
        projectId: string;
    },
    options?: InstanceOptions,
): NonLocalStorage
Create a NonLocalStorage instance.
Parameters
- credentials: { apiKey?: string; apiSecret?: string; accessToken?: string; projectId: string }
  API credentials.
- Optionaloptions: InstanceOptions
  Optional instance options.
Returns NonLocalStorage
Overrides WebSocketFunctions.constructor
- Defined in NonLocalStorage.ts:42

Properties

id

id: string

Unique instance identifier

isConnected

isConnected: boolean = false

Indicates if the WebSocket connection is currently established. True if connected, false otherwise.

Methods

`Static`retrieveAccessToken

retrieveAccessToken(
    projectId: string,
    apiKey: string,
    apiSecret: string,
): Promise<string>
Retrieves an access token for a given project using API credentials.
Parameters
- projectId: string
  The unique identifier of the project.
- apiKey: string
  The API key associated with the project.
- apiSecret: string
  The API secret associated with the project.
Returns Promise<string>
A promise that resolves to the access token as a string.
Example
```
const token = await NonLocalStorage.retrieveAccessToken('projectId', 'apiKey', 'apiSecret');
```
Inherited from WebSocketFunctions.retrieveAccessToken
- Defined in Base.ts:247

useAccessToken

useAccessToken(accessToken: string): number
Sets the access token to be used for authentication.
Parameters
- accessToken: string
  The access token string to set.
Returns number
token expiration in milliseconds from now
Inherited from WebSocketFunctions.useAccessToken
- Defined in Base.ts:305

onAccessTokenExpiring

onAccessTokenExpiring(handler: () => void): void
Registers a handler function to be called when the access token is about to expire.
Parameters
- handler: () => void
  A callback function that will be invoked before the access token expires.
Returns void
Inherited from WebSocketFunctions.onAccessTokenExpiring
- Defined in Base.ts:321

offAccessTokenExpiring

offAccessTokenExpiring(handler: () => void): void
Removes a previously registered handler for the access token expiring event.
Parameters
- handler: () => void
  The callback function to remove from the access token expiring handlers list.
Returns void
Inherited from WebSocketFunctions.offAccessTokenExpiring
- Defined in Base.ts:330

getEncryptionSettings

getEncryptionSettings(saltLength?: number): Promise<EncryptionSettingsInfos>
Retrieve or initialize encryption settings for end-to-end encryption.
Parameters
- OptionalsaltLength: number
  Optional salt length in bytes (default: 16).
Returns Promise<EncryptionSettingsInfos>
Promise resolving to encryption settings information.

Throws
Error if called without encryption configuration.

Remarks
This method is mandatory when using end-to-end encryption. It fetches the encryption salt and key version from the server, then initializes the encryption handler.
Inherited from WebSocketFunctions.getEncryptionSettings
- Defined in Base.ts:414

rotateEncryption

rotateEncryption(saltLength?: number): Promise<EncryptionSettingsInfos>
Rotate encryption keys to enhance security.
Parameters
- OptionalsaltLength: number
  Optional salt length in bytes (default: 16).
Returns Promise<EncryptionSettingsInfos>
Promise resolving to new encryption settings information.

Throws
Error if called without encryption configuration.

Remarks
This generates new encryption settings while preserving access to data encrypted with previous keys. Useful for periodic security rotation.
Inherited from WebSocketFunctions.rotateEncryption
- Defined in Base.ts:434

setItem

setItem(
    name: string,
    value: ValueType,
    options?: { ttl?: number; ifAbsent?: boolean },
): Promise<undefined | SetReturnType>
Store a value by key.
Parameters
- name: string
  The key name.
- value: ValueType
  The value to store.
- Optionaloptions: { ttl?: number; ifAbsent?: boolean }
  Optional overrides.
  - Optionalttl?: number
    Time-to-live in milliseconds for this item.
  - OptionalifAbsent?: boolean
    If true only set if item absent.
Returns Promise<undefined | SetReturnType>
Metadata about the stored item.
Default
```
3600000 (1 hour)
```
Default
```
false
```
- Defined in NonLocalStorage.ts:84

setItems

setItems(
    items: Record<
        string,
        { value: ValueType; ttl?: number; ifAbsent?: boolean },
    >,
): Promise<undefined | SetItemsType>
Store multiple values at once.
Parameters
- items: Record<string, { value: ValueType; ttl?: number; ifAbsent?: boolean }>
  Object of key/value pairs. Example: { key1: { value: 'foo' }, key2: { value: 'bar', ttl: 3600000 }, key2: { value: 'zip', ifAbsent: true } } ttl is time-to-live in milliseconds for each item.
Returns Promise<undefined | SetItemsType>
Metadata for each stored item.
Default
3600000 (1 hour) ifAbsent if true only set if item absent - for each item.
Default
```
false
```
- Defined in NonLocalStorage.ts:125

getItem

getItem<T = ValueType>(name: string): Promise<undefined | ItemType<T>>
Retrieve a value by key.
Type Parameters
- T = ValueType
Parameters
- name: string
  The key name.
Returns Promise<undefined | ItemType<T>>
The item, or undefined if not found.
- Defined in NonLocalStorage.ts:164

getItems

getItems(names: string[]): Promise<undefined | ItemsType>
Retrieve multiple values by key.
Parameters
- names: string[]
  Array of key names.
Returns Promise<undefined | ItemsType>
Object of items found.
- Defined in NonLocalStorage.ts:209

getAllItems

getAllItems(options?: { prefix?: string }): Promise<undefined | ItemsType>
Retrieve all items, optionally filtered by prefix.
Parameters
- Optionaloptions: { prefix?: string }
  Optional prefix filter.
Returns Promise<undefined | ItemsType>
Object of all items.
- Defined in NonLocalStorage.ts:274

getAllKeys

getAllKeys(options?: { prefix?: string }): Promise<undefined | string[]>
Get all keys, optionally filtered by prefix.
Parameters
- Optionaloptions: { prefix?: string }
  Optional prefix filter.
Returns Promise<undefined | string[]>
Array of key names.
- Defined in NonLocalStorage.ts:316

removeItem

removeItem(name: string): Promise<undefined>
Remove a value by key.
Parameters
- name: string
  The key name.
Returns Promise<undefined>
- Defined in NonLocalStorage.ts:325

removeItems

removeItems(names: string[]): Promise<undefined>
Remove multiple values by key.
Parameters
- names: string[]
  Array of key names.
Returns Promise<undefined>
- Defined in NonLocalStorage.ts:335

incrementItem

incrementItem(
    name: string,
    value?: number,
    options?: { ttl?: number },
): Promise<ItemType>
Atomically increment a numeric value.
Parameters
- name: string
  The key name.
- value: number = 1
  Amount to increment by (default 1).
- Optionaloptions: { ttl?: number }
  Optional TTL override.
Returns Promise<ItemType>
The updated item.
- Defined in NonLocalStorage.ts:348

decrementItem

decrementItem(
    name: string,
    value?: number,
    options?: { ttl?: number },
): Promise<ItemType>
Atomically decrement a numeric value.
Parameters
- name: string
  The key name.
- value: number = 1
  Amount to decrement by (default 1).
- Optionaloptions: { ttl?: number }
  Optional TTL override.
Returns Promise<ItemType>
The updated item.
- Defined in NonLocalStorage.ts:374

clear

clear(): Promise<undefined>
Remove all items for this instance.

Returns Promise<undefined>
- Defined in NonLocalStorage.ts:396

send

send(msg: JSONObj, options?: { transport?: "ws" | "http" }): Promise<undefined>
Send a message to the server or other clients.
Parameters
- msg: JSONObj
  The message object to send.
- options: { transport?: "ws" | "http" } = ...
  Transport options (WebSocket or HTTP).
Returns Promise<undefined>
Throws
Error if encryption is configured but getEncryptionSettings() not called.

Remarks
Messages are automatically encrypted if encryption is configured. WebSocket transport is preferred for real-time delivery, but HTTP can be used as fallback.
Example
```
await instance.send({ type: 'chat', message: 'Hello everyone!' });
// Send via HTTP instead of WebSocket
await instance.send({ data: 'important' }, { transport: 'http' });
```
Inherited from WebSocketFunctions.send
- Defined in Ws.ts:137

on

on(event: "connect", handler: () => void): any
Register an event handler for WebSocket connection events.
Parameters
- event: "connect"
  The 'connect' event name.
- handler: () => void
  Function to call when connected.
Returns any
Inherited from WebSocketFunctions.on
- Defined in Ws.ts:170
on(event: "disconnect", handler: () => void): any
Register an event handler for WebSocket disconnection events.
Parameters
- event: "disconnect"
  The 'disconnect' event name.
- handler: () => void
  Function to call when disconnected.
Returns any
Inherited from WebSocketFunctions.on
- Defined in Ws.ts:176
on(
event: "presence:join",
handler: (joinedConnection: JoinedConnection) => void,
): any
Register an event handler for presence join events.
Parameters
- event: "presence:join"
  The 'presence:join' event name.
- handler: (joinedConnection: JoinedConnection) => void
  Function to call when a connection joins.
Returns any
Inherited from WebSocketFunctions.on
- Defined in Ws.ts:182
on(
event: "presence:leave",
handler: (leavedConnection: LeavedConnection) => void,
): any
Register an event handler for presence leave events.
Parameters
- event: "presence:leave"
  The 'presence:leave' event name.
- handler: (leavedConnection: LeavedConnection) => void
  Function to call when a connection leaves.
Returns any
Inherited from WebSocketFunctions.on
- Defined in Ws.ts:188
on(event: "message", handler: (data: JSONObj) => void): any
Register an event handler for incoming messages.
Parameters
- event: "message"
  The 'message' event name.
- handler: (data: JSONObj) => void
  Function to call when a message is received.
Returns any
Inherited from WebSocketFunctions.on
- Defined in Ws.ts:194
on(event: "error", handler: (error: Error) => void): any
Register an event handler for WebSocket errors.
Parameters
- event: "error"
  The 'error' event name.
- handler: (error: Error) => void
  Function to call when an error occurs.
Returns any
Inherited from WebSocketFunctions.on
- Defined in Ws.ts:200
on(
    event: "setItem",
    handler: (
        item: { value: ValueType } & SetReturnType & { prop: string },
    ) => void,
): any
Register an event handler for all setItem events.
Parameters
- event: "setItem"
  The 'setItem' event name.
- handler: (item: { value: ValueType } & SetReturnType & { prop: string }) => void
  Function to call when any item is set.
Returns any
Inherited from WebSocketFunctions.on
- Defined in Ws.ts:206
on(
    event: "setItem",
    name: string,
    handler: (
        item: { value: ValueType } & SetReturnType & { prop: string },
    ) => void,
): any
Register an event handler for specific setItem events.
Parameters
- event: "setItem"
  The 'setItem' event name.
- name: string
  The specific item name to listen for.
- handler: (item: { value: ValueType } & SetReturnType & { prop: string }) => void
  Function to call when the named item is set.
Returns any
Inherited from WebSocketFunctions.on
- Defined in Ws.ts:213
on(event: "removeItem", handler: (item: { prop: string }) => void): any
Register an event handler for all removeItem events.
Parameters
- event: "removeItem"
  The 'removeItem' event name.
- handler: (item: { prop: string }) => void
  Function to call when any item is removed.
Returns any
Inherited from WebSocketFunctions.on
- Defined in Ws.ts:219
on(
    event: "removeItem",
    name: string,
    handler: (item: { prop: string }) => void,
): any
Register an event handler for specific removeItem events.
Parameters
- event: "removeItem"
  The 'removeItem' event name.
- name: string
  The specific item name to listen for.
- handler: (item: { prop: string }) => void
  Function to call when the named item is removed.
Returns any
Inherited from WebSocketFunctions.on
- Defined in Ws.ts:226

off

off(event: "connect", handler: () => void): any
Remove an event handler for WebSocket connection events.
Parameters
- event: "connect"
  The 'connect' event name.
- handler: () => void
  Function to remove.
Returns any
Inherited from WebSocketFunctions.off
- Defined in Ws.ts:428
off(event: "disconnect", handler: () => void): any
Remove an event handler for WebSocket disconnection events.
Parameters
- event: "disconnect"
  The 'disconnect' event name.
- handler: () => void
  Function to remove.
Returns any
Inherited from WebSocketFunctions.off
- Defined in Ws.ts:434
off(
event: "presence:join",
handler: (joinedConnection: JoinedConnection) => void,
): any
Remove an event handler for presence join events.
Parameters
- event: "presence:join"
  The 'presence:join' event name.
- handler: (joinedConnection: JoinedConnection) => void
  Function to remove.
Returns any
Inherited from WebSocketFunctions.off
- Defined in Ws.ts:440
off(
event: "presence:leave",
handler: (leavedConnection: LeavedConnection) => void,
): any
Remove an event handler for presence leave events.
Parameters
- event: "presence:leave"
  The 'presence:leave' event name.
- handler: (leavedConnection: LeavedConnection) => void
  Function to remove.
Returns any
Inherited from WebSocketFunctions.off
- Defined in Ws.ts:446
off(event: "message", handler: (data: JSONObj) => void): any
Remove an event handler for incoming messages.
Parameters
- event: "message"
  The 'message' event name.
- handler: (data: JSONObj) => void
  Function to remove.
Returns any
Inherited from WebSocketFunctions.off
- Defined in Ws.ts:452
off(event: "error", handler: (error: Error) => void): any
Remove an event handler for WebSocket errors.
Parameters
- event: "error"
  The 'error' event name.
- handler: (error: Error) => void
  Function to remove.
Returns any
Inherited from WebSocketFunctions.off
- Defined in Ws.ts:458
off(
    event: "setItem",
    handler: (
        item: { value: ValueType } & SetReturnType & { prop: string },
    ) => void,
): any
Remove an event handler for all setItem events.
Parameters
- event: "setItem"
  The 'setItem' event name.
- handler: (item: { value: ValueType } & SetReturnType & { prop: string }) => void
  Function to remove.
Returns any
Inherited from WebSocketFunctions.off
- Defined in Ws.ts:464
off(
    event: "setItem",
    name: string,
    handler: (
        item: { value: ValueType } & SetReturnType & { prop: string },
    ) => void,
): any
Remove an event handler for specific setItem events.
Parameters
- event: "setItem"
  The 'setItem' event name.
- name: string
  The specific item name.
- handler: (item: { value: ValueType } & SetReturnType & { prop: string }) => void
  Function to remove.
Returns any
Inherited from WebSocketFunctions.off
- Defined in Ws.ts:471
off(event: "removeItem", handler: (item: { prop: string }) => void): any
Remove an event handler for all removeItem events.
Parameters
- event: "removeItem"
  The 'removeItem' event name.
- handler: (item: { prop: string }) => void
  Function to remove.
Returns any
Inherited from WebSocketFunctions.off
- Defined in Ws.ts:477
off(
    event: "removeItem",
    name: string,
    handler: (item: { prop: string }) => void,
): any
Remove an event handler for specific removeItem events.
Parameters
- event: "removeItem"
  The 'removeItem' event name.
- name: string
  The specific item name.
- handler: (item: { prop: string }) => void
  Function to remove.
Returns any
Inherited from WebSocketFunctions.off
- Defined in Ws.ts:484

connect

connect(): Promise<void>
Opens the WebSocket connection.

Returns Promise<void>
Remarks
Does usually not need to be used, since the WebSocke connection is automatically established on WS feature usage.
Inherited from WebSocketFunctions.connect
- Defined in Ws.ts:591

disconnect

disconnect(): Promise<void>
Close the WebSocket connection and clean up resources.

Returns Promise<void>
Remarks
If the instance has joined the presence channel, it will automatically leave before disconnecting. This ensures proper cleanup and notifies other clients of the departure. All event handlers are also cleaned up.
Inherited from WebSocketFunctions.disconnect
- Defined in Ws.ts:604

join

join(data: JSONObj): Promise<undefined>
Join the presence channel to announce this connection to others.
Parameters
- data: JSONObj
  Optional data to associate with this connection.
Returns Promise<undefined>
Throws
Error if encryption is configured but getEncryptionSettings() not called.
Remarks
After joining, this connection will:
- Appear in getJoinedConnections() results for other clients
- Trigger 'presence:join' events for other connected clients
- Automatically send 'presence:leave' when disconnecting
Example
```
await instance.join({
  username: 'Alice',
  status: 'online',
  avatar: 'avatar1.png'
});
```
Inherited from WebSocketFunctions.join
- Defined in Ws.ts:839

leave

leave(): Promise<undefined>
Leave the presence channel.

Returns Promise<undefined>
Remarks
Notifies other connected clients that this connection has left. This is automatically called when disconnecting if the connection had previously joined.
Inherited from WebSocketFunctions.leave
- Defined in Ws.ts:860

getJoinedConnections

getJoinedConnections(): Promise<JoinedConnections>
Get a list of all currently connected clients in the presence channel.

Returns Promise<JoinedConnections>
Promise resolving to an array of connected clients with their data.
Throws
Error if encryption is configured but getEncryptionSettings() not called.
Remarks
Each connection object includes:
- connectionId: Unique identifier for the connection
- joinedAt: Timestamp when the connection joined
- data: Custom data provided when joining (automatically decrypted)
Example
```
const connections = await instance.getJoinedConnections();
console.log(`${connections.length} users online`);
connections.forEach(conn => {
  console.log(`User: ${conn.data.username}, joined: ${new Date(conn.joinedAt)}`);
});
```
Inherited from WebSocketFunctions.getJoinedConnections
- Defined in Ws.ts:891

Class NonLocalStorage

Remarks

Hierarchy

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns NonLocalStorage

Parameters

Returns NonLocalStorage

Properties

id

isConnected

Methods

StaticretrieveAccessToken

Parameters

Returns Promise<string>

Example

useAccessToken

Parameters

Returns number

onAccessTokenExpiring

Parameters

Returns void

offAccessTokenExpiring

Parameters

Returns void

getEncryptionSettings

Parameters

Returns Promise<EncryptionSettingsInfos>

Throws

Remarks

rotateEncryption

Parameters

Returns Promise<EncryptionSettingsInfos>

Throws

Remarks

setItem

Parameters

Optionalttl?: number

OptionalifAbsent?: boolean

Returns Promise<undefined | SetReturnType>

Default

Default

setItems

Parameters

Returns Promise<undefined | SetItemsType>

Default

Default

getItem

Type Parameters

Parameters

Returns Promise<undefined | ItemType<T>>

getItems

Parameters

Returns Promise<undefined | ItemsType>

getAllItems

Parameters

Returns Promise<undefined | ItemsType>

getAllKeys

Parameters

Returns Promise<undefined | string[]>

removeItem

Parameters

Returns Promise<undefined>

removeItems

Parameters

Returns Promise<undefined>

incrementItem

Parameters

Returns Promise<ItemType>

decrementItem

Parameters

Returns Promise<ItemType>

clear

Returns Promise<undefined>

send

`Static`retrieveAccessToken

`Optional`ttl?: number

`Optional`ifAbsent?: boolean