TinyBase logoTinyBase

createWsSynchronizer

The createWsSynchronizer function creates a WsSynchronizer object that can synchronize MergeableStore data to and from other MergeableStore instances via WebSockets facilitated by a WsServer.

createWsSynchronizer<WebSocketType>(
  store: MergeableStore,
  webSocket: WebSocketType,
  requestTimeoutSeconds?: number,
  onSend?: Send,
  onReceive?: Receive,
  onIgnoredError?: (error: any) => void,
): Promise<WsSynchronizer<WebSocketType>>
TypeDescription
storeMergeableStore

The MergeableStore to synchronize.

webSocketWebSocketType

The WebSocket to send synchronization messages over.

requestTimeoutSeconds?number

An optional time in seconds that the Synchronizer will wait for responses to request messages, defaulting to 1.

onSend?Send

An optional handler for the messages that this Synchronizer sends. This is suitable for debugging synchronization issues in a development environment, since v5.1.

onReceive?Receive

An optional handler for the messages that this Synchronizer receives. This is suitable for debugging synchronization issues in a development environment, since v5.1.

onIgnoredError?(error: any) => void

An optional handler for the errors that the Synchronizer would otherwise ignore when trying to synchronize data. This is suitable for debugging synchronization issues in a development environment.

returnsPromise<WsSynchronizer<WebSocketType>>

A reference to the new WsSynchronizer object.

As well as providing a reference to the MergeableStore to persist, you must provide a configured WebSocket to send synchronization messages over.

Instead of the raw browser implementation of WebSocket, you may prefer to use the Reconnecting WebSocket wrapper so that if a client goes offline, it can easily re-establish a connection when it comes back online. Its API is compatible with this Synchronizer.

You can indicate how long the Synchronizer will wait for responses to message requests before timing out. A final set of optional handlers can be provided to help debug sends, receives, and errors respectively.

This method is asynchronous because it will await the websocket's connection to the server. You will need to await a call to this function or handle the return type natively as a Promise.

Example

This example creates two WsSynchronizer objects to synchronize one MergeableStore to another via a server.

import {WebSocket, WebSocketServer} from 'ws';
import {createMergeableStore} from 'tinybase';
import {createWsServer} from 'tinybase/synchronizers/synchronizer-ws-server';
import {createWsSynchronizer} from 'tinybase/synchronizers/synchronizer-ws-client';

const server = createWsServer(new WebSocketServer({port: 8047}));

const store1 = createMergeableStore();
const store2 = createMergeableStore();

const synchronizer1 = await createWsSynchronizer(
  store1,
  new WebSocket('ws://localhost:8047'),
);
const synchronizer2 = await createWsSynchronizer(
  store2,
  new WebSocket('ws://localhost:8047'),
);

await synchronizer1.startSync();
await synchronizer2.startSync();

store1.setTables({pets: {fido: {species: 'dog'}}});
store2.setTables({pets: {felix: {species: 'cat'}}});

// ...
console.log(store1.getTables());
// -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
console.log(store2.getTables());
// -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}

synchronizer1.destroy();
synchronizer2.destroy();
server.destroy();

Since

v5.0.0