Support offline search for facet values (#306)

* Implement offline search for facet values in `MirroredIndex`

* Implement offline search for facet values in `OfflineIndex`

* Update pod dependencies

Offline search for facet values requires Offline Core’s version 1.1 (not yet released).

Author: Clément Le Provost

AlgoliaSearch-Offline-Swift.podspec

@@ -11,7 +11,7 @@ Pod::Spec.new do |s|
 
     s.ios.deployment_target = '8.0'
 
-    s.dependency 'AlgoliaSearchOfflineCore-iOS', '~> 1.0'
+    s.dependency 'AlgoliaSearchOfflineCore-iOS', '~> 1.1'
 
     # Activate Core-dependent code.
     # WARNING: Specifying the preprocessor macro is not enough; it must be added to Swift flags as well.

Podfile

@@ -3,7 +3,7 @@
 use_frameworks!
 
 def common_deps
-    pod 'AlgoliaSearchOfflineCore-iOS', '~> 1.0'
+    pod 'AlgoliaSearchOfflineCore-iOS', '~> 1.1'
 end
 
 target "AlgoliaSearch-Offline-iOS" do

Source/Offline/MirroredIndex.swift

@@ -1097,7 +1097,81 @@ import Foundation
         let (content, error) = OfflineClient.parseResponse(searchResults)
         return (MirroredIndex.tagAsLocal(content: content), error)
     }
+
+    // ----------------------------------------------------------------------
+    // MARK: - Search for facet values
+    // ----------------------------------------------------------------------
 
+    /// Search for facet values, using the current request strategy to choose between online and offline.
+    /// Same parameters as `Index.searchForFacetValues(...)`.
+    ///
+    @objc(searchForFacetValuesOf:matching:query:completionHandler:)
+    @discardableResult override public func searchForFacetValues(of facetName: String, matching text: String, query: Query? = nil, completionHandler: @escaping CompletionHandler) -> Operation {
+        // IMPORTANT: A non-mirrored index must behave exactly as an online index.
+        if (!mirrored) {
+            return super.searchForFacetValues(of: facetName, matching: text, query: query, completionHandler: completionHandler)
+        }
+        // A mirrored index launches a mixed offline/online request.
+        else {
+            let operation = MixedSearchFacetOperation(index: self, facetName: facetName, facetQuery: text, query: query, completionHandler: completionHandler)
+            offlineClient.mixedRequestQueue.addOperation(operation)
+            return operation
+        }
+    }
+    
+    private class MixedSearchFacetOperation: OnlineOfflineOperation {
+        let facetName: String
+        let facetQuery: String
+        let query: Query?
+        
+        init(index: MirroredIndex, facetName: String, facetQuery: String, query: Query?, completionHandler: @escaping CompletionHandler) {
+            self.facetName = facetName
+            self.facetQuery = facetQuery
+            self.query = query
+            super.init(index: index, completionHandler: completionHandler)
+        }
+        
+        override func startOnlineRequest(completionHandler: @escaping CompletionHandler) -> Operation {
+            return index.searchForFacetValuesOnline(of: facetName, matching: facetQuery, query: query, completionHandler: completionHandler)
+        }
+        
+        override func startOfflineRequest(completionHandler: @escaping CompletionHandler) -> Operation {
+            return index.searchForFacetValuesOffline(of: facetName, matching: facetQuery, query: query, completionHandler: completionHandler)
+        }
+    }
+    
+    /// Search for facet values on the online API, not the local mirror.
+    /// This method is an alias of `Index.searchForFacetValues(...)`.
+    ///
+    @objc(searchForFacetValuesOnlineOf:matching:query:completionHandler:)
+    @discardableResult public func searchForFacetValuesOnline(of facetName: String, matching text: String, query: Query? = nil, completionHandler: @escaping CompletionHandler) -> Operation {
+        return super.searchForFacetValues(of: facetName, matching: text, query: query, completionHandler: {
+            (content, error) in
+            completionHandler(MirroredIndex.tagAsRemote(content: content), error)
+        })
+    }
+    
+    /// Search for facet values on the local mirror, not the online API.
+    /// This method is the offline equivalent of `Index.searchForFacetValues(...)`.
+    ///
+    @objc(searchForFacetValuesOfflineOf:matching:query:completionHandler:)
+    @discardableResult public func searchForFacetValuesOffline(of facetName: String, matching text: String, query: Query? = nil, completionHandler: @escaping CompletionHandler) -> Operation {
+        assert(self.mirrored, "Mirroring not activated on this index")
+        let operation = AsyncBlockOperation(completionHandler: completionHandler) {
+            return self._searchForFacetValuesOffline(of: facetName, matching: text, query: query)
+        }
+        operation.completionQueue = client.completionQueue
+        self.offlineClient.searchQueue.addOperation(operation)
+        return operation
+    }
+    
+    /// Search for facet values on the local mirror synchronously.
+    private func _searchForFacetValuesOffline(of facetName: String, matching text: String, query: Query?) -> (content: JSONObject?, error: Error?) {
+        assert(!Thread.isMainThread) // make sure it's run in the background
+        let searchResults = localIndex.searchForFacetValues(of: facetName, matching: text, parameters: query?.build())
+        return OfflineClient.parseResponse(searchResults)
+    }
+
     // ----------------------------------------------------------------------
     // MARK: - Notifications
     // ----------------------------------------------------------------------

