Skip to content

[AIT-280] Update JS LiveObjects documentation for apply-on-ACK #3161

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lawrence-forooghian wants to merge 1 commit into
base: main
Choose a base branch
from
Open

[AIT-280] Update JS LiveObjects documentation for apply-on-ACK #3161

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/pages/docs/liveobjects/batch.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -198,7 +198,7 @@ try {
</Code>

<Aside data-type='note'>
Although the batch context provides a synchronous API, updates to objects are only applied _after_ the batch callback function has run and changes have been echoed back to the client, like regular mutation operations.
Although the batch context provides a synchronous API, updates to objects are only applied _after_ the batch callback function has run and the changes have been acknowledged by the Ably system. When the `batch()` promise resolves, all operations have been applied and you can immediately read the updated state.
</Aside>

Since the batch callback is synchronous, you can read current values inside a batch context without intermediate updates from other clients being applied between reads:
Expand Down
11 changes: 11 additions & 0 deletions src/pages/docs/liveobjects/concepts/synchronization.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,8 +51,19 @@ Calling [`channel.object.get()`](/docs/liveobjects/concepts/objects#channel-obje

All object operations published to the channel are broadcast to subscribed clients, which apply the operations to their local client objects when they are received. This allows clients to maintain a consistent view of the channel objects in a bandwidth-efficient way, since only the operations (rather than the updated objects themselves) are sent over the client's connection.

<If lang="javascript">
<Aside data-type='note'>
When a client publishes an operation, the operation is applied to its local objects as soon as the operation is acknowledged by the Ably system. This means that when a mutation method's promise resolves, the operation has already been applied and you can immediately read the updated state.
</Aside>

<Aside data-type='important'>
Copy link
Contributor

@GregHolmes GregHolmes Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this Aside needed? If the user is trying to implement with Swift or Java, they'll have the language relevant to them.

Copy link
Contributor Author

@lawrence-forooghian lawrence-forooghian Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was thinking that perhaps if they're using JS as their "main" SDK and then just porting their code across to Swift and Kotlin, then they might not re-read all the documentation for those two as well.

If you're also developing with the Swift or Java SDKs, note that they currently apply operations when [echoed](/docs/pub-sub/advanced#echo) back from the server rather than on acknowledgment. Apply-on-acknowledgment is coming soon to those SDKs.
</Aside>
</If>
<If lang="swift,java">
<Aside data-type='note'>
Currently, when a client publishes an operation it is not immediately applied to its local objects. Instead, the client only applies the operation when the operation is [echoed](/docs/pub-sub/advanced#echo) back to the client.
</Aside>
</If>

If there is a loss of continuity on the channel for any reason, such as the client becoming disconnected for more than two minutes and entering the [suspended state](/docs/connect/states#connection-states), the client objects will automatically be resynchronized when it reconnects.
2 changes: 1 addition & 1 deletion src/pages/docs/liveobjects/quickstart/javascript.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -200,7 +200,7 @@ await reactionsMap.remove('likes');
</Code>

<Aside data-type='note'>
Mutation methods do not directly modify the local object state. Instead, they send operations to the Ably system, and changes are applied when the operations are echoed back to the client. This means the state retrieved immediately after a mutation may not reflect the latest updates yet. You will be notified via subscription when the object is updated.
Mutation methods send operations to the Ably system and apply changes locally as soon as the operations are acknowledged. When a mutation method's promise resolves, the operation has been applied and you can immediately read the updated state. You will also be notified via subscription when the object is updated.
</Aside>

## Next steps <a id="step-8"/>
Expand Down