[PUB-773] LiveObjects product docs #2463

VeskeR · 2025-03-05T09:15:14Z

Description

Adds LiveObjects product documentation to content section. Final docs structure can be found here: https://ably.atlassian.net/wiki/spaces/LOB/pages/3839623174/LORFC-001+LiveObjects+Product+Docs+structure.

This PR adds documentation for next LiveObjects pages:

Resolves PUB-773

Site navigation for LiveObjects is added in #2464, but can be moved into this PR if requested.

Checklist

Commits have been rebased.
Linting has been run against the changed file(s).
The PR adheres to the writing style guide and contribution guide.

coderabbitai · 2025-03-05T09:15:22Z

Important

Review skipped

Auto reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

Review comments: Directly reply to a review comment made by CodeRabbit. Example:
- I pushed a fix in commit <commit_id>, please review it.
- Generate unit testing code for this file.
- Open a follow-up GitHub issue for this discussion.
Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
- @coderabbitai generate unit testing code for this file.
- @coderabbitai modularize this function.
PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
- @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
- @coderabbitai read src/utils.ts and generate unit testing code.
- @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
- @coderabbitai help me debug CodeRabbit configuration file.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

@coderabbitai pause to pause the reviews on a PR.
@coderabbitai resume to resume the paused reviews.
@coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
@coderabbitai full review to do a full review from scratch and review all the files again.
@coderabbitai summary to regenerate the summary of the PR.
@coderabbitai generate docstrings to generate docstrings for this PR.
@coderabbitai resolve resolve all the CodeRabbit review comments.
@coderabbitai plan to trigger planning for file edits and PR creation.
@coderabbitai configuration to show the current CodeRabbit configuration for the repository.
@coderabbitai help to get help.

Other keywords and placeholders

Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (`.coderabbit.yaml`)

You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
Please see the configuration documentation for more information.
If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

Visit our Documentation for detailed information on how to use CodeRabbit.
Join our Discord Community to get help, request features, and share feedback.
Follow us on X/Twitter for updates and announcements.

mschristensen

Great stuff, thanks for this! A few comments

content/liveobjects/index.textile

content/liveobjects/quickstart.textile

content/liveobjects/setup.textile

content/liveobjects/typing.textile

mschristensen

Great stuff, thanks Andrii. Final review from me and then this looks good - apologies for the high volume of nit picky comments, but I've attempted to suggest changes to ensure we have a consistent use of terminology:

"LiveObjects" is used to refer to the product name, rather than object instance (and is never "Live Objects")
objects is used to refer to object instances
avoid use of state and prefer channel objects

Hopefully in suggestion format these changes are relatively easy to apply. Thanks again for this :)

content/liveobjects/index.textile

content/liveobjects/quickstart.textile

content/liveobjects/batch.textile

content/liveobjects/index.textile

content/liveobjects/map.textile

content/liveobjects/quickstart.textile

paddybyers · 2025-03-13T06:29:46Z

content/liveobjects/batch.textile

+
+To batch operations together, use the @channel.objects.batch()@ method. This method accepts a callback function, which is provided with a batch context object. The batch context object provides a synchronous API to work with LiveObjects on a channel that stores operations inside the batch instead of applying them immediately.
+
+Using the batch context ensures that operations are grouped and sent after the batch callback function has run, which means that all clients receive them as a single message.


Maybe the emphasis here should be that they are applied atomically (both by the server and any clients), rather than just being received simultaneously

updated phrasing in https://github.com/ably/docs/compare/25b22986a872be1dab9b4d3122f66def13dc0d1a..453be49b85fe678c6d9efafaec5095e07d40ee4c

paddybyers · 2025-03-13T06:52:11Z

I've not seen anything explaining how this works offline. I think somewhere we should explain the model in that LiveObjects is an online-oriented feature; object creation and mutation operations initiated by a client are processed by the backend at the time. In this iteration at least, there's no offline mode, or synchronisation of changes made locally by a client while disconnected.

m-hulbert

This is really great, Andrii.

