feat(llc, core): add support for filtering and sorting threads (#2235)

Author: xsahil03x

packages/stream_chat/CHANGELOG.md

@@ -3,6 +3,7 @@
 ✅ Added
 
 - Added teams role support for users.
+- Added support for Filtering and Sorting in the `client.queryThreads` method.
 
 ## 9.8.0
 

packages/stream_chat/lib/src/client/client.dart

@@ -30,6 +30,7 @@ import 'package:stream_chat/src/core/models/own_user.dart';
 import 'package:stream_chat/src/core/models/poll.dart';
 import 'package:stream_chat/src/core/models/poll_option.dart';
 import 'package:stream_chat/src/core/models/poll_vote.dart';
+import 'package:stream_chat/src/core/models/thread.dart';
 import 'package:stream_chat/src/core/models/user.dart';
 import 'package:stream_chat/src/core/util/utils.dart';
 import 'package:stream_chat/src/db/chat_persistence_client.dart';
@@ -1841,11 +1842,17 @@ class StreamChatClient {
       _chatApi.general.enrichUrl(url);
 
   /// Queries threads with the given [options] and [pagination] params.
+  ///
+  /// Optionally, pass [filter] and [sort] to filter and sort the threads.
   Future<QueryThreadsResponse> queryThreads({
+    Filter? filter,
+    SortOrder<Thread>? sort,
     ThreadOptions options = const ThreadOptions(),
     PaginationParams pagination = const PaginationParams(),
   }) =>
       _chatApi.threads.queryThreads(
+        filter: filter,
+        sort: sort,
         options: options,
         pagination: pagination,
       );

packages/stream_chat/lib/src/core/api/threads_api.dart

@@ -2,7 +2,10 @@ import 'dart:convert';
 
 import 'package:stream_chat/src/core/api/requests.dart';
 import 'package:stream_chat/src/core/api/responses.dart';
+import 'package:stream_chat/src/core/api/sort_order.dart';
 import 'package:stream_chat/src/core/http/stream_http_client.dart';
+import 'package:stream_chat/src/core/models/filter.dart';
+import 'package:stream_chat/src/core/models/thread.dart';
 
 /// Defines the api dedicated to threads operations
 class ThreadsApi {
@@ -13,12 +16,16 @@ class ThreadsApi {
 
   /// Queries threads with the given [options] and [pagination] params.
   Future<QueryThreadsResponse> queryThreads({
+    Filter? filter,
+    SortOrder<Thread>? sort,
     ThreadOptions options = const ThreadOptions(),
     PaginationParams pagination = const PaginationParams(),
   }) async {
     final response = await _client.post(
       '/threads',
       data: jsonEncode({
+        if (filter != null) 'filter': filter.toJson(),
+        if (sort != null) 'sort': sort.map((e) => e.toJson()).toList(),
         ...options.toJson(),
         ...pagination.toJson(),
       }),

packages/stream_chat/lib/src/core/models/thread.dart

@@ -1,6 +1,7 @@
 import 'package:equatable/equatable.dart';
 import 'package:json_annotation/json_annotation.dart';
 import 'package:stream_chat/src/core/models/channel_model.dart';
+import 'package:stream_chat/src/core/models/comparable_field.dart';
 import 'package:stream_chat/src/core/models/draft.dart';
 import 'package:stream_chat/src/core/models/message.dart';
 import 'package:stream_chat/src/core/models/read.dart';
@@ -21,7 +22,7 @@ const _nullConst = _NullConst();
 /// to a message in a channel.
 /// {@endtemplate}
 @JsonSerializable()
-class Thread extends Equatable {
+class Thread extends Equatable implements ComparableFieldProvider {
   /// {@macro streamThread}
   Thread({
     this.activeParticipantCount,
@@ -227,4 +228,53 @@ class Thread extends Equatable {
         read,
         draft,
       ];
+
+  @override
+  ComparableField? getComparableField(String sortKey) {
+    final value = switch (sortKey) {
+      ThreadSortKey.lastMessageAt => lastMessageAt,
+      ThreadSortKey.createdAt => createdAt,
+      ThreadSortKey.updatedAt => updatedAt,
+      ThreadSortKey.replyCount => replyCount,
+      ThreadSortKey.participantCount => participantCount,
+      ThreadSortKey.activeParticipantCount => activeParticipantCount,
+      ThreadSortKey.parentMessageId => parentMessageId,
+      // TODO: Support providing default value for hasUnread
+      ThreadSortKey.hasUnread => null,
+      _ => null,
+    };
+
+    return ComparableField.fromValue(value);
+  }
+}
+
+/// Extension type representing sortable fields for [Thread].
+///
+/// This type provides type-safe keys that can be used for sorting threads
+/// in queries. Each constant represents a field that can be sorted on.
+extension type const ThreadSortKey(String key) implements String {
+  /// Sort threads by their last message date.
+  static const lastMessageAt = ThreadSortKey('last_message_at');
+
+  /// Sort threads by their creation date.
+  static const createdAt = ThreadSortKey('created_at');
+
+  /// Sort threads by their last update date.
+  static const updatedAt = ThreadSortKey('updated_at');
+
+  /// Sort threads by their reply count.
+  static const replyCount = ThreadSortKey('reply_count');
+
+  /// Sort threads by their participant count.
+  static const participantCount = ThreadSortKey('participant_count');
+
+  /// Sort threads by their active participant count.
+  static const activeParticipantCount =
+      ThreadSortKey('active_participant_count');
+
+  /// Sort threads by their parent message id.
+  static const parentMessageId = ThreadSortKey('parent_message_id');
+
+  /// Sort threads by their has unread.
+  static const hasUnread = ThreadSortKey('has_unread');
 }

packages/stream_chat_flutter_core/CHANGELOG.md

@@ -3,6 +3,7 @@
 ✅ Added
 
 - Added `StreamDraftListController` to manage the list of draft messages.
+- Added support for Filtering and Sorting in the `StreamThreadListController`.
 
 ## 9.8.0
 

packages/stream_chat_flutter_core/lib/src/stream_member_list_controller.dart

@@ -81,12 +81,18 @@ class StreamMemberListController extends PagedValueNotifier<int, Member> {
   ///
   /// Use this if you need to support runtime filter changes,
   /// through custom filters UI.
+  ///
+  /// Note: This will not trigger a new query. make sure to call
+  /// [doInitialLoad] after setting a new filter.
   set filter(Filter? value) => _activeFilter = value;
 
   /// Allows for the change of the query sort used for member queries.
   ///
   /// Use this if you need to support runtime sort changes,
   /// through custom sort UI.
+  ///
+  /// Note: This will not trigger a new query. make sure to call
+  /// [doInitialLoad] after setting a new sort.
   set sort(SortOrder<Member>? value) => _activeSort = value;
 
   @override

packages/stream_chat_flutter_core/lib/src/stream_message_search_list_controller.dart

@@ -112,24 +112,36 @@ class StreamMessageSearchListController
   ///
   /// Use this if you need to support runtime filter changes,
   /// through custom filters UI.
+  ///
+  /// Note: This will not trigger a new query. make sure to call
+  /// [doInitialLoad] after setting a new filter.
   set filter(Filter value) => _activeFilter = value;
 
   /// Allows for the change of message filters used for user queries.
   ///
   /// Use this if you need to support runtime filter changes,
   /// through custom filters UI.
+  ///
+  /// Note: This will not trigger a new query. make sure to call
+  /// [doInitialLoad] after setting a new filter.
   set messageFilter(Filter? value) => _activeMessageFilter = value;
 
   /// Allows for the change of filters used for user queries.
   ///
   /// Use this if you need to support runtime filter changes,
   /// through custom filters UI.
+  ///
+  /// Note: This will not trigger a new query. make sure to call
+  /// [doInitialLoad] after setting a new filter.
   set searchQuery(String? value) => _activeSearchQuery = value;
 
   /// Allows for the change of the query sort used for user queries.
   ///
   /// Use this if you need to support runtime sort changes,
   /// through custom sort UI.
+  ///
+  /// Note: This will not trigger a new query. make sure to call
+  /// [doInitialLoad] after setting a new sort.
   set sort(SortOrder? value) => _activeSort = value;
 
   @override

packages/stream_chat_flutter_core/lib/src/stream_poll_vote_list_controller.dart

@@ -90,12 +90,18 @@ class StreamPollVoteListController
   ///
   /// Use this if you need to support runtime filter changes,
   /// through custom filters UI.
+  ///
+  /// Note: This will not trigger a new query. make sure to call
+  /// [doInitialLoad] after setting a new filter.
   set filter(Filter? value) => _activeFilter = value;
 
   /// Allows for the change of the query sort used for poll vote queries.
   ///
   /// Use this if you need to support runtime sort changes,
   /// through custom sort UI.
+  ///
+  /// Note: This will not trigger a new query. make sure to call
+  /// [doInitialLoad] after setting a new sort.
   set sort(SortOrder<PollVote>? value) => _activeSort = value;
 
   @override

packages/stream_chat_flutter_core/lib/src/stream_thread_list_controller.dart

@@ -25,9 +25,13 @@ class StreamThreadListController extends PagedValueNotifier<String, Thread> {
   StreamThreadListController({
     required this.client,
     StreamThreadListEventHandler? eventHandler,
+    this.filter,
+    this.sort,
     this.options = const ThreadOptions(),
     this.limit = defaultThreadsPagedLimit,
-  })  : _activeOptions = options,
+  })  : _activeFilter = filter,
+        _activeSort = sort,
+        _activeOptions = options,
         _eventHandler = eventHandler ?? StreamThreadListEventHandler(),
         super(const PagedValue.loading());
 
@@ -36,9 +40,13 @@ class StreamThreadListController extends PagedValueNotifier<String, Thread> {
     super.value, {
     required this.client,
     StreamThreadListEventHandler? eventHandler,
+    this.filter,
+    this.sort,
     this.options = const ThreadOptions(),
     this.limit = defaultThreadsPagedLimit,
-  })  : _activeOptions = options,
+  })  : _activeFilter = filter,
+        _activeSort = sort,
+        _activeOptions = options,
         _eventHandler = eventHandler ?? StreamThreadListEventHandler();
 
   /// The Stream client used to perform the queries.
@@ -47,6 +55,21 @@ class StreamThreadListController extends PagedValueNotifier<String, Thread> {
   /// The thread event handlers to use for the thread list.
   final StreamThreadListEventHandler _eventHandler;
 
+  /// The query filters to use.
+  ///
+  /// You can query on any of the custom fields you've defined on the [Thread].
+  final Filter? filter;
+  Filter? _activeFilter;
+
+  /// The sorting used for the threads matching the filters.
+  ///
+  /// Sorting is based on field and direction, multiple sorting options
+  /// can be provided.
+  ///
+  /// Direction can be ascending or descending.
+  final SortOrder<Thread>? sort;
+  SortOrder<Thread>? _activeSort;
+
   /// The limit to apply to the thread list.
   ///
   /// The default is set to [defaultUserPagedLimit].
@@ -58,10 +81,31 @@ class StreamThreadListController extends PagedValueNotifier<String, Thread> {
   final ThreadOptions options;
   ThreadOptions _activeOptions;
 
+  /// Allows for the change of filters used for thread queries.
+  ///
+  /// Use this if you need to support runtime filter changes,
+  /// through custom filters UI.
+  ///
+  /// Note: This will not trigger a new query. make sure to call
+  /// [doInitialLoad] after setting a new filter.
+  set filter(Filter? value) => _activeFilter = value;
+
+  /// Allows for the change of the query sort used for thread queries.
+  ///
+  /// Use this if you need to support runtime sort changes,
+  /// through custom sort UI.
+  ///
+  /// Note: This will not trigger a new query. make sure to call
+  /// [doInitialLoad] after setting a new sort.
+  set sort(SortOrder<Thread>? value) => _activeSort = value;
+
   /// Allows for the change of the [options] at runtime.
   ///
   /// Use this if you need to support runtime option changes,
   /// through custom filters UI.
+  ///
+  /// Note: This will not trigger a new query. make sure to call
+  /// [doInitialLoad] after setting a new option.
   set options(ThreadOptions options) => _activeOptions = options;
 
   /// The ids of the threads that have unseen messages.
@@ -80,6 +124,19 @@ class StreamThreadListController extends PagedValueNotifier<String, Thread> {
   /// Clears the set of unseen thread IDs.
   void clearUnseenThreadIds() => _unseenThreadIds.value = const {};
 
+  @override
+  set value(PagedValue<String, Thread> newValue) {
+    super.value = switch (_activeSort) {
+      null => newValue,
+      final threadSort => newValue.maybeMap(
+          orElse: () => newValue,
+          (success) => success.copyWith(
+            items: success.items.sorted(threadSort.compare),
+          ),
+        ),
+    };
+  }
+
   @override
   Future<void> doInitialLoad() async {
     final limit = min(
@@ -88,6 +145,8 @@ class StreamThreadListController extends PagedValueNotifier<String, Thread> {
     );
     try {
       final response = await client.queryThreads(
+        filter: _activeFilter,
+        sort: _activeSort,
         options: _activeOptions,
         pagination: PaginationParams(limit: limit),
       );
@@ -114,6 +173,8 @@ class StreamThreadListController extends PagedValueNotifier<String, Thread> {
 
     try {
       final response = await client.queryThreads(
+        filter: _activeFilter,
+        sort: _activeSort,
         options: _activeOptions,
         pagination: PaginationParams(limit: limit, next: nextPageKey),
       );

packages/stream_chat_flutter_core/lib/src/stream_user_list_controller.dart

@@ -86,12 +86,18 @@ class StreamUserListController extends PagedValueNotifier<int, User> {
   ///
   /// Use this if you need to support runtime filter changes,
   /// through custom filters UI.
+  ///
+  /// Note: This will not trigger a new query. make sure to call
+  /// [doInitialLoad] after setting a new filter.
   set filter(Filter? value) => _activeFilter = value;
 
   /// Allows for the change of the query sort used for user queries.
   ///
   /// Use this if you need to support runtime sort changes,
   /// through custom sort UI.
+  ///
+  /// Note: This will not trigger a new query. make sure to call
+  /// [doInitialLoad] after setting a new sort.
   set sort(SortOrder<User>? value) => _activeSort = value;
 
   @override