feat(llc): add `onNewActivity` callback to Feed #65

xsahil03x · 2025-12-08T17:46:54Z

Submit a pull request

Description of the pull request

Introduces an onNewActivity callback to the Feed and feedFromQuery methods. This allows for custom logic to determine how new activities from real-time events are inserted into the activity list.

The callback returns an InsertionAction (addToStart, addToEnd, or ignore).

A default implementation is provided that adds activities from the current user to the start of the list if they match the query filter.

Important

Switch to pub dependency before merging the PR

Summary by CodeRabbit

New Features
- Added an onNewActivity callback to feed creation, letting you control whether new activities are inserted at start, end, or ignored.
- Added a convenience matches(filter) utility for simpler filter checks.
Breaking Changes
- Default activity insertion changed: activities from other users are ignored by default; only current-user activities matching feed filters are added automatically.
Tests
- Added tests covering default and custom onNewActivity behaviors.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Introduces an `onNewActivity` callback to the `Feed` and `feedFromQuery` methods. This allows for custom logic to determine how new activities from real-time events are inserted into the activity list. The callback returns an `InsertionAction` (`addToStart`, `addToEnd`, or `ignore`). A default implementation is provided that adds activities from the current user to the start of the list if they match the query filter.

…activities to the end

coderabbitai · 2025-12-08T17:47:09Z

Walkthrough

Adds an onNewActivity callback and InsertionAction enum to control how new activities from events are inserted (start, end, or ignored); updates Feed, FeedEventHandler, feed creation APIs to accept the callback; moves many event handlers into an event/handler/ subdirectory and updates imports; adds tests and sample usage.

Changes

Cohort / File(s)	Summary
Core insertion types & callback `packages/stream_feeds/lib/src/state/insertion_action.dart` `packages/stream_feeds/lib/src/state/event/on_activity_added.dart`	New `InsertionAction` enum (`ignore`, `addToEnd`, `addToStart`) and public typedef `OnNewActivity` plus `defaultOnNewActivity` implementation.
Feed API surface `packages/stream_feeds/lib/src/client/feeds_client_impl.dart` `packages/stream_feeds/lib/src/feeds_client.dart`	`feedFromQuery` / `feedFromId` / `feed` signatures extended with optional `onNewActivity` parameter and forwarded into Feed creation.
Feed & handler wiring `packages/stream_feeds/lib/src/state/feed.dart` `packages/stream_feeds/lib/src/state/event/handler/feed_event_handler.dart` `packages/stream_feeds/lib/src/state/feed_state.dart`	`Feed` now stores required `onNewActivity`; `FeedEventHandler` accepts and invokes `onNewActivity` to compute an `InsertionAction`; `FeedState.onActivityAdded` signature extended to accept `InsertionAction` and insert accordingly.
Event handler directory move & import updates `packages/stream_feeds/lib/src/state/event/handler/` `packages/stream_feeds/lib/src/state/.dart`	Many event handler files moved/ referenced under `event/handler/`; numerous relative import paths updated across state and handler files.
Utilities `packages/stream_feeds/lib/src/utils/filter.dart`	Added `MatchesExtensions<T>` with `matches(Filter<T>? filter)` to treat null filter as a match.
Public exports `packages/stream_feeds/lib/src/state.dart`	Export for `state/insertion_action.dart` added to public surface.
Tests & test utilities `packages/stream_feeds/test/state/feed_test.dart` `packages/stream_feeds/test/test_utils/fakes.dart`	New tests for onNewActivity insertion behaviors; test fakes updated to accept `userId` parameters.
Sample app `sample_app/lib/screens/user_feed/user_feed_screen.dart`	Stories feed now passes an `onNewActivity` callback returning `InsertionAction.addToEnd`.
Changelog `packages/stream_feeds/CHANGELOG.md`	Documents breaking change: default ActivityAddedEvent behavior changed and new `onNewActivity` API introduced.

Sequence Diagram

sequenceDiagram
    participant WS as WebSocket Event
    participant Handler as FeedEventHandler
    participant OnNew as onNewActivity Callback
    participant State as FeedState
    participant List as Activity List

    WS->>Handler: ActivityAddedEvent arrives
    Handler->>OnNew: onNewActivity(query, activity, currentUserId)
    OnNew->>OnNew: Evaluate ownership & query filter
    OnNew-->>Handler: InsertionAction (addToStart|addToEnd|ignore)

    alt insertionAction == ignore
        Handler->>Handler: Skip activity (no insertion)
    else insertionAction == addToStart
        Handler->>State: onActivityAdded(activity, insertionAction: addToStart)
        State->>List: Insert at index 0
    else insertionAction == addToEnd
        Handler->>State: onActivityAdded(activity, insertionAction: addToEnd)
        State->>List: Append to end
    end

    State-->>Handler: Activity processed / updated

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Areas to review carefully:
- FeedEventHandler: removal of previous query-filter short-circuit and new onNewActivity invocation.
- FeedState.onActivityAdded: insertion index computation and compatibility with existing callers.
- Import path changes across many files (event/handler/ relocation).
- Test suite changes validating insertion strategies and fakes updates.