I've made a few suggestions for fixes and enhancements. I've commented in a few places, but you don't need to include blang[] as that just hides/shows content only relevant to 1 language (see here for info).

I also wonder if we can include something a diagram, or something visual to help explain LiveObjects on the 'about' page.

content/liveobjects/index.textile

m-hulbert · 2025-03-17T11:41:01Z

content/liveobjects/index.textile

+* "Composability":#composability
+* "Batching operations":#batch


Do we consider batching and composability as features on par with LiveMap and LiveCounter, or are they more key functionality that the features implement?

batching

Batching probably deserves to be a separate feature, similarly like we have for message batching on channels.

Also I guess batching can be considered as a feature of the state synchronization engine - to enable applying operations to state atomically.

On the other hand, if we really want to make it a "functionallity of the feature", then I'm not sure where to add it. Batching is available on the top level channel.objects instance. Do we consider the Objects instance "a feature" that has batching functionallity? And following this thought, should we then add an Objects header to navigation to describe the API available on the Objects instance at channel.objects?

composability

This one is probably not a "feature", agree. Should probably just remove it from this list and unite the section with LiveMap

On a similar not, regarding Typing in the navigation:
It's not necessarily a "feature" by itself, but a pretty vital part of LiveObjects, we want developers to know that then can type their liveobjects and enjoy TypeScript with this product. Having it as a separate header in the navigation makes it more visible than hiding it under other features like Objects.

Batching provides a dedicated API in its own right, so I think it's sensible to include that with its own heading

content/liveobjects/index.textile

content/liveobjects/lifecycle.textile

content/liveobjects/batch.textile

m-hulbert · 2025-03-17T14:20:17Z

content/liveobjects/batch.textile

+
+The Batching API in LiveObjects allows multiple updates to be grouped into a single channel message and applied atomically. It ensures that all operations in a batch either succeed together or are discarded entirely. Batching operations is essential when multiple related updates to the state must be applied as a single atomic unit, for example, when application logic depends on multiple LiveObjects being updated simultaneously. Without batching, if one operation succeeds while another fails, your application state could become inconsistent.
+
+Note that this differs from "Message batching":/docs/messages/batch, the native Pub/Sub messages feature. LiveObjects provides a separate API specifically for grouping LiveObjects operations into a single channel message, allowing the Ably system to guarantee the atomicity of the applied changes.


Agree with Paddy here: I made that page to cover the different types of batching in Pub/Sub because the term was becoming very overloaded.

content/liveobjects/batch.textile

VeskeR · 2025-03-18T09:45:42Z

@mschristensen

I've attempted to suggest changes to ensure we have a consistent use of terminology

"LiveObjects" is used to refer to the product name, rather than object instance (and is never "Live Objects")

objects is used to refer to object instances

avoid use of state and prefer channel objects

This is actually great! I was struggling a bit with the correct way to address different concepts (for example, 'state on a channel') after the renaming change we made, so this really helps set things in stone.

I'll also add that terminology to the naming PR for future reference when I have a bit more time more time.

I've applied your suggestions and did another pass to remove additional instances of "Live Object" and "state" terminology where necessary.

VeskeR · 2025-03-18T11:20:26Z

@m-hulbert

you don't need to include blang[]

This was intentional, see my comment #2463 (comment)

I also wonder if we can include something a diagram, or something visual to help explain LiveObjects on the 'about' page.

The simplest thing would be to do some kind of the object tree diagram, but that alone doesn’t effectively convey the "realtime state synchronization" aspect of LiveObjects.

Rather than a purely technical diagram, a more marketing-oriented illustration - similar to the one we have for LiveSync - might be a better fit here.

Since LiveObjects is quite similar in nature, we can use the similar concept: Objects on the channel on the left, the Ably realtime system in the center, and two clients with some JSON data on the right being synced.
@mschristensen WDYT?

mschristensen · 2025-03-20T16:32:19Z

Since LiveObjects is quite similar in nature, we can use the similar concept: Objects on the channel on the left, the Ably realtime system in the center, and two clients with some JSON data on the right being synced.
@mschristensen WDYT?

