ably-js
ably-js copied to clipboard
Split `usePresence` hook into different hooks for entering presence and subscribing to presence events
usePresence
hook is quite opinionated right now - it enters presence and subscribes to presence events automatically on component mount, and there is no documentation on how to modify this behavior (via combination of modes
and subscribeOnly
options). Also docs (both on github, and Ably Docs) don't say a word about usePresence
entering presence.
It seems reasonable to have two separate hooks for these two behaviors.
This split depends on ChannelProvider
from https://github.com/ably/ably-js/pull/1620, to avoid confusion when using two different presence hooks with the same channel name. Channel name and options would be set in one place in ChannelProvider
, and other parts of the application will be just using that channel with set options.
Using ChannelProvider
will fix the issue of implicit usage of channel in usePresence
, which means that channel options we pass to usePresence
matter and may cause channel to reattach, which causes errors if options are not changes via setOptions
.
As part of the split, we can document or entirely remove next usePresence
options (they are undocumented and not obvious how to use):
-
skip
- no docs currently, nothing in commit messages (even in https://github.com/ably-labs/react-hooks). currently it disables allonMount
logic for presence (prevents entering presence and subscribing to events). not clear why it's needed -
subscribeOnly
- no docs, prevents entring presence on component mount. Reasoning for 'subscribeOnly': https://github.com/ably-labs/react-hooks/issues/40. - "modes" - decide how would your channel connection behave, but not necessary what API you will call
- since
usePresence
is quite opinionated currently (it enters and subscribes automatically), this means that if you don't have required capability set, you will get authorization error when trying to do operation you're not supposed to (e.g. trying to enter a presence when only subscribe capability is allowed viamodes
).
Probably should also create separate ChannelNameAndOptions
interfaces for useChannel
and new usePresence*
hooks (depends on the options we end up having). Currently, subscribeOnly
is not used in useChannel
, but is present in ChannelNameAndOptions
which is used by both useChannel
and usePresence
hooks.