Skip to content

Commit

Permalink
Update docs for doc.subscribe() events (#134)
Browse files Browse the repository at this point in the history
* Update docs for snapshot and change events

* Update docs for presence events
  • Loading branch information
chacha912 authored May 23, 2024
1 parent 85d6d14 commit dca06b3
Showing 1 changed file with 37 additions and 18 deletions.
55 changes: 37 additions & 18 deletions docs/js-sdk.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -140,33 +140,39 @@ Here is an example of showing a list of users participating in the collaborative

##### Document.subscribe('presence')

This method allows you to subscribe to all presence-related changes.
By subscribing to these events, you can be notified when specific changes occur within the document, such as clients attaching, detaching, or modifying their 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.

<Alert status="warning">
Subscribe before attaching the document to ensure you receive the initial `initialized` event.
</Alert>

```javascript
const unsubscribe = doc.subscribe('presence', (event) => {
if (event.type === 'initialized') {
// Array of other users currently participating in the document
// event.value;
// event.value: Array of users currently participating in the document
}

if (event.type === 'watched') {
// A user has joined the document editing in online
// event.value;
// event.value: A user has joined the document editing in online
}

if (event.type === 'unwatched') {
// A user has left the document editing
// event.value;
// event.value: A user has left the document editing
}

if (event.type === 'presence-changed') {
// A user has updated their presence
// event.value;
// event.value: A user has updated their presence
}
});
```

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.
Expand Down Expand Up @@ -241,14 +247,11 @@ Whenever the Document is modified, change events are triggered and we can subscr

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`.

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](https://yorkie.dev/yorkie-js-sdk/api-reference/interfaces/ChangeInfo.html).


```javascript
const unsubscribe = doc.subscribe((event) => {
if (event.type === 'local-change') {
if (event.type === 'snapshot') {
// Update with data from the Yorkie Document.
} else if (event.type === 'local-change') {
console.log(event);
} else if (event.type === 'remote-change') {
// `message` delivered when calling document.update
Expand All @@ -266,6 +269,24 @@ const unsubscribe = doc.subscribe((event) => {
});
```

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](https://yorkie.dev/yorkie-js-sdk/api-reference/interfaces/ChangeInfo.html).

<Alert status="warning">
The `event.rawChange` value for `local-change` and `remote-change` events, and the `event.value.snapshot` for `snapshot` event, are set only when [`enableDevtools`](/docs/devtools/#install-the-extension) option is configured as `true`.
</Alert>

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](https://github.com/yorkie-team/yorkie-js-sdk/blob/9c7accdfe337b9c9e7c7d0d3b3acc335951866ce/public/index.html#L346-L350) for handling snapshots in CodeMirror.

<Alert status="warning">
If a client has not synchronized for a prolonged period and then makes a sync request, it might receive a `snapshot` event.
Ensure your application processes these snapshot events correctly to maintain document synchronization.
</Alert>

##### 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.
Expand Down Expand Up @@ -317,8 +338,6 @@ You can subscribe to all events occurring in the document by using `document.sub

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()`).

The `event.rawChange` value for `local-change` and `remote-change` events, and the `event.value.snapshot` for `snapshot` event, are set only when `enableDevtools` option is configured as `true`.

```javascript
const unsubscribe = doc.subscribe('all', (transactionEvent) => {
for (const docEvent of transactionEvent) {
Expand Down

0 comments on commit dca06b3

Please sign in to comment.