apollo-ios: ApolloPagination's loadNext throwing `loadInProgress` incorrectly

@mapy1874 I found this – which seems to be in spirit with what i would have built out as a package: https://github.com/danielsaidi/ScrollKit/blob/main/Sources/ScrollKit/Helpers/ScrollViewOffsetTracker.swift#L11-L35

I haven’t used it, so I can’t speak to how well it works – but it seems like what you’re looking for

@mapy1874 As a quick aside – there should be a clean workaround for onAppear usage in the next release, when callbacks to fetch and refetch are added.

In the near future, your LaunchListViewModel could look something like this (note that I didn’t implement this for refetch in this example – but should):

(changes are: addition of hasFirstPageLoaded variable, adding a callback within fetch())

import Apollo
import ApolloPagination
import RocketReserverAPI
import SwiftUI

private let pageSize = 10

extension LaunchListQuery.Data.Launches.Launch: Identifiable { }

@Observable final class LaunchListViewModel: ObservableObject {
    var showTailSpinner = false
    var canLoadNext: Bool { pager.canLoadNext }
    var launches: [LaunchListQuery.Data.Launches.Launch] = []
    var hasFirstPageLoaded: Bool = false
    var error: Error?
    var showError: Bool {
        get { error != nil }
        set { error = nil }
    }
    private var pager: GraphQLQueryPager<[LaunchListQuery.Data.Launches.Launch]>

    init() {
        let initialQuery = LaunchListQuery(pageSize: .some(pageSize), cursor: .none)
        self.pager = GraphQLQueryPager(
            client: Network.shared.apollo,
            initialQuery: initialQuery,
            extractPageInfo: { data in
                CursorBasedPagination.Forward(hasNext: data.launches.hasMore, endCursor: data.launches.cursor)
            },
            pageResolver: { page, direction in
                LaunchListQuery(pageSize: .some(pageSize), cursor: page.endCursor ?? .none)
            },
            transform: { data in
                data.launches.launches.compactMap { $0 }
            }
        )
        pager.subscribe { result in
            switch result {
            case .success((let launches, _)):
                self.launches = launches
            case .failure(let error):
                // These are network errors, and worth showing to the user.
                self.error = error
            }
        }

        fetch()
    }

    func refresh() {
        pager.refetch()
    }

    func fetch() {
        hasFirstPageLoaded = false
        pager.fetch() {
            hasFirstPageLoaded = true
        }
    }

    func loadNextPage() {
        guard canLoadNext, !showTailSpinner else { return }
        self.showTailSpinner = true
        pager.loadNext() { error in
            self.showTailSpinner = false
            // This is a usage error
            if let error {
                assertionFailure(error.localizedDescription)
            }
        }
    }
}

You could somewhat emulate this behavior today, by having the file look like this:

(Changes are: Addition of hasFirstPageLoaded variable, setting hasFirstPageLoaded to false in fetch(), setting it to true in subscribe if source is fetch)

import Apollo
import ApolloPagination
import RocketReserverAPI
import SwiftUI

private let pageSize = 10

extension LaunchListQuery.Data.Launches.Launch: Identifiable { }

@Observable final class LaunchListViewModel: ObservableObject {
    var showTailSpinner = false
    var canLoadNext: Bool { pager.canLoadNext }
    var launches: [LaunchListQuery.Data.Launches.Launch] = []
    var hasFirstPageLoaded: Bool = false
    var error: Error?
    var showError: Bool {
        get { error != nil }
        set { error = nil }
    }
    private var pager: GraphQLQueryPager<[LaunchListQuery.Data.Launches.Launch]>