Source/Offline/OfflineIndex.swift

@@ -464,6 +464,28 @@ public struct IOError: CustomNSError {
         return self.multipleQueriesSync(queries, strategy: strategy?.rawValue)
     }
 
+    /// Search for facet values.
+    /// Same parameters as `Index.searchForFacetValues(...)`.
+    ///
+    @discardableResult
+    @objc(searchForFacetValuesOf:matching:query:completionHandler:)
+    public func searchForFacetValues(of facetName: String, matching text: String, query: Query? = nil, completionHandler: @escaping CompletionHandler) -> Operation {
+        let queryCopy = query != nil ? Query(copy: query!) : nil
+        let operation = BlockOperation() {
+            let (content, error) = self.searchForFacetValuesSync(of: facetName, matching: text, query: queryCopy)
+            self.callCompletionHandler(completionHandler, content: content, error: error)
+        }
+        client.searchQueue.addOperation(operation)
+        return operation
+    }
+
+    /// Search for facet values (synchronous version).
+    ///
+    private func searchForFacetValuesSync(of facetName: String, matching text: String, query: Query? = nil) -> APIResponse {
+        let searchResults = self.localIndex.searchForFacetValues(of: facetName, matching: text, parameters: query?.build())
+        return OfflineClient.parseResponse(searchResults)
+    }
+
     // ----------------------------------------------------------------------
     // MARK: - Write operations
     // ----------------------------------------------------------------------

Tests/Offline/MirroredIndexTests.swift

@@ -85,11 +85,14 @@ class MirroredIndexTests: OfflineTestCase {
                 return
             }
             // Populate the online index.
-            index.addObjects(Array(self.moreObjects.values)) { (content, error) in
-                guard let taskID = content?["taskID"] as? Int else { XCTFail(); return }
-                index.waitTask(withID: taskID) { (content, error) in
-                    XCTAssertNil(error)
-                    completionBlock(error)
+            index.setSettings(self.settings) { (content, error) in
+                XCTAssertNil(error)
+                index.addObjects(Array(self.moreObjects.values)) { (content, error) in
+                    guard let taskID = content?["taskID"] as? Int else { XCTFail(); return }
+                    index.waitTask(withID: taskID) { (content, error) in
+                        XCTAssertNil(error)
+                        completionBlock(error)
+                    }
                 }
             }
         }
@@ -625,4 +628,55 @@ class MirroredIndexTests: OfflineTestCase {
         }
         waitForExpectations(timeout: onlineExpectationTimeout, handler: nil)
     }