It would be good to get a diagram, but we need to get design to make one, so let's not block this on that basis. I've created a ticket: https://ably.atlassian.net/browse/PUB-1533

This looks good to me, @VeskeR can we redeploy the latest version to Heroku so I can take a final look at the result please?

@m-hulbert is it possible to feature flag these docs so we can merge this but they don't appear on the website until we're ready? There are other docs changes that are coming re. the REST API, which @zknill is working on, so if we can't feature flag we might need to merge this into an integration branch that other docs PRs can target.

… feature This commit does next changes: - removes `state` mentions in comments / internal API. Uses `objects` instead where possible - normalizes terminology used when referencing "LiveObjects" product and objects on a channel according to LiveObjects product docs PR [1] - `STATE` message action -> `OBJECT` - `STATE_SYNC` message action -> `OBJECT_SYNC` - `HAS_STATE` flag -> `HAS_OBJECT` - `StateMessage` type -> `ObjectMessage` - `StateOperation` type -> `ObjectOperation` - `StateObject` type -> `ObjectState` - `StateData` type -> `ObjectData` - `StateValue` type -> `ObjectValue` This brings ably-js LiveObjects implementation in line with the naming changes introduced in the spec PR [2]. [1] ably/docs#2463 (review) [2] ably/specification#279 (comment)

m-hulbert

I still have the open question around channel modes, but happy to merge this to the integration branch and address separately for ease.

Regardless of its outcome, can we add the new modes to channels/options#modes first though please?

mschristensen · 2025-03-31T13:55:39Z

I still have the open question around channel modes, but happy to merge this to the integration branch and address separately for ease.

Regardless of its outcome, can we add the new modes to channels/options#modes first though please?

I have another PR in flight that aligns existing pub/sub docs with any live objects related changes, which will include modes

mschristensen · 2025-03-31T14:17:51Z

@m-hulbert PR with modes changes here: #2503

… feature This commit does next changes: - removes `state` mentions in comments / internal API. Uses `objects` instead where possible - normalizes terminology used when referencing "LiveObjects" product and objects on a channel according to LiveObjects product docs PR [1] - `STATE` message action -> `OBJECT` - `STATE_SYNC` message action -> `OBJECT_SYNC` - `HAS_STATE` flag -> `HAS_OBJECT` - `StateMessage` type -> `ObjectMessage` - `StateOperation` type -> `ObjectOperation` - `StateObject` type -> `ObjectState` - `StateData` type -> `ObjectData` - `StateValue` type -> `ObjectValue` This brings ably-js LiveObjects implementation in line with the naming changes introduced in the spec PR [2]. [1] ably/docs#2463 (review) [2] ably/specification#279 (comment)

VeskeR · 2025-04-02T12:46:56Z

Removed the capabilities changes from this PR (326fde2) according to the comment. These will be added in #2503

… feature This commit does next changes: - removes `state` mentions in comments / internal API. Uses `objects` instead where possible - normalizes terminology used when referencing "LiveObjects" product and objects on a channel according to LiveObjects product docs PR [1] - `STATE` message action -> `OBJECT` - `STATE_SYNC` message action -> `OBJECT_SYNC` - `HAS_STATE` flag -> `HAS_OBJECT` - `StateMessage` type -> `ObjectMessage` - `StateOperation` type -> `ObjectOperation` - `StateObject` type -> `ObjectState` - `StateData` type -> `ObjectData` - `StateValue` type -> `ObjectValue` This brings ably-js LiveObjects implementation in line with the naming changes introduced in the spec PR [2]. [1] ably/docs#2463 (review) [2] ably/specification#279 (comment)

m-hulbert

LGTM - just one small change for sentence case.

m-hulbert · 2025-04-11T07:41:32Z

content/liveobjects/lifecycle.textile

@@ -0,0 +1,66 @@
+---
+title: Lifecycle Events


