Feed DataSource Expert - Paged Lists & Infinite Scroll

What: Pattern for paginated, reactive list/feed widgets using ValueNotifiers and Commands. Integrates with proxy pattern for entity lifecycle management.

CRITICAL RULES

• Auto-pagination triggers at items.length - 3 (not at the last item)
• updateDataCommand for initial/refresh loads, requestNextPageCommand for pagination - separate commands
• When refreshing with proxies: release OLD proxies AFTER replacing with new ones (delay release for animations)
• itemCount is a ValueNotifier - watch it to rebuild the list widget
• Feed data sources are typically created with createOnce in widgets, NOT registered in get_it
• getItemAtIndex(index) both returns the item AND triggers auto-pagination

Base FeedDataSource

Non-paged feed for finite data sets:

dart
1abstract class FeedDataSource<TItem> {
2  FeedDataSource({List<TItem>? initialItems})
3      : items = initialItems ?? [];
4
5  final List<TItem> items;
6  final _itemCount = CustomValueNotifier<int>(0);
7  ValueListenable<int> get itemCount => _itemCount;
8  bool updateWasCalled = false;
9
10  late final updateDataCommand = Command.createAsyncNoParamNoResult(
11    () async {
12      await updateFeedData();
13      updateWasCalled = true;
14      refreshItemCount();
15    },
16    errorFilter: const LocalOnlyErrorFilter(),
17  );
18
19  ValueListenable<bool> get isFetchingNextPage => updateDataCommand.isRunning;
20  ValueListenable<CommandError?> get commandErrors => updateDataCommand.errors;
21
22  /// Subclasses implement - fetch data and populate items list
23  Future<void> updateFeedData();
24
25  /// Subclasses implement - compare items for deduplication
26  bool itemsAreEqual(TItem item1, TItem item2);
27
28  TItem getItemAtIndex(int index) {
29    assert(index >= 0 && index < items.length);
30    return items[index];
31  }
32
33  void refreshItemCount() {
34    _itemCount.value = items.length;
35  }
36
37  void addItemAtStart(TItem item) {
38    items.insert(0, item);
39    refreshItemCount();
40  }
41
42  void removeObject(TItem itemToRemove) {
43    items.removeWhere((item) => itemsAreEqual(item, itemToRemove));
44    refreshItemCount();
45  }
46
47  void reset() {
48    items.clear();
49    updateWasCalled = false;
50    refreshItemCount();
51  }
52
53  void dispose() {
54    _itemCount.dispose();
55  }
56}

PagedFeedDataSource

Extends FeedDataSource with cursor-based pagination:

dart
1abstract class PagedFeedDataSource<TItem> extends FeedDataSource<TItem> {
2  String? nextPageUrl;
3  bool? datasetExpired;
4
5  bool get hasNextPage => nextPageUrl != null && datasetExpired != true;
6
7  late final requestNextPageCommand = Command.createAsyncNoParamNoResult(
8    () async {
9      await requestNextPage();
10      refreshItemCount();
11    },
12    errorFilter: const LocalOnlyErrorFilter(),
13  );
14
15  /// Subclasses implement - fetch next page and append to items
16  Future<void> requestNextPage();
17
18  /// Call after parsing API response to store next page URL
19  void extractNextPageParams(String? url) {
20    nextPageUrl = url;
21  }
22
23  /// Auto-pagination: triggers when scrolling near the end
24  @override
25  TItem getItemAtIndex(int index) {
26    if (index >= items.length - 3 &&
27        commandErrors.value == null &&
28        hasNextPage &&
29        !requestNextPageCommand.isRunning.value) {
30      requestNextPageCommand.run();
31    }
32    return super.getItemAtIndex(index);
33  }
34
35  // Merged loading/error state from both commands
36  late final ValueNotifier<bool> _isFetchingNextPage = ValueNotifier(false);
37  @override
38  ValueListenable<bool> get isFetchingNextPage => _isFetchingNextPage;
39
40  // Listen to both commands and merge their isRunning states
41  // _isFetchingNextPage.value = updateDataCommand.isRunning.value ||
42  //                              requestNextPageCommand.isRunning.value;
43
44  @override
45  void reset() {
46    nextPageUrl = null;
47    datasetExpired = null;
48    super.reset();
49  }
50}

Concrete Implementation with Proxies

dart
1class PostsFeedSource extends PagedFeedDataSource<PostProxy> {
2  PostsFeedSource(this.feedType);
3  final PostFeedType feedType;
4
5  @override
6  bool itemsAreEqual(PostProxy a, PostProxy b) => a.id == b.id;
7
8  @override
9  Future<void> updateFeedData() async {
10    final api = PostApi(di<ApiClient>());
11    final response = await api.getPosts(type: feedType);
12    if (response == null) return;
13
14    // Release old proxies (delay for exit animations)
15    final oldItems = List<PostProxy>.from(items);
16    items.clear();
17
18    // Create new proxies via manager (increments ref count)
19    final proxies = di<PostsManager>().createProxies(response.data);
20    items.addAll(proxies);
21    extractNextPageParams(response.links?.next);
22
23    // Release old proxies after animations complete
24    Future.delayed(const Duration(milliseconds: 1000), () {
25      di<PostsManager>().releaseProxies(oldItems);
26    });
27  }
28
29  @override
30  Future<void> requestNextPage() async {
31    if (nextPageUrl == null) return;
32    final response = await callNextPageWithUrl<PostListResponse>(nextPageUrl!);
33    if (response == null) return;
34
35    final proxies = di<PostsManager>().createProxies(response.data);
36    items.addAll(proxies);
37    extractNextPageParams(response.links?.next);
38  }
39
40  // Override to manage reference counting on individual operations
41  @override
42  void addItemAtStart(PostProxy item) {
43    item.incrementReferenceCount();
44    super.addItemAtStart(item);
45  }
46
47  @override
48  void removeObject(PostProxy item) {
49    super.removeObject(item);
50    di<PostsManager>().releaseProxy(item);
51  }
52}