    init() {
        let initialQuery = LaunchListQuery(pageSize: .some(pageSize), cursor: .none)
        self.pager = GraphQLQueryPager(
            client: Network.shared.apollo,
            initialQuery: initialQuery,
            extractPageInfo: { data in
                CursorBasedPagination.Forward(hasNext: data.launches.hasMore, endCursor: data.launches.cursor)
            },
            pageResolver: { page, direction in
                LaunchListQuery(pageSize: .some(pageSize), cursor: page.endCursor ?? .none)
            },
            transform: { data in
                data.launches.launches.compactMap { $0 }
            }
        )
        pager.subscribe { result in
            switch result {
            case .success((let launches, let source)):
                self.launches = launches
                if source == .fetch {
                    self.hasFirstPageLoaded = true
                }
            case .failure(let error):
                // These are network errors, and worth showing to the user.
                self.error = error
            }
        }

        fetch()
    }

    func refresh() {
        pager.refetch()
    }

    func fetch() {
        hasFirstPageLoaded = false
        pager.fetch()
    }

    func loadNextPage() {
        guard canLoadNext, !showTailSpinner else { return }
        self.showTailSpinner = true
        pager.loadNext() { error in
            self.showTailSpinner = false
            // This is a usage error
            if let error {
                assertionFailure(error.localizedDescription)
            }
        }
    }
}

This would rely on a task picking up on the onChange effect of a fetch() coming in (the hasFirstPageLoaded variable changing), and firing its event again. A bit of an abuse of SwiftUI, but functional for folks relying on task of the last row. This should also work even in the event of cached results – as you showcased in your code sample above.

I think the error being experienced at this point isn’t to do with ApolloPagination specifically – but rather, SwiftUI’s default behavior.

Stepping away from early invocation of loadNextPage for a moment – the issue you’re describing seems to boil down to the behavior of the .task modifier, and could be triggered with any networking scheme – inclusive of the out-of-the-box URLSession’s data(from:delegate:). The .task modifier will trigger its closure onAppear/onChange and will cancel its asynchronous operation onDisappear – so the moment you scroll off-screen, any active Task will be cancelled. Since ApolloPagination’s GraphQLQueryPager relies on Tasks under the hood, it respects Task cancellations – and will attempt to respond to cancellations.

You could build in the behavior you’d prefer by:

• Avoiding the use of task, instead preferring to use onAppear and onChange.
• Building your own custom modifier.
• Something else.

As far as invocating loadNextPage early – there are a few ways of doing that. For UIKit-based apps, you could create your own InfiniteScrollController that communicates with a UICollectionView/UITableView, hooks into the scrollViewWillEndDragging(_:withVelocity:targetContentOffset) function to determine whether or not to fire off a load request. For a SwiftUI-based app, I would imagine you’d want some sort of ScrollViewReader based solution.

Ultimately, the question of what should trigger a load is somewhat philosophical. I’m of the opinion that it’s a user-triggered event. I fall into the camp of thinking that a specific row of data appearing on-screen isn’t a user-triggered event – but a side effect of the action the user took: scrolling. Given that, it makes sense to me that an infinite scroll load is triggered on scroll-based logic – especially given the default behaviors of the onAppear and task modifiers.

As an aside, I think I’ve got an idea for a small SwiftUI package centered around providing that kind of behavior to List. 🤔

---

As a quick note on why we don’t allow fetches on cached data, since I don’t think I explained that in the previous message – we don’t allow fetches on cached data, since cached data may be stale. This is a common bug for folks that use a returnCacheDataAndFetch CachePolicy – and I’ve seen it across a fair number of apps.

@mapy1874 I took another look at your project – and realized that this could be rewritten in-place without relying on any changes in the pagination library:

https://github.com/mapy1874/loadInProgressBugDemo/compare/main...Iron-Ham:loadInProgressBugDemo:main

To summarize the changes made:

• (Unrelated) I updated the project target to iOS 17, purely for my convenience in using @Observable instead of ObservedObject.
• LaunchListView changes:
  • I moved the reset-button to a refreshable, so we can pull-to-refresh. Notably, this goes through a different code-path than the initial fetch (it uses refetch under the hood).
  • I updated the fetch logic for fetching the next page. See the change from onAppear to task. Note: I’m using task as it’s a multi-purpose function. It will trigger both onAppear and onChange, as well as cancel onDisappear. You may or may not want the cancellation behavior onDisappear inherent to task – and in the case you don’t, you can choose to instead implement both onChange and onAppear.
  • I removed the error view at the top of the screen in favor of an error alert modal.
  • I removed the tail-load text indicator in favor of a ProgressView().
• LaunchListViewModel changes:
  • Set canLoadNext to be a calculated property.
  • Use a transforming initializer of GraphQLQueryPager, given that we are only seemingly interested in the Launch model of the results.
  • Swap to using subscribe(completion:) instead of receive(on:).sink(receiveValue:). Really just a convenience thing, this isn’t a functional change.
  • Note that the subscribe call is just being used to set launches or error, and nothing else.
  • I renamed isLoading to showTailSpinner, since that’s a more accurate representation of what’s happening. If we wanted to show a spinner on first load, a tail spinner likely isn’t the appropriate design choice.
  • I added a guard to the loadNextPage, which ensures that we aren’t calling this when we shouldn’t.
  • I added an error assertionFailure: We will halt execution in DEBUG if something is wrong. I didn’t hit this in my testing.

My mental model of list view UIs

Everyone has a different mental model, and every application has unique constraints and requirements. With that said, my mental model for list view, generally speaking, is as follows:

1. We have an optional array of values that represent each entry in the list.
2. When the array is nil, it means we haven’t fetched our first page of values (and we don’t have any cached values) and should be showing the full screen loading page.
3. When the array is empty, it means we received values, but we should be showing an empty state.
4. Every list view should be refreshable; a pull to refresh should replace the full list of data with a brand new fetch of the first page. This should be a real, non-cache driven fetch, which means that the pull-to-refresh control will remain visible and spinning until data comes back. Note that this isn’t happening in the code-sample above. When this change is merged & shipped, it should give you the capability to attach a callback to refetch() – which means you can make this an async function via a Continuation. That will allow you to await the function, and have the refresh control remain spinning until it is done fetching data.
5. Pagination should ideally happen prior to getting to the last item to minimize the chance that a user ever sees a tail loading spinner.
6. Network errors should be shown to the user – either via a full-screen error view (with retry button) or via a toast.

Let me know if that’s helpful as a demonstration!

Before diving in – I think that this change should allow you to set your isLoading value in the callbacks of both fetch and loadNext – instead of sink. By default, loadNext and loadPrevious fetches aren’t performed with optimistic cache data, so that may be sufficient for your case?

---

Thanks! May I get more context on why we choose to throw a PaginationError in when isFetching == true, instead of queueing the requests up/let it fetch even other threads are fetching?

I intentionally didn’t allow for parallel execution for a few reasons:

• It’s too easy to accidentally trigger identical fetches. loadNext and loadPrevious rely on the pager’s internal pagination state. That information isn’t committed to the internal value-set until an operation completes. That means that two simultaneous loadNext operations would be fetching the same query, with the same arguments. Allowing for use of the cache-values opens up a can of worms with data consistency, as you could fetch data based on pagination-parameters that are no longer valid.
• I saw a potential use-case for allowing a loadPrevious and loadNext at the same time, but it didn’t seem worth the difficulty of implementing it given the niche use-case of a bi-directional pager.

Queued fetches weren’t allowed for similar reasons:

