fix: channels sorting with predefined filters

src/channel_manager.ts

@@ -1,10 +1,11 @@
-import type { StreamChat } from './client';
+import type { QueryChannelsResponseWithChannels, StreamChat } from './client';
 import type {
   ChannelFilters,
   ChannelOptions,
   ChannelSort,
   ChannelStateOptions,
   Event,
+  QueryChannelsAPIResponse,
 } from './types';
 import type { ValueOrPatch } from './store';
 import { isPatch, StateStore } from './store';
@@ -34,6 +35,8 @@ export type ChannelManagerPagination = {
   isLoading: boolean;
   isLoadingNext: boolean;
   options: ChannelOptions;
+  responseFilters?: ChannelFilters;
+  responseSort?: ChannelSort;
   sort: ChannelSort;
 };
 
@@ -133,9 +136,14 @@ export type ChannelManagerOptions = {
   lockChannelOrder?: boolean;
 };
 
+export type QueryChannelsRequestOutput = Channel[] | QueryChannelsResponseWithChannels;
+
 export type QueryChannelsRequestType = (
-  ...params: Parameters<StreamChat['queryChannels']>
-) => Promise<Channel[]>;
+  filters: ChannelFilters,
+  sort?: ChannelSort,
+  options?: ChannelOptions,
+  stateOptions?: ChannelStateOptions,
+) => Promise<QueryChannelsRequestOutput>;
 
 export const DEFAULT_CHANNEL_MANAGER_OPTIONS = {
   abortInFlightQuery: false,
@@ -152,6 +160,54 @@ export const DEFAULT_CHANNEL_MANAGER_PAGINATION_OPTIONS = {
   offset: 0,
 };
 
+const mapPredefinedFilterSortToChannelSort = (
+  sort: NonNullable<QueryChannelsAPIResponse['predefined_filter']>['sort'],
+): ChannelSort =>
+  (sort ?? []).map(({ direction = 1, field }) => ({
+    [field]: direction,
+  })) as ChannelSort;
+
+const getResponsePaginationParams = ({
+  queryChannelsResponse,
+  sort,
+}: {
+  queryChannelsResponse?: Pick<QueryChannelsAPIResponse, 'predefined_filter'>;
+  sort: ChannelSort;
+}): Pick<ChannelManagerPagination, 'responseFilters' | 'responseSort'> => {
+  const predefinedFilter = queryChannelsResponse?.predefined_filter;
+
+  if (!predefinedFilter) {
+    return {};
+  }
+
+  return {
+    responseFilters: predefinedFilter.filter as ChannelFilters,
+    responseSort:
+      predefinedFilter.sort !== undefined
+        ? mapPredefinedFilterSortToChannelSort(predefinedFilter.sort)
+        : sort,
+  };
+};
+
+const getResponseFiltersAndSort = (
+  pagination: ChannelManagerPagination,
+): Pick<ChannelManagerPagination, 'filters' | 'sort'> => ({
+  filters: pagination.responseFilters ?? pagination.filters,
+  sort: pagination.responseSort ?? pagination.sort,
+});
+
+const omitResponsePaginationParams = (pagination: ChannelManagerPagination) => {
+  const paginationWithoutResponseParams = { ...pagination };
+  delete paginationWithoutResponseParams.responseFilters;
+  delete paginationWithoutResponseParams.responseSort;
+
+  return paginationWithoutResponseParams;
+};
+
+const isQueryChannelsResponseWithChannels = (
+  response: QueryChannelsRequestOutput,
+): response is QueryChannelsResponseWithChannels => !Array.isArray(response);
+
 /**
  * A class that manages a list of channels and changes it based on configuration and WS events. The
  * list of channels is reactive as well as the pagination and it can be subscribed to for state updates.
@@ -279,23 +335,39 @@ export class ChannelManager extends WithSubscriptions {
       ...options,
     };
     try {
-      const channels = await this.queryChannelsRequest(
+      const queryChannelsResponse = await this.queryChannelsRequest(
         filters,
         sort,
         options,
-        stateOptions,
+        { ...stateOptions, withResponse: true },
       );
+      const channels = isQueryChannelsResponseWithChannels(queryChannelsResponse)
+        ? queryChannelsResponse.channels
+        : queryChannelsResponse;
       const newOffset = offset + (channels?.length ?? 0);
       const newOptions = { ...options, offset: newOffset };
       const { pagination } = this.state.getLatestValue();
+      const responsePaginationParams = getResponsePaginationParams({
+        queryChannelsResponse: isQueryChannelsResponseWithChannels(queryChannelsResponse)
+          ? queryChannelsResponse
+          : undefined,
+        sort,
+      });
+      const paginationWithoutResponseParams = omitResponsePaginationParams(pagination);
 
       this.state.partialNext({
         channels,
         pagination: {
-          ...pagination,
+          // Drop response derived filter/sort from the previous query before applying
+          // the current response. Non predefined queries do not return this metadata,
+          // so keeping the old values would make later WS mutations use stale
+          // predefined filter semantics. Also the predefined_filter might change, producing
+          // a different combination as well so we always need to first clean up.
+          ...paginationWithoutResponseParams,
           hasNext: (channels?.length ?? 0) >= (limit ?? 1),
           isLoading: false,
           options: newOptions,
+          ...responsePaginationParams,
         },
         initialized: true,
         error: undefined,
@@ -368,7 +440,7 @@ export class ChannelManager extends WithSubscriptions {
       this.state.next((currentState) => ({
         ...currentState,
         pagination: {
-          ...currentState.pagination,
+          ...omitResponsePaginationParams(currentState.pagination),
           isLoading: true,
           isLoadingNext: false,
           filters,
@@ -434,12 +506,15 @@ export class ChannelManager extends WithSubscriptions {
       this.state.partialNext({
         pagination: { ...pagination, isLoading: false, isLoadingNext: true },
       });
-      const nextChannels = await this.queryChannelsRequest(
+      const queryChannelsResponse = await this.queryChannelsRequest(
         filters,
         sort,
         options,
         this.stateOptions,
       );
+      const nextChannels = isQueryChannelsResponseWithChannels(queryChannelsResponse)
+        ? queryChannelsResponse.channels
+        : queryChannelsResponse;
       const { channels } = this.state.getLatestValue();
       const newOffset = offset + (nextChannels?.length ?? 0);
       const newOptions = { ...options, offset: newOffset };
@@ -498,7 +573,7 @@ export class ChannelManager extends WithSubscriptions {
       return;
     }
 
-    const { sort } = pagination ?? {};
+    const { sort } = getResponseFiltersAndSort(pagination);
 
     this.setChannels(
       promoteChannel({
@@ -535,7 +610,7 @@ export class ChannelManager extends WithSubscriptions {
     if (!channels) {
       return;
     }
-    const { filters, sort } = pagination ?? {};
+    const { filters, sort } = getResponseFiltersAndSort(pagination);
 
     const channelType = event.channel_type;
     const channelId = event.channel_id;
@@ -594,7 +669,7 @@ export class ChannelManager extends WithSubscriptions {
     });
 
     const { channels, pagination } = this.state.getLatestValue();
-    const { filters, sort } = pagination ?? {};
+    const { filters, sort } = getResponseFiltersAndSort(pagination);
 
     const considerArchivedChannels = shouldConsiderArchivedChannels(filters);
     const isTargetChannelArchived = isChannelArchived(channel);
@@ -631,7 +706,7 @@ export class ChannelManager extends WithSubscriptions {
     });
 
     const { channels, pagination } = this.state.getLatestValue();
-    const { sort, filters } = pagination ?? {};
+    const { filters, sort } = getResponseFiltersAndSort(pagination);
 
     const considerArchivedChannels = shouldConsiderArchivedChannels(filters);
     const isTargetChannelArchived = isChannelArchived(channel);
@@ -658,7 +733,7 @@ export class ChannelManager extends WithSubscriptions {
 
   private memberUpdatedHandler = (event: Event) => {
     const { pagination, channels } = this.state.getLatestValue();
-    const { filters, sort } = pagination;
+    const { filters, sort } = getResponseFiltersAndSort(pagination);
     if (
       !event.member?.user ||
       event.member.user.id !== this.client.userID ||

src/client.ts

@@ -281,6 +281,13 @@ function isString(x: unknown): x is string {
 
 type MessageComposerTearDownFunction = () => void;
 
+export type QueryChannelsResponseWithChannels = Omit<
+  QueryChannelsAPIResponse,
+  'channels'
+> & {
+  channels: Channel[];
+};
+
 type MessageComposerSetupFunction = ({
   composer,
 }: {
@@ -1888,20 +1895,26 @@ export class StreamChat {
   }
 
   /**
-   * queryChannelsRequest - Queries channels and returns the raw response
+   * queryChannelsRequestWithResponse - Queries channels and returns the full API response
+   * including top-level metadata such as `predefined_filter`.
+   *
+   * This exists as a compatibility bridge, as changing `queryChannelsRequest()` to return
+   * `QueryChannelsAPIResponse` would be a breaking change because it currently returns
+   * only the channel list. In the next major release, the request/response APIs should
+   * be consolidated so callers can access the full response through the primary API.
    *
    * @param {ChannelFilters} filterConditions object MongoDB style filters. Can be empty object when using predefined_filter in options.
    * @param {ChannelSort} [sort] Sort options, for instance {created_at: -1}.
    * When using multiple fields, make sure you use array of objects to guarantee field order, for instance [{last_updated: -1}, {created_at: 1}]
    * @param {ChannelOptions} [options] Options object. Can include predefined_filter, filter_values, and sort_values for using predefined filters.
    *
-   * @return {Promise<Array<ChannelAPIResponse>>} search channels response
+   * @return {Promise<QueryChannelsAPIResponse>} full search channels response
    */
-  async queryChannelsRequest(
+  async queryChannelsRequestWithResponse(
     filterConditions: ChannelFilters,
     sort: ChannelSort = [],
     options: ChannelOptions = {},
-  ) {
+  ): Promise<QueryChannelsAPIResponse> {
     const defaultOptions: ChannelOptions = {
       state: true,
       watch: true,
@@ -1934,9 +1947,33 @@ export class StreamChat {
           ...restOptions,
         };
 
-    const data = await this.post<QueryChannelsAPIResponse>(
-      this.baseURL + '/channels',
-      payload,
+    return await this.post<QueryChannelsAPIResponse>(this.baseURL + '/channels', payload);
+  }
+
+  /**
+   * queryChannelsRequest - Queries channels and returns the raw channel response list.
+   *
+   * This preserves the historical return shape for backwards compatibility. Use
+   * `queryChannelsRequestWithResponse()` when response level metadata such as
+   * `predefined_filter` is needed. In the next major release these APIs should be
+   * consolidated into a single full-response API.
+   *
+   * @param {ChannelFilters} filterConditions object MongoDB style filters. Can be empty object when using predefined_filter in options.
+   * @param {ChannelSort} [sort] Sort options, for instance {created_at: -1}.
+   * When using multiple fields, make sure you use array of objects to guarantee field order, for instance [{last_updated: -1}, {created_at: 1}]
+   * @param {ChannelOptions} [options] Options object. Can include predefined_filter, filter_values, and sort_values for using predefined filters.
+   *
+   * @return {Promise<Array<ChannelAPIResponse>>} search channels response
+   */
+  async queryChannelsRequest(
+    filterConditions: ChannelFilters,
+    sort: ChannelSort = [],
+    options: ChannelOptions = {},
+  ) {
+    const data = await this.queryChannelsRequestWithResponse(
+      filterConditions,
+      sort,
+      options,
     );
 
     // FIXME: In the next major release, return the full QueryChannelsAPIResponse
@@ -1955,16 +1992,34 @@ export class StreamChat {
    * @param {ChannelStateOptions} [stateOptions] State options object. These options will only be used for state management and won't be sent in the request.
    * - stateOptions.skipInitialization - Skips the initialization of the state for the channels matching the ids in the list.
    * - stateOptions.skipHydration - Skips returning the channels as instances of the Channel class and rather returns the raw query response.
+   * - stateOptions.withResponse - Returns the full query response with hydrated channels. This is a compatibility bridge for internal callers that need response-level metadata while the default return value remains `Channel[]`.
    *
    * @return {Promise<Array<Channel>>} search channels response
    */
+  async queryChannels(
+    filterConditions: ChannelFilters,
+    sort: ChannelSort,
+    options: ChannelOptions,
+    stateOptions: ChannelStateOptions & { withResponse: true },
+  ): Promise<QueryChannelsResponseWithChannels>;
+  async queryChannels(
+    filterConditions?: ChannelFilters,
+    sort?: ChannelSort,
+    options?: ChannelOptions,
+    stateOptions?: ChannelStateOptions,
+  ): Promise<Channel[]>;
   async queryChannels(
     filterConditions: ChannelFilters,
     sort: ChannelSort = [],
     options: ChannelOptions = {},
     stateOptions: ChannelStateOptions = {},
-  ) {
-    const channels = await this.queryChannelsRequest(filterConditions, sort, options);
+  ): Promise<Channel[] | QueryChannelsResponseWithChannels> {
+    const queryChannelsResponse = await this.queryChannelsRequestWithResponse(
+      filterConditions,
+      sort,
+      options,
+    );
+    const channels = queryChannelsResponse.channels;
 
     this.dispatchEvent({
       type: 'channels.queried',
@@ -1980,7 +2035,16 @@ export class StreamChat {
       });
     }
 
-    return this.hydrateActiveChannels(channels, stateOptions, options);
+    const hydratedChannels = this.hydrateActiveChannels(channels, stateOptions, options);
+
+    if (stateOptions.withResponse) {
+      return {
+        ...queryChannelsResponse,
+        channels: hydratedChannels,
+      };
+    }
+
+    return hydratedChannels;
   }
 
   /**

src/types.ts

@@ -1111,6 +1111,15 @@ export type ChannelStateOptions = {
   offlineMode?: boolean;
   skipInitialization?: string[];
   skipHydration?: boolean;
+  /**
+   * Returns the full query response with hydrated channels from `queryChannels()`.
+   *
+   * This is a compatibility bridge for internal callers that need response level
+   * metadata such as `predefined_filter`. The default `queryChannels()` return value
+   * remains `Channel[]` to avoid a breaking change. This should be folded into a
+   * single full response API in the next major release.
+   */
+  withResponse?: boolean;
 };
 
 export type CreateChannelOptions = {