[AIT-1138] docs(liveobjects): JS sections for PathObject.instance() wrapping primitives (RTPO8f)

[sacOO7]

Fixes https://ably.atlassian.net/browse/AIT-1138

Summary

Updates the JavaScript sections of the LiveObjects docs to reflect the new PathObject.instance() behaviour: it now returns an Instance wrapping any resolved value, whether a LiveObject or a primitive. undefined is returned only when the path does not resolve.

The Java sections were already updated for this behaviour; this PR brings the JavaScript sections into full parity with them.

Why

The spec deprecated RTPO8d (primitive → undefined/null) in favour of RTPO8f (primitive → Instance wrapping the primitive value), and ably-js has adopted the change. A primitive-backed Instance is read-only: it has no id and exposes the primitive via value().

• Spec change: [AIT-1138] Deprecate RTPO8d: PathObject#instance wraps primitives (RTPO8f) specification#504
• ably-js implementation: [AIT-1138] fix(liveobjects): PathObject.instance() wraps primitives per RTPO8f ably-js#2260

Changes

concepts/path-object.mdx

• Reworded the JavaScript statement in "Obtain object instances": instance() returns undefined only if the entry at the path does not exist; a primitive value is wrapped in a read-only Instance.
• Replaced the JavaScript example that showed instance() returning undefined for a primitive. It now demonstrates the new behaviour (id is undefined, value() returns the primitive) and shows that undefined is returned only for a nonexistent path, mirroring the adjacent Java example.

concepts/instance.mdx

• Updated the JavaScript statement under "Get an Instance" to match the Java wording: instance() returns undefined only if nothing exists at the path, and wraps whatever value resolves there.
• Added a paragraph to the page intro noting that an Instance can also wrap a primitive value; the previous intro described Instance purely as a reference to a LiveObject identified by its object ID, contradicting the behaviour documented further down the page.
• Clarified the id getter docs: on a primitive-backed instance, id returns undefined, because primitives have no object ID.
• Added the // undefined only if nothing exists at the path code comment for parity with the equivalent Java example comment.

concepts/objects.mdx

• Added the same parity code comment to the JavaScript instance() example, mirroring the existing Java comment.

batch.mdx

• Fixed a pre-existing typo ("an PathObject" → "a PathObject"). The statement itself is unchanged: batch() still requires the path to resolve to a LiveMap or LiveCounter, since ably-js deliberately kept the 92007 guard for non-LiveObject paths.

Verified unaffected

All value(), size(), subscribe-restriction, and batch() behavioural statements across the LiveObjects docs were reviewed against the spec change and remain correct. Every <If lang="java"> block mentioning Instance was cross-checked to confirm its JavaScript counterpart is now consistent.

[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.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: eba7f63c-1456-4efe-921c-561216ef185e

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

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch liveobjects-js-instance-wraps-primitives

---

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.}

[Copilot]

Pull request overview

Updates the LiveObjects documentation to reflect the newer PathObject.instance() JavaScript behavior: it now returns an Instance wrapping any resolved value (including primitives), and returns undefined only when the path does not resolve.

Changes:

• Updated JS prose in PathObject and Instance docs to match the new “wrap primitives” behavior (parity with Java).
• Updated JavaScript examples to demonstrate primitive-backed Instance behavior (id is undefined, primitive exposed via value()), and added parity comments clarifying when undefined is returned.
• Fixed a small grammar issue in batch.mdx (“an PathObject” → “a PathObject”).

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
src/pages/docs/liveobjects/concepts/path-object.mdx	Updates JS explanation and example to show primitives are wrapped in a read-only Instance, and undefined is only for missing paths.
src/pages/docs/liveobjects/concepts/objects.mdx	Adds a JS parity comment clarifying instance() returns undefined only when nothing exists at the path.
src/pages/docs/liveobjects/concepts/instance.mdx	Expands intro and JS wording to include primitive-backed instances; clarifies id behavior and adds parity comment in example.
src/pages/docs/liveobjects/batch.mdx	Fixes a minor article typo in prose.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ttypic]

LGTM