These methods were added in ably-js a long time ago (first mention is in https://github.com/ably/ably-js/commit/55b1be4), being described as an "undocumented feature" used by a test case. We seem to now consider them a part of the public API of ably-js; for example, they were added to the TypeScript typings in https://github.com/ably/ably-js/pull/444.
on the other hand, when RealtimeChannel is already in the given state, whenState emits a nullish state change, contrary to what its signature claims (see https://github.com/ably/ably-js/issues/1598)
I suggested in https://github.com/ably/ably-js/issues/1597 that we simply remove these methods in ably-js v2, but @SimonWoolf indicated that he considers these to be useful APIs worth considering keeping:
IMO it's quite useful to be able to write await realtime.connection.whenState('connected'); without having to worry about the edge case that the connection is already connected.
So, here I add them to the specification so that we can agree on the intended behaviour and then test the implementation.
I’ve chosen to emit a null state change when the receiver is already in the given state. This is in line with the already-attached behaviour described for RealtimeChannel#attach() in RTL4d1, and I think makes more sense than the alternatives of trying to synthesise a state change, or returning the state change that led to the given state (this latter approach wouldn’t work for the initial state anyway).
We’ll implement the behaviour specified here in ably-js v2, and I’ll figure out what’s the best we can do in v1.
These methods were added in ably-js a long time ago (first mention is in https://github.com/ably/ably-js/commit/55b1be4), being described as an "undocumented feature" used by a test case. We seem to now consider them a part of the public API of ably-js; for example, they were added to the TypeScript typings in https://github.com/ably/ably-js/pull/444.
The implemention of these methods, however, is inconsistent and flawed. As of https://github.com/ably/ably-js/commit/64caf8e:
Connectionis already in the given state,whenStatesynthesises a state change, and this state change is invalid (see https://github.com/ably/ably-js/issues/1599)RealtimeChannelis already in the given state,whenStateemits a nullish state change, contrary to what its signature claims (see https://github.com/ably/ably-js/issues/1598)I suggested in https://github.com/ably/ably-js/issues/1597 that we simply remove these methods in ably-js v2, but @SimonWoolf indicated that he considers these to be useful APIs worth considering keeping:
So, here I add them to the specification so that we can agree on the intended behaviour and then test the implementation.
I’ve chosen to emit a null state change when the receiver is already in the given state. This is in line with the already-attached behaviour described for
RealtimeChannel#attach()in RTL4d1, and I think makes more sense than the alternatives of trying to synthesise a state change, or returning the state change that led to the given state (this latter approach wouldn’t work for the initial state anyway).We’ll implement the behaviour specified here in ably-js v2, and I’ll figure out what’s the best we can do in v1.