[AIT-31] LiveObjects Path-based API migration guide by VeskeR · Pull Request #2124 · ably/ably-js

VeskeR · 2025-12-09T11:52:34Z

Related to AIT-31

Summary by CodeRabbit

Documentation
- Added a comprehensive LiveObjects v2 migration guide covering PathObject-based APIs, runtime path resolution, migration steps, TypeScript updates, new patterns, and examples.
Bug Fixes
- Clarified subscription event descriptions to reflect the actual path where an object changed.
New Features
- Subscription API now returns a subscription handle and includes an explicit unregister method for safer listener management.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

coderabbitai · 2025-12-09T11:52:44Z

Walkthrough

Added a LiveObjects migration guide for ably-js v2.16, clarified two liveobjects type doc strings, and refactored RealtimeObject's subscription API to return StatusSubscription and add an off(event, callback) method.

Changes

Cohort / File(s)	Summary
Migration Documentation `docs/migration-guides/v2/liveobjects.md`	New migration guide introducing PathObject-based API, runtime path resolution, breaking changes, TypeScript updates, subscription/creation patterns, examples, and helpers like `.compact()` / `.compactJson()` and async iterator subscriptions.
Type Definition Updates `liveobjects.d.ts`	Documentation wording updated for `PathObjectBase.subscribe` and `PathObjectSubscriptionEvent.object` to say "the path at which there was an object change".
RealtimeObject API Refactoring `src/plugins/liveobjects/realtimeobject.ts`	Removed `OnObjectsEventResponse` interface; changed `on(event, callback)` return type to `StatusSubscription`; added `off(event, callback): void`; updated imports to include `StatusSubscription`.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Verify all call sites and tests updated to handle on() returning StatusSubscription.
Ensure no remaining references to the removed OnObjectsEventResponse interface.
Confirm import/path and public typings for StatusSubscription are correct and exported as expected.
Check that off(event, callback) unregisters callbacks in all edge cases (e.g., multiple identical callbacks).

Poem

🐰 I hopped along each runtime path so neat,
Swapped roots for objects that resolve on feet,
Subscriptions bound, then slipped away with "off",
I nibbled docs and nudged a tiny scoff,
LiveObjects now: compact, tidy, and sweet. 🥕

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title clearly and concisely summarizes the main change: adding a migration guide for LiveObjects Path-based API as specified in issue AIT-31.
Linked Issues check	✅ Passed	The PR fulfills the linked issue AIT-31 objectives by adding comprehensive migration documentation for the LiveObjects path-based API with code examples.
Out of Scope Changes check	✅ Passed	All changes are within scope: the new migration guide, TypeScript definitions documentation updates, and method signature changes in RealtimeObject align with LiveObjects path-based API migration requirements.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

📝 Generate docstrings

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch AIT-31/objects-migration-guide

📜 Recent review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

Jira integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between b77e4c2 and 760ddc2.

📒 Files selected for processing (2)

docs/migration-guides/v2/liveobjects.md (1 hunks)
liveobjects.d.ts (2 hunks)

🧰 Additional context used

🪛 LanguageTool

docs/migration-guides/v2/liveobjects.md

[style] ~554-~554: This adverb was used twice in the sentence. Consider removing one of them or replacing them with a synonym.
Context: ... been moved from the 'ably' export to 'ably/liveobjects'. This consolidates all Li...

(ADVERB_REPETITION_PREMIUM)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (7)

GitHub Check: test-node (20.x)
GitHub Check: test-node (18.x)
GitHub Check: test-node (16.x)
GitHub Check: test-npm-package
GitHub Check: test-browser (webkit)
GitHub Check: test-browser (chromium)
GitHub Check: test-browser (firefox)

🔇 Additional comments (1)

liveobjects.d.ts (1)

258-258: LGTM! Documentation wording improved for clarity.

The documentation updates consistently clarify that the PathObject represents "the path at which there was an object change" rather than "the updated path." This terminology better reflects the PathObject-based API model where subscriptions observe paths that resolve at runtime.

Also applies to: 1439-1439

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

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

Jira integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 0bdd674 and b083173.

📒 Files selected for processing (1)

docs/migration-guides/v2/liveobjects.md (1 hunks)

🧰 Additional context used

🪛 GitHub Actions: Lint

docs/migration-guides/v2/liveobjects.md

[warning] 1-1: Code style issues found in this file by Prettier. Run 'prettier --write' to fix.

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (6)

GitHub Check: test-node (20.x)
GitHub Check: test-node (16.x)
GitHub Check: test-node (18.x)
GitHub Check: test-browser (firefox)
GitHub Check: test-browser (chromium)
GitHub Check: test-browser (webkit)

🔇 Additional comments (9)

docs/migration-guides/v2/liveobjects.md (9)

1-50: Comprehensive and well-structured migration guide.

The introduction and overview effectively set up the migration context with clear key improvements. The table of contents provides good navigability.

44-88: Entrypoint and PathObject sections are clear and thorough.

The Before/After pattern effectively illustrates the API shift from channel.objects to channel.object, and the PathObject explanation provides good rationale for the design change (runtime resolution, resilience to replacements). The chaining examples (.get() calls) and .at() method are well-documented.