Possibly related PRs

refactor(llc)!: unify comment data model and add tests #64 — Similar modifications to feed event handling and feed state insertion logic; likely relevant to design/compatibility.

Suggested reviewers

Brazol

Poem

🐰 I nibble code where new events play,

"To start or end — or hop away?"
With onNewActivity I pick the scene,
Insert with care, keep feeds serene. ✨

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main feature addition - adding an onNewActivity callback to the Feed API.
Description check	✅ Passed	The PR description covers the key aspects: callback purpose, return types, default implementation, and includes a note about pub dependency. However, it's missing CLA confirmation and testing instructions from the template.
Linked Issues check	✅ Passed	The implementation fully addresses FLU-348 objectives: introduces onNewActivity handler with InsertionAction enum (ignore/addToStart/addToEnd), provides default behavior for activities from current user matching filters, and uses an option-list API as requested.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing the onNewActivity feature. Import path reorganization (moving handlers to event/handler subdirectory) and related structural changes are necessary to support the new feature implementation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch feat/introduce-onNewActivity

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

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

coderabbitai

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

packages/stream_feeds/lib/src/feeds_client.dart (1)
800-834: OnNewActivity typedef and defaultOnNewActivity function are not exported in the public API.

The OnNewActivity typedef is used in the public feed() and feedFromId() method signatures in feeds_client.dart, but it's not exported through state.dart. The file state/on_activity_added.dart is missing from the export list in packages/stream_feeds/lib/src/state.dart. Additionally, defaultOnNewActivity is marked @internal and should not be part of the public API. Add the export to state.dart:
export 'state/on_activity_added.dart';

🧹 Nitpick comments (5)

packages/stream_feeds/lib/src/state/insertion_action.dart (1)

1-13: Consider adding barrel file annotation.

The enum is well-designed and clearly documented. However, since this is part of the public API (used by the OnNewActivity callback), consider marking it with @includeInBarrelFile annotation if it should be exported through the barrel file mechanism.

Based on coding guidelines, public APIs should be marked with @includeInBarrelFile annotation.

packages/stream_feeds/lib/src/utils/filter.dart (1)

9-15: Consider narrowing the extension scope.

While the extension is well-implemented with proper null-handling, extending all objects (T extends Object) is quite broad and could lead to API pollution. Consider whether this extension could be more narrowly scoped to specific types that actually need filter matching (e.g., ActivityData, CommentData) rather than all objects.

If the current generic approach is intentional for reusability, this is acceptable. However, more targeted extensions would be clearer and less intrusive to the global namespace.
packages/stream_feeds/lib/src/state/event/on_activity_added.dart (1)
8-71: OnNewActivity contract and default behavior align with requirements

The typedef and defaultOnNewActivity implement the intended “add-if-from-current-user-and-matching-filter” default, giving consumers full control via InsertionAction. As a tiny clean‑up, you could flatten the nested if without changing behavior:
-  if (activity.user.id == currentUserId) {
-    if (activity.matches(query.activityFilter)) {
-      return InsertionAction.addToStart;
-    }
-  }
-
-  return InsertionAction.ignore;
+  if (activity.user.id == currentUserId &&
+      activity.matches(query.activityFilter)) {
+    return InsertionAction.addToStart;
+  }
+
+  return InsertionAction.ignore;
packages/stream_feeds/lib/src/state/feed_state.dart (1)

23-27: onActivityAdded now cleanly supports configurable insertion

The InsertionAction parameter plus insertAt computation and early return on ignore give a simple, extensible way to control placement while preserving the old default. Using upsert(..., insertAt: (_) => insertAt) is a good fit to avoid duplicating list manipulation logic.

If this method is a primary extension point, consider expanding its doc comment to briefly describe how insertionAction influences ordering and how it relates to OnNewActivity, so future maintainers don’t have to chase the call chain.

Also applies to: 111-133

packages/stream_feeds/lib/src/state/event/handler/feed_event_handler.dart (1)

3-18: FeedEventHandler correctly delegates ActivityAdded behavior to OnNewActivity

Wiring onNewActivity into the constructor and using it exclusively for ActivityAddedEvent (while keeping matchesQueryFilter for other events) cleanly hands off insertion decisions to the callback and matches the new tests’ expectations. The sequence of:

compute InsertionAction,

call state.onActivityAdded(...),

optionally enrich via withUpdatedFeedCapabilities(...)
is straightforward and keeps capability updates orthogonal to insertion policy.

One nuance worth keeping in mind (and which your tests already model) is that custom onNewActivity implementations are now solely responsible for honoring query.activityFilter for added activities; the previous automatic filter check no longer runs for this branch.

