[PUB-1039] Update Live Objects README section #1969
Conversation
WalkthroughThe documentation in the Changes
Possibly related PRs
Suggested reviewers
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
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
github-actions
bot
temporarily deployed
to
staging/pull/1969/bundle-report
github-actions
bot
temporarily deployed
to
staging/pull/1969/features
github-actions
bot
temporarily deployed
to
staging/pull/1969/typedoc
|
|
||
| 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.
There was a problem hiding this comment.
The current behaviour is consistent with that of presence in the core SDKs, right? e.g. if you call presence.get() immediately after the completion of presence.enter(), you might not see yourself in the presence set.
README.md
Outdated
|
|
||
| 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" ?
There was a problem hiding this comment.
Changed to "getting" as it is also used in "getting presence:"
https://github.com/ably/ably-js/compare/54a5125fcd43b43948ca982f7a1ed89c538cec50..3ca50035284754bf9cac21af0de744a0ae97ef85
README.md
Outdated
|
|
||
| #### 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. |
There was a problem hiding this comment.
README.md
Outdated
| 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. |
There was a problem hiding this comment.
README.md
Outdated
|
|
||
| #### 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. |
There was a problem hiding this comment.
README.md
Outdated
|
|
||
| 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.
There was a problem hiding this comment.
|
|
||
| // 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?
There was a problem hiding this comment.
the current API only exposes the name of the key that got updated/deleted. it is trivial at this point to just call root.get(key) to get the new value.
a bit more useful could be exposing both the previous and teh new value, just like we do with ChannelStateChange, but currently it's not implemented
There was a problem hiding this comment.
created https://ably.atlassian.net/browse/PUB-1207 to track this
README.md
Outdated
| }); | ||
| ``` | ||
|
|
||
| **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. |
There was a problem hiding this comment.
Also maybe related to the root -> accessible from the root map object.
There was a problem hiding this comment.
README.md
Outdated
|
|
||
| #### State Channel Modes | ||
|
|
||
| To use Live Objects feature, clients must attach to a channel with the correct channel mode: |
There was a problem hiding this comment.
Are we calling it Live Objects or LiveObjects? I think we should use a consistent name, so probably LiveObjects
There was a problem hiding this comment.
right, it's the LiveObjects product, but sometimes the readme explicitly refers to the objects in LiveObjects, which are just Live Objects.
I've gone through all of the "liveobjects"/"live objects" uses to double check which they are referring to and update accordingly:
https://github.com/ably/ably-js/compare/54a5125fcd43b43948ca982f7a1ed89c538cec50..3ca50035284754bf9cac21af0de744a0ae97ef85
https://github.com/ably/ably-js/compare/3ca50035284754bf9cac21af0de744a0ae97ef85..2065e11c8b39e421b3289cad832930814d03a618
README.md
Outdated
| await root.set('qux', new Uint8Array([21, 31])); | ||
| // as well as other live objects | ||
| const counter = await liveObjects.createCounter(); | ||
| await root.get('quux', counter); |
There was a problem hiding this comment.
Should this be root.set ?
There was a problem hiding this comment.
README.md
Outdated
|
|
||
| #### Batch Operations | ||
|
|
||
| Batching allows multiple operations to be grouped into a single message that is sent to the Ably service. |
There was a problem hiding this comment.
| Batching allows multiple operations to be grouped into a single message that is sent to the Ably service. | |
| Batching allows multiple operations to be grouped into a single message that is sent to the Ably service. This allows batched operations to be applied atomically together. |
There was a problem hiding this comment.
README.md
Outdated
| }); | ||
| ``` | ||
|
|
||
| **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.
Also maybe related to the root -> accessible from the root map object.
README.md
Outdated
| } | ||
| ``` | ||
|
|
||
| This will enable IntelliSense support when interacting with the Live Objects API: |
There was a problem hiding this comment.
I think IntelliSense is a microsoft-specific concept, perhaps code completion and editor hints ?
There was a problem hiding this comment.
VeskeR
force-pushed
the
PUB-1039/update-readme
branch
from
54a5125 to
3ca5003
Compare
github-actions
bot
temporarily deployed
to
staging/pull/1969/features
github-actions
bot
temporarily deployed
to
staging/pull/1969/typedoc
github-actions
bot
temporarily deployed
to
staging/pull/1969/bundle-report
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (5)
README.md (5)
591-594: Using the LiveObjects Plugin – Wording Suggestion
The description in this block is clear; however, the sentence “In order to use LiveObjects, you must pass in the plugin via client options.” can be made more concise. Consider rephrasing it as, for example:
- “To use LiveObjects, include the plugin in your client options.”
This improves readability without losing meaning.-LiveObjects functionality is supported for Realtime clients via the LiveObjects plugin. In order to use LiveObjects, you must pass in the plugin via client options. +LiveObjects functionality is supported for Realtime clients via the LiveObjects plugin. To use LiveObjects, include the plugin in your client options.🧰 Tools
🪛 LanguageTool
[style] ~593-~593: Consider a shorter alternative to avoid wordiness.
Context: ...ime clients via the LiveObjects plugin. In order to use LiveObjects, you must pass in the p...(IN_ORDER_TO_PREMIUM)
646-650: Getting the Root Object – Clarity and Terminology
The “#### Getting the Root Object” section explains the purpose clearly.
Suggestion: Instead of “gives access to all other nested Live Objects,” consider “provides access to all other nested Live Objects” to improve clarity.-The root object represents the top-level entry point for LiveObjects state within a channel. It gives access to all other nested Live Objects. +The root object represents the top-level entry point for LiveObjects state within a channel. It provides access to all nested Live Objects.🧰 Tools
🪛 LanguageTool
[style] ~648-~648: Try using a synonym here to strengthen your writing.
Context: ... LiveObjects state within a channel. It gives access to all other nested Live Objects...(GIVE_PROVIDE)
🪛 markdownlint-cli2 (0.17.2)
650-650: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
707-714: Subscribing to Updates – Description and Guidance
The introduction to subscription updates is mostly clear. Note that one of the static analysis hints suggested that the sentence may be missing an apostrophe in a possessive form. Please double-check for minor grammatical correctness (e.g. “clients’ updates” if applicable). Overall, the explanation is helpful.🧰 Tools
🪛 LanguageTool
[uncategorized] ~709-~709: 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)
826-834: Object Deletion Events – Grammar and Clarity
The explanation for deletion events is comprehensive.
Suggestion: Consider adding a comma before “and you should remove all references…” for better readability.-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. +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.🧰 Tools
🪛 LanguageTool
[uncategorized] ~826-~826: Use a comma before ‘and’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...g its data or trying to update its value and you should remove all references to the...(COMMA_COMPOUND_SENTENCE)
🪛 markdownlint-cli2 (0.17.2)
828-828: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
595-595: Markdown Code Block Style Consistency
Several static analysis hints indicate a preference for indented code blocks over fenced code blocks in these regions. Although many teams favor fenced code blocks for clarity, please confirm that this style conforms to the project’s markdown guidelines. If a change is necessary, consider adjusting the code block style as recommended by markdownlint.Also applies to: 615-615, 633-633, 650-650, 664-664, 693-693, 715-715, 745-745, 763-763, 770-770, 792-792, 814-814, 828-828, 840-840, 859-859, 879-879, 889-889
🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
595-595: 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 LiveObjects, you must pass in the p...
(IN_ORDER_TO_PREMIUM)
[style] ~648-~648: Try using a synonym here to strengthen your writing.
Context: ... LiveObjects state within a channel. It gives access to all other nested Live Objects...
(GIVE_PROVIDE)
[uncategorized] ~709-~709: 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)
[uncategorized] ~812-~812: It seems likely that a singular genitive (’s) apostrophe is missing.
Context: ...nd synced events notify when the Live Objects state is being synchronized with the Ab...
(AI_HYDRA_LEO_APOSTROPHE_S_XS)
[uncategorized] ~826-~826: Use a comma before ‘and’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...g its data or trying to update its value and you should remove all references to the...
(COMMA_COMPOUND_SENTENCE)
🪛 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)
693-693: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
715-715: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
745-745: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
763-763: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
770-770: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
792-792: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
814-814: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
828-828: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
840-840: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
859-859: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
879-879: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
889-889: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
⏰ 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-node (16.x)
- GitHub Check: test-browser (chromium)
- GitHub Check: test-npm-package
🔇 Additional comments (22)
README.md (22)
587-588: External Reference for Push Notifications Documentation
The link and short description for more information on publishing push notifications look correct and clear.
589-590: Section Title Update to “LiveObjects”
The new “### LiveObjects” header clearly distinguishes this section. The consistency with other documentation now improves.
595-603: TypeScript Example: Import and Initialization of LiveObjects (Module Import)
The code snippet demonstrating how to import and initialize the LiveObjects plugin using TypeScript is well written and follows best practices.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
595-595: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
610-612: HTML Example for Loading the LiveObjects Plugin
The HTML code snippet for loading the LiveObjects plugin via a<script>tag is clear and correct.
615-620: TypeScript Example: Global Plugin Usage for LiveObjects
This snippet correctly demonstrates how to use the globalAblyLiveObjectsPluginwhen loading the plugin via a script tag. It clearly shows the alternative initialization approach.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
615-615: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
624-625: Product Documentation Link for LiveObjects
The reference link for further information on the LiveObjects product is appropriate.
626-630: State Channel Modes Explanation
The “#### State Channel Modes” section correctly enumerates the required channel modes (state_subscribeandstate_publish). The list is informative and precise.
633-642: Code Example: Attaching Channel Modes for LiveObjects
The TypeScript code snippet that demonstrates setting channel options with the required modes is clear and effective.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
633-633: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
644-645: Clarification on Authentication Requirements
The note emphasizing that the authentication token must include corresponding capabilities is concise and clear.
656-660: Introduction to Live Object Types
The brief introduction describing that LiveObjects supports two primary data structures (LiveMapandLiveCounter) is concise and informative.
662-687: LiveMap Usage Example
The code example for using aLiveMap(setting, getting, and removing keys) is clear and includes diverse operations. The inline comments help clarify the output expectations.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
664-664: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
691-705: LiveCounter Usage Example
The LiveCounter example demonstrates initialization, incrementing, and decrementing, along with expected outputs. The snippet is accurate and well documented.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
693-693: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
716-727: Code Example: Updating Subscription on Live Objects
The TypeScript code that subscribes to updates on both aLiveMapand aLiveCounterworks as intended and documents the expected console outputs effectively.
743-751: Deregistering Subscription Listeners
The provided examples showing both the dedicated unsubscribe function and passing a listener reference are clear and useful for developers.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
745-745: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
759-767: Creating New Live Objects
The “#### Creating New Objects” section along with the accompanying TypeScript snippet clearly demonstrates how to create aLiveCounterand aLiveMapwith optional initial values.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
763-763: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
767-774: Persisting Live Objects in State
The instructions for persisting new objects by assigning them to a parentLiveMapare clear. The structured code snippet makes the object hierarchy easy to understand.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
770-770: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
786-800: Batch Operations Example
The batch operation snippet is well presented. It clearly shows how to group operations atomically using a batch callback and then verifies the results.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
792-792: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
808-820: Lifecycle Events: Synchronization Notifications
This section clearly explains the purpose ofsyncingandsyncedevents and provides a concise TypeScript example.
Note: One of the static hints mentioned a potential apostrophe issue; consider ensuring possessives (if needed) are formatted correctly.🧰 Tools
🪛 LanguageTool
[uncategorized] ~812-~812: It seems likely that a singular genitive (’s) apostrophe is missing.
Context: ...ndsyncedevents notify when the Live Objects state is being synchronized with the Ab...(AI_HYDRA_LEO_APOSTROPHE_S_XS)
🪛 markdownlint-cli2 (0.17.2)
814-814: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
838-848: Unsubscribing from Lifecycle Events
The TypeScript snippet demonstrating how to unregister lifecycle event listeners (using both a destructured off function and passing a listener reference) is clear and instructive.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
840-840: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
855-871: Providing Custom TypeScript Typings for LiveObjects
The instructions and example for providing custom typings via the globalLiveObjectsTypesinterface are well structured and useful for enabling improved code completion.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
859-859: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
877-883: Example: Enabling Code Completion with Custom Typings
This snippet accurately demonstrates how the globally declared types influence code completion. The inline comment about the TypeError is a helpful indicator for type safety.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
879-879: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
886-897: Multiple Typings for Different LiveObjects State Trees
The example showing how to supply different state typings for different channels is clear and valuable for advanced use cases.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
889-889: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
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.
VeskeR
force-pushed
the
PUB-1039/update-readme
branch
from
3ca5003 to
2065e11
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
README.md (2)
646-650: Document how to obtain the root LiveObjects object.
The “#### Getting the Root Object” section introduces the concept clearly. Nitpick: Consider rewording “gives access” to “provides access” for a slightly more formal tone.🧰 Tools
🪛 LanguageTool
[style] ~648-~648: Try using a synonym here to strengthen your writing.
Context: ... LiveObjects state within a channel. It gives access to all other nested Live Objects...(GIVE_PROVIDE)
🪛 markdownlint-cli2 (0.17.2)
650-650: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
826-836: Explain object deletion events and adjust punctuation for clarity.
The “Object Deletion Events” description explains that orphaned LiveObjects will eventually be deleted and emphasizes that applications should not access them thereafter.
Nitpick: Consider adding a comma before “and you should remove all references…” for improved clarity.🧰 Tools
🪛 LanguageTool
[uncategorized] ~826-~826: Use a comma before ‘and’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...g its data or trying to update its value and you should remove all references to the...(COMMA_COMPOUND_SENTENCE)
🪛 markdownlint-cli2 (0.17.2)
828-828: 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 (2)
README.md(3 hunks)ably.d.ts(2 hunks)
✅ Files skipped from review due to trivial changes (1)
- ably.d.ts
🧰 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 LiveObjects, you must pass in the p...
(IN_ORDER_TO_PREMIUM)
[style] ~648-~648: Try using a synonym here to strengthen your writing.
Context: ... LiveObjects state within a channel. It gives access to all other nested Live Objects...
(GIVE_PROVIDE)
[uncategorized] ~826-~826: Use a comma before ‘and’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...g its data or trying to update its value and you should remove all references to the...
(COMMA_COMPOUND_SENTENCE)
🪛 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)
693-693: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
715-715: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
745-745: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
763-763: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
770-770: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
792-792: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
814-814: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
828-828: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
840-840: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
859-859: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
879-879: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
889-889: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
⏰ Context from checks skipped due to timeout of 90000ms (7)
- GitHub Check: test-browser (webkit)
- GitHub Check: test-node (20.x)
- GitHub Check: test-browser (firefox)
- GitHub Check: test-node (18.x)
- GitHub Check: test-npm-package
- GitHub Check: test-node (16.x)
- GitHub Check: test-browser (chromium)
🔇 Additional comments (18)
README.md (18)
587-587: Add reference to push notifications documentation.
The additional line clarifies where users can learn more about publishing push notifications over Ably. This is a useful pointer in the push notifications section.
589-594: Introduce and label the LiveObjects section.
The new “### LiveObjects” header with the subsequent “#### Using the plugin” subheading clearly marks the beginning of the LiveObjects documentation. This improves the structure and discoverability of the new feature documentation.🧰 Tools
🪛 LanguageTool
[style] ~593-~593: Consider a shorter alternative to avoid wordiness.
Context: ...ime clients via the LiveObjects plugin. In order to use LiveObjects, you must pass in the p...(IN_ORDER_TO_PREMIUM)
595-603: Correctly demonstrate LiveObjects plugin usage in TypeScript.
The code snippet importingLiveObjectsfrom'ably/liveobjects'and initializing the Ably client withplugins: { LiveObjects }is well presented and consistent with TypeScript usage.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
595-595: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
604-606: Clarify support for the modular variant.
The statement that “LiveObjects plugin also works with the [Modular variant]” is concise and informs users about multiple integration options.
607-611: Provide an HTML-based loading example for the LiveObjects plugin.
The HTML snippet for loading the LiveObjects plugin via a<script>tag is clear. Consider verifying that the referenced URL (https://cdn.ably.com/lib/liveobjects.umd.min-2.js) is up-to-date with your release strategy.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
609-609: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
612-619: Demonstrate usage of the global LiveObjects plugin.
The TypeScript snippet showing how to initialize the client using the globalAblyLiveObjectsPlugin(i.e. passing{ LiveObjects: AblyLiveObjectsPlugin }) is correct. This helps users who load the plugin via a<script>tag.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
615-615: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
626-632: Explain the required channel modes for LiveObjects.
The “#### State Channel Modes” section and the accompanying list (withstate_subscribeandstate_publish) clearly explain the necessary channel modes. This is important for ensuring that clients attach with the correct permissions.
633-642: Show channel initialization with state channel modes.
The code snippet initializing the client with state channel modes is well formatted and instructive. It demonstrates how to pass channel options for enabling LiveObjects features.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
633-633: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
654-654: State the type of the root object.
The note that “The root object is aLiveMapinstance…” succinctly informs users of the underlying type, which is helpful for further usage.
656-664: Detail LiveObjects’ primary data structures with a LiveMap example.
The “#### Live Object Types” section along with the LiveMap usage code snippet is clear and comprehensive. The snippet demonstrates setting, getting, and removing keys as well as handling various data types—including nesting another live object.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
664-664: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
688-694: Demonstrate LiveCounter usage.
The LiveCounter example clarifies how to create a counter and perform basic operations (incrementing and decrementing). The concise example provides immediate clarity on its behavior.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
693-693: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
706-715: Explain subscription to updates for LiveObjects.
The “#### Subscribing to Updates” section and its code snippet clearly illustrate how to subscribe to updates on both LiveMap and LiveCounter. This section effectively demonstrates the concept of real‑time change propagation.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
715-715: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
742-745: Show how to deregister subscription listeners.
The provided code snippet for unsubscribing from update events (using both a dedicated unsubscribe function and the listener reference) is straightforward and instructive.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
745-745: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
758-767: Introduce creation of new LiveObjects.
The “#### Creating New Objects” section and accompanying snippet clearly explain how to instantiate newLiveMapandLiveCounterobjects. This new section aligns well with the rest of the documentation.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
763-763: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
767-776: Illustrate how to persist new objects within the LiveObjects state tree.
The snippet showing how to assign newly created objects to a parentLiveMap(thereby integrating them into the hierarchy) is helpful. The visual structure comment further reinforces understanding.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
770-770: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
807-818: Demonstrate handling of synchronization lifecycle events.
The “#### Lifecycle Events” section shows how to subscribe to syncing and synced events. This example is clear and helps developers understand how to hook into synchronization state changes to, for example, manage loading indicators.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
814-814: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
839-853: Show how to unsubscribe from lifecycle events.
The unsubscribe snippet demonstrates both the dedicatedofffunction and the usage of passing a listener reference. This provides clear guidance on how to clean up event handlers.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
840-840: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
854-902: Provide comprehensive TypeScript typings for LiveObjects.
The “#### Typing LiveObjects” section—including the global declaration inably.config.d.tsand the examples showing both the default type usage and generic usage withgetRoot—enhances developer experience by enabling code completion and type safety. All examples are thorough and clearly documented.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
859-859: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
879-879: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
889-889: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
| // set a key on map | ||
| await root.set('name', 'Alice'); | ||
| // get a value for a key | ||
| console.log(root.get('name')); // output: 'Alice' |
There was a problem hiding this comment.
I get the point that we're trying to make in demonstrating this API, but it might be a bit misleading or confusing given that, as you say later, updates are not immediately reflected in the local state.
| const root = await liveObjects.getRoot(); | ||
|
|
||
| // subscribe to updates on a LiveMap | ||
| root.subscribe((update: LiveMapUpdate) => { |
There was a problem hiding this comment.
Maybe we could make it clearer that the user does not need to look at the contents of the update; i.e. that they can just re-read the entire LiveMap or LiveCounter if they wish?
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