90-122: Excellent explanation of runtime resolution behavior.

The breakdown of how PathObject handles non-existent paths (access methods return defaults, mutation methods throw errors) is clear and practical. This distinction helps developers understand error handling expectations without needing to read source code.

143-188: Object creation examples are clear and show progression.

The transition from individual .createCounter() / .createMap() to static factory methods (.create()) is well-illustrated. The nested structure example effectively demonstrates a key improvement: creating deeply nested objects in a single operation. This is a strong selling point for the migration.

190-238: Subscription pattern updates are thorough.

The new { object, message } destructuring signature is clearly shown, and the depth-control feature is well-explained with practical examples. The shift from instance-based to path-based subscriptions (resilient to object replacements) is a key benefit clearly articulated.

269-351: Instance API section handles a complex transition well.

The distinction between PathObject (resolves path on each call) and Instance (operates on specific object) is clearly explained. Runtime type checking behavior and the note about the old API returning explicit instances are helpful for developers accustomed to the previous version. Instance subscription auto-unsubscribe on garbage collection is a useful detail.

353-441: TypeScript-specific changes are comprehensive.

The removal of global AblyObjectsTypes and shift to explicit generic parameters (channel.object.get<T>()) is well-explained. The extended example showing nested type inference through PathObject<LiveMap<...>> effectively demonstrates the type safety benefits. This section should help TS users maintain type safety during migration.

443-528: Common migration patterns provide practical guidance.

The progression from reading → updating → observing → working with instances covers typical workflows. Each pattern shows both old and new idioms side-by-side, making it easy to map existing code to new API.

530-613: New features section effectively showcases benefits.

The .compact() method, async iterator API, and implicit channel attach are presented with clear use cases. The mention of automatic base64 encoding for binary data in compact representation is a helpful implementation detail.

lawrence-forooghian · 2025-12-09T13:07:46Z

+const player = myObject.get('players').get('player1').instance();
+// player is a LiveMap | undefined
+if (player) {
+  console.log(player.id()); // map:...


I don't know whether this applies to any other methods (I know that some can throw errors so it makes sense for them to be methods) but id seems like it should just be a property and not a method?

Instance object can wrap a primitive value as well as a LiveObject. In this case, id() returns undefined as this is not a valid operation on a primitive value (doesn't have an ID). As such, this was left as method

I'm not sure I understand the connection; why does it need to be a method in order to return undefined for primitive Instances?

Oh, sorry, I see. Yeah, technically it can be a getter that checks the type of the underlying instance. We don't really do any computations to have it as a method, but I think we just didn't consider to make it just a prop? The whole API surface for LiveObjects is methods. Even stuff like .size() is a method (but rightly so, it iterates through entries and performs additional checks whether to count them in or not, as opposed to just returning the number of entries in the internal map), so we didn't really think much of introducing properties to the API.

Do you feel like this is something we should consider for ably-js specifically, or can be left up to the specific SDK to decide how they want to expose id based on what is most idiomatic?

I think that individual SDKs can choose, will leave it to you to decide based on what we do elsewhere in JS.

Had a look at other types we have ,more specifically classes with behavior and unique identifiers.
Found two examples: Connection and LocalDevice describe a type that is more than just a "data structure" and expose id as a prop, not a method.
As such, changed id for liveobjects API to also be a prop (getter in this instance as we need to do some checks), see: #2128.
Updated the guide to reflect the change, see: https://github.com/ably/ably-js/compare/8a291ea8eee55ea0441dafd2245786b7afe87548..8b901e01c96df6b6a5077e05e0286424932c10e6

coderabbitai

Actionable comments posted: 2

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

Jira integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 8e7b06d and 93f4d26.

📒 Files selected for processing (2)

docs/migration-guides/v2/liveobjects.md (1 hunks)
src/plugins/objects/realtimeobject.ts (1 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

src/plugins/objects/realtimeobject.ts (1)

ably.d.ts (3)

ObjectsEvent (2308-2308)

ObjectsEventCallback (1658-1658)

StatusSubscription (1702-1711)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (6)

GitHub Check: test-browser (webkit)
GitHub Check: test-browser (chromium)
GitHub Check: test-browser (firefox)
GitHub Check: test-node (16.x)
GitHub Check: test-node (18.x)
GitHub Check: test-node (20.x)

🔇 Additional comments (1)

src/plugins/objects/realtimeobject.ts (1)

90-99: StatusSubscription return type matches implementation semantics.

The change to return API.StatusSubscription is consistent with the d.ts definition and the existing behavior of returning an object with an off() function that unregisters the listener. No further changes needed here.

coderabbitai

Actionable comments posted: 1

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

Jira integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 8b901e0 and 21f8a02.

📒 Files selected for processing (3)

docs/migration-guides/v2/liveobjects.md (1 hunks)
liveobjects.d.ts (2 hunks)
src/plugins/liveobjects/realtimeobject.ts (1 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

src/plugins/liveobjects/realtimeobject.ts (2)

liveobjects.d.ts (2)

ObjectsEvent (53-53)

ObjectsEventCallback (58-58)

ably.d.ts (1)

StatusSubscription (1698-1707)

🪛 GitHub Actions: API Reference