Feed Widget

dart
1class FeedView<TItem> extends WatchingWidget {
2  const FeedView({
3    required this.feedSource,
4    required this.itemBuilder,
5    this.emptyListWidget,
6  });
7
8  final FeedDataSource<TItem> feedSource;
9  final Widget Function(BuildContext, TItem) itemBuilder;
10  final Widget? emptyListWidget;
11
12  @override
13  Widget build(BuildContext context) {
14    final itemCount = watch(feedSource.itemCount).value;
15    final isFetching = watch(feedSource.isFetchingNextPage).value;
16
17    // Trigger initial load
18    callOnce((_) => feedSource.updateDataCommand.run());
19
20    // Error handler
21    registerHandler(
22      target: feedSource.commandErrors,
23      handler: (context, error, _) {
24        showErrorSnackbar(context, error.error);
25      },
26    );
27
28    // Error state with retry
29    if (feedSource.commandErrors.value != null && itemCount == 0) {
30      return ErrorWidget(
31        onRetry: () => feedSource.updateDataCommand.run(),
32      );
33    }
34
35    // Initial loading
36    if (!feedSource.updateWasCalled && isFetching) {
37      return Center(child: CircularProgressIndicator());
38    }
39
40    // Empty state
41    if (itemCount == 0 && feedSource.updateWasCalled) {
42      return emptyListWidget ?? Text('No items');
43    }
44
45    // List with pull-to-refresh
46    return RefreshIndicator(
47      onRefresh: () => feedSource.updateDataCommand.runAsync(),
48      child: ListView.builder(
49        itemCount: itemCount + (isFetching ? 1 : 0),
50        itemBuilder: (context, index) {
51          if (index >= itemCount) {
52            return Center(child: CircularProgressIndicator());
53          }
54          // getItemAtIndex auto-triggers pagination near end
55          final item = feedSource.getItemAtIndex(index);
56          return itemBuilder(context, item);
57        },
58      ),
59    );
60  }
61}

Creation Pattern

dart
1// Create with createOnce in the widget that owns the feed
2class PostsFeedPage extends WatchingWidget {
3  @override
4  Widget build(BuildContext context) {
5    final feedSource = createOnce(
6      () => PostsFeedSource(PostFeedType.latest),
7      dispose: (source) => source.dispose(),
8    );
9
10    return FeedView<PostProxy>(
11      feedSource: feedSource,
12      itemBuilder: (context, post) => PostCard(post: post),
13      emptyListWidget: Text('No posts yet'),
14    );
15  }
16}

Filtered Feeds

Same data, different views via filter functions:

dart
1class ChatsListSource extends PagedFeedDataSource<ChatProxy> {
2  ChatFilterType _filter = ChatFilterType.ALL;
3  String _query = '';
4
5  void setTypeFilter(ChatFilterType filter) {
6    _filter = filter;
7    updateDataCommand.run();  // Re-fetch with new filter
8  }
9
10  void setSearchQuery(String query) {
11    _query = query;
12    updateDataCommand.run();
13  }
14}

Event Bus Integration

Feeds can react to events from other parts of the app:

dart
1// In FeedDataSource constructor
2di<EventBus>().on<FeedEvent>().listen((event) {
3  if (event.feedsToApply.contains(feedId)) {
4    switch (event.action) {
5      case FeedEventActions.update:
6        updateDataCommand.run();
7      case FeedEventActions.addItem:
8        addItemAtStart(event.data as TItem);
9      case FeedEventActions.removeItem:
10        removeObject(event.data as TItem);
11    }
12  }
13});
14
15// Trigger from anywhere in the app
16di<EventBus>().fire(FeedEvent(
17  action: FeedEventActions.addItem,
18  data: newPostProxy,
19  feedsToApply: [FeedIds.latestPostsFeed, FeedIds.followingPostsFeed],
20));

Anti-Patterns

dart
1// ❌ Releasing proxies immediately on refresh (breaks exit animations)
2items.clear();
3di<Manager>().releaseProxies(oldItems);  // Widgets still animating!
4items.addAll(newProxies);
5
6// ✅ Delay release for animations
7final oldItems = List.from(items);
8items.clear();
9items.addAll(newProxies);
10Future.delayed(Duration(milliseconds: 1000), () {
11  di<Manager>().releaseProxies(oldItems);
12});
13
14// ❌ Registering feed in get_it as singleton
15di.registerSingleton<PostsFeed>(PostsFeedSource());
16// ✅ Create with createOnce in the widget that owns it
17final feed = createOnce(() => PostsFeedSource());
18
19// ❌ Manually checking scroll position for pagination
20scrollController.addListener(() {
21  if (scrollController.position.pixels >= ...) loadMore();
22});
23// ✅ Auto-pagination via getItemAtIndex triggers at length - 3
24
25// ❌ Single command for both initial load and pagination
26// ✅ Separate commands: updateDataCommand + requestNextPageCommand
27//    Allows independent loading/error states and restrictions