Paginated Watchers for GraphQL Queries

Sources/Apollo/CustomDataTransformer.swift

@@ -0,0 +1,23 @@
+#if !COCOAPODS
+import ApolloAPI
+#endif
+
+/// Gives the caller full control over how to transform data.
+/// Can be used to output a custom type, or can be used for fine grain control over how a `Query.Data` is merged.
+public struct CustomDataTransformer<Query: GraphQLQuery, Output: Hashable>: DataTransformer {
+
+  private let _transform: (Query.Data) -> Output?
+
+  /// Designated intializer
+  /// - Parameter transform: A user provided function which can transform a given network response into any `Hashable` output.
+  public init(transform: @escaping (Query.Data) -> Output?) {
+    self._transform = transform
+  }
+
+  /// The function by which we transform a `Query.Data` into an output
+  /// - Parameter data: Network response
+  /// - Returns: `Output`
+  public func transform(data: Query.Data) -> Output? {
+    _transform(data)
+  }
+}

Sources/Apollo/CustomNextPageStrategy.swift

@@ -0,0 +1,16 @@
+#if !COCOAPODS
+import ApolloAPI
+#endif
+
+/// The strategy by which we create the next query in a series of paginated queries. Gives full custom control over mapping a `Page` into a `Query`.
+public struct CustomNextPageStrategy<Page: Hashable, Query: GraphQLQuery>: NextPageStrategy {
+  private let _transform: (Page) -> Query
+
+  public init(transform: @escaping (Page) -> Query) {
+    self._transform = transform
+  }
+
+  public func createNextPageQuery(page: Page) -> Query {
+    _transform(page)
+  }
+}

Sources/Apollo/CustomPaginationMergeStrategy.swift

@@ -0,0 +1,22 @@
+#if !COCOAPODS
+import ApolloAPI
+#endif
+
+/// A `PaginationMergeStrategy` which gives the caller fine-grain control over how to merge data together.
+public class CustomPaginationMergeStrategy<Query: GraphQLQuery, Output: Hashable>: PaginationMergeStrategy {
+
+  let _transform: (PaginationDataResponse<Query, Output>) -> Output
+
+  /// Designated initializer
+  /// - Parameter transform: a user-defined function which can transform a `PaginationDataResponse` into an `Output`.
+  public init(transform: @escaping (PaginationDataResponse<Query, Output>) -> Output) {
+    self._transform = transform
+  }
+
+  /// The function by which we merge several responses, in the form of a `PaginationDataResponse` into one `Output`.
+  /// - Parameter paginationResponse: A data type which contains the most recent response, the source of that response, and all other responses.
+  /// - Returns: `Output`
+  public func mergePageResults(paginationResponse: PaginationDataResponse<Query, Output>) -> Output {
+    _transform(paginationResponse)
+  }
+}

Sources/Apollo/DataTransformer.swift

@@ -0,0 +1,14 @@
+#if !COCOAPODS
+import ApolloAPI
+#endif
+
+/// The protocol by which we transform a network/cache response into some `Output`.
+public protocol DataTransformer {
+  associatedtype Query: GraphQLQuery
+  associatedtype Output: Hashable
+
+  /// Given a network response, transform it into the intended result type of the `PaginationStrategy`.
+  /// - Parameter data: A network response
+  /// - Returns: `Output`
+  func transform(data: Query.Data) -> Output?
+}

Sources/Apollo/GraphQLPaginatedQueryWatcher.swift

@@ -0,0 +1,102 @@
+#if !COCOAPODS
+import ApolloAPI
+#endif
+import Dispatch
+
+/// Handles pagination in the queue by managing multiple query watchers.
+public final class GraphQLPaginatedQueryWatcher<Strategy: PaginationStrategy> {
+  public typealias Page = Strategy.NextPageConstructor.Page
+  private typealias ResultHandler = (Result<GraphQLResult<Strategy.Query.Data>, Error>) -> Void
+
+  private let client: any ApolloClientProtocol
+  private var watchers: [GraphQLQueryWatcher<Strategy.Query>] = []
+  private var callbackQueue: DispatchQueue
+  let strategy: Strategy
+
+  /// Designated initalizer
+  /// - Parameters:
+  ///   - client: the Apollo client
+  ///   - callbackQueue: The `DispatchQueue` that results are returned on.
+  ///   - strategy: The `PaginationStrategy` that this watcher employs.
+  ///   - initialQuery: The `Query` that is being watched.
+  public init(
+    client: ApolloClientProtocol,
+    callbackQueue: DispatchQueue = .main,
+    strategy: Strategy,
+    initialQuery: Strategy.Query
+  ) {
+    self.callbackQueue = callbackQueue
+    self.client = client
+    self.strategy = strategy
+    let initialWatcher = GraphQLQueryWatcher(
+      client: client,
+      query: initialQuery,
+      callbackQueue: callbackQueue,
+      resultHandler: strategy.onWatchResult(result:)
+    )
+    watchers = [initialWatcher]
+  }
+
+  /// Fetch the first page
+  /// NOTE: Does not refresh subsequent pages nor remove them from the return value.
+  public func fetch(cachePolicy: CachePolicy = .returnCacheDataAndFetch) {
+    watchers.first?.fetch(cachePolicy: cachePolicy)
+  }
+
+  /// Fetches the first page and purges all data from subsequent pages.
+  public func refetch(cachePolicy: CachePolicy = .fetchIgnoringCacheData) {
+    // Reset mapping of data and order of data
+    strategy.reset()
+    // Remove and cancel all watchers aside from the first page
+    guard let initialWatcher = watchers.first else { return }
+    let subsequentWatchers = watchers.dropFirst()
+    subsequentWatchers.forEach { $0.cancel() }
+    watchers = [initialWatcher]
+    initialWatcher.refetch(cachePolicy: cachePolicy)
+  }
+
+  /// Fetches the next page
+  @discardableResult public func fetchMore(
+    cachePolicy: CachePolicy = .fetchIgnoringCacheData,
+    completion: (() -> Void)? = nil
+  ) -> Bool {
+    guard strategy.canFetchNextPage(),
+          let currentPage = strategy.currentPage
+    else { return false }
+    let nextPageQuery = strategy.nextPageStrategy.createNextPageQuery(page: currentPage)
+
+    let nextPageWatcher = client.watch(
+      query: nextPageQuery,
+      cachePolicy: cachePolicy,
+      callbackQueue: callbackQueue
+    ) { [weak self] result in
+      self?.strategy.onWatchResult(result: result)
+      completion?()
+    }
+    watchers.append(nextPageWatcher)
+
+    return true
+  }
+
+  /// Refetches data for a given page.
+  /// NOTE: Does not refresh previous or subsequent pages nor remove them from the return value.
+  public func refresh(page: Page?, cachePolicy: CachePolicy = .returnCacheDataAndFetch) {
+    guard let page else {
+      // Fetch first page
+      return fetch(cachePolicy: cachePolicy)
+    }
+    guard let index = strategy.pages.firstIndex(where: { $0 == page }),
+          watchers.count > index
+    else { return }
+    watchers[index].fetch(cachePolicy: cachePolicy)
+  }
+
+  /// Cancel any in progress fetching operations and unsubscribe from the store.
+  public func cancel() {
+    watchers.forEach { $0.cancel() }
+  }
+
+  deinit {
+    cancel()
+  }
+}