+
+    func testSearchForFacetValues() {
+        let expectation_indexing = self.expectation(description: "indexing")
+        let expectation_onlineQuery = self.expectation(description: "onlineQuery")
+        let expectation_offlineQuery = self.expectation(description: "offlineQuery")
+        let expectation_mixedQuery = self.expectation(description: "offlineQuery")
+        
+        // Populate the online index & sync the offline mirror.
+        let index: MirroredIndex = client.index(withName: safeIndexName(#function))
+        sync(index: index) { (error) in
+            if let error = error { XCTFail("\(error)"); return }
+            
+            // Query the online index explicitly.
+            index.searchForFacetValuesOnline(of: "series", matching: "") { (content, error) in
+                XCTAssertNil(error)
+                guard let facetHits = content?["facetHits"] as? [JSONObject] else { XCTFail(); return }
+                XCTAssertEqual(2, facetHits.count)
+                XCTAssertEqual("remote", content?["origin"] as? String)
+                expectation_onlineQuery.fulfill()
+            }
+            
+            // Query the offline index explicitly.
+            index.searchForFacetValuesOffline(of: "series", matching: "") { (content, error) in
+                XCTAssertNil(error)
+                guard let facetHits = content?["facetHits"] as? [JSONObject] else { XCTFail(); return }
+                XCTAssertEqual(1, facetHits.count)
+                XCTAssertEqual("Peanuts", facetHits[0]["value"] as? String)
+                XCTAssertEqual(3, facetHits[0]["count"] as? Int)
+                XCTAssertEqual("local", content?["origin"] as? String)
+                expectation_offlineQuery.fulfill()
+            }
+            
+            // Test offline fallback.
+            self.client.readHosts = [ "unknown.algolia.com" ]
+            index.requestStrategy = .fallbackOnFailure
+            let query = Query()
+            query.query = "snoopy"
+            index.searchForFacetValues(of: "series", matching: "pea", query: query) { (content, error) in
+                XCTAssertNil(error)
+                guard let facetHits = content?["facetHits"] as? [JSONObject] else { XCTFail(); return }
+                XCTAssertEqual(1, facetHits.count)
+                XCTAssertEqual("Peanuts", facetHits[0]["value"] as? String)
+                XCTAssertEqual(1, facetHits[0]["count"] as? Int)
+                XCTAssertEqual("local", content?["origin"] as? String)
+                expectation_mixedQuery.fulfill()
+            }
+            
+            expectation_indexing.fulfill()
+        }
+        waitForExpectations(timeout: onlineExpectationTimeout, handler: nil)
+    }
 }

Tests/Offline/OfflineIndexTests.swift

@@ -467,4 +467,29 @@ class OfflineIndexTests: OfflineTestCase {
         }
         waitForExpectations(timeout: 10, handler: nil)
     }
+
+    func testSearchForFacetValues() {
+        let expectation = self.expectation(description: #function)
+        let index = client.offlineIndex(withName: #function)
+        let transaction = index.newTransaction()
+        transaction.setSettings(settings) { (content, error) in
+            XCTAssertNil(error)
+            transaction.saveObjects(Array(self.objects.values)) { (content, error) in
+                XCTAssertNil(error)
+                transaction.commit() { (content, error) in
+                    guard error == nil else { XCTFail(); return }
+                    let query = Query(query: "snoopy")
+                    index.searchForFacetValues(of: "series", matching: "pea", query: query) { (content, error) in
+                        guard let content = content else { XCTFail(); return }
+                        guard let facetHits = content["facetHits"] as? [JSONObject] else { XCTFail(); return }
+                        XCTAssertEqual(1, facetHits.count)
+                        XCTAssertEqual("Peanuts", facetHits[0]["value"] as? String)
+                        XCTAssertEqual(1, facetHits[0]["count"] as? Int)
+                        expectation.fulfill()
+                    }
+                }
+            }
+        }
+        waitForExpectations(timeout:  expectationTimeout, handler: nil)
+    }
 }

Tests/Offline/OfflineTestCase.swift

@@ -50,6 +50,11 @@ class OfflineTestCase: XCTestCase {
         super.tearDown()
     }
 
+    let settings: [String: Any] = [
+        "searchableAttributes": ["name", "kind", "series"],
+        "attributesForFaceting": ["searchable(series)"]
+    ]
+    
     let objects: [String: JSONObject] = [
         "snoopy": [
             "objectID": "1",