ably-js icon indicating copy to clipboard operation
ably-js copied to clipboard

Split `usePresence` hook into different hooks for entering presence and subscribing to presence events

Open VeskeR opened this issue 1 year ago • 0 comments

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 all onMount 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 via modes).

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.

┆Issue is synchronized with this Jira Task by Unito

VeskeR avatar Feb 12 '24 13:02 VeskeR