diff --git a/docs/js-sdk.mdx b/docs/js-sdk.mdx index e078f4f..5669a53 100644 --- a/docs/js-sdk.mdx +++ b/docs/js-sdk.mdx @@ -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. + + +Subscribe before attaching the document to ensure you receive the initial `initialized` event. + ```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. @@ -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 @@ -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). + + +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`. + + +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. + + +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. + + ##### 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. @@ -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`. 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) {