Support predefined filters in ChannelListQuery

.github/workflows/smoke-checks.yml

@@ -71,6 +71,7 @@ jobs:
       - run: bundle exec fastlane rubocop
       - run: bundle exec fastlane run_swift_format strict:true
       - run: bundle exec fastlane validate_public_interface
+      - run: bundle exec fastlane validate_generated_code
 
   build-old-xcode:
     name: Build SDKs (Old Xcode)

.swiftlint.yml

@@ -1,5 +1,6 @@
 excluded:
   - Scripts
+  - Sources/StreamChat/Generated
   - Sources/StreamChatCommonUI/Generated
   - Sources/StreamChatUI/StreamSwiftyGif
   - Sources/StreamChatUI/StreamNuke

CHANGELOG.md

@@ -3,7 +3,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 # Upcoming
 
-### 🔄 Changed
+## 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)
 
 # [5.4.0](https://github.com/GetStream/stream-chat-swift/releases/tag/5.4.0)
 _May 28, 2026_

DemoApp/StreamChat/Components/DemoChatChannelListVC.swift

@@ -110,6 +110,22 @@ 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 predefinedArchivedHiddenChannelsQuery: ChannelListQuery = .init(
+        predefinedFilter: "user_per_channel_type_archived_hidden",
+        filterValues: [
+            "channel_type": .string(ChannelType.messaging.rawValue),
+            "hidden": .bool(false),
+            "user_id": .string(currentUserId),
+            "archived": .bool(false)
+        ],
+        sortValues: nil
+    )
     lazy var livestreamChannelsQuery: ChannelListQuery = .init(filter: .equal(.type, to: .livestream))
 
     var demoRouter: DemoChatChannelListRouter? {
@@ -270,6 +286,23 @@ final class DemoChatChannelListVC: ChatChannelListVC {
             }
         )
 
+        let predefinedMessagingChannelsAction = UIAlertAction(
+            title: "Predefined: messaging",
+            style: .default,
+            handler: { [weak self] _ in
+                self?.title = "Predefined: messaging"
+                self?.setPredefinedMessagingChannelsQuery()
+            }
+        )
+
+        let predefinedArchivedHiddenChannelsAction = UIAlertAction(
+            title: "Predefined: not archived and hidden",
+            style: .default,
+            handler: { [weak self] _ in
+                self?.title = "Predefined: not archived and hidden"
+                self?.setPredefinedArchivedHiddenChannelsQuery()
+            }
+        )
         let livestreamChannelsAction = UIAlertAction(
             title: "Livestream Channels",
             style: .default
@@ -294,6 +327,8 @@ final class DemoChatChannelListVC: ChatChannelListVC {
                 equalMembersAction,
                 channelRoleChannelsAction,
                 taggedChannelsAction,
+                predefinedMessagingChannelsAction,
+                predefinedArchivedHiddenChannelsAction,
                 livestreamChannelsAction
             ].sorted(by: { $0.title ?? "" < $1.title ?? "" }),
             preferredStyle: .actionSheet,
@@ -355,6 +390,14 @@ final class DemoChatChannelListVC: ChatChannelListVC {
         replaceQuery(premiumTaggedChannelsQuery)
     }
 
+    func setPredefinedMessagingChannelsQuery() {
+        replaceQuery(predefinedMessagingChannelsQuery)
+    }
+
+    func setPredefinedArchivedHiddenChannelsQuery() {
+        replaceQuery(predefinedArchivedHiddenChannelsQuery)
+    }
+
     func setLivestreamChannelsQuery() {
         replaceQuery(livestreamChannelsQuery)
     }

Githubfile

@@ -10,3 +10,4 @@ export INTERFACE_ANALYZER_VERSION='1.0.7'
 export SWIFT_LINT_VERSION='0.59.1'
 export SWIFT_FORMAT_VERSION='0.58.2'
 export SWIFT_GEN_VERSION='6.5.1'
+export SOURCERY_VERSION='2.3.0'

Makefile

@@ -3,6 +3,9 @@ MAKEFLAGS += --silent
 bootstrap:
 	./Scripts/bootstrap.sh
 
+generate:
+	sourcery --config Sources/StreamChat/.sourcery.yml
+
 update_dependencies:
 	echo "👉 Updating Nuke"
 	make update_nuke version=10.3.3

Package.swift

@@ -41,7 +41,7 @@ let package = Package(
             dependencies: [
                 .product(name: "StreamCore", package: "stream-core-swift")
             ],
-            exclude: ["Info.plist"],
+            exclude: ["Info.plist", "Generated/PredefinedFilter.stencil"],
             resources: [.copy("Database/StreamChatModel.xcdatamodeld")]
         ),
         .target(

Scripts/bootstrap.sh

@@ -57,6 +57,19 @@ if [ "${SKIP_SWIFT_BOOTSTRAP:-}" != true ]; then
   sudo sudo rm -f "$BIN_PATH"
   sudo sudo ln -s "$INSTALL_DIR/bin/swiftgen" "$BIN_PATH"
   swiftgen --version
+
+  puts "Install Sourcery v${SOURCERY_VERSION}"
+  DOWNLOAD_URL="https://github.com/krzysztofzablocki/Sourcery/releases/download/${SOURCERY_VERSION}/sourcery-${SOURCERY_VERSION}.zip"
+  DOWNLOAD_PATH="/tmp/sourcery-${SOURCERY_VERSION}.zip"
+  INSTALL_DIR="/usr/local/lib/sourcery"
+  BIN_PATH="/usr/local/bin/sourcery"
+  wget "$DOWNLOAD_URL" -O "$DOWNLOAD_PATH"
+  sudo rm -rf "$INSTALL_DIR"
+  sudo mkdir -p "$INSTALL_DIR"
+  sudo unzip -o "$DOWNLOAD_PATH" -d "$INSTALL_DIR"
+  sudo rm -f "$BIN_PATH"
+  sudo ln -s "$INSTALL_DIR/bin/sourcery" "$BIN_PATH"
+  sourcery --version
 fi
 
 if [[ ${INSTALL_SONAR-default} == true ]]; then

Sources/StreamChat/.sourcery.yml

@@ -0,0 +1,7 @@
+sources:
+  - ./Query/ChannelListQuery.swift
+  - ./Query/Sorting/ChannelListSortingKey.swift
+templates:
+  - ./Generated/PredefinedFilter.stencil
+output:
+  ./Generated/PredefinedFilter+Generated.swift

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
@@ -82,8 +82,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 +108,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
@@ -146,11 +153,8 @@ public class ChatChannelListController: DataController, DelegateCallable, DataSt
         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 { [weak self] result in
+            self?.callback { completion?(result.error) }
         }
     }
 
@@ -179,9 +183,9 @@ 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
                 self.callback { completion?(nil) }
             case let .failure(error):
                 self.callback { completion?(error) }
@@ -199,24 +203,30 @@ 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)) }
             }
         }
     }
@@ -264,6 +274,16 @@ 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()
+        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] = [