Sources/Apollo/NextPageStrategy.swift

@@ -0,0 +1,12 @@
+#if !COCOAPODS
+import ApolloAPI
+#endif
+
+/// The strategy by which we create the next query in a series of paginated queries.
+public protocol NextPageStrategy {
+  associatedtype Query: GraphQLQuery
+  associatedtype Page: Hashable
+
+  /// Given some `Page`, returns a formed `Query` that uses the information contained within the `Page` to paginate.
+  func createNextPageQuery(page: Page) -> Query
+}

Sources/Apollo/OffsetPageExtractor.swift

@@ -0,0 +1,77 @@
+#if !COCOAPODS
+import ApolloAPI
+#endif
+
+/// Can extract and identify a `Page` for cursor-based endpoints
+public struct OffsetPageExtractor<Query: GraphQLQuery>: PageExtractionStrategy {
+
+  /// A formed input for the `OffsetPageExtractor`
+  public struct Input: Hashable {
+
+    /// The `Query.Data`
+    public let data: Query.Data
+
+    /// The current offset
+    public let offset: Int
+
+    /// The number of expected results per page
+    public let pageSize: Int
+
+    init(data: Query.Data, offset: Int, pageSize: Int) {
+      self.data = data
+      self.offset = offset
+      self.pageSize = pageSize
+    }
+  }
+
+  /// A minimal definiton for a `Page`
+  public struct Page: Hashable {
+    /// Where in the list the server should start when returning items for a particular query
+    public let offset: Int
+
+    /// Whether or not there is potentially another page of results
+    public let hasNextPage: Bool
+
+    /// Designated Initializer
+    /// - Parameters:
+    ///   - offset: Where in the list the server should start when returning items for a particular query
+    ///   - hasNextPage: Whether or not there is potentially another page of results
+    public init(offset: Int, hasNextPage: Bool) {
+      self.offset = offset
+      self.hasNextPage = hasNextPage
+    }
+  }
+
+  private let _transform: (Input) -> Page
+
+  /// Designated initializer
+  /// - Parameter transform: A user provided function which can extract a `Page` from a `Query.Data`
+  public init(transform: @escaping (Input) -> Page) {
+    self._transform = transform
+  }
+
+  /// Convenience initializer
+  /// - Parameter arrayKeyPath: A `KeyPath` over a `Query.Data` which identifies the array key within the `Query.Data`.
+  public init(arrayKeyPath: KeyPath<Query.Data, [(some SelectionSet)?]?>) {
+    self._transform = { input in
+      let count = input.data[keyPath: arrayKeyPath]?.count ?? 0
+      return Page(offset: input.offset + count, hasNextPage: count == input.pageSize)
+    }
+  }
+
+  /// Convenience initializer
+  /// - Parameter arrayKeyPath: A `KeyPath` over a `Query.Data` which identifies the array key within the `Query.Data`.
+  public init(arrayKeyPath: KeyPath<Query.Data, [(some SelectionSet)]?>) {
+    self._transform = { input in
+      let count = input.data[keyPath: arrayKeyPath]?.count ?? 0
+      return Page(offset: input.offset + count, hasNextPage: count == input.pageSize)
+    }
+  }
+
+  /// Transforms the `Query.Data` into a `Page` by utilizing the user-provided functions or key paths.
+  /// - Parameter input: A query response data.
+  /// - Returns: A `Page`.
+  public func transform(input: Input) -> Page {
+    _transform(input)
+  }
+}