JS SDK

Through Yorkie JS SDK, you can efficiently build collaborative applications. On the client-side implementation, you can create Documents that are automatically synced with remote peers with minimal effort.

Client

Client is a normal client that can communicate with the server. It has Documents and sends changes of the Document from local to the server to synchronize with other replicas in remote.

Creating a Client

We can create a Client using new yorkie.Client(). After the Client has been activated, it is connected to the server and ready to use.

const client = new yorkie.Client('localhost:8080');
await client.activate();

Subscribing to Client events

We can use client.subscribe to subscribe to client-based events, such as status-changed, stream-connection-status-changed and peer-changed.

const unsubscribe = client.subscribe((event) => {
  if (event.type === 'status-changed') {
    console.log(event.value); // 'activated' or 'deactivated'
  } else if (event.type === 'stream-connection-status-changed') {
    console.log(event.value); // 'connected' or 'disconnected'
  }
});

By using the value of the stream-connection-status-changed event, it is possible to determine whether the Client is connected to the network.

If you want to know about other ClientEvents, please refer to the ClientEventType.

Document

Document is a primary data type in Yorkie, which provides a JSON-like updating experience that makes it easy to represent your application’s model. A Document can be updated without being attached to the client, and its changes are automatically propagated to other peers when the Document is attached to the Client or when the network is restored.

Creating a Document

We can create a Document using yorkie.Document(). Let’s create a Document with a key and attach it to the Client.

const doc = new yorkie.Document('doc-1');
await client.attach(doc);

After attaching the Document to the Client, all changes to the Document are automatically synchronized with remote peers.

Editing the Document

Document.update(changeFn, message) enables you to modify a Document. The optional message allows you to add a description to the change. If the Document is attached to the Client, all changes are automatically synchronized with other Clients.

const message = 'update document for test';
doc.update((root) => {
  root.obj = {};              // {"obj":{}}
  root.obj.num = 1;           // {"obj":{"num":1}}
  root.obj.obj = {'str':'a'}; // {"obj":{"num":1,"obj":{"str":"a"}}}
  root.obj.arr = ['1', '2'];  // {"obj":{"num":1,"obj":{"str":"a"},"arr":[1,2]}}
}, message);

Under the hood, root in the update function creates a change, a set of operations, using a JavaScript proxy. Every element has its unique ID, created by the logical clock. This ID is used by Yorkie to track which object is which.

You can get the contents of the Document using document.getRoot().

const root = doc.getRoot();
console.log(root.obj);     // {"num":1,"obj":{"str":"a"},"arr":[1,2]}
console.log(root.obj.num); // 1
console.log(root.obj.obj); // {"str":"a"}
console.log(root.obj.arr); // [1,2]

Subscribing to Document events

A Document is modified by changes generated remotely or locally in Yorkie. When the Document is modified, change events occur, to which we can subscribe using document.subscribe. Here, we can do post-processing such as repaint in the application using the path of the change events.

doc.subscribe((event) => {
  if (event.type === 'local-change') {
    console.log(event);
  } else if (event.type === 'remote-change') {
    for (const changeInfo of event.value) {
      // `message` delivered when calling document.update
      console.log(changeInfo.change.message);
      for (const path of changeInfo.paths) {
        if (path.startsWith('$.obj.num') {
          // root.obj.num is changed
        } else if (path.startsWith('$.obj')) {
          // root.obj is changed
        }
      }
    }
  }
});

Detaching the Document

If the document is no longer used, it should be detached to increase the efficiency of GC removing CRDT tombstones. For more information about GC, please refer to Garbage Collection.

await client.detach(doc);

Custom CRDT types

Custom CRDT types are data types that can be used for special applications such as text editors and counters, unlike general JSON data types such as Object and Array. Custom CRDT types can be created in the callback function of document.update.

Text

Text provides supports for collaborative plain text editing. Under the hood, Text is represented as a list of characters. Compared to a regular JavaScript array, Text offers better performance. It also has selection information for sharing the cursor position.

doc.update((root) => {
  root.text = new yorkie.Text();  // {"text":""}
  root.text.edit(0, 0, 'hello');  // {"text":"hello"}
  root.text.edit(0, 1, 'H');      // {"text":"Hello"}
  root.text.select(0, 1);         // {"text":"^H^ello"}
});

An example of Text co-editing with CodeMirror: CodeMirror example, Demos

RichText

RichText is similar to Text except that we can add attributes to contents.

doc.update((root) => {
  root.text = new yorkie.RichText();       // {"text":""}
  root.text.edit(0, 0, 'hello');           // {"text":"hello"}
  root.text.edit(0, 1, 'H');               // {"text":"Hello"}
  root.text.setStyle(0, 1, {bold: true});  // {"text":"<b>H</b>ello"}
});

An example of RichText co-editing with Quill: Quill example, Demos

Counter

Counter supports numeric types that change with addition and subtraction. If a numeric data needs to be modified at the same time, Counter should be used instead of primitives.

doc.update((root) => {
  root.counter = new yorkie.Counter(1);     // {"counter":1}
  root.counter.increase(2);                 // {"counter":3}
  root.counter.increase(3.5);               // {"counter":6.5}
  root.counter.increase(-3.5);              // {"counter":3}
});

TypeScript Support

To use the Document more strictly, we can use type variable in TypeScript when creating a Document.

type DocType = {
  list: Array<number>;
  text: yorkie.Text;
}

const doc = new yorkie.Document<DocType>('key');
doc.update((root) => {
  root.list = [1, 2, 3];
  root.text = new yorkie.Text();
});

Reference

For details on how to use the JS SDK, please refer to JS SDK Reference.

Next, Let’s take a look at the various Tasks that can be performed with Yorkie.

Edit this page