Directional Pagination

GraphQLQueryPager supports pagination in both the forward and reverse direction, as well as both at once.

Forward Pagination

Forward pagination is the most common form of pagination. It is used to fetch the next n items in a list. While we have many options depending on our requirements -- whether we use one query or two, whether we want to use a cursor or an offset, whether we want to transform the results, etc. -- we will examine using a cursor with a single query.

1
let initialQuery = MyQuery(first: 10, after: nil)
2
let pager = GraphQLQueryPager(
3
    client: client,
4
    initialQuery: initialQuery,
5
    extractPageInfo: { data in
6
        CursorBasedPagination.Forward(
7
            hasNext: data.values.pageInfo.hasNextPage ?? false,
8
            endCursor: data.values.pageInfo.endCursor
9
        )
10
    },
11
    pageResolver: { page, paginationDirection in
12
        // As we only want to support forward pagination, we can return `nil` for reverse pagination
13
        switch paginationDirection {
14
        case .next:
15
            return MyQuery(first: 10, after: page.endCursor ?? .none)
16
        case .previous:
17
            return nil
18
        }
19
    }
20
)

Reverse Pagination

Reverse pagination is used to fetch the previous n items in a list. While we have many options depending on our requirements -- whether we use one query or two, whether we want to use a cursor or an offset, whether we want to transform the results, etc. -- we will examine using a cursor with a single query.

1
let initialQuery = MyQuery(first: 10, after: nil)
2
let pager = GraphQLQueryPager(
3
    client: client,
4
    initialQuery: initialQuery,
5
    extractPageInfo: { data in
6
        CursorBasedPagination.Reverse(
7
            hasNext: data.values.pageInfo.hasPrevious ?? false,
8
            endCursor: data.values.pageInfo.startCursor
9
        )
10
    },
11
    pageResolver: { page, paginationDirection in
12
        // As we only want to support reverse pagination, we can return `nil` for forward pagination
13
        switch paginationDirection {
14
        case .next:
15
            return nil
16
        case .previous:
17
            return MyQuery(first: 10, before: page.startCursor ?? .none)
18
        }
19
    }
20
)

Bi-directional Pagination

Bi-directional pagination is used to fetch the next n items in a list, as well as the previous n items in a list. Given that we can fetch in both directions, the implication is that the initial query fetched is at neither the head nor tail of the list of results. For this example, we will examine using a cursor with a single query.

1
let pager = GraphQLQueryPager(
2
    client: client,
3
    initialQuery: MyQuery(first: 10, after: nil),
4
    extractPageInfo: { data in
5
        CursorBasedPagination.Bidirectional(
6
            hasNext: data.values.pageInfo.hasNextPage ?? false,
7
            endCursor: data.values.pageInfo.endCursor,
8
            hasPrevious: data.values.pageInfo.hasPreviousPage ?? false,
9
            startCursor: data.values.pageInfo.startCursor
10
        )
11
    },
12
    pageResolver: { page, direction in
13
        switch direction {
14
        case .next:
15
            return MyQuery(first: 10, after: page?.endCursor ?? .none)
16
        case .previous:
17
            return MyQuery(first: 10, before: page?.startCursor ?? .none)
18
        }
19
    }
20
)

Custom Configuration

Generally, it's recommended to use a convenience initializer to create a configured GraphQLQueryPager. However, if you need to customize the configuration, you can use the init method directly. If your application only uses a specific type of pagination, it is simple to declare a custom GraphQLQueryPager convenience initializer that can be used throughout your application. This allows you to easily instantiate a pager without worrying about cases that your application does not support. If your pagination scheme only supports forward pagination and offsets, you can declare a custom GraphQLQueryPager convenience initializer that only supports forward pagination and offsets. In this example, we declare two initializers for forward offset pagination -- one with a transform, and one without:

1
extension GraphQLQueryPager {
2
  static func makeForwardOffsetQueryPager<InitialQuery: GraphQLQuery>(
3
    client: ApolloClientProtocol,
4
    watcherDispatchQueue: DispatchQueue = .main,
5
    queryProvider: @escaping (OffsetPagination.Forward?) -> InitialQuery,
6
    extractPageInfo: @escaping (InitialQuery.Data) -> OffsetPagination.Forward
7
  ) -> GraphQLQueryPager where Model == PaginationOutput<InitialQuery, InitialQuery> {
8
    GraphQLQueryPager.init(
9
      client: client,
10
      initialQuery: queryProvider(nil),
11
      watcherDispatchQueue: watcherDispatchQueue,
12
      extractPageInfo: pageExtraction(transform: extractPageInfo),
13
      pageResolver: { page, direction in
14
        guard direction == .next else { return nil }
15
        return queryProvider(page)
16
      }
17
    )
18
  }
19

20
  static func makeForwardOffsetQueryPager<InitialQuery: GraphQLQuery, T>(
21
    client: ApolloClientProtocol,
22
    watcherDispatchQueue: DispatchQueue = .main,
23
    queryProvider: @escaping (OffsetPagination.Forward?) -> InitialQuery,
24
    extractPageInfo: @escaping (InitialQuery.Data) -> OffsetPagination.Forward,
25
    transform: @escaping (InitialQuery.Data) throws -> Model
26
  ) -> GraphQLQueryPager where Model: RangeReplaceableCollection, T == Model.Element {
27
    GraphQLQueryPager.init(
28
      client: client,
29
      initialQuery: queryProvider(nil),
30
      watcherDispatchQueue: watcherDispatchQueue,
31
      extractPageInfo: pageExtraction(transform: extractPageInfo),
32
      pageResolver: { page, direction in
33
        guard direction == .next else { return nil }
34
        return queryProvider(page)
35
      },
36
      initialTransform: transform,
37
      pageTransform: transform
38
    )
39
  }
40
}
41

42
private func pageExtraction<InitialQuery: GraphQLQuery, P: PaginationInfo, T>(
43
  transform: @escaping (InitialQuery.Data) -> P
44
) -> (PageExtractionData<InitialQuery, InitialQuery, T>) -> P {
45
  { extractionData in
46
    switch extractionData {
47
    case .initial(let value, _), .paginated(let value, _):
48
      return transform(value)
49
    }
50
  }
51
}
52

53
private func pageExtraction<InitialQuery: GraphQLQuery, PaginatedQuery: GraphQLQuery, P: PaginationInfo, T>(
54
  initialTransform: @escaping (InitialQuery.Data) -> P,
55
  paginatedTransform: @escaping (PaginatedQuery.Data) -> P
56
) -> (PageExtractionData<InitialQuery, PaginatedQuery, T>) -> P {
57
  { extractionData in
58
    switch extractionData {
59
    case .initial(let value, _):
60
      return initialTransfom(value)
61
    case .paginated(let value, _):
62
      return paginatedTransform(value)
63
    }
64
  }
65
}

Using Custom Response Models

Multi-query Pagination