Update SearchResult.matchingName and batch results documentation and …

…availability (#334)

### Description
Fixes SSDK-1155

- Update documentation for `SearchResult.matchingName` field to convey that this field is absent in ApiType.searchBox.
- Update documentation for `SearchEngine.select(suggestions:)` is not available for ApiType.searchBox.
- Update tests and behavior

CHANGELOG.md

@@ -8,6 +8,9 @@ Guide: https://keepachangelog.com/en/1.0.0/
 
 <!-- Add changes for active work here -->
 
+- [SearchResult] Mark `matchingName` field as deprecated and add note for absence of values in ApiType.searchBox results.
+- [SearchEngine] Add documentation and assertion that ApiType.searchBox does _not_ support batch requests.
+
 ## 2.5.1
 
 - [Demo] Add example for forward(query:options:completion:) to Demo app using SwiftUI.

Sources/MapboxSearch/InternalAPI/CoreSearchResultProtocol.swift

@@ -21,6 +21,9 @@ protocol CoreSearchResultProtocol {
 
     var addressDescription: String? { get }
 
+    /// The feature name, as matched by the search algorithm.
+    /// Not available in ``ApiType/searchBox`` results.
+    /// - Warning: The field is exposed for compatibility only and should be considered deprecated.
     var matchingName: String? { get }
 
     var centerLocation: CLLocation? { get }

Sources/MapboxSearch/PublicAPI/Engine/SearchEngine.swift

@@ -243,6 +243,7 @@ public class SearchEngine: AbstractSearchEngine {
         }
     }
 
+    // NOTE: SearchBox does not support batch responses.
     private func processBatchResponse(_ coreResponse: CoreSearchResponseProtocol?) {
         guard let coreResponse else {
             eventsManager.reportError(.responseProcessingFailed)
@@ -443,9 +444,12 @@ extension SearchEngine {
     /// All suggestions must originate from the same search request.
     /// Suggestions with other types will be ignored. You can use `SearchSuggestion.batchResolveSupported` field for
     /// filtering.
+    /// SearchBox does _not_ support batch requests.
     /// - Parameter suggestions: suggestions list to resolve. All suggestions must originate from the same search
     /// request.
     public func select(suggestions: [SearchSuggestion]) {
+        assert(apiType == .geocoding || apiType == .SBS, "Only geocoding and SBS API types support batch results.")
+
         for suggestion in suggestions {
             let supported = (suggestion as? CoreResponseProvider)?.originalResponse.coreResult.action?.multiRetrievable
                 == true
@@ -458,8 +462,6 @@ extension SearchEngine {
             .compactMap { $0 as? CoreResponseProvider }
             .filter { $0.originalResponse.coreResult.action?.multiRetrievable == true }
 
-        // let coreSearchResults = suggestionsImpls.compactMap { $0.originalResponse.coreResult }
-
         guard suggestionsImpls.isEmpty == false else {
             return
         }

Sources/MapboxSearch/PublicAPI/FavoriteRecord.swift

@@ -11,11 +11,9 @@ public struct FavoriteRecord: IndexableRecord, SearchResult, Codable, Equatable
     /// A unique identifier for the geographic feature
     public var mapboxId: String?
 
-    /**
-         The feature name, as matched by the search algorithm.
-
-         - Warning: The field is exposed for compatibility only, will be removed soon.
-     */
+    /// The feature name, as matched by the search algorithm.
+    /// Not available in ``ApiType/searchBox`` results.
+    /// - Warning: The field is exposed for compatibility only and should be considered deprecated.
     public var matchingName: String?
 
     /// address formatted with medium style.

Sources/MapboxSearch/PublicAPI/HistoryRecord.swift

@@ -33,11 +33,9 @@ public struct HistoryRecord: IndexableRecord, SearchResult, Codable, Hashable {
     /// A point accuracy metric for the returned address.
     public let accuracy: SearchResultAccuracy?
 
-    /**
-         The feature name, as matched by the search algorithm.
-
-         - Warning: The field is exposed for compatibility only, will be removed soon.
-     */
+    /// The feature name, as matched by the search algorithm.
+    /// Not available in ``ApiType/searchBox`` results.
+    /// - Warning: The field is exposed for compatibility only and should be considered deprecated.
     public private(set) var matchingName: String?
 
     /// Address formatted with medium style

Sources/MapboxSearch/PublicAPI/Search Results/SearchResult.swift

@@ -28,6 +28,8 @@ public protocol SearchResult {
     var coordinate: CLLocationCoordinate2D { get }
 
     /// The feature name, as matched by the search algorithm.
+    /// Not available in ``ApiType/searchBox`` results.
+    /// - Warning: The field is exposed for compatibility only and should be considered deprecated.
     var matchingName: String? { get }
 
     /// Result address.

Tests/MapboxSearchIntegrationTests/search-box/SearchBox_CategorySearchEngineIntegrationTests.swift

@@ -25,6 +25,8 @@ final class SearchBox_CategorySearchEngineIntegrationTests: MockServerIntegratio
             switch result {
             case .success(let searchResults):
                 XCTAssertFalse(searchResults.isEmpty)
+                let matchingNames = searchResults.compactMap(\.matchingName)
+                XCTAssertTrue(matchingNames.isEmpty)
                 expectation.fulfill()
             case .failure:
                 XCTFail("Error not expected")

Tests/MapboxSearchIntegrationTests/search-box/SearchBox_SearchEngineIntegrationTests.swift

@@ -143,40 +143,6 @@ class SearchBox_SearchEngineIntegrationTests: MockServerIntegrationTestCase<Sear
         XCTAssertNil(delegate.resolvedResult)
     }
 
-    func testBatchResolve() throws {
-        try server.setResponse(.multiRetrieve)
-
-        let results = CoreSearchResultStub.makeMixedResultsSet().map(\.asCoreSearchResult)
-        let coreResponse = CoreSearchResponseStub.successSample(results: results)
-
-        let suggestions = CoreSearchResultStub.makeSuggestionsSet().map(\.asCoreSearchResult).compactMap {
-            SearchResultSuggestionImpl(coreResult: $0, response: coreResponse)
-        }
-
-        let expectation = delegate.batchUpdateExpectation
-        searchEngine.select(suggestions: suggestions)
-
-        wait(for: [expectation], timeout: 10)
-        XCTAssertFalse(delegate.resolvedResults.isEmpty)
-    }
-
-    func testBatchResolveFailed() throws {
-        try server.setResponse(.multiRetrieve, statusCode: 500)
-
-        let results = CoreSearchResultStub.makeMixedResultsSet().map(\.asCoreSearchResult)
-        let coreResponse = CoreSearchResponseStub.successSample(results: results)
-
-        let suggestions = CoreSearchResultStub.makeSuggestionsSet().map(\.asCoreSearchResult).compactMap {
-            SearchResultSuggestionImpl(coreResult: $0, response: coreResponse)
-        }
-
-        let expectation = delegate.errorExpectation
-        searchEngine.select(suggestions: suggestions)
-
-        wait(for: [expectation], timeout: 10)
-        XCTAssert(delegate.error?.errorCode == 500)
-    }
-
     func testSuggestionTypeQuery() throws {
         try server.setResponse(.recursion)
         try server.setResponse(.retrieveRecursion)

Tests/MapboxSearchTests/Legacy/CategorySearchEngineTests.swift

@@ -56,6 +56,8 @@ class CategorySearchEngineTests: XCTestCase {
             switch result {
             case .success(let searchResults):
                 results = searchResults
+                let matchingNames = searchResults.compactMap(\.matchingName)
+                XCTAssertTrue(matchingNames.isEmpty)
                 expectation.fulfill()
             case .failure:
                 assertionFailure("Error not expected")