Merge pull request #1620 from ably/SDK-4083/channel-provider

`ChannelProvider` implementation

src/platform/react-hooks/sample-app/src/App.tsx

@@ -22,7 +22,7 @@ function App() {
   useChannel(
     {
       channelName: 'your-derived-channel-name',
-      deriveOptions: { filter: 'headers.email == `"rob.pike@domain.com"` || headers.company == `"domain"`' },
+      id: 'rob',
     },
     (message) => {
       updateDerivedChannelMessages((prev) => [...prev, message]);
@@ -32,14 +32,16 @@ function App() {
   useChannel(
     {
       channelName: 'your-derived-channel-name',
-      deriveOptions: { filter: 'headers.role == `"front-office"` || headers.company == `"domain"`' },
+      id: 'frontOffice',
     },
     (message) => {
       updateFrontOfficeOnlyMessages((prev) => [...prev, message]);
     }
   );
 
-  const { channel: anotherChannelPublisher } = useChannel({ channelName: 'your-derived-channel-name' });
+  const { channel: anotherChannelPublisher } = useChannel({
+    channelName: 'your-derived-channel-name',
+  });
 
   const { presenceData, updateStatus } = usePresence(
     { channelName: 'your-channel-name', skip },

src/platform/react-hooks/sample-app/src/script.tsx

@@ -3,9 +3,8 @@ import { createRoot } from 'react-dom/client';
 // eslint-disable-next-line @typescript-eslint/ban-ts-comment
 // @ts-ignore
 import * as Ably from 'ably';
-
 import App from './App.js';
-import { AblyProvider } from '../../src/index.js';
+import { AblyProvider, ChannelProvider } from '../../src/index.js';
 
 const container = document.getElementById('root')!;
 
@@ -22,7 +21,27 @@ const root = createRoot(container);
 root.render(
   <React.StrictMode>
     <AblyProvider client={client}>
-      <App />
+      <AblyProvider id="rob" client={client}>
+        <AblyProvider id="frontOffice" client={client}>
+          <ChannelProvider channelName="your-channel-name" options={{ modes: ['PRESENCE', 'PUBLISH', 'SUBSCRIBE'] }}>
+            <ChannelProvider channelName="your-derived-channel-name">
+              <ChannelProvider
+                id="rob"
+                channelName="your-derived-channel-name"
+                deriveOptions={{ filter: 'headers.email == `"rob.pike@domain.com"` || headers.company == `"domain"`' }}
+              >
+                <ChannelProvider
+                  id="frontOffice"
+                  channelName="your-derived-channel-name"
+                  deriveOptions={{ filter: 'headers.role == `"front-office"` || headers.company == `"domain"`' }}
+                >
+                  <App />
+                </ChannelProvider>
+              </ChannelProvider>
+            </ChannelProvider>
+          </ChannelProvider>
+        </AblyProvider>
+      </AblyProvider>
     </AblyProvider>
   </React.StrictMode>
 );

src/platform/react-hooks/src/AblyProvider.tsx

@@ -9,7 +9,12 @@ interface AblyProviderProps {
   id?: string;
 }
 
-type AblyContextType = React.Context<Ably.RealtimeClient>;
+export interface AblyContextProps {
+  client: Ably.RealtimeClient;
+  _channelNameToInstance: Record<string, Ably.RealtimeChannel>;
+}
+
+type AblyContextType = React.Context<AblyContextProps>;
 
 // An object is appended to `React.createContext` which stores all contexts
 // indexed by id, which is used by useAbly to find the correct context when an
@@ -24,16 +29,22 @@ export function getContext(ctxId = 'default'): AblyContextType {
 }
 
 export const AblyProvider = ({ client, children, id = 'default' }: AblyProviderProps) => {
+  const value: AblyContextProps = useMemo(
+    () => ({
+      client,
+      _channelNameToInstance: {},
+    }),
+    [client]
+  );
+
   if (!client) {
     throw new Error('AblyProvider: the `client` prop is required');
   }
 
-  const realtime = useMemo(() => client, [client]);
-
   let context = getContext(id);
   if (!context) {
-    context = ctxMap[id] = React.createContext(realtime);
+    context = ctxMap[id] = React.createContext({ client, _channelNameToInstance: {} });
   }
 
-  return <context.Provider value={realtime}>{children}</context.Provider>;
+  return <context.Provider value={value}>{children}</context.Provider>;
 };

src/platform/react-hooks/src/AblyReactHooks.ts

@@ -2,8 +2,6 @@ import * as Ably from 'ably';
 
 export type ChannelNameAndOptions = {
   channelName: string;
-  options?: Ably.ChannelOptions;
-  deriveOptions?: Ably.DeriveOptions;
   id?: string;
   subscribeOnly?: boolean;
   skip?: boolean;

src/platform/react-hooks/src/ChannelProvider.tsx

@@ -0,0 +1,47 @@
+import React, { useEffect, useMemo } from 'react';
+import * as Ably from 'ably';
+import { type AblyContextProps, getContext } from './AblyProvider.js';
+import { channelOptionsWithAgent } from './AblyReactHooks.js';
+
+interface ChannelProviderProps {
+  id?: string;
+  channelName: string;
+  options?: Ably.ChannelOptions;
+  deriveOptions?: Ably.DeriveOptions;
+  children?: React.ReactNode | React.ReactNode[] | null;
+}
+
+export const ChannelProvider = ({
+  id = 'default',
+  channelName,
+  options,
+  deriveOptions,
+  children,
+}: ChannelProviderProps) => {
+  const context = getContext(id);
+  const { client, _channelNameToInstance } = React.useContext(context);
+
+  if (_channelNameToInstance[channelName]) {
+    throw new Error('You can not use more than one `ChannelProvider` with the same channel name');
+  }
+
+  const channel = deriveOptions
+    ? client.channels.getDerived(channelName, deriveOptions)
+    : client.channels.get(channelName);
+
+  const value: AblyContextProps = useMemo(() => {
+    return {
+      client,
+      _channelNameToInstance: {
+        ..._channelNameToInstance,
+        [channelName]: channel,
+      },
+    };
+  }, [client, channel, channelName, _channelNameToInstance]);
+
+  useEffect(() => {
+    channel.setOptions(channelOptionsWithAgent(options));
+  }, [channel, options]);
+
+  return <context.Provider value={value}>{children}</context.Provider>;
+};

src/platform/react-hooks/src/fakes/ably.ts

@@ -104,7 +104,7 @@ export class ClientChannelsCollection {
     if (channelConnection) {
       return channelConnection;
     } else {
-      channelConnection = new ClientSingleChannelConnection(this.client, this.channels.get(name));
+      channelConnection = new ClientSingleChannelConnection(this.client, this.channels.get(name), name);
       this._channelConnections.set(name, channelConnection);
       return channelConnection;
     }
@@ -115,7 +115,7 @@ export class ClientChannelsCollection {
     if (channelConnection) return channelConnection as ClientSingleDerivedChannelConnection;
 
     const channel = this.channels.get(name);
-    channelConnection = new ClientSingleDerivedChannelConnection(this.client, channel, options);
+    channelConnection = new ClientSingleDerivedChannelConnection(this.client, channel, options, name);
     this._channelConnections.set(name, channelConnection);
     return channelConnection;
   }
@@ -127,13 +127,15 @@ export class ClientSingleChannelConnection extends EventEmitter {
 
   public presence: any;
   public state: string;
+  public name: string;
 
-  constructor(client: FakeAblySdk, channel: Channel) {
+  constructor(client: FakeAblySdk, channel: Channel, name: string) {
     super();
     this.client = client;
     this.channel = channel;
     this.presence = new ClientPresenceConnection(this.client, this.channel.presence);
     this.state = 'attached';
+    this.name = name;
   }
 
   publish(messages: any, callback?: Ably.errorCallback): void;
@@ -157,18 +159,24 @@ export class ClientSingleChannelConnection extends EventEmitter {
   public detach() {
     this.channel.subscriptionsPerClient.delete(this.client.clientId);
   }
+
+  public async setOptions() {
+    // do nothing
+  }
 }
 
 export class ClientSingleDerivedChannelConnection extends EventEmitter {
   private client: FakeAblySdk;
   private channel: Channel;
   private deriveOpts: Ably.DeriveOptions;
+  public name?: string;
 
-  constructor(client: FakeAblySdk, channel: Channel, deriveOptions?: Ably.DeriveOptions) {
+  constructor(client: FakeAblySdk, channel: Channel, deriveOptions?: Ably.DeriveOptions, name?: string) {
     super();
     this.client = client;
     this.channel = channel;
     this.deriveOpts = deriveOptions;
+    this.name = name;
   }
 
   public async subscribe(
@@ -183,6 +191,10 @@ export class ClientSingleDerivedChannelConnection extends EventEmitter {
   public unsubscribe() {
     this.channel.subscriptionsPerClient.delete(this.client.clientId);
   }
+
+  public async setOptions() {
+    // do nothing
+  }
 }
 
 export class ClientPresenceConnection {
@@ -328,6 +340,10 @@ export class Channel {
       subs.push(callback);
     }
   }
+
+  public async setOptions() {
+    // do nothing
+  }
 }
 
 export class ChannelPresence {

src/platform/react-hooks/src/hooks/useAbly.ts

@@ -3,7 +3,7 @@ import { getContext } from '../AblyProvider.js';
 import * as API from 'ably';
 
 export function useAbly(id = 'default'): API.RealtimeClient {
-  const client = React.useContext(getContext(id)) as API.RealtimeClient;
+  const client = React.useContext(getContext(id)).client;
 
   if (!client) {
     throw new Error(