ably-js [PUB-1197] LiveObjects REST client

Summary by CodeRabbit

New Features
- REST-based object API: channel.object supports get (compact/expanded) and publish for map/counter operations, including batch publishes; get returns undefined for missing objects.
Documentation
- Docs updated to show RestClient / Rest usage with the Objects plugin and plugin integration notes.
Tests
- Comprehensive REST and realtime tests added; shared object test helpers introduced and reused.
Chores
- RestClient, BaseRest and Rest surfaced in modular exports for plugin use.

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

Nov 14 '25 09:11 VeskeR

Walkthrough

Adds REST-based Objects support: new TypeScript types, a RestObject class with get/publish on RestChannel, BaseClient plugin wiring, RestChannel object getter and annotations getter, plugin export updates, a RestObject implementation, and new/updated tests and helpers for REST and realtime object operations.

Changes

Cohort / File(s)	Summary
Type definitions `ably.d.ts`	Added REST object operation and data types (RestObjectOperationBase, TargetByObjectId/Path, AnyTargetOperationBase, OperationMapCreate/Set/Remove, OperationCounterCreate/Inc, RestObjectOperation union, RestObjectPublishResult, RestCompactObjectData, RestLiveObject, RestLiveMap, RestObjectMapEntry, RestObjectData, RestLiveCounter, AnyRestLiveObject, GetObjectParams, RestObject interface, PrimitiveOrObjectReference); updated ObjectOperationAction docs.
Docs / usage exports `objects.d.ts`	Export/import updates to reference `RestClient`, `BaseRest`, and `Rest` in examples/docs and modular exports.
Base client plugin wiring `src/common/lib/client/baseclient.ts`	Added `readonly _objectsPlugin: typeof ObjectsPlugin
Realtime client cleanup `src/common/lib/client/baserealtime.ts`	Removed the `_objectsPlugin` field and its initialization from BaseRealtime.
Realtime channel plugin sourcing `src/common/lib/client/realtimechannel.ts`	RealtimeChannel now uses `client._objectsPlugin` to initialize `RealtimeObject` when present.
REST channel object API `src/common/lib/client/restchannel.ts`	Added private `_object?: RestObject`, public `get object(): RestObject` (lazy-init, throws if plugin missing), reintroduced `get annotations(): RestAnnotations`, added RestObject type import.
Plugin exports `src/plugins/objects/index.ts`	Exported `RestObject` in named exports and included it in the default export bundle.
RestObject implementation `src/plugins/objects/restobject.ts`	New `RestObject` class with overloaded `get()` (compact/expanded) and `publish()` (single/batch). Implements path construction, request format negotiation (msgpack/json), encoding/decoding helpers, publish body construction, response decoding, and 404->undefined behavior. Exposes several wire types.
Test helpers `test/common/modules/objects_helper.js`	Added static helpers: `waitFixtureChannelIsReady`, `waitForMapKeyUpdate`, `waitForCounterUpdate`, `waitForObjectOperation`, `waitForObjectSync`.
Realtime tests `test/realtime/objects.test.js`	Replaced in-file wait helpers with `ObjectsHelper` references, removed local implementations, adjusted call signatures to pass channel name.
REST tests `test/rest/objects.test.js`	Added REST Objects test suite covering channel.object behavior, `get()` variations (compact/expanded, id/path, primitives/buffers), `publish()` operations (MAP_SET/CREATE/REMOVE, COUNTER_CREATE/INC, batching) and state verification.
Test harness `test/common/modules/shared_helper.js`	Consolidated protocol test wiring with a `createTest` wrapper to unify JSON/msgpack invocation.
REST request test `test/rest/request.test.js`	Converted a header assertion to async coordination (manual promise) and updated the test callback to async.
Module report `scripts/moduleReport.ts`	Added `src/plugins/objects/restobject.ts` to allowedFiles for bundle size checks.

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant RestChannel
    participant RestObject
    participant AblyAPI

    Note over Client,RestObject: RestObject.get() flow
    Client->>RestChannel: access channel.object
    RestChannel->>RestObject: lazy-init (new RestObject(channel))
    Client->>RestObject: get(params)
    RestObject->>RestObject: _basePath(params)
    RestObject->>AblyAPI: HTTP GET /objects{path|id}
    AblyAPI-->>RestObject: 200/404 + payload
    RestObject->>RestObject: decode (msgpack/json)
    RestObject-->>Client: RestCompactObjectData | RestLiveObject | undefined

    Note over Client,RestObject: RestObject.publish() flow
    Client->>RestObject: publish(op or [ops])
    RestObject->>RestObject: _constructPublishBody(ops)
    RestObject->>RestObject: _encodePrimitive(...) for values
    RestObject->>AblyAPI: HTTP POST /objects{path|id} with encoded body
    AblyAPI-->>RestObject: 200 + publish result
    RestObject-->>Client: RestObjectPublishResult

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Pay particular attention to:
- src/plugins/objects/restobject.ts — encoding/decoding, wire-format construction, binary vs JSON handling, header composition, error mapping (404 -> undefined).
- src/common/lib/client/* — plugin lifecycle, initialization differences between BaseClient and BaseRealtime, and channel getters.
- test/rest/objects.test.js — many scenarios and encoding expectations; ensure fixtures and readiness helpers align with implementation.
- ably.d.ts — overloads/unions and exported type compatibility.

Suggested reviewers

lawrence-forooghian

Poem

🐇 I hopped to a RESTful glade today,
where get() and publish dance and play,
compact crumbs or live-map stew,
counters nudge and maps hop through,
a rabbit cheers: "Objects — hip hooray!"

Pre-merge checks and finishing touches

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run `@coderabbitai generate docstrings` to improve docstring coverage.
Linked Issues check	❓ Inconclusive	The linked issue (AIT-27) title is incomplete/missing in the provided context, making it impossible to validate whether all coding requirements are met.	Provide the complete description and acceptance criteria from AIT-27 and PUB-1197 to verify all coding requirements are addressed.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title '[PUB-1197] LiveObjects REST client' clearly summarizes the main objective: implementing REST client support for LiveObjects functionality.
Out of Scope Changes check	✅ Passed	All changes appear scoped to REST client LiveObjects support: type definitions, RestObject implementation, test helpers, test suites, and necessary infrastructure updates align with the PR objective.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ 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 PUB-1197/liveobjects-rest-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

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

Nov 14 '25 09:11 coderabbitai[bot]

Something I noticed when testing this branch for Msgpack requests. The SDK currently isn't setting the correct content type header of application/msgpack it was being set to JSON still

Nov 21 '25 16:11 kaschula

Something I noticed when testing this branch for Msgpack requests. The SDK currently isn't setting the correct content type header of application/msgpack it was being set to JSON still

Fixed in https://github.com/ably/ably-js/compare/879347fb8c1ce499a871d718619a6f84987d6c62..3ac564136007a5f3b9d53bf7f30136d425a9cdba, now sends correct headers based on client format.

Dec 04 '25 08:12 VeskeR

Can we try running these tests with msgpack to see if it works? I did find this ticket which may indicate an issue with msgpack over rest currently: https://ably.atlassian.net/browse/PUB-1835

Updated all Objects REST tests to run with msgpack and json, see https://github.com/ably/ably-js/pull/2109/commits/173b03c0358c1d1a23a970bd65667a604ab2ce38

Dec 04 '25 09:12 VeskeR