Support predefined filters in ChannelListQuery

CHANGELOG.md

@@ -3,6 +3,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 # Upcoming
 
+## StreamChat
+### ✅ Added
+- Add `ChannelListQuery(predefinedFilter:filterValues:sortValues:)` for creating channel list queries with predefined filters [#4113](https://github.com/GetStream/stream-chat-swift/pull/4113)
+
 ## StreamChatUI
 ### 🐞 Fixed
 - Fix attachment upload overlay text and action buttons being illegible in dark mode [#4111](https://github.com/GetStream/stream-chat-swift/pull/4111)

DemoApp/StreamChat/Components/DemoChatChannelListVC.swift

@@ -110,6 +110,17 @@ final class DemoChatChannelListVC: ChatChannelListVC {
 
     lazy var premiumTaggedChannelsQuery: ChannelListQuery = .init(filter: .in(.filterTags, values: ["premium"]))
 
+    lazy var predefinedMessagingChannelsQuery: ChannelListQuery = .init(
+        predefinedFilter: "user_per_channel_type_channels",
+        filterValues: ["channel_type": .string(ChannelType.messaging.rawValue), "user_id": .string(currentUserId)],
+        sortValues: nil
+    )
+
+    lazy var predefinedLivestreamChannelsQuery: ChannelListQuery = .init(
+        predefinedFilter: "user_per_channel_type_channels",
+        filterValues: ["channel_type": .string(ChannelType.livestream.rawValue), "user_id": .string(currentUserId)],
+        sortValues: nil
+    )
     lazy var livestreamChannelsQuery: ChannelListQuery = .init(filter: .equal(.type, to: .livestream))
 
     var demoRouter: DemoChatChannelListRouter? {
@@ -270,6 +281,23 @@ final class DemoChatChannelListVC: ChatChannelListVC {
             }
         )
 
+        let predefinedMessagingChannelsAction = UIAlertAction(
+            title: "Predefined: messaging",
+            style: .default,
+            handler: { [weak self] _ in
+                self?.title = "Predefined: messaging"
+                self?.setPredefinedMessagingChannelsQuery()
+            }
+        )
+
+        let predefinedLivestreamChannelsAction = UIAlertAction(
+            title: "Predefined: livestream",
+            style: .default,
+            handler: { [weak self] _ in
+                self?.title = "Predefined: livestream"
+                self?.setPredefinedLivestreamChannelsQuery()
+            }
+        )
         let livestreamChannelsAction = UIAlertAction(
             title: "Livestream Channels",
             style: .default
@@ -294,6 +322,8 @@ final class DemoChatChannelListVC: ChatChannelListVC {
                 equalMembersAction,
                 channelRoleChannelsAction,
                 taggedChannelsAction,
+                predefinedMessagingChannelsAction,
+                predefinedLivestreamChannelsAction,
                 livestreamChannelsAction
             ].sorted(by: { $0.title ?? "" < $1.title ?? "" }),
             preferredStyle: .actionSheet,
@@ -355,6 +385,14 @@ final class DemoChatChannelListVC: ChatChannelListVC {
         replaceQuery(premiumTaggedChannelsQuery)
     }
 
+    func setPredefinedMessagingChannelsQuery() {
+        replaceQuery(predefinedMessagingChannelsQuery)
+    }
+
+    func setPredefinedLivestreamChannelsQuery() {
+        replaceQuery(predefinedLivestreamChannelsQuery)
+    }
+
     func setLivestreamChannelsQuery() {
         replaceQuery(livestreamChannelsQuery)
     }

Sources/StreamChat/APIClient/Endpoints/Payloads/ChannelListPayload.swift

@@ -7,24 +7,48 @@ import Foundation
 struct ChannelListPayload {
     /// A list of channels response (see `ChannelQuery`).
     let channels: [ChannelPayload]
+
+    /// Server-resolved predefined filter, present only when the query was made with a predefined filter.
+    let predefinedFilter: PredefinedFilterPayload?
+
+    init(channels: [ChannelPayload], predefinedFilter: PredefinedFilterPayload? = nil) {
+        self.channels = channels
+        self.predefinedFilter = predefinedFilter
+    }
 }
 
 extension ChannelListPayload: Decodable {
     enum CodingKeys: String, CodingKey {
         case channels
+        case predefinedFilter = "predefined_filter"
     }
 
     init(from decoder: Decoder) throws {
         let container = try decoder.container(keyedBy: CodingKeys.self)
         let channels = try container
             .decodeArrayIgnoringFailures([ChannelPayload].self, forKey: .channels)
+        let predefinedFilter = try container
+            .decodeIfPresent(PredefinedFilterPayload.self, forKey: .predefinedFilter)
 
         self.init(
-            channels: channels
+            channels: channels,
+            predefinedFilter: predefinedFilter
         )
     }
 }
 
+final class PredefinedFilterPayload: Decodable, Sendable {
+    let name: String
+    let filter: [String: RawJSON]
+    let sort: [[String: RawJSON]]
+
+    init(name: String, filter: [String: RawJSON], sort: [[String: RawJSON]]) {
+        self.name = name
+        self.filter = filter
+        self.sort = sort
+    }
+}
+
 struct ChannelPayload {
     let channel: ChannelDetailPayload
 

Sources/StreamChat/Controllers/ChannelListController/ChannelListController.swift

@@ -35,7 +35,7 @@ extension ChatClient {
 /// - Note: For an async-await alternative of the `ChatChannelListController`, please check ``ChannelList`` in the async-await supported [state layer](https://getstream.io/chat/docs/sdk/ios/client/state-layer/state-layer-overview/).
 public class ChatChannelListController: DataController, DelegateCallable, DataStoreProvider, @unchecked Sendable {
     /// The query specifying and filtering the list of channels.
-    public let query: ChannelListQuery
+    public internal(set) var query: ChannelListQuery
 
     /// The `ChatClient` instance this controller belongs to.
     public let client: ChatClient
@@ -51,11 +51,7 @@ public class ChatChannelListController: DataController, DelegateCallable, DataSt
     }
 
     /// The worker used to fetch the remote data and communicate with servers.
-    private lazy var worker: ChannelListUpdater = self.environment
-        .channelQueryUpdaterBuilder(
-            client.databaseContainer,
-            client.apiClient
-        )
+    private let worker: ChannelListUpdater
 
     /// The worker used to update current user data.
     private lazy var currentUserUpdater: CurrentUserUpdater = self.environment
@@ -82,8 +78,15 @@ public class ChatChannelListController: DataController, DelegateCallable, DataSt
     }
 
     private(set) lazy var channelListObserver: BackgroundListDatabaseObserver<ChatChannel, ChannelDTO> = {
+        if let updated = worker.loadPredefinedFilter(for: query) {
+            query = updated
+        }
+        return makeChannelListObserver()
+    }()
+
+    private func makeChannelListObserver() -> BackgroundListDatabaseObserver<ChatChannel, ChannelDTO> {
         let request = ChannelDTO.channelListFetchRequest(query: self.query, chatClientConfig: client.config)
-        let observer = self.environment.createChannelListDatabaseObserver(
+        let observer = environment.createChannelListDatabaseObserver(
             client.databaseContainer,
             request,
             { try $0.asModel() },
@@ -101,7 +104,7 @@ public class ChatChannelListController: DataController, DelegateCallable, DataSt
             }
         }
         return observer
-    }()
+    }
 
     var _basePublishers: Any?
     /// An internal backing object for all publicly available Combine publishers. We use it to simplify the way we expose
@@ -117,10 +120,18 @@ public class ChatChannelListController: DataController, DelegateCallable, DataSt
 
     private let filter: (@Sendable (ChatChannel) -> Bool)?
     private let environment: Environment
-    private lazy var channelListLinker: ChannelListLinker = self.environment
-        .channelListLinkerBuilder(
-            query, filter, client.config, client.databaseContainer, worker, client.channelWatcherHandler
+    private var channelListLinker: ChannelListLinker
+
+    private func makeChannelListLinker() -> ChannelListLinker {
+        environment.channelListLinkerBuilder(
+            query,
+            filter,
+            client.config,
+            client.databaseContainer,
+            worker,
+            client.channelWatcherHandler
         )
+    }
 
     /// Creates a new `ChannelListController`.
     ///
@@ -139,21 +150,28 @@ public class ChatChannelListController: DataController, DelegateCallable, DataSt
         self.filter = filter
         self.environment = environment
         self.deliveryCriteriaValidator = environment.deliveryCriteriaValidatorBuilder()
+        let worker = environment.channelQueryUpdaterBuilder(client.databaseContainer, client.apiClient)
+        self.worker = worker
+        channelListLinker = environment.channelListLinkerBuilder(
+            query,
+            filter,
+            client.config,
+            client.databaseContainer,
+            worker,
+            client.channelWatcherHandler
+        )
         super.init()
     }
 
     override public func synchronize(_ completion: (@MainActor (_ error: Error?) -> Void)? = nil) {
         startChannelListObserverIfNeeded()
         channelListLinker.start(with: client.eventNotificationCenter)
         client.syncRepository.startTrackingChannelListController(self)
-        updateChannelList { [weak self] error in
-            guard let completion else { return }
-            self?.callback {
-                completion(error)
-            }
+        updateChannelList { result in
+            self.callback { completion?(result.error) }
         }
     }
-
+    
     // MARK: - Actions
 
     /// Loads next channels from backend.
@@ -179,9 +197,13 @@ public class ChatChannelListController: DataController, DelegateCallable, DataSt
         updatedQuery.pagination = Pagination(pageSize: limit, offset: channels.count)
         worker.update(channelListQuery: updatedQuery) { result in
             switch result {
-            case let .success(channels):
-                self.markChannelsAsDeliveredIfNeeded(channels: channels)
-                self.hasLoadedAllPreviousChannels = channels.count < limit
+            case let .success(updateResult):
+                self.markChannelsAsDeliveredIfNeeded(channels: updateResult.channels)
+                self.hasLoadedAllPreviousChannels = updateResult.channels.count < limit
+                if let updatedQuery = updateResult.updatedQuery {
+                    self.query = updatedQuery
+                    self.updateChannelListObserver()
+                }
                 self.callback { completion?(nil) }
             case let .failure(error):
                 self.callback { completion?(error) }
@@ -199,28 +221,34 @@ public class ChatChannelListController: DataController, DelegateCallable, DataSt
     // MARK: - Helpers
 
     private func updateChannelList(
-        _ completion: (@MainActor (_ error: Error?) -> Void)? = nil
+        _ completion: (@MainActor (Result<ChannelListUpdateResult, Error>) -> Void)? = nil
     ) {
         let limit = query.pagination.pageSize
         worker.update(
             channelListQuery: query
         ) { [weak self] result in
             switch result {
-            case let .success(channels):
+            case let .success(updateResult):
                 self?.state = .remoteDataFetched
-                self?.hasLoadedAllPreviousChannels = channels.count < limit
-                
+                self?.hasLoadedAllPreviousChannels = updateResult.channels.count < limit
+
                 // Mark channels as delivered if synchronization was successful
-                self?.markChannelsAsDeliveredIfNeeded(channels: channels)
+                self?.markChannelsAsDeliveredIfNeeded(channels: updateResult.channels)
+
+                // Predefined filters can update local query representation (query gets backend defined filter and sort which must be set to FRC)
+                if let updatedQuery = updateResult.updatedQuery {
+                    self?.query = updatedQuery
+                    self?.updateChannelListObserver()
+                }
 
-                self?.callback { completion?(nil) }
+                self?.callback { completion?(.success(updateResult)) }
             case let .failure(error):
                 self?.state = .remoteDataFetchFailed(ClientError(with: error))
-                self?.callback { completion?(error) }
+                self?.callback { completion?(.failure(error)) }
             }
         }
     }
-    
+
     /// Marks channels as delivered if they meet the specified criteria.
     /// - Parameter channels: The channels to evaluate for marking as delivered.
     private func markChannelsAsDeliveredIfNeeded(channels: [ChatChannel]) {
@@ -264,6 +292,18 @@ public class ChatChannelListController: DataController, DelegateCallable, DataSt
             log.error("Failed to perform fetch request with error: \(error). This is an internal error.")
         }
     }
+
+    private func updateChannelListObserver() {
+        channelListObserver = makeChannelListObserver()
+        channelListLinker = makeChannelListLinker()
+        channelListLinker.start(with: client.eventNotificationCenter)
+        do {
+            try channelListObserver.startObserving()
+        } catch {
+            state = .localDataFetchFailed(ClientError(with: error))
+            log.error("Failed to update the channel list observer: \(error)")
+        }
+    }
 }
 
 extension ChatChannelListController {

Sources/StreamChat/Database/DTOs/ChannelDTO.swift

@@ -234,7 +234,7 @@ extension NSManagedObjectContext {
         // the query won't be saved, which will cause any future
         // channels to not become linked to this query
         if let query = query {
-            _ = saveQuery(query: query)
+            _ = saveQuery(query: query, predefinedFilter: payload.predefinedFilter)
         }
 
         return payload.channels.compactMapLoggingError { channelPayload in
@@ -444,7 +444,7 @@ extension NSManagedObjectContext {
     }
 
     func delete(query: ChannelListQuery) {
-        guard let dto = channelListQuery(filterHash: query.filter.filterHash) else { return }
+        guard let dto = channelListQuery(query: query) else { return }
 
         delete(dto)
     }
@@ -477,7 +477,7 @@ extension ChannelDTO {
 
         request.sortDescriptors = sortDescriptors.isEmpty ? [ChannelListSortingKey.defaultSortDescriptor] : sortDescriptors
 
-        let matchingQuery = NSPredicate(format: "ANY queries.filterHash == %@", query.filter.filterHash)
+        let matchingQuery = NSPredicate(format: "ANY queries.filterHash == %@", query.queryHash)
         let notDeleted = NSPredicate(format: "deletedAt == nil")
 
         var subpredicates: [NSPredicate] = [