Understand if `whenState` can be removed from v2 API

[lawrence-forooghian]

It's not clear to me why these methods are part of the SDK’s public API.

The first one was added in 55b1be4fde0ccf15535a89c9da2a79cd430ce181 as an "undocumented feature" used by a test case. It was then added to the typings in https://github.com/ably/ably-js/pull/444, again not sure why.

It's not in the specification, and it's not clear how the state change that it claims to emit should be populated (I guess it should probably return the state change that led to the object being in that state, but that's not what it does). This has led to bugs like #1598 and #1599.

I suggest that we remove it from the public API (i.e. the typings) in v2. (And if for some reason we do have to keep it, I'd suggest that we add it to the feature spec, properly defining what value it should emit.)

┆Issue is synchronized with this Jira Task by Unito

[sync-by-unito[bot]]

➤ Automation for Jira commented:

The link to the corresponding Jira issue is https://ably.atlassian.net/browse/SDK-4057

[lawrence-forooghian]

Raised spec PR https://github.com/ably/specification/pull/183 to add these methods (see justification there). Will address #1598 and #1599 and then implement the spec for v2.

[lawrence-forooghian]

Opened #1640 to implement https://github.com/ably/specification/pull/183. #1598 and #1599 can be done separately.