[AIT-31] LiveObjects Path-based API product docs for JavaScript SDK

[VeskeR]

Description

Product docs for LiveObjects Path-based API for JavaScript SDK.
See:

• ably-js migration guide
• Path-based API DR

Resolves AIT-31

Checklist

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

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository.

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

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

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch AIT-31/objects-path-api

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[VeskeR]

One concern I have regarding describing one of the benefits of Instance subscriptions as tracking objects "as they move" through the object tree, e.g. here:

Use Instance when you need to:

• Track a specific object instance as it moves through the structure

"Issue": There's actually currently no way to "move" an object via the Realtime API - no OBJECT_MOVE operation exists, and you can't set a map key to an existing object instance, only create new objects with LiveMap.create()/LiveCounter.create(). Moving is only achievable via REST API and by using object IDs explicitly.

Options:

1. Remove "movement" language and focus on other Instance benefits (getting object ID, deletion notifications)
2. Explicitly mention that object "movement" is only possible via REST API requests (we don't have a REST SDK client ready though, so won't be able to provide code samples unfortunately how it would look like)

Thoughts? @lawrence-forooghian @mschristensen

[lawrence-forooghian]

This is a big PR, nice work 😅 I've had a look through all of it and left some comments, nothing major though

[lawrence-forooghian]

This doesn't seem to be rendering correctly:

[lawrence-forooghian]

Might it be worth explicitly mentioning, in the places where we talk about the path-based API, that it's only available in JS at the moment and that Swift and Kotlin still use an older API?

[mschristensen]

Also, there is no language selector in this page (presumably because there are no code snippets?) so it's unclear to me that these conditional blocks are really doing anything

[VeskeR]

If-ed the whole bullet list to make sure it renders correctly and added languages list for this page in nav configs - not sure what's a condition for it to appear automatically, but now it works as expected.

Might it be worth explicitly mentioning, in the places where we talk about the path-based API, that it's only available in JS at the moment and that Swift and Kotlin still use an older API?

I believe most places will have Ifs to handle that, but I added a not for new PathObject and Instance pages to indicate they're JS specific

[lawrence-forooghian]

not sure that "updated path" makes sense (the path hasn't changed; its contents have)

Suggested change

	- `object`: A `PathObject` representing the updated path
	- `object`: A `PathObject` representing the path at which there was an object change

[VeskeR]

fixed

[lawrence-forooghian]

Forgive my ignorance here but what happens if the user tries setting fontSize before the client receives the map created in myObject.set('settings')? Does the client end up potentially updating the map (if any) that was previously at the settings entry instead, thus causing the fontSize change to be lost?

[VeskeR]

Yes ,this can happen as we still don't have apply operation on ACK implemented. This behavior is documented for all publish operation and subscription methods.
That said, I think this code example is simple enough to just drop an "access" part (as its main focus is to show how to create an object, just like java/swift examples below) bit so we can avoid the need to clarify this behavior here.

[lawrence-forooghian]

I have a similar question here to above; in this scenario, is it possible that the counter that gets incremented here is not the one that they created in the myObject.set('visits', LiveCounter.create(0)) call?

[lawrence-forooghian]

I think that this needs to be language-<If>-d?

[lawrence-forooghian]

I am curious why we chose to return an iterator and not just an array? Is it a common thing to do in JS? I'd get it if perhaps we wanted to do some sort of lazy streaming of results or something, but otherwise it seems it's something that's harder to log to the console and which some developers might not be familiar with.

[lawrence-forooghian]

I think just Instance would be OK? else lowercase the "Instance"

[mschristensen]

I agree it should be Instance

[lawrence-forooghian]

Something I've been wondering whilst looking at this API — are the subscriptions added at a path level or at a PathObject instance level? That, is, if I write

const pathObject = myObject.get('visits').subscribe(() => {
  console.log("pathObject listener fired")
});

// pathObject presumably gets garbage collected shortly after since the user has no reference to it?

— does the listener still get called when events happen at that path even though the PathObject instance through which they subscribed no longer exists?

[lawrence-forooghian]

I think that if you wish to show both the PathObject and Instance APIs here (which I'm not sure you need to do since it's not that important for explaining the semantics of the operations) then it might be better as two separate code blocks to make it clear they're not related

[lawrence-forooghian]

minor: maybe we could pick some other example values? this confused me at first because it looked like they were keys that control the behaviour of LiveMap.create

[lawrence-forooghian]

Explicitly mention that object "movement" is only possible via REST API requests (we don't have a REST SDK client ready though, so won't be able to provide code samples unfortunately how it would look like)

I think that whatever it is we do, we should handle the mention of cyclic references in the same way (either not mention them or mention them and explain the limited circumstances in which they might occur); I'd lean towards the latter.

[mschristensen]

Submitting my review with initial comments - we caught up on a call and I will take this further forward based on our discussions :)

[mschristensen]

Also, there is no language selector in this page (presumably because there are no code snippets?) so it's unclear to me that these conditional blocks are really doing anything

[mschristensen]

I was going to suggest:

  console.log('Reactions map updated:', [...object.entries()]);

but then I realised that's wrong, as object might be some nested object that changed.

I think we need to add some context here explaining this, at least at the surface level, as on initial read the user immediately wonders why the counter example uses the object but the map example doesn't

[mschristensen]

Suggested change

	Update objects using mutation methods on `PathObject`. All subscribers (including you) will be notified of the changes:
	Update objects using mutation methods on `PathObject`. All subscribers, including the client that made the update, will be notified of the changes:

[mschristensen]

To align this log with the examples that follow:

Suggested change

	console.log('Visits updated:', object.value());
	console.log('Visits counter updated:', object.value());

[mschristensen]

We should update this - we call it the "channel object" in the index page, we should use that framing here too

[mschristensen]

Not quite true, should be e.g. "Get a JavaScript object representation of the data"

[mschristensen]

I think we need to implement what we discussed the other day - i.e. the compact method should either return a JSON serializable value which is identical to that returned by REST, or it should return a JS object with cyclic references and ArrayBuffer binary values.

Let me know if we need to sync on this. Changing the behaviour would be a breaking change post release, so I would suggest we tag the method experimental in the release (and label it as such here) before we do so.

[mschristensen]

This should appear below subscribeIterator() method heading, and include an example of providing options for both styles of subscription API

[mschristensen]

Should this include an example of using .instance() with a instanceof LiveMapInstance (or similar) to assert on the expected type at runtime?

[mschristensen]

I agree it should be Instance

[VeskeR]

see above, ObjectData also represents the value for the intial entries in operation.map.entries

[mschristensen]

Yeah let's leave it for now, as we need to document subscriptions with the sync messages, if you could please create a ticket that would be grand