Yorkie

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.

If you want to install the SDK, refer to the Getting Started with JS SDK.

Client

Client is a regular client that communicates with the server. It has documents and sends local changes to the server to synchronize with other replicas remotely.

Creating a Client

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

1const client = new yorkie.Client({
2  rpcAddr: 'https://api.yorkie.dev',
3  apiKey: 'xxxxxxxxxxxxxxxxxxxx',
4});
5await client.activate();

Creating a Client with Auth Token

You can configure authentication for the client by setting up an authTokenInjector to provide tokens for Auth Webhook verification. If a codes.Unauthenticated error occurs, the authTokenInjector will be called again with the webhook's response reason, enabling automatic token refresh. For more information about Auth Webhook, please refer to the Auth Webhook.

1const client = new yorkie.Client({
2  rpcAddr: 'https://api.yorkie.dev',
3  apiKey: 'xxxxxxxxxxxxxxxxxxxx',
4  authTokenInjector: async (reason) => {
5    // Handle token refresh logic based on webhook response
6    if (reason === 'token expired') {
7      return await refreshAccessToken();
8    }
9    return accessToken;
10  },
11});

Measuring MAU

You can measure MAU(Monthly Active Users) by setting the userID metadata when creating a client. The userID should be a unique identifier for each user.

1const client = new yorkie.Client({
2  rpcAddr: 'https://api.yorkie.dev',
3  apiKey: 'xxxxxxxxxxxxxxxxxxxx',
4  metadata: { userID: 'user-1234' },
5});

You can check the MAU in the Dashboard by selecting the project and clicking the overview tab.

Deactivate the Client

When the client is no longer needed, you can deactivate it to release resources and disconnect from the server.

1await client.deactivate();

This will detach all documents attached to the client for efficient garbage collection.

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 clients when the Document is attached to the Client or when the network is restored.

Creating a Document

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

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

Attaching the Document

When you attach, the client notifies the server that it is subscribing to this document. If the document does not exist on the server, it will be created, and any local changes that occurred will be updated to the server's document. If the server already has a document associated with the provided key, it sends the existing changes to the client, which are then applied to synchronize the document.

Once attached, the document becomes synchronized with other clients. This ensures that any modifications made by one client are instantly propagated to other clients collaborating on the same document.

The second argument is options.

• initialPresence: Sets the initial presence of the client that attaches the document. The presence is shared with other users participating in the document. It must be serializable to JSON.
• syncMode(Optional): Specifies synchronization modes. The default value is SyncMode.Realtime, which automatically pushes and pulls changes. If you set it to SyncMode.Manual, you'll need to manually handle synchronization.

1await client.attach(doc, {
2  initialPresence: { color: 'blue', cursor: { x: 0, y: 0 } },
3  syncMode: SyncMode.Manual,
4});

Initializing root

The root is used to manage the application's data, such as primitives, arrays, Counters, and Text in a form within the Document. You can set the initial values when calling Document.attach() using the initialRoot option.

1await client.attach(doc, {
2  initialRoot: {
3    list: [1, 2, 3],
4    counter: new yorkie.Counter(yorkie.IntType, 0),
5  },
6});

The initial values are partially applied. For each element in initialRoot:

• If the key doesn't exist, the element will be applied.
• If the key already exists in the Document, that element will be discarded. Users don't need to worry about overwriting existing valid counters.

1await client.attach(doc, {
2  initialRoot: {
3    list: [],
4  },
5});
6
7// Another client tries to attach with initialRoot option:
8await client.attach(doc, {
9  initialRoot: {
10    list: [1, 2, 3],    // this update will be discarded
11    counter: new yorkie.Counter(yorkie.IntType, 0), // this update will be applied
12  },
13});
14
15// final state
16// root = {
17//   list: [],
18//   counter: {}
19// }

We support element types for Primitives, and Custom CRDT types.

Updating presence

The Document.update() method allows you to make changes to the state of the current user's presence.

