**UNOFFICIAL** Opinionated React library for using Ably channels and clients. This library can handle multiple clients in a single page/app.
npm install ably-reactuseAbly hook to register multiple clients.This hook can be used any number of times. Each hook will register a lock on the client.
If all locks disappear the client will be destroyed and disconnected.
``jsx
import { useAbly } from 'ably-react';
function App() {
const ably = useAbly({
// OPTIONAL: whether to skip client initialization for now.
// useful when waiting for authentication
skip: false,
// OPTIONAL: can be used to identify the client
clientId: 'user-id',
// OPTIONAL [default: true]: whether to automatically connect the client
autoConnect: true,
// OPTIONAL [default: "default"]: the name to register the client under
// the library allows for multiple clients (named)
name: 'default',
// OPTIONAL: Callback used to authenticate. This callback is a promise as opposed.
authCallback: async (data) => {
return fetchToken();
},
// OPTIONAL: Any other options to pass through to the client
clientOptions: {},
});
}
`
by default).
It does not register a lock on the client and simply returns the raw Ably.Realtime client.`js
const ablyClient = useAblyClient('default')
`$3
This hook simply gets a the client status from the context by name ( by default)
As with the useAblyClient hook, this also does not register a lock on the client and simply returns the client status.`js
const ablyClientStatus = useAblyClientStatus('default')
`$3
This hook simply gets a channel reference.js
const ably = useAbly()
const channel = useChannel(ably.client, 'my-channel')
`$3
This hook will track and return the status of a channel.js
const ably = useAbly()
const channel = useChannel(ably.client, 'my-channel')
const status = useChannelStatus(channel)
`$3
This hook will keep track of whether a specific client is present. This is useful for peer to peer like communication.js
const ably = useAbly()
const channel = useChannel(ably.client, 'my-channel')
const isClientPresent = useIsClientPresent(channel, 'client-id', (error) => {
// do something on error
});
`$3
This hook will announce it's presence on a channel (and remove it if not rendered).js
const ably = useAbly()
const channel = useChannel(ably.client, 'my-channel')
usePresent(channel)
`$3
This hook will retry attaching a channel until the callback returns .
This is useful for recovering failed channel states.`js
const ably = useAbly()
const channel = useChannel(ably.client, 'my-channel')
useRetryAttachUntil(channel, 1000, (retryCount, event) => retryCount > 3, (event) => {
// do something on failure
});
`$3
This hook should be used with the utility (see below). This hook simply handles responding to a handshake request. (should only be rendered once per channel).`js
const ably = useAbly()
const channel = useChannel(ably.client, 'my-channel')
useHandshakeHandler(channel);
`Utilities
$3
This utility returns a promise which waits for a channel to be attached (or rejects on timeout if specified).js
await waitForAttached(channel, 1000); // if timeout is omitted, the promise will never reject
`$3
This utility returns a promise which waits for a specific message from a channel (or rejects on timeout if specified).]js
await waitForMessage(channel, (message) => message.name === 'ping', 1000); // if timeout is omitted, the promise will never reject
`$3
This utility returns a promise which will send a handshake request (and retry per interval), until the handshake is accepted by another client.js
await waitForHandshake(
channel,
1000 / retry interval /,
1000 / timeout /,
(message) => true, / only accept handshake if ... /
); // if timeout is omitted, the promise will never reject
``