Also applies to: 22-34, 48-58

codecov · 2025-12-10T12:37:16Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 59.52%. Comparing base (4bbd1dc) to head (f324079).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #65      +/-   ##
==========================================
- Coverage   59.60%   59.52%   -0.08%     
==========================================
  Files         120      121       +1     
  Lines        3758     3778      +20     
==========================================
+ Hits         2240     2249       +9     
- Misses       1518     1529      +11

☔ View full report in Codecov by Sentry.
📢 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.

coderabbitai

Actionable comments posted: 1

🧹 Nitpick comments (1)

packages/stream_feeds/test/state/feed_test.dart (1)

1827-1862: Consider adding a test for duplicate activity handling.

The test suite covers the happy paths well. Consider adding a test case that verifies behavior when an ActivityAddedEvent arrives for an activity ID that already exists in the list. This would confirm whether the implementation prevents duplicates or updates existing activities.

Would you like me to help draft a test case for the duplicate activity scenario?

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 07eae50 and f324079.

📒 Files selected for processing (1)

packages/stream_feeds/test/state/feed_test.dart (4 hunks)

🧰 Additional context used

📓 Path-based instructions (2)

**/*.dart

📄 CodeRabbit inference engine (.cursor/rules/cursor-rules-location.mdc)

**/*.dart: Use the barrel_files package with @includeInBarrelFile annotations for public API management in Dart projects; keep implementation details in lib/src/ without annotations
Mark only classes, functions, and enums intended for external package usage with @includeInBarrelFile; keep repository classes, mappers, and internal state objects in lib/src/ without annotations

**/*.dart: Use @freezed mixed mode for data classes in Dart
Return Result<T> from all repository methods in Dart
Apply early return patterns consistently in Dart code
Use pattern matching with switch expressions in Dart
Mark public APIs with @includeInBarrelFile annotation in Dart
Follow enhanced enum vs sealed class guidelines in Dart
Use const constructors where possible in Dart
Implement proper disposal patterns in Dart StateNotifiers and providers
Ensure pure Dart compatibility across VM, Flutter, and Web environments
Plan for StateNotifier reactive patterns when implementing state management in Dart

**/*.dart: Use @freezed for all data classes with required id fields and const constructors
Implement StateNotifier-based reactive state management with automatic change notifications
Apply Result pattern for all async operations with explicit error handling
Use early return patterns for clean control flow in Dart code
Create extension functions for data mapping using .toModel() pattern instead of mapper classes
Mark public APIs with @includeInBarrelFile annotation for barrel file export management
Implement proper resource management with disposal and cleanup patterns in Dart code
Use constructor injection for all dependencies in Dart classes

**/*.dart: All data models should use @freezed with Dart's mixed mode syntax and include @OverRide annotations on fields
Mark classes for public export using @includeInBarrelFile annotation
Use extension functions with .toModel() convention for data mapping instead of dedicated mapper classes
All repository methods must return Result...

Files:

packages/stream_feeds/test/state/feed_test.dart

packages/stream_feeds/test/**/*.dart

📄 CodeRabbit inference engine (AGENTS.md)

packages/stream_feeds/test/**/*.dart: Test through public APIs only, not internal StateNotifier implementations
Use HTTP interceptors instead of mocking repositories in tests
Mirror the lib/ structure in test/ directory organization

Files:

packages/stream_feeds/test/state/feed_test.dart

🧠 Learnings (15)

📓 Common learnings

Learnt from: CR
Repo: GetStream/stream-feeds-flutter PR: 0
File: .cursor/rules/stream-feeds-api.mdc:0-0
Timestamp: 2025-12-05T14:37:17.519Z
Learning: Applies to {**/api/**/*.dart,**/*_api.dart,**/client/*.dart} : Stream Feeds API integration should be implemented according to the Activity Streams specification with structured actor, verb, object, and target fields

Learnt from: CR
Repo: GetStream/stream-feeds-flutter PR: 0
File: .cursor/rules/stream-feeds-api.mdc:0-0
Timestamp: 2025-12-05T14:37:17.519Z
Learning: Applies to {**/api/**/*.dart,**/*_api.dart,**/client/*.dart} : Implement WebSocket event handlers for real-time Stream Feeds updates including activity events, reaction events, follow events, and member events

📚 Learning: 2025-12-05T14:37:17.519Z

Learnt from: CR
Repo: GetStream/stream-feeds-flutter PR: 0
File: .cursor/rules/stream-feeds-api.mdc:0-0
Timestamp: 2025-12-05T14:37:17.519Z
Learning: Applies to {**/api/**/*.dart,**/*_api.dart,**/client/*.dart} : Stream Feeds API integration should be implemented according to the Activity Streams specification with structured actor, verb, object, and target fields

Applied to files:

packages/stream_feeds/test/state/feed_test.dart