Specific properties provided will be changed. The existing presence object will be updated by merging the new changes. In other words, properties not specified in the update function will remain unchanged.

1doc.update((root, presence) => {
2  presence.set({ cursor: { x: 1, y: 1 } });
3});
4
5// final state
6// presence = { color: 'blue', cursor: { x: 1, y: 1 } }
7// we can see that the changes made were merged and the final state of the current user's presence is as we desire

1await client.attach(doc, {
2  // let's say 'color' is a property of cursor
3  initialPresence: {cursor: { x: 0, y: 0, color: 'red'}}, 
4});
5
6doc.update((root, presence) => {
7  // we want to change the x y coordinates of our cursor
8  presence.set({ cursor: { x: 1, y: 1 } }); 
9});
10
11// final state
12// presence = { cursor: { x: 1, y: 1 } } 
13// we can see that all properties inside cursor get replaced (i.e. we lose the property 'color')

Getting presence

You can get the presences of the current client and other clients participating in the document.

Document.getPresence(clientID)

It returns the presence of a specific client.

1doc.getPresence(client.getID()); // { color: 'blue', cursor: { x: 1, y: 1 } }

Document.getMyPresence()

It returns the presence of the current client that has attached to the document.

1doc.getMyPresence(); // { color: 'blue', cursor: { x: 1, y: 1 } }

Document.getPresences()

It returns an array about all clients currently participating in the document. Each entry in the array includes the client's id and presence.

1const users = doc.getPresences();
2for (const { clientID, presence } of users ) {
3  // Do something
4}

Here is an example of showing a list of users participating in the collaborative application.

• Profile Stack

Document.subscribe('presence')

This method allows you to subscribe to presence-related changes. You'll be notified whenever clients watch, unwatch, or modify their presence.

The initialized event occurs when the client list needs to be initialized. For example, this happens when you first connect a watch stream to a document, when the connection is lost, or when it is reconnected.

1const unsubscribe = doc.subscribe('presence', (event) => {
2  if (event.type === 'initialized') {
3    // event.value: Array of users currently participating in the document
4  }
5
6  if (event.type === 'watched') {
7    // event.value: A user has joined the document editing in online
8  }
9
10  if (event.type === 'unwatched') {
11    // event.value: A user has left the document editing
12  }
13
14  if (event.type === 'presence-changed') {
15    // event.value: A user has updated their presence
16  }
17});

Use my-presence and others topics to distinguish between your own events and those of others.

Document.subscribe('my-presence')

This method is specifically for subscribing to changes in the presence of the current client that has attached to the document.

The possible event.type are: initialized, presence-changed.

1const unsubscribe = doc.subscribe('my-presence', (event) => {
2  // Do something
3});

Document.subscribe('others')

This method enables you to subscribe to changes in the presence of other clients participating in the document.

The possible event.type are: watched, unwatched, presence-changed.

1const unsubscribe = doc.subscribe('others', (event) => {
2  if (event.type === 'watched') {
3    addUser(event.value);
4  }
5
6  if (event.type === 'unwatched') {
7    removeUser(event.value);
8  }
9
10  if (event.type === 'presence-changed') {
11    updateUser(event.value);
12  }
13});

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.