Can this be sentence case please? In the table of contents too (and the same for 'Batch Operations'

updated in https://github.com/ably/docs/compare/b782e1fa9393cb5bb8a7ecb0f203720b84088c2d..6532e7ff31e55eace57a9bcd05cd3703c34ba600

VeskeR requested review from mschristensen and a team March 5, 2025 09:15

ably-ci temporarily deployed to ably-docs-pub-773-liveo-07sgjc March 5, 2025 09:15 Inactive

VeskeR force-pushed the PUB-773/liveobjects-product-docs branch from 3bfe8d2 to 145457e Compare March 5, 2025 09:31

m-hulbert temporarily deployed to ably-docs-pub-773-liveo-07sgjc March 5, 2025 10:06 Inactive

VeskeR requested a review from a team March 5, 2025 20:26

VeskeR force-pushed the PUB-773/liveobjects-product-docs branch 3 times, most recently from 1f7289e to 2f870cd Compare March 7, 2025 09:18

VeskeR marked this pull request as ready for review March 7, 2025 09:19

mschristensen requested changes Mar 7, 2025

View reviewed changes

VeskeR force-pushed the PUB-773/liveobjects-product-docs branch 2 times, most recently from 7c9bad3 to 25b2298 Compare March 11, 2025 08:24

VeskeR mentioned this pull request Mar 11, 2025

Fix formatting for links #2469

Merged

3 tasks

VeskeR requested a review from mschristensen March 11, 2025 08:34

VeskeR mentioned this pull request Mar 11, 2025

Add LiveObjects product to site navigation #2464

Merged

5 tasks

m-hulbert temporarily deployed to ably-docs-pub-773-liveo-snhs8k March 12, 2025 08:56 Inactive

mschristensen requested changes Mar 12, 2025

View reviewed changes

paddybyers reviewed Mar 13, 2025

View reviewed changes

m-hulbert temporarily deployed to ably-docs-pub-773-liveo-olyhs1 March 17, 2025 11:10 Inactive

m-hulbert requested changes Mar 17, 2025

View reviewed changes

VeskeR force-pushed the PUB-773/liveobjects-product-docs branch 2 times, most recently from 70e3d74 to 0d1c04b Compare March 18, 2025 09:40

VeskeR requested a review from mschristensen March 18, 2025 09:47

VeskeR requested a review from m-hulbert March 18, 2025 11:20

VeskeR force-pushed the PUB-773/liveobjects-product-docs branch 2 times, most recently from 56c767d to 326fde2 Compare March 27, 2025 08:43

VeskeR mentioned this pull request Mar 27, 2025

[PUB-1539] Replace internal usage of "state" term with "objects" for LiveObjects ably/ably-js#1992

Merged

m-hulbert temporarily deployed to ably-docs-pub-773-liveo-76mgiy March 28, 2025 14:40 Inactive

m-hulbert reviewed Mar 28, 2025

View reviewed changes

VeskeR mentioned this pull request Apr 2, 2025

Feature/pub 1049 pubsub docs liveobjects #2503

Merged

3 tasks

VeskeR force-pushed the PUB-773/liveobjects-product-docs branch from 326fde2 to 4d498e1 Compare April 2, 2025 12:46

VeskeR added 2 commits April 9, 2025 09:12

Add LiveObjects index docs

cc575fd

Add channels.objects property to realtime api docs

9545871

VeskeR force-pushed the PUB-773/liveobjects-product-docs branch from 4d498e1 to 451c972 Compare April 9, 2025 08:13

VeskeR added 4 commits April 9, 2025 09:22

Add LiveObjects Quickstart docs

70e751f

Add LiveObjects LiveCounter docs

5a41d6e

Add LiveObjects LiveMap docs

35cd419

Add LiveObjects Batch Operations docs

1cae8e9

VeskeR force-pushed the PUB-773/liveobjects-product-docs branch from 451c972 to b782e1f Compare April 9, 2025 08:22

VeskeR requested a review from m-hulbert April 9, 2025 08:23

m-hulbert deployed to ably-docs-pub-773-liveo-mnjl2i April 11, 2025 07:33 View deployment

m-hulbert approved these changes Apr 11, 2025

View reviewed changes

VeskeR added 3 commits April 11, 2025 10:10

Add LiveObjects Lifecycle events docs

b4b4a6f

Add LiveObjects Typings docs

5a0dd9d

Use sentence case in navigation

6532e7f

VeskeR force-pushed the PUB-773/liveobjects-product-docs branch from b782e1f to 6532e7f Compare April 11, 2025 09:10

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[PUB-773] LiveObjects product docs #2463

[PUB-773] LiveObjects product docs #2463

VeskeR commented Mar 5, 2025 •

edited

Loading

coderabbitai bot commented Mar 5, 2025 •

edited

Loading

Review skipped

Chat

CodeRabbit Commands (Invoked using PR comments)

Other keywords and placeholders

CodeRabbit Configuration File (`.coderabbit.yaml`)

Documentation and Community

mschristensen left a comment

mschristensen left a comment

paddybyers Mar 13, 2025

VeskeR Mar 18, 2025

paddybyers commented Mar 13, 2025 •

edited

Loading

m-hulbert left a comment

m-hulbert Mar 17, 2025

VeskeR Mar 18, 2025

mschristensen Mar 20, 2025

m-hulbert Mar 17, 2025

VeskeR commented Mar 18, 2025 •

edited

Loading

VeskeR commented Mar 18, 2025

mschristensen commented Mar 20, 2025

m-hulbert left a comment

mschristensen commented Mar 31, 2025

mschristensen commented Mar 31, 2025

VeskeR commented Apr 2, 2025

m-hulbert left a comment

m-hulbert Apr 11, 2025

VeskeR Apr 11, 2025


		To batch operations together, use the @channel.objects.batch()@ method. This method accepts a callback function, which is provided with a batch context object. The batch context object provides a synchronous API to work with LiveObjects on a channel that stores operations inside the batch instead of applying them immediately.

		Using the batch context ensures that operations are grouped and sent after the batch callback function has run, which means that all clients receive them as a single message.

		* "Composability":#composability
		* "Batching operations":#batch


		The Batching API in LiveObjects allows multiple updates to be grouped into a single channel message and applied atomically. It ensures that all operations in a batch either succeed together or are discarded entirely. Batching operations is essential when multiple related updates to the state must be applied as a single atomic unit, for example, when application logic depends on multiple LiveObjects being updated simultaneously. Without batching, if one operation succeeds while another fails, your application state could become inconsistent.

		Note that this differs from "Message batching":/docs/messages/batch, the native Pub/Sub messages feature. LiveObjects provides a separate API specifically for grouping LiveObjects operations into a single channel message, allowing the Ably system to guarantee the atomicity of the applied changes.

[PUB-773] LiveObjects product docs #2463

Are you sure you want to change the base?

[PUB-773] LiveObjects product docs #2463

Conversation

VeskeR commented Mar 5, 2025 • edited Loading

Description

Checklist

coderabbitai bot commented Mar 5, 2025 • edited Loading

Review skipped

Chat

CodeRabbit Commands (Invoked using PR comments)

Other keywords and placeholders

CodeRabbit Configuration File (.coderabbit.yaml)

Documentation and Community

mschristensen left a comment

Choose a reason for hiding this comment

mschristensen left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

paddybyers commented Mar 13, 2025 • edited Loading

m-hulbert left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

VeskeR commented Mar 18, 2025 • edited Loading

VeskeR commented Mar 18, 2025

mschristensen commented Mar 20, 2025

m-hulbert left a comment

Choose a reason for hiding this comment

mschristensen commented Mar 31, 2025

mschristensen commented Mar 31, 2025

VeskeR commented Apr 2, 2025

m-hulbert left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

VeskeR commented Mar 5, 2025 •

edited

Loading

coderabbitai bot commented Mar 5, 2025 •

edited

Loading

CodeRabbit Configuration File (`.coderabbit.yaml`)

paddybyers commented Mar 13, 2025 •

edited

Loading

VeskeR commented Mar 18, 2025 •

edited

Loading