Understanding the fundamental concepts behind the Vaultrice SDK will help you use the library to its full potential.
The NonLocalStorage class is the primary entry point for interacting with the Vaultrice service. It manages the API connection, handles real-time events, and provides the core methods for data storage and retrieval.
It provides direct, method-based access to every feature, including storage, real-time events, and presence. It's the underlying engine that powers the SyncObject and is perfect for when you need fine-grained, low-level control over your application's real-time architecture.
To get started, you create an instance of the NonLocalStorage client. The constructor accepts your credentials and an optional options object to customize its behavior or an optional id string.
import { NonLocalStorage } from '@vaultrice/sdk';
const nls = new NonLocalStorage(credentials, options);
// or const nls = new NonLocalStorage(credentials, 'my-id');An object containing your project's authentication details:
• apiKey (string): Your public API key
• apiSecret (string): Your secret key
• projectId (string): The ID of the project you want to connect to
This parameter can be a string (which will be used as the object id) or an object with properties like:
• id: Unique identifier for the data object
• class: Namespace for separating data objects
• ttl: Time-to-live for data in milliseconds
• passphrase: Enables End-to-End Encryption
• idSignature: Signature for authorization
Vaultrice is more than just a key-value store; it's a real-time communication platform. This is made possible by its built-in WebSocket layer.
When you create a NonLocalStorage instance, it automatically establishes a WebSocket connection to the Vaultrice service. This connection remains active, allowing the server to instantly "push" updates to your client without you needing to poll for changes.
This real-time layer powers two key features:
Whenever a client modifies a key-value pair (using setItem, removeItem, etc.), the Vaultrice server broadcasts that change to all other clients currently connected to the same object ID. The SDK receives this event and emits it locally, allowing you to update your UI in real-time.
The WebSocket connection also manages presence. When a user connects, you can have them join a presence channel. When they do, the server broadcasts a presence:join event to all other connected clients. Similarly, when they disconnect, a presence:leave event is sent.
// Listen for when another client changes 'userStatus'
nls.on('setItem', 'userStatus', (item) => {
console.log(`User status updated to: ${item.value}`);
});
// or
// Listen for when another client changes any item
nls.on('setItem', (item) => {
console.log(`${item.prop} updated to: ${item.value}`);
});
// Listen for users joining
nls.on('presence:join', (joinedConnection) => {
console.log(`${joinedConnection.data.name} just came online.`);
});The SyncObject is the recommended way to build most real-time and collaborative applications with Vaultrice. It's a high-level abstraction that combines state, presence, and events into a single, easy-to-use JavaScript Proxy object.
Here's how all the core concepts work together:
It handles all the low-level complexity for you, providing three core capabilities in one package:
Interact with the SyncObject as if it were a normal JavaScript object. When you set a property (mySyncObject.theme = 'dark'), the change is automatically saved and synced to all other clients.
The SyncObject automatically manages user presence. You can call .join() to announce a user, and then simply read the .joinedConnections property to get a live, always-up-to-date list of who's online.
The full event system is exposed directly on the object. You can call .on('setItem', ...) or .on('presence:join', ...) without needing to manage a separate client instance.
This all-in-one approach dramatically reduces boilerplate and simplifies your code, allowing you to build powerful collaborative features faster.
Under the hood, the SyncObject is actually a JavaScript Proxy that wraps a NonLocalStorage instance. Here's how it works internally:
The magic happens in the JavaScript Proxy handlers, which intercept property access and assignment to provide seamless real-time synchronization.
The magic happens in the JavaScript Proxy handlers:
When you read syncObject.theme, the proxy checks the local store for a cached value. If found and not expired, it returns the value immediately - no network call needed.
When you write syncObject.theme = 'dark', the proxy calls nls.setItem('theme', 'dark') and updates the local store. This triggers real-time sync to all connected clients.
Special properties like join, on, and joinedConnections are bound directly to the underlying NonLocalStorage methods, giving you full access to the low-level API.
import { createSyncObject } from '@vaultrice/sdk';
// A single object that handles everything
const doc = await createSyncObject(credentials, 'shared-document-123');
// 1. Set a property directly
doc.title = 'My Live Document';
// 2. And simply use it (also on a different client)
console.log(doc.title);
// 3. Read the live presence list
console.log(doc.joinedConnections.length + ' users online');
// 4. Listen for events directly on the object
doc.on('presence:join', (user) => {
console.log(user.data.name + ' joined.');
});Now that you understand the core concepts, dive deeper into practical implementation or explore advanced features.