feat: allow to pass custom function customQueryChannels to ChannelList to query channels (#2260)

Author: MartinCupela

docusaurus/docs/React/components/core-components/channel-list.mdx

@@ -219,6 +219,103 @@ Set a channel (with this ID) to active and force it to move to the top of the li
 | ------ |
 | string |
 
+### customQueryChannels
+
+Custom function that handles the channel pagination.
+
+Takes parameters:
+
+| Parameter         | Description                                                                                                                                                           |
+|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `currentChannels` | The state of loaded `Channel` objects queried thus far. Has to be set with `setChannels` (see below).                                                                 |
+| `queryType`       | A string indicating, whether the channels state has to be reset to the first page ('reload') or newly queried channels should be appended to the `currentChannels`.   |
+| `setChannels`     | Function that allows us to set the channels state reflected in `currentChannels`.                                                                                     |
+| `setHasNextPage`  | Flag indicating whether there are more items to be loaded from the API. Should be infered from the comparison of the query result length and the query options limit. |
+
+The function has to:
+1. build / provide own query filters, sort and options parameters
+2. query and append channels to the current channels state
+3. update the `hasNext` pagination flag after each query with `setChannels` function
+
+An example below implements a custom query function that uses different filters sequentially once a preceding filter is exhausted:
+
+```ts
+import uniqBy from "lodash.uniqby";
+import throttle from 'lodash.throttle';
+import {useCallback, useRef} from 'react';
+import {ChannelFilters, ChannelOptions, ChannelSort, StreamChat} from 'stream-chat';
+import {
+    CustomQueryChannelParams,
+    useChatContext,
+} from 'stream-chat-react';
+
+const DEFAULT_PAGE_SIZE = 30 as const;
+
+export const useCustomQueryChannels = () => {
+  const { client } = useChatContext();
+  const filters1: ChannelFilters = {
+    member_count: { $gt: 10 },
+    members: { $in: [client.user?.id || ''] },
+    type: 'messaging',
+  };
+  const filters2: ChannelFilters = { members: { $in: [client.user?.id || ''] }, type: 'messaging' };
+  const options: ChannelOptions = { limit: 10, presence: true, state: true };
+  const sort: ChannelSort = { last_message_at: -1, updated_at: -1 };
+
+  const filtersArray = [filters1, filters2];
+  const appliedFilterIndex = useRef(0);
+
+  const customQueryChannels = useCallback(
+    throttle(
+      async ({
+        currentChannels,
+        queryType,
+        setChannels,
+        setHasNextPage,
+      }: CustomQueryChannelParams) => {
+        const offset = queryType === 'reload' ? 0 : currentChannels.length;
+
+        const newOptions = {
+          limit: options.limit ?? DEFAULT_PAGE_SIZE,
+          offset,
+          ...options,
+        };
+
+        const filters = filtersArray[appliedFilterIndex.current];
+        const channelQueryResponse = await client.queryChannels(filters, sort || {}, newOptions);
+
+        const newChannels =
+          queryType === 'reload'
+            ? channelQueryResponse
+            : uniqBy([...currentChannels, ...channelQueryResponse], 'cid');
+
+        setChannels(newChannels);
+
+        const lastPageForCurrentFilter = channelQueryResponse.length < newOptions.limit;
+        const isLastPageForAllFilters =
+          lastPageForCurrentFilter && appliedFilterIndex.current === filtersArray.length - 1;
+
+        setHasNextPage(!isLastPageForAllFilters);
+        if (lastPageForCurrentFilter) {
+          appliedFilterIndex.current += 1;
+        }
+      },
+      500,
+      { leading: true, trailing: false },
+    ),
+    [client, filtersArray],
+  );
+
+  return customQueryChannels;
+};
+```
+
+It is recommended to control for duplicate requests by throttling the custom function calls.
+
+| Type                                                                                              |
+|---------------------------------------------------------------------------------------------------|
+| <GHComponentLink text='CustomQueryChannelsFn' path='/ChannelList/hooks/usePaginatedChannels.ts'/> |
+
 ### EmptyStateIndicator
 
 Custom UI component for rendering an empty list.

src/components/ChannelList/ChannelList.tsx

@@ -13,7 +13,7 @@ import { useMobileNavigation } from './hooks/useMobileNavigation';
 import { useNotificationAddedToChannelListener } from './hooks/useNotificationAddedToChannelListener';
 import { useNotificationMessageNewListener } from './hooks/useNotificationMessageNewListener';
 import { useNotificationRemovedFromChannelListener } from './hooks/useNotificationRemovedFromChannelListener';
-import { usePaginatedChannels } from './hooks/usePaginatedChannels';
+import { CustomQueryChannelsFn, usePaginatedChannels } from './hooks/usePaginatedChannels';
 import { useUserPresenceChangedListener } from './hooks/useUserPresenceChangedListener';
 import { MAX_QUERY_CHANNELS_LIMIT, moveChannelUp } from './utils';
 
@@ -64,6 +64,8 @@ export type ChannelListProps<
   ChannelSearch?: React.ComponentType<ChannelSearchProps<StreamChatGenerics>>;
   /** Set a channel (with this ID) to active and manually move it to the top of the list */
   customActiveChannel?: string;
+  /** Custom function that handles the channel pagination. Has to build query filters, sort and options and query and append channels to the current channels state and update the hasNext pagination flag after each query. */
+  customQueryChannels?: CustomQueryChannelsFn<StreamChatGenerics>;
   /** Custom UI component for rendering an empty list, defaults to and accepts same props as: [EmptyStateIndicator](https://github.com/GetStream/stream-chat-react/blob/master/src/components/EmptyStateIndicator/EmptyStateIndicator.tsx) */
   EmptyStateIndicator?: React.ComponentType<EmptyStateIndicatorProps>;
   /** An object containing channel query filters */
@@ -163,6 +165,7 @@ const UnMemoizedChannelList = <
     channelRenderFilterFn,
     ChannelSearch = DefaultChannelSearch,
     customActiveChannel,
+    customQueryChannels,
     EmptyStateIndicator = DefaultEmptyStateIndicator,
     filters,
     LoadingErrorIndicator = ChatDown,
@@ -274,6 +277,7 @@ const UnMemoizedChannelList = <
     options || DEFAULT_OPTIONS,
     activeChannelHandler,
     recoveryThrottleIntervalMs,
+    customQueryChannels,
   );
 
   const loadedChannels = channelRenderFilterFn ? channelRenderFilterFn(channels) : channels;