• Allowing for queued fetches mask logical errors. If I have an API that is triggering loadNext far more often than it should, all of these fetches would be queued, and the incorrect operation would be masked.
• The underlying AsyncGraphQLQueryPagerCoordinator, which performs all of the pagination, technically does queue all of its messages by virtue of being an actor. What it doesn’t do is ensure sequential execution; it will swap to the next message if the currently active message suspends execution. As I understand it (and I’m happy to be told otherwise!) that behavior violates a principal of Swift Concurrency, since it opens up the possibility of permanently suspending execution.
• We would need to manage the queue manually: removing all queued values on reset isn’t a big deal, but being able to determine when we should remove invalid queued operations is a bit harder. Let’s imagine we have 10 queued loadNext operation, and that after the currently executing loadNext, we receive the final page of data. At that point, we’d have to look at all of the queued operations and manually remove loadNext. If there is a loadPrevious in the queue, that may still be a valid operation.
• fetch and refetch would jump the queue by virtue of calling reset prior to their execution.
• Though – perhaps we can maintain a queue with a limit of one, and that would alleviate issues. Definitely something to explore.

Effectively, what this translates into is an intentional design decision that it’s up to the caller to ensure that they aren’t calling loadNext and loadPrevious more than they should be.

In the context of GitHub, we do so by having an object which manages infinite-scroll behavior. At its core, it observes a list view’s scroll position and triggers a load when we are within a certain distance of the end of the list (e.g., when we are within min(1.5*Vertical_Screen_Size, Some_Value) we trigger a fetch). We’re primarily a UIKit app, so our conventions aren’t identical to a SwiftUI app – but the gist of how we’re using ApolloPagination for simple pagination tasks:

• When we reach our threshold for infinite scroll, we call loadNext/loadPrevious.
• Initial fetches are done via fetch, usually in viewDidLoad.
• Pull-to-refresh fetches are done via refetch – as this guarantees that we show the user new data, and that the pull-to-refresh spinner appears, spins, and disappears when the new data comes in.

---

The current way of throwing an error makes it challenging to work with the “onAppear of last item, try loadNext” scenario

I’ll take some some time this week and think on improvements to SwiftUI with an onAppear/task scheme. task encapsulates onAppear, onDisappear, and onChange – with cancellations being automatically forwarded as necessary.

I really appreciate the feedback on this, it’s super valuable!

Totally, that makes sense to me. Adding additional docs around AsyncGraphQLQueryPager may be a good move here – as I can see that it’s not obvious that something like this is available.

The assumption was that when we assign the new list and rendering the items on view, the library should have already done loading. Thus when the last item appears on the view, we are safe to trigger loadNext again.

I think what’s hard about this assumption is that it’s not universally true. Imagine that you were fetching with returnCacheDataAndFetch instead of just fetching from the server. You could receive data twice: once from the cache, and then later from the server. When you receive data from the cache, you are still performing the fetch from the server. In that instance you’re not done until:

• GraphQLQueryPager’s loadNext’s callback fires
• Or, if you’re using AsyncGraphQLQueryPager, you continue on from your await.

I’d have to think about how best to improve this – whether that’s documentation or API. 🤔

@Iron-Ham Thanks for your quick response!

For the need, I guess it’s less about the loading indicator. The bug was that no pagination would happen after we get the loadInProgress error given that we don’t have any retry mechanism. It’s about whether or not the pager is currently fetching in order to trigger loadNext after the loading is finished.

The assumption was that when we assign the new list and rendering the items on view, the library should have already done loading. Thus when the last item appears on the view, we are safe to trigger loadNext again.

For your questions:

Would exposing the loading state of the pager publicly have been helpful?

I do see people could get confused by this given it’s natural to assume when GraphQLQueryPager publisher emits events with data/error, the loading is complete.

Why use the GraphQLQueryPager instead of the Async variety when it seems you’re in an async context?

We started using ApolloPagination months ago, and there was no documentations back then and it seems natural for us to start with GraphQLQueryPager. Also, there are not that many materials on how to use AsyncGraphQLQueryPager in the official document. Thus, I assume people would default to use non-async one

Here’s a demo app to repro this if that helps: https://github.com/mapy1874/loadInProgressBugDemo

thanks for reporting! I’ll take a look at this momentarily.

@Iron-Ham 👀