1const message = 'update document for test';
2doc.update((root) => {
3  root.todos = [];
4  root.todos.push('todo-1');
5  root.obj = {
6    name: 'yorkie',
7    age: 14,
8  };
9  root.counter = new yorkie.Counter(yorkie.IntType, 0);
10  root.counter.increase(1);
11}, 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().

1const root = doc.getRoot();
2console.log(root.todos);    // ["todo-1"]
3console.log(root.obj);      // {"name":"yorkie","age":14}
4console.log(root.obj.name); // "yorkie"
5console.log(root.counter.getValue()); // 1

Subscribing to Document

You can subscribe to various events occurring in the Document, such as changes, connection status, synchronization status, and all events by using the document.subscribe() method. By subscribing to these events, you can update the UI in real-time and handle exceptions that may occur during synchronization.

Document.subscribe()

A Document can be modified by changes generated remotely or locally in Yorkie. Whenever the Document is modified, change events are triggered and you can subscribe to these events using the document.subscribe(callback) method. By subscribing to changes in the Document, you can receive updates in real-time, which is useful for updating the UI when the Document changes.

The callback is called with an event object, and the event.type property indicates the source of the change, which can be one of the following values: local-change, remote-change, or snapshot.

1const unsubscribe = doc.subscribe((event) => {
2  if (event.type === 'snapshot') {
3    // `snapshot` delivered when the entire document is updated from the server.
4  } else if (event.type === 'local-change') {
5    // `local-change` delivered when calling document.update from the current client.
6  } else if (event.type === 'remote-change') {
7    // `remote-change` delivered when the document is updated from other clients.
8    const { message, operations } = event.value;
9    
10    // You can access the operations that have been applied to the document.
11    for (const op of operations) {
12      // e.g.) { type: 'increase', value: 1, path: '$.counter' }
13      switch (op.type) {
14        case 'increase':
15          // ...
16          break;
17      }
18    }
19  }
20});

When the event.type is local-change or remote-change, the event.value is a changeInfo, which has {operations, message} properties. For more information about changeInfo for document events, please refer to the ChangeInfo.

The snapshot event is triggered when a snapshot is received from the server. This occurs when the changes that a document needs to fetch from the server exceed a certain SnapshotThreshold. Instead of sending numerous changes, the server sends a snapshot of the document. In such cases, it is essential to update with data from the Yorkie Document. Refer to the example code for handling snapshots in CodeMirror.

Document.subscribe('$.path')

Additionally, you can subscribe to changes for a specific path in the Document using doc.subscribe(path, callback) with a path argument, such as $.todos, where the $ sign indicates the root of the document. The callback function is called when the target path and its nested values are changed.

With this feature, you can easily subscribe to changes for a specific part of the document and perform different actions based on the updated values.

1// The event is triggered when the value of the path("$.todos") is changed.
2const unsubscribe = doc.subscribe('$.todos', (event) => { 
3  // You can access the updated value of the path.
4  const target = doc.getValueByPath('$.todos');
5});

Document.subscribe('connection')

After attaching the document to the client, the document is continuously synchronized with the server in real-time. This is achieved by maintaining a watch stream connection between the client and the server, which allows the client to receive events and updates from other users.

To monitor the connection status of the stream, you can use a callback function that is triggered whenever the connection status changes. The possible values for event.value are StreamConnectionStatus.Connected and StreamConnectionStatus.Disconnected.

When the watch stream is disconnected, it indicates that the user is offline and will not receive real-time updates from other users.

1const unsubscribe = doc.subscribe('connection', (event) => {
2  if (event.value === StreamConnectionStatus.Connected) {
3    // The watch stream is connected.
4  } else if (event.value === StreamConnectionStatus.Disconnected) {
5    // The watch stream is disconnected.
6  }
7});

For more information about StreamConnectionStatus, please refer to the StreamConnectionStatus.

Document.subscribe('sync')

If the document is attached to the client in SyncMode.Realtime, the document is automatically synchronized with the server in real-time. Under this mode, the document executes synchronization in the background, and you can track the synchronization status using the sync event. The possible event.value values are: DocumentSyncStatus.Synced and DocumentSyncStatus.SyncFailed.

1const unsubscribe = doc.subscribe('sync', (event) => {
2  if (event.value === DocumentSyncStatus.Synced) {
3    // The document is synchronized with the server.
4  } else if (event.value === DocumentSyncStatus.SyncFailed) {
5    // The document failed to synchronize with the server.
6  }
7});

For more information about DocumentSyncStatus, please refer to the DocumentSyncStatus.

Document.subscribe('status')

You can subscribe to the status of the document using doc.subscribe('status', callback). The possible values for event.value.status are DocumentStatus.Attached and DocumentStatus.Detached.

1const unsubscribe = doc.subscribe('status', (event) => {
2  if (event.value.status === DocumentStatus.Attached) {
3    // The document is attached to the client.
4  } else if (event.value.status === DocumentStatus.Detached) {
5    // The document is detached from the client.
6  }
7});

For more information about DocumentStatus, please refer to the DocumentStatus.

Document.subscribe('auth-error')

You can subscribe to authentication error events using doc.subscribe('auth-error', callback). This event is triggered when an unauthenticated error occurs during PushPull or WatchDocuments operations, specifically when the system automatically refreshes the token and retries the operation.

1const unsubscribe = doc.subscribe('auth-error', (event) => {
2  console.log(event.value);
3  // event.value contains:
4  // - reason: string
5  // - method: 'PushPull' | 'WatchDocuments'
6});

This subscription allows you to monitor when token refreshes occur due to authentication errors.
For more information about Auth Webhook, please refer to the Auth Webhook.

Document.subscribe('all')

You can subscribe to all events occurring in the document by using document.subscribe('all', callback). This is used for displaying events in Devtools extension.

Events received from the callback function are of type TransactionEvent, which is an Array<DocEvent>. TransactionEvent represents a collection of events occurring within a single transaction (e.g., doc.update()).

1const unsubscribe = doc.subscribe('all', (transactionEvent) => {
2  for (const docEvent of transactionEvent) {
3    console.log(docEvent);
4  }
5});

Broadcasting a Message

Broadcasting allows clients to share custom events with other clients connected to the same document. Unlike document updates or presence changes, broadcasts are ephemeral messages that are not persisted in the document's state.

1// Broadcasting a message
2const payload = { message: 'Hello everyone!' };
3doc.broadcast('chat', payload);
4
5// Subscribing to broadcast messages
6doc.subscribe('broadcast', (event) => {
7  const { topic, payload, clientID } = event.value;
8  
9  if (topic === 'chat') {
10    console.log(`Message from ${clientID}: ${payload.message}`);
11  }
12});

The broadcast event contains:

• topic: A string identifying the type of broadcast message
• payload: The data being broadcast (must be JSON serializable)
• clientID: The ID of the client that sent the broadcast

This feature is useful for sending temporary messages or signals between clients, such as:

• Chat messages
• Cursor movement notifications
• Application-specific events
• User action notifications

Changing Synchronization Mode

To change the synchronization mode for a document, you can use client.changeSyncMode(doc, syncMode).

Yorkie offers four SyncModes:

• SyncMode.Realtime: Local changes are automatically pushed to the server, and remote changes are pulled from the server.

• SyncMode.RealtimePushOnly: Only local changes are pushed, and remote changes are not pulled.

• SyncMode.RealtimeSyncOff: Changes are not synchronized, but the watch stream remains active.

• SyncMode.Manual: Synchronization no longer occurs in real-time, and the watch stream is disconneted. Manual handling is required for synchronization.

1// Enable automatic synchronization of both local and remote changes.
2await client.changeSyncMode(doc, SyncMode.Realtime);
3
4// Only push local changes automatically.
5await client.changeSyncMode(doc, SyncMode.RealtimePushOnly);
6
7// Synchronization turned off, but the watch stream remains active.
8await client.changeSyncMode(doc, SyncMode.RealtimeSyncOff);
9
10// Synchronization turned off, and the watch stream is disconneted.
11await client.changeSyncMode(doc, SyncMode.Manual);
12await client.sync(doc); // Trigger synchronization manually using the sync function.

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.

1await client.detach(doc);

Document Limits

Yorkie enforces certain limits on document operations to ensure system stability and optimal performance. These limits can be configured through the Yorkie Dashboard's Project Settings.

Max Attachments per Document

When you attach a document, the server keeps track of the number of clients subscribed to it. The Max Attachments per Document setting determines how many clients can be attached to a single document simultaneously. If a client attempts to attach when this limit is reached, the server will reject the attachment with an error.

If the attachment fails due to the limit, the client will need to retry the attachment by either reloading the SDK or calling attach again, as there is no automatic retry mechanism.

Max Subscribers per Document

When a client attaches to a document, it creates a subscription stream to receive real-time updates. The Max Subscribers per Document setting determines how many clients can maintain subscription streams simultaneously for a single document. If a client attempts to create a subscription stream when this limit is reached, the server will reject the request.

Unlike attachment limits, the SDK automatically handles subscription limit errors by retrying the connection (1 retry per second).

1doc.subscribe('connection', (event) => {
2  if (event.value === StreamConnectionStatus.Disconnected) {
3    // The connection is disconnected due to subscription limit or other issues
4    console.log('Watch stream disconnected, retrying automatically...');
5  }
6});

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 text editing. In addition, contents in Text can have attributes; for example, characters can be bold, italic, or underlined.

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

Selection using presence

The temporary client information, such as text selection, does not need to be stored in the document permanently. Instead, it can be effectively shared using presence.

When transmitting text selection information, it is essential to convert the index, which can vary based on the text state, into the position used by Yorkie.Text. This converted position selection can then be sent and applied through presence.

Here is an example where presence is used to share text selection between users in CodeMirror editor.

• When the text selection is changed:

1// Update selection through text editing
2codemirror.on('beforeChange', (cm, change) => {
3  doc.update((root, presence) => {
4    const range = root.content.edit(from, to, content); // return updated index range
5    presence.set({
6      selection: root.content.indexRangeToPosRange(range), // update presence
7    });
8  });
9});
10
11// Update selection using mouse or keyboard
12codemirror.on('beforeSelectionChange', (cm, change) => {
13  const fromIdx = cm.indexFromPos(change.ranges[0].anchor);
14  const toIdx = cm.indexFromPos(change.ranges[0].head);
15  doc.update((root, presence) => {
16    presence.set({
17      selection: root.content.indexRangeToPosRange([fromIdx, toIdx]), // update presence
18    });
19  });
20});

• When applying other user's selection changes:

1doc.subscribe('others', (event) => {
2  if (event.type === 'presence-changed') {
3    const { clientID, presence } = event.value;
4    const range = doc.getRoot().content.posRangeToIndexRange(presence.selection);
5    // Handle the updated selection in the editor
6  }
7});

Text selection can be efficiently shared using presence. Please refer to the following example for a complete code:

• An example of Text co-editing with CodeMirror: CodeMirror example
• An example of Text co-editing with Quill: Quill example

Counter

Counter supports integer types changing with addition and subtraction. If an integer data needs to be modified simultaneously, Counter should be used instead of primitives.

1doc.update((root) => {
2  root.counter = new yorkie.Counter(yorkie.IntType, 1); // {"counter":1}
3  root.counter.increase(2);                             // {"counter":3}
4  root.counter.increase(3);                             // {"counter":6}
5  root.counter.increase(-4);                            // {"counter":2}
6});

TypeScript Support

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

1import yorkie, { JSONArray } from '@yorkie-js/sdk';
2type DocType = {
3  list: JSONArray<number>;
4  text: yorkie.Text;
5};
6type PresenceType = {
7  username: string;
8  color: string;
9};
10
11const doc = new yorkie.Document<DocType, PresenceType>('key');
12await client.attach(doc, {
13  initialPresence: {
14    username: 'alice',
15    color: 'blue',
16  },
17});
18doc.update((root, presence) => {
19  root.list = [1, 2, 3];
20  root.text = new yorkie.Text();
21  presence.set({ color: 'red' });
22});

Logger Options

The Logger outputs events occurring within the SDK to the console for debugging purposes. To modify these options, you can use the setLogLevel function.

1import { setLogLevel, LogLevel } from '@yorkie-js/sdk';
2
3setLogLevel(LogLevel.Error); // Display logs with Error or higher

The available log levels for setLogLevel are:

Adjust the log level for flexible control over log verbosity in your application.

Reference

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