src/components/ChannelList/__tests__/ChannelList.test.js

@@ -38,6 +38,7 @@ import {
 
 import { ChatContext, useChannelListContext, useChatContext } from '../../../context';
 import { ChannelListMessenger } from '../ChannelListMessenger';
+import { initClientWithChannels } from '../../../mock-builders';
 
 expect.extend(toHaveNoViolations);
 
@@ -203,6 +204,66 @@ describe('ChannelList', () => {
     expect(results).toHaveNoViolations();
   });
 
+  it('should use custom query channels function instead of default channels query', async () => {
+    const { channels, client } = await initClientWithChannels({
+      channelsData: [testChannel1],
+    });
+    const props = {
+      customQueryChannels: jest
+        .fn()
+        .mockImplementationOnce(({ currentChannels, setChannels, setHasNextPage }) => {
+          if (!currentChannels.length) setChannels([channels[0]]);
+          setHasNextPage(true);
+        }),
+      filters: {},
+    };
+    const queryChannelsMock = jest.spyOn(client, 'queryChannels').mockImplementationOnce();
+
+    let rerender;
+    await act(async () => {
+      const result = await render(
+        <Chat client={client}>
+          <ChannelList {...props} />
+        </Chat>,
+      );
+      rerender = result.rerender;
+    });
+
+    expect(queryChannelsMock).toHaveBeenCalledTimes(0);
+    expect(props.customQueryChannels).toHaveBeenCalledTimes(1);
+    expect(props.customQueryChannels).toHaveBeenCalledWith(
+      expect.objectContaining({
+        currentChannels: [],
+        queryType: 'reload',
+        setChannels: expect.any(Function),
+        setHasNextPage: expect.any(Function),
+      }),
+    );
+
+    await act(async () => {
+      await rerender(
+        <Chat client={client}>
+          <ChannelList {...props} />
+        </Chat>,
+      );
+    });
+    await act(() => {
+      fireEvent.click(screen.getByTestId('load-more-button'));
+    });
+
+    expect(queryChannelsMock).toHaveBeenCalledTimes(0);
+    expect(props.customQueryChannels).toHaveBeenCalledTimes(2);
+    expect(props.customQueryChannels).toHaveBeenCalledWith(
+      expect.objectContaining({
+        currentChannels: [channels[0]],
+        queryType: 'load-more',
+        setChannels: expect.any(Function),
+        setHasNextPage: expect.any(Function),
+      }),
+    );
+    queryChannelsMock.mockRestore();
+  });
+
   it('should only show filtered channels when a filter function prop is provided', async () => {
     const filteredChannel = generateChannel({ channel: { type: 'filtered' } });
 

src/components/ChannelList/hooks/usePaginatedChannels.ts

@@ -8,10 +8,26 @@ import type { Channel, ChannelFilters, ChannelOptions, ChannelSort, StreamChat }
 import { useChatContext } from '../../../context/ChatContext';
 
 import type { DefaultStreamChatGenerics } from '../../../types/types';
+import type { ChannelsQueryState } from '../../Chat/hooks/useChannelsQueryState';
 
 const RECOVER_LOADED_CHANNELS_THROTTLE_INTERVAL_IN_MS = 5000;
 const MIN_RECOVER_LOADED_CHANNELS_THROTTLE_INTERVAL_IN_MS = 2000;
 
+type AllowedQueryType = Extract<ChannelsQueryState['queryInProgress'], 'reload' | 'load-more'>;
+
+export type CustomQueryChannelParams<
+  StreamChatGenerics extends DefaultStreamChatGenerics = DefaultStreamChatGenerics
+> = {
+  currentChannels: Array<Channel<StreamChatGenerics>>;
+  queryType: AllowedQueryType;
+  setChannels: React.Dispatch<React.SetStateAction<Array<Channel<StreamChatGenerics>>>>;
+  setHasNextPage: React.Dispatch<React.SetStateAction<boolean>>;
+};
+
+export type CustomQueryChannelsFn<
+  StreamChatGenerics extends DefaultStreamChatGenerics = DefaultStreamChatGenerics
+> = (params: CustomQueryChannelParams<StreamChatGenerics>) => Promise<void>;
+
 export const usePaginatedChannels = <
   StreamChatGenerics extends DefaultStreamChatGenerics = DefaultStreamChatGenerics
 >(
@@ -24,6 +40,7 @@ export const usePaginatedChannels = <
     setChannels: React.Dispatch<React.SetStateAction<Array<Channel<StreamChatGenerics>>>>,
   ) => void,
   recoveryThrottleIntervalMs: number = RECOVER_LOADED_CHANNELS_THROTTLE_INTERVAL_IN_MS,
+  customQueryChannels?: CustomQueryChannelsFn<StreamChatGenerics>,
 ) => {
   const {
     channelsQueryState: { error, setError, setQueryInProgress },
@@ -43,38 +60,45 @@ export const usePaginatedChannels = <
   const sortString = useMemo(() => JSON.stringify(sort), [sort]);
 
   // eslint-disable-next-line react-hooks/exhaustive-deps
-  const queryChannels = async (queryType?: string) => {
+  const queryChannels = async (queryType = 'load-more') => {
     setError(null);
 
     if (queryType === 'reload') {
       setChannels([]);
-      setQueryInProgress('reload');
-    } else {
-      setQueryInProgress('load-more');
     }
-
-    const offset = queryType === 'reload' ? 0 : channels.length;
-
-    const newOptions = {
-      limit: options?.limit ?? MAX_QUERY_CHANNELS_LIMIT,
-      offset,
-      ...options,
-    };
+    setQueryInProgress(queryType as AllowedQueryType);
 
     try {
-      const channelQueryResponse = await client.queryChannels(filters, sort || {}, newOptions);
-
-      const newChannels =
-        queryType === 'reload'
-          ? channelQueryResponse
-          : uniqBy([...channels, ...channelQueryResponse], 'cid');
-
-      setChannels(newChannels);
-      setHasNextPage(channelQueryResponse.length >= newOptions.limit);
-
-      // Set active channel only on load of first page
-      if (!offset && activeChannelHandler) {
-        activeChannelHandler(newChannels, setChannels);
+      if (customQueryChannels) {
+        await customQueryChannels({
+          currentChannels: channels,
+          queryType: queryType as AllowedQueryType,
+          setChannels,
+          setHasNextPage,
+        });
+      } else {
+        const offset = queryType === 'reload' ? 0 : channels.length;
+
+        const newOptions = {
+          limit: options?.limit ?? MAX_QUERY_CHANNELS_LIMIT,
+          offset,
+          ...options,
+        };
+
+        const channelQueryResponse = await client.queryChannels(filters, sort || {}, newOptions);
+
+        const newChannels =
+          queryType === 'reload'
+            ? channelQueryResponse
+            : uniqBy([...channels, ...channelQueryResponse], 'cid');
+
+        setChannels(newChannels);
+        setHasNextPage(channelQueryResponse.length >= newOptions.limit);
+
+        // Set active channel only on load of first page
+        if (!offset && activeChannelHandler) {
+          activeChannelHandler(newChannels, setChannels);
+        }
       }
     } catch (err) {
       console.warn(err);

src/components/Chat/hooks/useChannelsQueryState.ts

@@ -9,9 +9,9 @@ type ChannelQueryState =
 
 export interface ChannelsQueryState {
   error: ErrorFromResponse<APIErrorResponse> | null;
-  queryInProgress: ChannelQueryState | null;
+  queryInProgress: ChannelQueryState;
   setError: Dispatch<SetStateAction<ErrorFromResponse<APIErrorResponse> | null>>;
-  setQueryInProgress: Dispatch<SetStateAction<ChannelQueryState | null>>;
+  setQueryInProgress: Dispatch<SetStateAction<ChannelQueryState>>;
 }
 
 export const useChannelsQueryState = (): ChannelsQueryState => {