feat(llc, core, persistence): Add support for PredefinedFilters on QueryChannels(v9)

[VelikovPetar]

Submit a pull request

Linear: FLU-357

CLA

• I have signed the Stream CLA (required).
• The code changes follow best practices
• Code changes are tested (add some information if not applicable)

Description of the pull request

v9 back-port of #2709. Adds support for server-defined predefined filters on queryChannels across the LLC, persistence, and core layers.

A predefined filter is a named filter/sort preset that lives on the server. The client sends predefined_filter (plus optional filter_values / sort_values to interpolate placeholders) instead of an inline filter, and the server echoes back the materialized filter and sort it applied.

stream_chat (LLC)

• ChannelApi.queryChannels and StreamChatClient.queryChannels accept predefinedFilter, filterValues, sortValues.
• New StreamChatClient.queryChannelsWithResult returns a QueryChannelsResult exposing both the live channels and the server-resolved PredefinedFilter (name + materialized filter + sort).
• New PredefinedFilter model and predefined_filter field on QueryChannelsResponse.
• New ChatPersistenceClient.queryChannelStates and ChatPersistenceClient.saveChannelQueries as the unified read/write methods for channel-query persistence (both accept standard and predefined-filter parameters and internally dispatch). Default implementations route through the legacy methods so existing custom persistence clients keep compiling.
• Deprecated ChatPersistenceClient.getChannelStates and ChatPersistenceClient.updateChannelQueries in favor of the unified methods. The deprecated methods stay overridable so downstream subclasses keep working unchanged.

stream_chat_persistence

• New channel_query_metadata table that stores the server-resolved filter + sort keyed by the predefined-filter query hash, so offline reads reconstruct the exact resolved spec the server applied. Drift schema version bumped 29 → 30.
• New FilterConverter and ChannelStateSortOrderConverter Drift converters.
• StreamChatPersistenceClient overrides the new queryChannelStates / saveChannelQueries methods; ChannelQueryDao gains updateChannelQueriesByPredefinedFilter and getChannelsAndSpecByPredefinedFilter.

stream_chat_flutter_core

• StreamChannelListController accepts predefinedFilter, filterValues, sortValues. When set, they take precedence over filter / channelStateSort.
• The controller tracks a _resolvedChannelStateSort that is overwritten with the server-resolved sort on every successful query, so event-driven inserts keep matching the server's ordering even when the caller only specifies a predefinedFilter.

Sample app

• ChannelList now uses the stream_chat_flutter_sample_app_v9 predefined filter (interpolated with the current user_id) to demonstrate the flow end-to-end.

How to test

• Run the sample app and confirm the channel list renders, paginates, and reacts to events as before.
• Toggle offline (airplane mode) after an online query and reopen — channels for the predefined-filter query should be served from persistence, ordered using the server-resolved sort.

Test coverage

• predefined_filter_test.dart — model + effectiveSort fallback selection.
• client_test.dart — online/offline queryChannels paths and queryChannelsWithResult. Existing getChannelStates / updateChannelQueries verifications updated to target the new queryChannelStates / saveChannelQueries methods.
• channel_api_test.dart — request payload assertions for predefined_filter / filter_values / sort_values.
• filter_converter_test.dart / sort_order_converter_test.dart — Drift converters.
• channel_query_dao_test.dart — DAO read/write of cids + metadata.
• stream_chat_persistence_client_test.dart — persistence client integration for both standard and predefined-filter modes of queryChannelStates / saveChannelQueries.
• stream_channel_list_controller_test.dart — controller path including resolved-sort tracking.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b9b25e70-848b-41dc-902b-d4f6b846405a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/FLU-357_predefined_filters_v9

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

⚠️ Database Entity Files Modified

The following database entity files have been modified in this PR:

packages/stream_chat_persistence/lib/src/entity/channel_queries_metadata.dart
packages/stream_chat_persistence/lib/src/entity/entity.dart

📝 Remember to:

1. ✅ Database schema version bumped to 30.
2. Update entity schema tests if necessary.

Note: This comment is automatically generated by the CI workflow.

[codecov]

Codecov Report

❌ Patch coverage is 91.76471% with 14 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (v9@fa471c5). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
...tream_chat/lib/src/db/chat_persistence_client.dart	0.00%	6 Missing ⚠️
...r_core/lib/src/stream_channel_list_controller.dart	80.95%	4 Missing ⚠️
packages/stream_chat/lib/src/client/client.dart	94.28%	2 Missing ⚠️
...hat_persistence/lib/src/dao/channel_query_dao.dart	97.82%	1 Missing ⚠️
...stence/lib/src/stream_chat_persistence_client.dart	95.00%	1 Missing ⚠️

Additional details and impacted files

@@          Coverage Diff          @@
##             v9    #2775   +/-   ##
=====================================
  Coverage      ?   66.30%           
=====================================
  Files         ?      429           
  Lines         ?    27096           
  Branches      ?        0           
=====================================
  Hits          ?    17965           
  Misses        ?     9131           
  Partials      ?        0           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.