@netless/synced-store NPM

SyncedStore

A white-web-sdk plugin for storing shared replayable states and sending/receiving replayable events.

Install

npm add @netless/synced-store

Example

Init SyncedStore right after joining room:

import { createSyncedStorePlugin } from "@netless/synced-store";

const SyncedStorePlugin = createSyncedStorePlugin();

const whiteboard = new WhiteWebSdk({
  appIdentifier: "xxxxxxxxxxxxxx",
  useMobXState: true, // This is required to use SyncedStorePlugin
  deviceType: DeviceType.Surface,
});

const room = await whiteboard.joinRoom({
  uuid: roomUUID,
  roomToken: roomToken,
  uid: userID,
  invisiblePlugins: [SyncedStorePlugin],
  // Only writable users can modify states and dispatch events.
  // Set this to false for readonly users(audience) for better performance
  isWritable: true,
});

// Define typed event keys and payloads
type EventData = {
  "click-event": { id: string };
};

const syncedStore = await SyncedStorePlugin.init<EventData>(room);

interface State {
  count: number;
}

// connect to a namespaced storage
const storage = await syncedStore.connectStorage<State>("a-name", { count: 0 });

storage.state; // => { count: 0 }

if (storage.isWritable) {
  storage.setState({ count: 2 });
}

const stateChangedDisposer = storage.on("stateChanged", diff => {
  if (diff.count) {
    // count: 0 -> 2
    console.log("count:", diff.count.oldValue, "->", diff.count.newValue);
    console.log(diff.count.newValue === app.state.count);
  }
});

if (syncStore.isRoomWritable) {
  syncedStore.dispatchEvent("click-event", { id: "item1" });
}

const eventDisposer = syncedStore.addEventListener(
  "click-event",
  ({ payload }) => {
    console.log(payload.id); // item1
  }
);

Develop

Add .env at project root following the .env.example reference.

pnpm i
pnpm start

Testing

Unit Test:

pnpm t

End-to-end Test:

Start hosting the testing resources
```
pnpm e2e:page
```
Then then open a new terminal to start e2e tests
```
pnpm e2e
```

API

static SyncedStorePlugin.init(room)
A static method that inits the SyncedStore. Should be called right after joining room.
Returns: Promise<SyncedStore<EventData>>
SyncedStore.isRoomWritable
Type: boolean
Shortcut to whiteboard room writable state. When it is false, calling storage.setState() and dispatchEvent() will throw errors.
SyncedStore.setRoomWritable(isWritable)
Shortcut to change whiteboard room writable state.
SyncedStore.addRoomWritableChangeListener(listener)
It fires when whiteboard room writable state changes.
Type: (isRoomWritable: boolean) => void
Returns: () => void - a disposable function that can be called to remove the listener.
SyncedStore.isPluginWritable
Type: boolean
It is true if isRoomWritable === true and plugin finished initialization. When it is false, calling storage.setState() will throw errors.
SyncedStore.addPluginWritableChangeListener(listener)
It fires when plugin writable state changes.
Type: (isPluginWritable: boolean) => void
Returns: () => void - a disposable function that can be called to remove the listener.
SyncedStore.dispatchEvent(event, payload)
Broadcast an event message to other clients.
```
syncedStore.dispatchEvent("click", { data: "data" });
```

SyncedStore.addEventListener(event, listener)

It fires when receiving messages from other clients (when other clients called syncedStore.dispatchEvent()).

Returns: () => void a disposer function.

const disposer = syncedStore.addEventListener(
  "click-event",
  ({ payload }) => {
    console.log(payload.data);
    disposer();
  }
);

syncedStore.dispatchEvent("click-event", { data: "data" });

SyncedStore.connectStorage(namespace, defaultState)
Connect to a namespaced storage. Each call returns an fresh storage instance with its own life-cycle. Calling multiple times with same namespace will result in different storage instances sharing the same data.
namespace
Name for the storage. Storages with the same namespace share the same state(but each storage instance keeps it own life-cycle).
Type: string
defaultState
Type: State
Returns: Storage<State>
```
const storage = syncedStore.connectStorage("my-storage", { count: 0 });
```
Storage.state
Type: State
Default: initialState
The synchronized state across all clients. To change it, call storage.setState().
Storage.setState(partialState)
Works like React's setState, it updates storage.state and synchronize it to other clients.
When some field's value is undefined, it will be removed from storage.state.
Important: Do not rely on the order of state changes:
- storage.setState() alters storage.state synchronously but onStateChanged will wait until the data is successfully synced.
- State syncing time span varies due to network status and data size. It is recommended to store only necessary data in the store.
partialState
Type: Partial<State>
```
storage.state; //=> { count: 0, a: 1 }
storage.setState({ count: storage.state.count + 1, a: undefined, b: 2 });
storage.state; //=> { count: 1, b: 2 }
```
Storage.on("stateChanged", listener)
A state changed event that fires after someone called storage.setState() (including the current syncedStore itself).
Returns: () => void - A disposable function that can be called to remove the listener.
```
const disposer = storage.on("stateChanged", diff => {
  console.log("state changed", diff.oldValue, diff.newValue);
  disposer(); // remove listener by calling disposer
});
```
Storage.on("disconnected", listener)
An event that fires after the storage instance is disconnected.
Returns: () => void - A disposable function that can be called to remove the listener.
```
const disposer = storage.on("disconnected", () => {
  console.log(storage.disconnected); // true
});
```
Stoarge.disconnect()
Disconnect or dispose the storage, triggers disconnected event, and release all listeners.