[PUB-1039] Update Live Objects README section #1969
Conversation
|
Warning Rate limit exceeded@VeskeR has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 21 minutes and 24 seconds before requesting another review. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📒 Files selected for processing (1)
WalkthroughThe documentation in the Changes
Possibly related PRs
Poem
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
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)
Other keywords and placeholders
CodeRabbit Configuration File (
|
github-actions
bot
temporarily deployed
to
staging/pull/1969/bundle-report
github-actions
bot
temporarily deployed
to
staging/pull/1969/typedoc
github-actions
bot
temporarily deployed
to
staging/pull/1969/features
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (3)
README.md (3)
626-645: Consider adding examples of required capabilities.The State Channel Modes section clearly explains the required channel modes. However, it would be helpful to include examples of the corresponding capabilities required in the authentication token.
Add examples of required capabilities:
+```typescript +// Example capabilities for Live Objects +{ + "channel": { + "my_live_objects_channel": ["state_subscribe", "state_publish"] + } +} +```🧰 Tools
🪛 LanguageTool
[uncategorized] ~628-~628: Possible missing article found.
Context: ...cts). #### State Channel Modes To use Live Objects feature, clients must attach to...(AI_HYDRA_LEO_MISSING_THE)
🪛 markdownlint-cli2 (0.17.2)
633-633: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
707-756: Consider adding error handling examples.The Subscribing to Updates section is well-documented, but it would be beneficial to include examples of error handling in the subscription callbacks.
Add error handling examples:
+```typescript +// Example with error handling +root.subscribe((update: LiveMapUpdate) => { + try { + console.log('LiveMap updated:', update); + // Handle the update + } catch (error) { + console.error('Error handling LiveMap update:', error); + } +}); +```🧰 Tools
🪛 LanguageTool
[uncategorized] ~708-~708: It seems likely that a singular genitive (’s) apostrophe is missing.
Context: ...ltiple clients may modify the same Live Objects state, subscribing ensures that your ap...(AI_HYDRA_LEO_APOSTROPHE_S_XS)
🪛 markdownlint-cli2 (0.17.2)
714-714: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
744-744: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
785-805: Consider adding error handling for batch operations.The Batch Operations section clearly explains batching, but should include guidance on error handling within batch callbacks.
Add error handling example:
+```typescript +// Example with error handling +try { + await liveObjects.batch((ctx) => { + // ... batch operations + }); +} catch (error) { + console.error('Batch operation failed:', error); + // Handle the error appropriately +} +```🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
791-791: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
README.md(3 hunks)
🧰 Additional context used
🪛 LanguageTool
README.md
[style] ~593-~593: Consider a shorter alternative to avoid wordiness.
Context: ...ime clients via the LiveObjects plugin. In order to use Live Objects, you must pass in the ...
(IN_ORDER_TO_PREMIUM)
[uncategorized] ~628-~628: Possible missing article found.
Context: ...cts). #### State Channel Modes To use Live Objects feature, clients must attach to...
(AI_HYDRA_LEO_MISSING_THE)
[style] ~648-~648: Consider a shorter alternative to avoid wordiness.
Context: ...d data structures and must be retrieved in order to interact with the existing state. ```t...
(IN_ORDER_TO_PREMIUM)
[uncategorized] ~708-~708: It seems likely that a singular genitive (’s) apostrophe is missing.
Context: ...ltiple clients may modify the same Live Objects state, subscribing ensures that your ap...
(AI_HYDRA_LEO_APOSTROPHE_S_XS)
🪛 markdownlint-cli2 (0.17.2)
README.md
595-595: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
615-615: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
633-633: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
650-650: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
664-664: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
692-692: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
714-714: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
744-744: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
762-762: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
769-769: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
791-791: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
813-813: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
827-827: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
839-839: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
858-858: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
878-878: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
888-888: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
🪛 GitHub Actions: Lint
README.md
[warning] 1-1: Code style issues found in the above file. Run Prettier with --write to fix.
⏰ Context from checks skipped due to timeout of 90000ms (7)
- GitHub Check: test-node (20.x)
- GitHub Check: test-browser (webkit)
- GitHub Check: test-node (18.x)
- GitHub Check: test-browser (firefox)
- GitHub Check: test-browser (chromium)
- GitHub Check: test-node (16.x)
- GitHub Check: test-npm-package
🔇 Additional comments (7)
README.md (7)
587-587: LGTM!Good addition of the link to push notifications documentation, which helps users find more detailed information.
589-624: LGTM! Well-structured introduction to Live Objects.The introduction and plugin usage section is clear and comprehensive, providing both npm and CDN installation options with proper versioning information.
🧰 Tools
🪛 LanguageTool
[style] ~593-~593: Consider a shorter alternative to avoid wordiness.
Context: ...ime clients via the LiveObjects plugin. In order to use Live Objects, you must pass in the ...(IN_ORDER_TO_PREMIUM)
[uncategorized] ~622-~622: Possible missing comma found.
Context: ...y.com/lib/liveobjects.umd.min-2.4.0.js. Note you can load the non-minified version b...(AI_HYDRA_LEO_MISSING_COMMA)
🪛 markdownlint-cli2 (0.17.2)
595-595: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
609-609: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
615-615: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
622-622: Bare URL used
null(MD034, no-bare-urls)
622-622: Bare URL used
null(MD034, no-bare-urls)
622-622: Bare URL used
null(MD034, no-bare-urls)
622-622: Bare URL used
null(MD034, no-bare-urls)
622-622: Spaces inside emphasis markers
null(MD037, no-space-in-emphasis)
647-655: LGTM! Clear explanation of the root object.The Root Object section effectively explains its role as the entry point for Live Objects state.
🧰 Tools
🪛 LanguageTool
[style] ~648-~648: Consider a shorter alternative to avoid wordiness.
Context: ...d data structures and must be retrieved in order to interact with the existing state. ```t...(IN_ORDER_TO_PREMIUM)
🪛 markdownlint-cli2 (0.17.2)
650-650: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
657-705: LGTM! Comprehensive coverage of Live Object Types.The Live Object Types section provides clear explanations and examples for both
LiveMapandLiveCountertypes.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
664-664: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
692-692: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
758-783: LGTM! Clear examples of object creation and hierarchy.The Creating New Objects section effectively demonstrates how to create and organize Live Objects in a hierarchy.
🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
762-762: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
769-769: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
807-852: LGTM! Comprehensive coverage of lifecycle events.The Lifecycle Events section effectively explains both synchronization and deletion events with clear examples.
🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
813-813: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
827-827: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
839-839: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
854-885: LGTM! Well-documented TypeScript support.The Typing Live Objects section provides clear examples of both global and channel-specific type definitions.
🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
858-858: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
878-878: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
README.md
Outdated
|
|
||
| #### Live Object Types | ||
|
|
||
| Live Objects support two primary data structures: |
VeskeR
force-pushed
the
PUB-1039/update-readme
branch
from
344c5e9 to
cf1c49b
Compare
Describe the Live Objects create/edit/read API, live object types, root object, state channel modes, batch operations lifecycle events and user provided typings for Live Objects.
github-actions
bot
temporarily deployed
to
staging/pull/1969/bundle-report
VeskeR
force-pushed
the
PUB-1039/update-readme
branch
from
cf1c49b to
54a5125
Compare
|
|
||
| Subscribing to updates on Live Objects allows you to receive changes made by other clients in realtime. Since multiple clients may modify the same Live Objects state, subscribing ensures that your application reacts to external updates as soon as they are received. | ||
|
|
||
| Additionally, mutation methods such as `LiveMap.set`, `LiveCounter.increment`, and `LiveCounter.decrement` do not directly edit the current state of the object locally. Instead, they send the intended operation to the Ably system, and the change is applied to the local object only when the corresponding realtime operation is echoed back to the client. This means that the state you retrieve immediately after a mutation may not reflect the latest updates yet. |
There was a problem hiding this comment.
Can you clarify this? If you await a mutation, the local state does not have that mutation applied after completion of the operation?
There was a problem hiding this comment.
Correct, the mutation operation might not be applied after we await the mutation call, as this only awaits the ACK message for the mutation operation. It will be applied only once the operation is echoed back to the client.
We discussed this with Mike in this DR, and considered the possibility of applying the mutation client-side when we receive an ACK message (meaning it would be applied locally after await). It needed more thought (as we rely on applying messages from a given site in regional order), and it was put on hold for the time being.
|
|
||
| The authentication token must include corresponding capabilities for the client to interact with Live Objects. | ||
|
|
||
| #### Obtaining the Root Object |
There was a problem hiding this comment.
Obtaining is a really convoluted word. Where possible we should prefer the simplest possible language. How about "getting" or "accessing" ?
|
|
||
| #### Obtaining the Root Object | ||
|
|
||
| The root object represents the top-level entry point for Live Objects state within a channel. It acts as a container for all nested data structures and must be retrieved in order to interact with the existing state. |
There was a problem hiding this comment.
| The root object represents the top-level entry point for Live Objects state within a channel. It acts as a container for all nested data structures and must be retrieved in order to interact with the existing state. | |
| The root object represents the top-level entry point for Live Objects state within a channel. It give access to all other nested live objects. |
| const root = await liveObjects.getRoot(); | ||
| ``` | ||
|
|
||
| The root object is always a `LiveMap` instance and serves as the starting point for storing and organizing Live Objects state. |
There was a problem hiding this comment.
| The root object is always a `LiveMap` instance and serves as the starting point for storing and organizing Live Objects state. | |
| The root object is a `LiveMap` instance and serves as the starting point for storing and organizing Live Objects state. |
|
|
||
| #### Live Object Types | ||
|
|
||
| Live Objects currently support two primary data structures: |
There was a problem hiding this comment.
| Live Objects currently support two primary data structures: | |
| Live Objects currently supports two primary data structures; LiveMap and LiveCounter. |
|
|
||
| Additionally, mutation methods such as `LiveMap.set`, `LiveCounter.increment`, and `LiveCounter.decrement` do not directly edit the current state of the object locally. Instead, they send the intended operation to the Ably system, and the change is applied to the local object only when the corresponding realtime operation is echoed back to the client. This means that the state you retrieve immediately after a mutation may not reflect the latest updates yet. | ||
|
|
||
| To ensure you react to state changes at the correct moment, you can subscribe to updates on all Live Objects as follows: |
There was a problem hiding this comment.
| To ensure you react to state changes at the correct moment, you can subscribe to updates on all Live Objects as follows: | |
| You can subscribe to updates on all Live Objects using subscription listeners as follows: |
I've added "subscription listeners" here because later way say you can de-register "subscription listeners" without mentioning them before. Obviously you can see from the code, but adding clarity here.
|
|
||
| // perform operations on LiveMap and LiveCounter | ||
| await root.set('name', 'Alice'); | ||
| // LiveMap updated: { update: { name: 'updated' } } |
There was a problem hiding this comment.
question: should the update event carry the new value as well as the key that was modified?
| }); | ||
| ``` | ||
|
|
||
| **Object Deletion Events** - objects that have been orphaned for a long period (i.e., not connected to the state tree graph by being set as a key in a map related to the root) will eventually be deleted. Once a Live Object is deleted, it can no longer be interacted with. You should avoid accessing its data or try to update its value and should remove all references to the deleted object in your application. |
There was a problem hiding this comment.
| **Object Deletion Events** - objects that have been orphaned for a long period (i.e., not connected to the state tree graph by being set as a key in a map related to the root) will eventually be deleted. Once a Live Object is deleted, it can no longer be interacted with. You should avoid accessing its data or try to update its value and should remove all references to the deleted object in your application. | |
| **Object Deletion Events** - objects that have been orphaned for a long period (i.e., not connected to the state tree graph by being set as a key in a map related to the root) will eventually be deleted. Once a Live Object is deleted, it can no longer be interacted with. You should avoid accessing its data or trying to update its value and you should remove all references to the deleted object in your application. |
Describe the Live Objects create/edit/read API, live object types, root object, state channel modes, batch operations lifecycle events and user provided typings for Live Objects.
Resolves PUB-1039
Summary by CodeRabbit