Add 'CacheClearingPolicy' for users to have more control over cleanup

Author: Mordil

Sources/Apollo/ApolloClient.swift

@@ -80,9 +80,12 @@ extension ApolloClient: ApolloClientProtocol {
     }
   }
 
-  public func clearCache(callbackQueue: DispatchQueue = .main,
-                         completion: ((Result<Void, Error>) -> Void)? = nil) {
-    self.store.clearCache(completion: completion)
+  public func clearCache(
+    usingPolicy policy: CacheClearingPolicy,
+    callbackQueue: DispatchQueue = .main,
+    completion: ((Result<Void, Error>) -> Void)? = nil
+  ) {
+    self.store.clearCache(usingPolicy: policy, callbackQueue: callbackQueue, completion: completion)
   }
 
   @discardableResult public func fetch<Query: GraphQLQuery>(query: Query,

Sources/Apollo/ApolloClientProtocol.swift

@@ -9,13 +9,15 @@ public protocol ApolloClientProtocol: class {
   /// A function that returns a cache key for a particular result object. If it returns `nil`, a default cache key based on the field path will be used.
   var cacheKeyForObject: CacheKeyForObject? { get set }
 
-  /// Clears the underlying cache.
-  /// Be aware: In more complex setups, the same underlying cache can be used across multiple instances, so if you call this on one instance, it'll clear that cache across all instances which share that cache.
-  ///
+  /// Clears the cache store according to the specified policy.
+  /// - Warning: The cache may be used by other clients. Calling this method will affect all clients using the same cache!
   /// - Parameters:
-  ///   - callbackQueue: The queue to fall back on. Should default to the main queue.
-  ///   - completion: [optional] A completion closure to execute when clearing has completed. Should default to nil.
-  func clearCache(callbackQueue: DispatchQueue, completion: ((Result<Void, Error>) -> Void)?)
+  ///   - policy: The cache cleaning policy to use.
+  ///   - callbackQueue: An optional queue to execute the completion handler on. Should default to the `.main` queue.
+  ///   - completion: An optional completion closure to execute when the cache has been cleared. Should default to `nil`.
+  func clearCache(usingPolicy policy: CacheClearingPolicy,
+                  callbackQueue: DispatchQueue,
+                  completion: ((Result<Void, Error>) -> Void)?)
 
   /// Fetches a query from the server or from the local cache, depending on the current contents of the cache and the specified cache policy.
   ///
@@ -79,3 +81,16 @@ public protocol ApolloClientProtocol: class {
                                                     queue: DispatchQueue,
                                                     resultHandler: @escaping GraphQLResultHandler<Subscription.Data>) -> Cancellable
 }
+
+// MARK: conveniences
+
+extension ApolloClientProtocol {
+  /// Clears all records from the cache store.
+  /// - Warning: The cache may be used by other clients. Calling this method will affect all clients using the same cache!
+  /// - Parameters:
+  ///   - callbackQueue: An optional queue to execute the completion handler on. The default is `.main`.
+  ///   - completion: An optional completion closure to execute when the cache has been cleared. The default is `nil`.
+  func clearCache(callbackQueue: DispatchQueue = .main, completion: ((Result<Void, Error>) -> Void)? = nil) {
+    self.clearCache(usingPolicy: .allRecords, callbackQueue: callbackQueue, completion: completion)
+  }
+}

Sources/Apollo/ApolloStore.swift

@@ -45,18 +45,34 @@ public final class ApolloStore {
     }
   }
 
-  /// Clears the instance of the cache. Note that a cache can be shared across multiple `ApolloClient` objects, so clearing that underlying cache will clear it for all clients.
-  ///
-  /// - Returns: A promise which fulfills when the Cache is cleared.
+  /// Clears all records from the cache.
+  /// - Warning: If this cache is shared between multiple `ApolloClient` objects, each client will be affected by the change in the cache.
+  /// - Parameters:
+  ///   - callbackQueue: An optional callback queue to execute the `completion` handler on. The default is `.main`.
+  ///   - completion: An optional completion handler to execute when the cache has been cleared according the specified policy.
+  /// - Returns: A promise which fulfills when the cache has been cleared.
   public func clearCache(callbackQueue: DispatchQueue = .main, completion: ((Result<Void, Error>) -> Void)? = nil) {
-    queue.async(flags: .barrier) {
-      self.cacheLock.withWriteLock {
-          self.cache.clearPromise()
-        }.andThen {
-          DispatchQueue.apollo.returnResultAsyncIfNeeded(on: callbackQueue,
-                                                         action: completion,
-                                                         result: .success(()))
-      }
+    self.clearCache(usingPolicy: .allRecords, callbackQueue: callbackQueue, completion: completion)
+  }
+
+  /// Clears the cache according to the specified policy.
+  /// - Warning: If this cache is shared between multiple `ApolloClient` objects, each client will be affected by the change in the cache.
+  /// - Parameters:
+  ///   - policy: The cache clearing policy to use during cleanup.
+  ///   - callbackQueue: An optional callback queue to execute the `completion` handler on. The default is `.main`.
+  ///   - completion: An optional completion handler to execute when the cache has been cleared according the specified policy.
+  /// - Returns: A promise which fulfills when the cache has been cleared.
+  public func clearCache(
+    usingPolicy policy: CacheClearingPolicy,
+    callbackQueue: DispatchQueue = .main,
+    completion: ((Result<Void, Error>) -> Void)? = nil
+  ) {
+    self.queue.async(flags: .barrier) {
+      self.cacheLock
+        .withWriteLock { self.cache.clearPromise(policy) }
+        .andThen {
+          DispatchQueue.apollo.returnResultAsyncIfNeeded(on: callbackQueue, action: completion, result: .success(()))
+        }
     }
   }
 
@@ -380,9 +396,9 @@ internal extension NormalizedCache {
     }
   }
 
-  func clearPromise() -> Promise<Void> {
+  func clearPromise(_ policy: CacheClearingPolicy) -> Promise<Void> {
     return Promise { fulfill, reject in
-      self.clear(callbackQueue: nil) { result in
+      self.clear(policy, callbackQueue: nil) { result in
         switch result {
         case .success(let success):
           fulfill(success)

Sources/Apollo/InMemoryNormalizedCache.swift

@@ -4,16 +4,14 @@ public final class InMemoryNormalizedCache: NormalizedCache {
   private var records: RecordSet
   private let recordsLock = NSRecursiveLock()
 
-  public init(records: RecordSet = RecordSet()) {
+  public init(records: RecordSet = .init()) {
     self.records = records
   }
 
   public func loadRecords(forKeys keys: [CacheKey],
                           callbackQueue: DispatchQueue?,
                           completion: @escaping (Result<[RecordRow?], Error>) -> Void) {
-    self.recordsLock.lock()
-    let records = keys.map { self.records[$0] }
-    self.recordsLock.unlock()
+    let records = self.threadSafe { keys.map{ self.records[$0] } }
     DispatchQueue.apollo.returnResultAsyncIfNeeded(on: callbackQueue,
                                                    action: completion,
                                                    result: .success(records))
@@ -22,17 +20,18 @@ public final class InMemoryNormalizedCache: NormalizedCache {
   public func merge(records: RecordSet,
                     callbackQueue: DispatchQueue?,
                     completion: @escaping (Result<Set<CacheKey>, Error>) -> Void) {
-    self.recordsLock.lock()
-    let cacheKeys = self.records.merge(records: records)
-    self.recordsLock.unlock()
+    let cacheKeys = self.threadSafe { self.records.merge(records: records) }
     DispatchQueue.apollo.returnResultAsyncIfNeeded(on: callbackQueue,
                                                    action: completion,
                                                    result: .success(cacheKeys))
   }
 
-  public func clear(callbackQueue: DispatchQueue?,
-                    completion: ((Result<Void, Error>) -> Void)?) {
-    clearImmediately()
+  public func clear(
+    _ clearingPolicy: CacheClearingPolicy,
+    callbackQueue: DispatchQueue?,
+    completion: ((Result<Void, Error>) -> Void)?
+  ) {
+    self.clearImmediately(clearingPolicy)
 
     guard let completion = completion else {
       return
@@ -43,9 +42,14 @@ public final class InMemoryNormalizedCache: NormalizedCache {
                                                    result: .success(()))
   }
 
-  public func clearImmediately() {
+  public func clearImmediately(_ clearingPolicy: CacheClearingPolicy) {
+    self.threadSafe { self.records.clear(clearingPolicy) }
+  }
+
+  private func threadSafe<Result>(_ operation: () -> Result) -> Result {
     self.recordsLock.lock()
-    self.records.clear()
+    let result = operation()
     self.recordsLock.unlock()
+    return result
   }
 }

Sources/Apollo/NormalizedCache.swift

@@ -1,5 +1,46 @@
 import Foundation
 
+/// An object that drives behavior of clear operations on a given cache.
+public struct CacheClearingPolicy: Equatable {
+  /// Clears all records in the cache.
+  public static let allRecords = CacheClearingPolicy(.allRecords)
+  /// Clears all records whose key matches the provided glob pattern.
+  /// - Parameter pattern: The glob pattern to use for key matching. For example `*pollo` will match both `Apollo` and `pollo`.
+  public static func allMatchingKeyPattern(_ pattern: String) -> CacheClearingPolicy { .init(.allMatchingKeyPattern(pattern)) }
+  /// Clears the the first (oldest) records in the cache up to the given limit.
+  /// - Parameter k: The number of records to remove from the cache.
+  public static func first(_ k: Int) -> CacheClearingPolicy { .init(.first(k)) }
+  /// Clears the the last (most recent) records in the cache up to the given limit.
+  /// - Parameter k: The number of records to remove from the cache.
+  public static func last(_ k: Int) -> CacheClearingPolicy { .init(.last(k)) }
+
+  // actual policy storage
+
+  /// This is public due to language requirements for cross-target access.
+  /// Do not use this value, nor its type as they are an implementation detail.
+  public let _value: _Policy
+  private init(_ policy: _Policy) { self._value = policy }
+
+  /// This is public due to language requirements for cross-target access.
+  /// Do not use this type, nor any of its values, as they are an implementation detail.
+  public enum _Policy: Equatable {
+    case allRecords
+    case allMatchingKeyPattern(String)
+    case first(Int)
+    case last(Int)
+
+    public static func ==(lhs: _Policy, rhs: _Policy) -> Bool {
+      switch (lhs, rhs) {
+      case (.allRecords, .allRecords): return true
+      case let (.allMatchingKeyPattern(left), .allMatchingKeyPattern(right)): return left == right
+      case let (.first(left), .first(right)): return left == right
+      case let (.last(left), .last(right)): return left == right
+      default: return false
+      }
+    }
+  }
+}
+
 public protocol NormalizedCache {
 
   /// Loads records corresponding to the given keys.
@@ -22,14 +63,31 @@ public protocol NormalizedCache {
              callbackQueue: DispatchQueue?,
              completion: @escaping (Result<Set<CacheKey>, Error>) -> Void)
 
-  // Clears all records
-  ///
+  /// Clears records from the cache according to the policy provided.
   /// - Parameters:
-  ///   - callbackQueue: [optional] An alternate queue to fire the completion closure on. If nil, will fire on the current queue.
-  ///   - completion: [optional] A completion closure to fire when the clear function has completed.
-  func clear(callbackQueue: DispatchQueue?,
+  ///   - policy: The policy to use in determining which records to clear.
+  ///   - callbackQueue: An optional queue to execute the completion closure on.
+  ///   - completion: An optional completion closure to execute when the cache clearing has completed.
+  func clear(_ clearingPolicy: CacheClearingPolicy,
+             callbackQueue: DispatchQueue?,
              completion: ((Result<Void, Error>) -> Void)?)
 
-  // Clears all records synchronously
-  func clearImmediately() throws
+  /// Clears records from the cache synchronously according to the policy provided.
+  /// - Parameter policy: The policy to use in determining which records to clear.
+  func clearImmediately(_ clearingPolicy: CacheClearingPolicy) throws
+}
+
+extension NormalizedCache {
+  /// Clears all records in the cache.
+  /// - Parameters:
+  ///   - callbackQueue: An optional queue to execute the completion closure on.
+  ///   - completion: An optional completion closure to execute when the cache clearing has completed.
+  public func clear(callbackQueue: DispatchQueue? = nil, completion: ((Result<Void, Error>) -> Void)? = nil) {
+    self.clear(.allRecords, callbackQueue: callbackQueue, completion: completion)
+  }
+
+  /// Clears all records in the cache synchronously.
+  public func clearImmediately() throws {
+    try self.clearImmediately(.allRecords)
+  }
 }

Sources/Apollo/RecordSet.swift

@@ -23,8 +23,17 @@ public struct RecordSet {
     self.storage[row.record.key] = row
   }
 
-  public mutating func clear() {
-    storage.removeAll()
+  public mutating func clear(_ clearingPolicy: CacheClearingPolicy = .allRecords) {
+    switch clearingPolicy._value {
+    case let .first(count): self.storage = .init(self.storage.dropFirst(count))
+
+    case let .last(count): self.storage = .init(self.storage.dropLast(count))
+
+    case let .allMatchingKeyPattern(pattern): self.storage = self.storage.filter { !$0.key.contains(pattern) }
+
+    case .allRecords: fallthrough
+    default: self.storage.removeAll()
+    }
   }
 
   public mutating func insert<S: Sequence>(contentsOf rows: S) where S.Iterator.Element == RecordRow {

Sources/ApolloSQLite/SQLiteNormalizedCache.swift

@@ -125,11 +125,30 @@ public final class SQLiteNormalizedCache {
     return try self.db.prepare(query).map { try parse(row: $0) }
   }
 
-  private func clearRecords() throws {
-    try self.db.run(records.delete())
-    if self.shouldVacuumOnClear {
-      try self.db.prepare("VACUUM;").run()
+  private func clearRecords(accordingTo policy: CacheClearingPolicy) throws {
+    switch policy._value {
+    case let .first(count):
+      let firstKRecords = records.select(self.id).order(self.id.asc).limit(count)
+      try self.db.run(firstKRecords.delete())
+
+    case let .last(count):
+      let lastKRecords = records.select(self.id).order(self.id.desc).limit(count)
+      try self.db.run(lastKRecords.delete())
+
+    case let .allMatchingKeyPattern(pattern):
+      let matchingRecords = records.where(
+        self.key.like(pattern.replacingOccurrences(of: "*", with: "%"))
+      )
+      try self.db.run(matchingRecords.delete())
+
+    case .allRecords: fallthrough
+    default:
+      try self.db.run(records.delete())
     }
+
+    guard self.shouldVacuumOnClear else { return }
+
+    try self.db.prepare("VACUUM;").run()
   }
 
   private func parse(row: Row) throws -> RecordRow {
@@ -217,10 +236,14 @@ extension SQLiteNormalizedCache: NormalizedCache {
                                                    result: result)
   }
 
-  public func clear(callbackQueue: DispatchQueue?, completion: ((Swift.Result<Void, Error>) -> Void)?) {
+  public func clear(
+    _ clearingPolicy: CacheClearingPolicy,
+    callbackQueue: DispatchQueue?,
+    completion: ((Swift.Result<Void, Error>) -> Void)?
+  ) {
     let result: Swift.Result<Void, Error>
     do {
-      try clearImmediately()
+      try self.clearRecords(accordingTo: clearingPolicy)
       result = .success(())
     } catch {
       result = .failure(error)
@@ -231,8 +254,8 @@ extension SQLiteNormalizedCache: NormalizedCache {
                                                    result: result)
   }
 
-  public func clearImmediately() throws {
-    try clearRecords()
+  public func clearImmediately(_ clearingPolicy: CacheClearingPolicy) throws {
+    try self.clearRecords(accordingTo: clearingPolicy)
   }
 }