Synchronise JSON

api

The SyncAPI.SyncDocument API enables clients to synchronise JSON documents.

cli

Not yet implemented.

fusebox

There is currently no UI support for synchronising JSON documents, however it is possible to use the fusebox to interrogate the underlying sync database.

More functionality will be added in future.

javascript

The SyncDocument API can be used to synchronise JSON documents, however this requires boilerplate code to handle the sync protocol. The SyncProvider class encapsulates this boilerplate and provides a simple API for synchronising JSON documents.

SyncProvider

The SyncProvider class is a wrapper around the SyncDocument API. It manages the sync protocol exchange with the Volt and provides a consistent API for synchronising JSON documents.

The SyncProvder class is instantiated with a Yjs document, a sync database id or alias and a Volt client.

See the yjs documentation for more information about the Yjs library.

nodejs

The following example demonstrates how to use the SyncProvider class to synchronise a JSON document with the Volt in a nodejs application.

In order to use this example, you will need to:

initialise voltConfig variable, replacing the /path/to/config.json with the path to a valid Volt client configuration file.
initialise syncDatabaseId variable, replacing the @provider-example-db with a valid sync database id or alias.
initialise ydoc.guid variable, replacing the my-sync-document with a valid sync document guid.

import grpc from "@grpc/grpc-js";
import { SyncProvider, VoltClient } from "@tdxvolt/volt-client-grpc";
import * as Y from "yjs";

const syncDatabaseId = "@provider-example-db";

const voltConfig = "/path/to/config.json";

// Create a Volt client with the grpc package.
const voltClient = new VoltClient(grpc);

// Create a yjs document to store the JSON.
const ydoc = new Y.Doc();

// Set the document guid to identify the document in the sync database.
ydoc.guid = "my-sync-document";

// Create a sync provider to synchronise the document with the Volt.
const syncProvider = new SyncProvider(voltClient, syncDatabaseId, ydoc);

syncProvider.on("status", ({status}) => {
  console.log("sync status: %s", status);

  if (status === "connected") {
    // The document is now synced. Any changes you make to the document will
    // automatically be synchronised to other clients, and any changes made
    // by other clients will be automatically synchronised to this client.
    const someJSON = ydoc.getMap();
    if (!someJSON.has("foo")) {
      console.log("setting foo");
      someJSON.set("foo", "bar");
    }

    console.log(someJSON.toJSON());
  }
});

voltClient.initialise(voltConfig).then(() => {
  syncProvider.startSync();
});

browser

The following example is similar to the nodejs example, but uses the browser WebSocket API to connect to the Volt.

The differences are:

import the SyncProvider and VoltClient classes from the @tdxvolt/volt-client-web package.
the voltConfig is provided by the application rather than being loaded from a file. This is usually created when the user logs in to the application.
the syncProvider is created with the {base64: true} option to encode the sync messages in base64. This is required by the websocket API.

import { SyncProvider, VoltClient } from "@tdxvolt/volt-client-web";
import * as Y from "yjs";

const syncDatabaseId = "@provider-example-db";

const voltConfig = <*** supplied by application ***>;

const voltClient = new VoltClient();

// Create a yjs document to store the JSON.
const ydoc = new Y.Doc();

// Set the document guid to identify the document in the sync database.
ydoc.guid = "my-sync-document";

// Create the sync provider, specifying the base64 option to encode the sync messages in base64.
const syncProvider = new SyncProvider(voltClient, syncDatabaseId, ydoc, {
  base64: true,
});

syncProvider.on("status", ({status}) => {
  console.log("sync status: %s", status);

  if (status === "connected") {
    // The document is now synced. Any changes you make to the document will
    // automatically be synchronised to other clients, and any changes made
    // by other clients will be automatically synchronised to this client.
    const someJSON = ydoc.getMap();
    if (!someJSON.has("foo")) {
      console.log("setting foo");
      someJSON.set("foo", "bar");
    }

    console.log(someJSON.toJSON());
  }
});

voltClient.initialise(voltConfig).then(() => {
  syncProvider.startSync();
});

C++

Not yet implemented.