fix(llc): update watcher count and watchers from realtime events

[VelikovPetar]

Submit a pull request

Linear: FLU-619

Github Issue: #

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

ChannelClientState.watcherCount and ChannelClientState.watchers never reflected realtime events during a session:

• The server's watcher_count on user.watching.start / user.watching.stop / message.new was dropped into Event.extraData, so the count stayed frozen at the last full channel.watch() / queryChannels snapshot.
• Watchers were never removed from watchers on user.watching.stop — the additive keyed merge in updateChannelState (needed for watcher pagination) can only upsert, so the departing watcher lingered until the next full query.

iOS and Android already trust the server-provided watcher_count per event, so Flutter was the outlier.

Changes

• Add Event.watcherCount, mapping the server watcher_count field (promoted to a first-class field instead of extraData).
• Apply the count on user.watching.start, user.watching.stop, and message.new.
• Remove the departing watcher from ChannelClientState.watchers on user.watching.stop (assign state directly, bypassing the additive merge).

notification.message_new / notification.thread_message_new are intentionally excluded: the backend fetches the watcher count (via GetChannelWatchersCount) only after the notification fan-out in PostMessageInsert, so these events structurally carry watcher_count: 0.

Tests

• New Watching Events test group in channel_test.dart: start/stop update the count, stop removes the watcher, a null count preserves the existing value, message.new updates the count, and notification.message_new does not overwrite it.
• melos run format + melos run analyze clean; watching-event tests pass.

Screenshots / Videos

No UI changes.

Summary by CodeRabbit

• New Features

  • Added watcher counts to channel events, including watching and new-message events.
  • Watcher counts are now available through event data and remain synchronized with channel activity.

• Bug Fixes

  • Fixed stale watcher counts during active sessions.
  • Fixed watcher lists so users are removed when they stop watching.
  • Prevented unreliable notifications from overwriting accurate watcher counts.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 8bf37abc-06a3-4e14-b681-af3728dd2067

📥 Commits

Reviewing files that changed from the base of the PR and between 577aeee and 9e53ae2.

📒 Files selected for processing (5)

• packages/stream_chat/CHANGELOG.md
• packages/stream_chat/lib/src/client/channel.dart
• packages/stream_chat/lib/src/core/models/event.dart
• packages/stream_chat/lib/src/core/models/event.g.dart
• packages/stream_chat/test/src/client/channel_test.dart

---

📝 Walkthrough

Walkthrough

Changes

Watcher count synchronization

Layer / File(s)	Summary
Event watcher count contract packages/stream_chat/lib/src/core/models/event.dart, packages/stream_chat/lib/src/core/models/event.g.dart	Adds nullable Event.watcherCount, supports copyWith, and maps it to and from watcher_count.
Channel watcher state updates packages/stream_chat/lib/src/client/channel.dart	Synchronizes watcher counts, removes stopped watchers, and ignores unreliable notification counts.
Watcher event validation and changelog packages/stream_chat/test/src/client/channel_test.dart, packages/stream_chat/CHANGELOG.md	Adds coverage for watcher and message events and documents the changes.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Suggested reviewers: xsahil03x, renefloor

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: syncing watcher count and watcher list from realtime events.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch bug/FLU-619_watcher-count-realtime-events

---

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.}

[xsahil03x]

Any particular reason to not use updateChannelState here?

[VelikovPetar]

The problem is that updateChannelState does a "merge" operation over the watchers:

final watchers = _channelState.watchers ?? const <User>[];
final newWatchers = watchers.merge(
      updatedState.watchers,
      key: (watcher) => watcher.id,
);

So basically, if the initial watcher state is: ["a", "b", "c"]
And we receive a user.stop.watching for c, we would merge ["a", "b"] into ["a", "b", "c"] which wouldn't actually update the state.

We could introduce some new flags to the updateChannelState method to handle such scenarios, but I think that it would make things more complicated.

Let me know what do you think!

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 71.53%. Comparing base (141dec2) to head (e4d924e).

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2837      +/-   ##
==========================================
+ Coverage   71.48%   71.53%   +0.05%     
==========================================
  Files         426      426              
  Lines       26892    26897       +5     
==========================================
+ Hits        19224    19242      +18     
+ Misses       7668     7655      -13     

☔ 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.