fetchNext method

Future<List<User>> fetchNext({
  1. required dynamic onSuccess(
    1. List<User> userList
    )?,
  2. required dynamic onError(
    1. CometChatException excep
    )?,
  3. UserFetchListener? listener,
})

Fetch a list of users based on the provided filters.

Android Reference: UsersRequest.fetchNext()

Implementation

Future<List<User>> fetchNext({
  required Function(List<User> userList)? onSuccess,
  required Function(CometChatException excep)? onError,
  UserFetchListener? listener,
}) async {
  try {
    if (limit <= 0) {
      final error = CometChatException(
        ErrorCode.errorNonPositiveLimit,
        'Limit must be a positive number',
        'Limit must be a positive number',
      );
      if (onError != null) onError(error);
      listener?.onError(error);
      return [];
    }

    if (limit > _maxLimit) {
      final error = CometChatException(
        ErrorCode.errorLimitExceeded,
        'Limit cannot exceed $_maxLimit',
        'Limit cannot exceed $_maxLimit',
      );
      if (onError != null) onError(error);
      listener?.onError(error);
      return [];
    }

    // Past the end of history a two-phase read with offline running still
    // asks the server: an empty answer ends the list, no answer is the
    // not-connected error (BEH-READ-05, BEH-READ-09a, R105). A legacy caller,
    // or any caller with offline off, keeps the empty page it always got
    // (BEH-AUTH-05).
    if ((listener == null || OfflineRuntime.instance.store == null) &&
        _nextPage > _totalPages &&
        _totalPages != -1) {
      if (onSuccess != null) onSuccess([]);
      listener?.onServerUsers(const []);
      return [];
    }

    // A concurrent fetch answers an empty success, settling the listener
    // too, so a listener-only caller is never left waiting (BEH-SNAP-14).
    if (_inProgress) {
      if (onSuccess != null) onSuccess([]);
      listener?.onServerUsers(const []);
      return [];
    }
    // Set before the cache phase: a fetch called while this one is in
    // flight fires no cache phase and leaves the replay index alone
    // (BEH-SNAP-14).
    _inProgress = true;

    // Phase 1 — replay a recorded page for this query. The signature is
    // computed from the request's FILTERS only, and the snapshot's replay
    // index is independent of `_nextPage`, so replaying never advances the
    // server cursor.
    if (listener != null) {
      final cached = await _snapshots.cachedPhase(User.fromMap);
      if (cached != null) listener.onCachedUsers(cached);
    }

    final sdk = SdkRegistry.getInstance();

    // Captured as the request goes out: a page answered after this
    // session ended is never written (BEH-SYNC-06).
    final issuedIn = OfflineRuntime.instance.readSession;
    final result = await sdk.users.getUsers(
      limit: limit,
      token: _token != 0 ? _token : null,
      page: _nextPage > 0 ? _nextPage : null,
      searchKeyword: searchKeyword,
      status: userStatus,
      hideBlockedUsers: hideBlockedUsers,
      roles: roles,
      friendsOnly: friendsOnly,
      tags: tags,
      withTags: withTags,
      uids: uids,
      searchInFields: searchIn,
      sortBy: sortBy,
      sortOrder: sortByOrder,
    );

    if (result.pagination != null) {
      if (result.pagination!.totalPages != null) {
        _totalPages = result.pagination!.totalPages!;
      }
      if (result.pagination!.currentPage != null) {
        _currentPage = result.pagination!.currentPage!;
        _nextPage = _currentPage + _pageOffset;
      }
    }

    if (result.nextToken != null) {
      _token = result.nextToken!;
      key = _token.toString();
    }

    final users = result.users;

    // Record before delivering, so a caller that re-reads immediately sees
    // the same page.
    await _snapshots.recordEntities(
      users,
      hasNext: _totalPages != -1 && _nextPage <= _totalPages,
      issuedIn: issuedIn,
      toJson: (u) => (u as User).toJson(),
    );

    // Held through the record step, so a fetch landing during it cannot
    // replay the page about to be delivered (BEH-SNAP-14); cleared before
    // the callbacks, so a fetch made from one of them is a new fetch.
    _inProgress = false;
    if (onSuccess != null) onSuccess(users);
    listener?.onServerUsers(users);
    return users;
  } on SdkException catch (sdkEx) {
    _inProgress = false;
    final cometChatEx = CometChatException(
      sdkEx.code,
      sdkEx.details ?? sdkEx.message,
      sdkEx.message,
    );
    if (onError != null) onError(cometChatEx);
    listener?.onError(cometChatEx);
  } catch (e) {
    _inProgress = false;
    final cometChatEx = CometChatException(
      ErrorCode.errorUnhandledException,
      e.toString(),
      e.toString(),
    );
    if (onError != null) onError(cometChatEx);
    listener?.onError(cometChatEx);
  }
  return [];
}