[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 9 minutes and 28 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 (2)
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.
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.
I believe it matches the behavior of presence, yes. However, this is currently the case for LiveObjects due to technical limitations, as we do not yet have a way to apply operations client-side outside of the regional order. Eventually, we would like to apply the operation immediately after receiving acknowledgment (on receiving ACK) that the operation message was received by the server, or ideally, even optimistically before sending the message to the realtime system (which would enable a synchronous mutation API).
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.
README.md
Outdated
|
|
||
| // 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)
VeskeR
force-pushed
the
PUB-1039/update-readme
branch
from
3ca5003 to
2065e11
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
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)
VeskeR
force-pushed
the
PUB-1039/update-readme
branch
from
2065e11 to
2f5a078
Compare
github-actions
bot
temporarily deployed
to
staging/pull/1969/features
github-actions
bot
temporarily deployed
to
staging/pull/1969/bundle-report
github-actions
bot
temporarily deployed
to
staging/pull/1969/typedoc
VeskeR
force-pushed
the
PUB-1039/update-readme
branch
from
2f5a078 to
50e40ef
Compare
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
README.md (1)
791-809:⚠️ Potential issueBatch Operations Example – Variable Scope Issue.
The batch operations snippet demonstrates grouping several operations; however, it reuses the variablerootin theconsole.logstatements even though it is locally defined within the callback. This can lead to confusion or undefined behavior. Consider revising the example as follows:- await liveObjects.batch((ctx) => { - const root = ctx.getRoot(); - root.set('foo', 'bar'); - root.set('baz', 42); - const counter = root.get('counter'); - counter.increment(5); - }); - - console.log(root.get('foo')); // output: 'bar' - console.log(root.get('baz')); // output: 42 - console.log(root.get('counter').value()); // output: 5 + const initialRoot = await liveObjects.getRoot(); + await liveObjects.batch((ctx) => { + const batchRoot = ctx.getRoot(); + batchRoot.set('foo', 'bar'); + batchRoot.set('baz', 42); + const counter = batchRoot.get('counter'); + counter.increment(5); + }); + + // Retrieve the updated state after the batch operation + const updatedRoot = await liveObjects.getRoot(); + console.log(updatedRoot.get('foo')); // expected output: 'bar'This revision avoids the scope ambiguity.
🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
795-795: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
🧹 Nitpick comments (7)
README.md (7)
591-591: Using the Plugin Subsection.
The header “#### Using the plugin” introduces the usage example well. For consistency and clarity, you might consider capitalizing “Plugin” (i.e. “Using the Plugin”) to align with the product’s naming conventions.
607-611: HTML Loading Alternative.
The HTML snippet for loading the LiveObjects plugin via a CDN is a useful alternative for non-package-manager environments. Consider adding a brief comment (either inline or in the surrounding text) to explain when this approach might be preferred over the TypeScript/ES module method.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
609-609: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
648-653: LiveObjects Root Object Description.
The explanation and code snippet for retrieving the root object are clear and instructive. To enhance technical tone, consider replacing “gives access” with “provides access.”🧰 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)
658-662: LiveMap Description.
The description forLiveMapis clear and explains its functionality well. For improved clarity, review the phrasing and ensure consistent formatting—using backticks for both code terms and data type names.
664-687: LiveMap Usage Example.
The comprehensive code snippet illustrates various operations on aLiveMap. It might be beneficial to include inline comments to guide less-experienced users through each operation.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
664-664: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
829-839: Object Deletion Events Example.
This example shows how to listen for deletion events on a Live Object. A minor nitpick: in the accompanying text, consider adding a comma before ‘and’ when linking two independent clauses for improved readability.🧰 Tools
🪛 LanguageTool
[uncategorized] ~829-~829: 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)
831-831: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
595-595: Markdown Code Block Styling Issues.
The static analysis indicates that several code blocks (e.g. those starting on lines 595, 615, 633, etc.) are reported as using fenced code blocks whereas indented code blocks are expected by the linter. If your project guidelines require the indented style, please run Prettier (or adjust your markdownlint configuration) to ensure consistency.Also applies to: 615-615, 633-633, 650-650, 664-664, 693-693, 712-712, 748-748, 766-766, 773-773, 795-795, 817-817, 831-831, 843-843, 862-862, 882-882, 892-892
🧰 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 (2)
README.md(3 hunks)ably.d.ts(2 hunks)
🚧 Files skipped from review as they are similar to previous 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] ~706-~706: 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] ~829-~829: 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)
712-712: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
748-748: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
766-766: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
773-773: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
795-795: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
817-817: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
831-831: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
843-843: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
862-862: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
882-882: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
892-892: 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-browser (webkit)
- GitHub Check: test-browser (firefox)
- GitHub Check: test-browser (chromium)
- GitHub Check: test-node (20.x)
- GitHub Check: test-node (18.x)
- GitHub Check: test-node (16.x)
- GitHub Check: test-npm-package
🔇 Additional comments (28)
README.md (28)
1-1: Prettier Lint Warning.
A recent Prettier run found code style issues in this file. Please runprettier --write .(or your usual formatter command) to fix formatting inconsistencies.🧰 Tools
🪛 GitHub Actions: Lint
[warning] 1-1: Code style issues found in the above file. Run Prettier with --write to fix.
587-587: Push Documentation Link Added.
The link to the Ably push documentation is a helpful reference for users who need information on push notifications.
589-589: LiveObjects Section Header.
The new “### LiveObjects” header clearly signals the start of the updated documentation. Ensure that the naming is consistently applied throughout the document (e.g. use “LiveObjects” rather than “Live Objects” when referring to the plugin’s product name).
595-603: TypeScript Initialization Example.
The provided TypeScript snippet demonstrates how to import and integrate the LiveObjects plugin with the Ably Realtime client. It’s precise and clear. Just verify that your users have the necessary TypeScript typings available when using this approach.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
595-595: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
615-620: Alternative Client Initialization Using Global Plugin.
The snippet shows how to initialize the client using the global object (AblyLiveObjectsPlugin). This is clear and aligns with the previous example. Just ensure that the documentation elsewhere reflects consistent naming conventions.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
615-615: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
624-624: LiveObjects Documentation Link.
Adding a direct link to additional LiveObjects product documentation is very helpful for users who want more in‐depth information.
626-626: State Channel Modes Section Header.
Introducing “#### State Channel Modes” is a great way to highlight the importance of channel configuration when using LiveObjects.
628-632: Channel Modes Explanation.
The details about the required modes—state_subscribeandstate_publish—are clearly laid out. For consistency, confirm that you use the standardized “LiveObjects” nomenclature throughout (e.g. avoiding “Live Objects” if the product is branded as “LiveObjects”).
633-642: Channel Initialization Example with Modes.
This TypeScript snippet effectively demonstrates setting up a Realtime client with the proper channel modes needed for LiveObjects. The inline comment about authentication options reminds users to supply their own credentials.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
633-633: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
644-645: Authentication Capabilities Reminder.
A concise reminder that the authentication token must include the proper capabilities is valuable.
646-646: Getting the Root Object Header.
The “#### Getting the Root Object” section header is clear. It properly introduces the next step in interacting with LiveObjects.
656-656: Live Object Types Section Header.
This header aptly introduces the supported LiveObjects data structures.
689-692: LiveCounter Description.
The brief description ofLiveCounterclearly explains its purpose.
693-702: LiveCounter Usage Example.
The code snippet forLiveCounterusage demonstrates reading, incrementing, and decrementing effectively. Adding expected output comments could further assist in clarifying the behavior.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
693-693: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
704-704: Subscribing to Updates Section Header.
This header marks the start of an important section on handling realtime updates with LiveObjects.
707-744: LiveObjects Subscription Example.
The subscription examples for bothLiveMapandLiveCounterare thorough and illustrate how to handle update events. The inline logging statements help clarify the intended behavior during state changes.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
712-712: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
746-760: Deregistering Subscription Listeners.
The provided examples cover multiple approaches to removing event listeners, which is helpful for different usage scenarios.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
748-748: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
762-762: Creating New LiveObjects Instances.
The “#### Creating New Objects” section header succinctly introduces how to instantiate new LiveMap and LiveCounter objects.
767-769: New Live Object Creation Examples.
The code snippets for creating aLiveCounterand aLiveMapclearly demonstrate the use of optional initial values and entries.
771-787: Persisting LiveObjects in State.
This example shows how to nest LiveMaps (and by extension, other LiveObjects) to build out a state tree. The accompanying diagram is very helpful for visualizing the hierarchy.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
773-773: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
789-789: Batch Operations Section Header.
The header “#### Batch Operations” introduces the concept well, alerting users to how grouped operations can be handled atomically.
811-811: Lifecycle Events Section Header.
The “#### Lifecycle Events” header clearly introduces this topic.
812-827: Lifecycle Events Example.
The lifecycle events code snippet (usingsyncingandsyncedevents) is straightforward and demonstrates how to hook into key state changes.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
817-817: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
841-856: Deregistering Lifecycle Event Listeners.
The provided examples illustrate two approaches to removing event listeners—using the dedicated off function and referencing event names along with listener functions. This consistency matches earlier patterns.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
843-843: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
858-858: Typing LiveObjects Section Header.
Introducing custom TypeScript typings for LiveObjects gives users insight into tailoring the API to their needs. The header is clear and descriptive.
863-878: Custom Global Typings Example.
The snippet for extending the globalLiveObjectsTypesinterface is well structured and clearly shows how to add custom state definitions. Ensure that these typings are maintained as the API evolves.
882-889: LiveObjects Typing Usage Example.
This snippet effectively demonstrates how the custom typings enable strong type checks and autocompletion, which is valuable for TypeScript users.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
882-882: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
890-904: Alternative State Typings Example.
The examples for fetching typed state trees on different channels (e.g.ReactionsRootandPollsRoot) are clear and provide helpful context for applying custom typings per channel.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
892-892: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
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
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (4)
README.md (4)
587-592: Improve Conciseness in the "Using the plugin" SectionThe sentence “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.” is a bit wordy. Consider simplifying it to something like:
“To use LiveObjects, include the plugin in your client options.”
This revision is more concise while still communicating the required step.
[style]
646-650: Refine Language in the "Getting the Root Object" SectionThe text “The root object represents the top-level entry point for LiveObjects state within a channel. It gives access to all other nested Live Objects.” could be improved for clarity and consistency. Consider rewording “gives access to” to “provides access to” to strengthen the tone.
[style]Suggested diff:
-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 and 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)
704-710: Clarify Wording in the "Subscribing to Updates" IntroductionThe introductory text in this section is generally clear; however, consider a minor grammatical tweak. For instance, ensuring that possessive apostrophes are used where needed may improve clarity. For example, you might rephrase “multiple clients may modify the same Live Objects state” to “multiple clients may modify the same LiveObjects’ state”.
[style]🧰 Tools
🪛 LanguageTool
[uncategorized] ~706-~706: 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)
829-835: Minor Punctuation Improvement in "Object Deletion Events"In the sentence “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.” a comma before “and” would improve readability.
[minor]Suggested revision:
-... its value and you should remove all references ... +... its value, and you should remove all references ...🧰 Tools
🪛 LanguageTool
[uncategorized] ~829-~829: 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)
831-831: 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 as they are similar to previous 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] ~706-~706: 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] ~829-~829: 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)
712-712: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
748-748: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
766-766: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
773-773: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
795-795: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
817-817: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
831-831: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
843-843: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
862-862: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
882-882: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
892-892: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
⏰ Context from checks skipped due to timeout of 90000ms (6)
- GitHub Check: test-node (20.x)
- GitHub Check: test-node (18.x)
- GitHub Check: test-browser (webkit)
- GitHub Check: test-browser (firefox)
- GitHub Check: test-node (16.x)
- GitHub Check: test-browser (chromium)
🔇 Additional comments (9)
README.md (9)
595-602: Verify the TypeScript Example for Using the PluginThe provided TypeScript snippet for initializing the client with LiveObjects is clear and accurate. It correctly demonstrates the import and configuration pattern.
🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
595-595: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
607-615: Alternative HTML Script Loading Example is ClearThe alternate approach—loading the LiveObjects plugin via a script tag and then initializing the client with the global
AblyLiveObjectsPlugin—is well demonstrated. Ensure that accompanying documentation clearly states when this approach is preferable (e.g. when a package manager is not available).🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
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)
626-635: "State Channel Modes" Section ReviewThe “State Channel Modes” example clearly lists the required channel modes (
state_subscribeandstate_publish) and shows how to set them via the channel options. The code snippet is straightforward and the instructions are clear.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
633-633: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
656-662: "Live Object Types" Section is Clear and InformativeThe section effectively differentiates between
LiveMapandLiveCounterand gives concise examples of how to use each. The examples are clear and well formatted.
710-744: "Subscribing to Updates" Example ReviewThe example code for subscribing to updates for both a LiveMap and a LiveCounter is comprehensive and demonstrates how to access update details effectively. The inline comments further clarify expected behavior.
🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
712-712: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
762-775: "Creating New Objects" Section is Well StructuredThe instructions and code snippets in this section clearly illustrate the creation and persistence of new LiveMap and LiveCounter instances. No changes are needed here.
🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
766-766: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
773-773: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
858-889: "Typing LiveObjects" Section is ComprehensiveThe section on providing custom TypeScript typings for LiveObjects is detailed and offers clear examples of how to extend type definitions. The guidance on using global interfaces and specifying typings on
getRootis useful for developers.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
862-862: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
882-882: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
890-904: Additional Typing Examples Enhance ClarityThe extended examples demonstrating how to provide separate typings for different channels further enhance clarity and demonstrate the flexibility of the API. This addition aligns well with the overall documentation update.
🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
892-892: Code block style
Expected: indented; Actual: fenced(MD046, code-block-style)
912-920: Overall Documentation ImprovementsThe updated sections on LiveObjects—including the new subsections, revised TypeScript examples, and detailed instructions on channel modes, object creation, updates, batch operations, and lifecycle events—substantially improve clarity and usability of the documentation. Great work on covering the feature comprehensively.
🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
915-915: Bare URL used
null(MD034, no-bare-urls)
VeskeR
force-pushed
the
PUB-1039/update-readme
branch
from
50e40ef to
54c1c60
Compare
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
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
54c1c60 to
fcceb2c
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.
Resolves PUB-1039
Summary by CodeRabbit