Merge pull request #112 from algolia/feature/relevance-helper-function

Relevance helper functions

Author: q-litzler

src/commonMain/kotlin/com/algolia/search/endpoint/EndpointSearch.kt

@@ -2,8 +2,8 @@ package com.algolia.search.endpoint
 
 import com.algolia.search.model.Attribute
 import com.algolia.search.model.IndexName
-import com.algolia.search.model.filter.Filter
 import com.algolia.search.model.filter.FilterGroup
+import com.algolia.search.model.response.ResponseHitWithPosition
 import com.algolia.search.model.response.ResponseSearch
 import com.algolia.search.model.response.ResponseSearchForFacets
 import com.algolia.search.model.search.Cursor
@@ -121,4 +121,26 @@ public interface EndpointSearch {
         filterGroups: Set<FilterGroup<*>> = setOf(),
         requestOptions: RequestOptions? = null
     ): ResponseSearch
-}
+
+    /**
+     *  Search iteratively through the search response [ResponseSearch.hits] field to find the first response hit that
+     *  would match against the given [match] function.
+     *  If no object has been found within the first result set, the function
+     *  will perform a new search operation on the next page of results, if any,
+     *  until a matching object is found or the end of results is reached, whichever
+     *  happens first.
+     *  [doNotPaginate] will stop the function at the end of the first page of search results even if no object does
+     *  match.
+     *
+     *  @param match Predicate to match a given [ResponseSearch.Hit]
+     *  @param query The [Query] used to search.
+     *  @param doNotPaginate To prevent the iteration through pages of results.
+     *  @param requestOptions Configure request locally with [RequestOptions].
+     */
+    tailrec suspend fun findFirstObject(
+        match: (ResponseSearch.Hit) -> Boolean,
+        query: Query = Query(),
+        doNotPaginate: Boolean = false,
+        requestOptions: RequestOptions? = null
+    ): ResponseHitWithPosition?
+}

src/commonMain/kotlin/com/algolia/search/endpoint/EndpointSearchImpl.kt

@@ -9,6 +9,7 @@ import com.algolia.search.model.filter.Filter
 import com.algolia.search.model.filter.FilterGroup
 import com.algolia.search.model.multipleindex.IndexQuery
 import com.algolia.search.model.request.RequestParams
+import com.algolia.search.model.response.ResponseHitWithPosition
 import com.algolia.search.model.response.ResponseSearch
 import com.algolia.search.model.response.ResponseSearchForFacets
 import com.algolia.search.model.response.ResponseSearches
@@ -34,6 +35,23 @@ internal class EndpointSearchImpl(
         return transport.request(HttpMethod.Post, CallType.Read, indexName.toPath("/query"), requestOptions, body)
     }
 
+    override tailrec suspend fun findFirstObject(
+        match: (ResponseSearch.Hit) -> Boolean,
+        query: Query,
+        doNotPaginate: Boolean,
+        requestOptions: RequestOptions?
+    ): ResponseHitWithPosition? {
+        val response = search(query, requestOptions)
+        val hit = response.hits.find(match)
+        val hasNextPage = response.page + 1 < response.nbPages
+
+        return if (hit != null) {
+            ResponseHitWithPosition(hit, response.hits.indexOf(hit), response.page)
+        } else if (!doNotPaginate && hasNextPage) {
+            findFirstObject(match, query.copy(page = (query.page ?: 0) + 1), doNotPaginate, requestOptions)
+        } else null
+    }
+
     override suspend fun browse(query: Query, requestOptions: RequestOptions?): ResponseSearch {
         val params = RequestParams(query.toJsonNoDefaults().urlEncode())
         val body = JsonNoDefaults.stringify(RequestParams.serializer(), params)

src/commonMain/kotlin/com/algolia/search/model/response/ResponseHitWithPosition.kt

@@ -0,0 +1,11 @@
+package com.algolia.search.model.response
+
+import kotlinx.serialization.Serializable
+
+
+@Serializable
+public data class ResponseHitWithPosition(
+    val hit: ResponseSearch.Hit,
+    val position: Int,
+    val page: Int
+)

src/commonMain/kotlin/com/algolia/search/model/response/ResponseSearch.kt

@@ -3,6 +3,7 @@ package com.algolia.search.model.response
 import com.algolia.search.endpoint.EndpointSearch
 import com.algolia.search.model.Attribute
 import com.algolia.search.model.IndexName
+import com.algolia.search.model.ObjectID
 import com.algolia.search.model.QueryID
 import com.algolia.search.model.insights.InsightsEvent
 import com.algolia.search.model.search.*
@@ -272,6 +273,14 @@ public data class ResponseSearch(
     public val hierarchicalFacets: Map<Attribute, List<Facet>>
         get() = hierarchicalFacetsOrNull!!
 
+    /**
+     * Returns the position (0-based) within the [hits] result list of the record matching against the given [objectID].
+     * If the [objectID] is not found, -1 is returned.
+     */
+    public fun getObjectIDPosition(objectID: ObjectID): Int {
+        return hits.indexOfFirst { it.json.getPrimitiveOrNull("objectID")?.content == objectID.raw }
+    }
+
     /**
      * A Hit returned by the search.
      */

src/commonTest/kotlin/suite/TestSuiteSearch.kt

@@ -3,6 +3,8 @@ package suite
 import clientAdmin1
 import clientSearch
 import com.algolia.search.helper.toAttribute
+import com.algolia.search.model.ObjectID
+import com.algolia.search.model.response.ResponseSearch
 import com.algolia.search.model.search.Query
 import com.algolia.search.model.settings.AttributeForFaceting
 import com.algolia.search.model.settings.Settings
@@ -11,6 +13,7 @@ import com.algolia.search.model.task.TaskStatus
 import kotlinx.serialization.json.JsonObjectSerializer
 import kotlinx.serialization.list
 import runBlocking
+import shouldBeNull
 import shouldBeTrue
 import shouldContain
 import shouldEqual
@@ -46,13 +49,33 @@ internal class TestSuiteSearch {
             index.apply {
                 tasks += setSettings(settings)
                 tasks += saveObjects(objects)
-
                 tasks.wait().all { it is TaskStatus.Published }.shouldBeTrue()
-                search(Query("algolia")).nbHits shouldEqual 2
-                val hits = search(Query("elon", clickAnalytics = true)).hits
 
-                hits.shouldNotBeNull()
-                hits.shouldNotBeEmpty()
+                search(Query("algolia")).apply {
+                    nbHits shouldEqual 2
+                    getObjectIDPosition(ObjectID("nicolas-dessaigne")) shouldEqual 0
+                    getObjectIDPosition(ObjectID("julien-lemoine")) shouldEqual 1
+                    getObjectIDPosition(ObjectID("unknown")) shouldEqual -1
+                }
+
+                findFirstObject({ false }, Query(""), false).shouldBeNull()
+                findFirstObject({ true }, Query(""), false)!!.apply {
+                    page shouldEqual 0
+                    position shouldEqual 0
+                }
+                val predicate = { hit: ResponseSearch.Hit -> hit.json.getPrimitive("company").content == "Apple" }
+
+                findFirstObject(predicate, Query("Algolia"), false).shouldBeNull()
+                findFirstObject(predicate, Query(hitsPerPage = 5), true).shouldBeNull()
+                findFirstObject(predicate, Query(hitsPerPage = 5), false)!!.apply {
+                    position shouldEqual 0
+                    page shouldEqual 2
+                }
+
+               search(Query("elon", clickAnalytics = true)).apply {
+                   hits.shouldNotBeNull()
+                   hits.shouldNotBeEmpty()
+               }
             }
             search.apply {
                 search(Query(facets = allFacets, filters = "company:tesla")).nbHits shouldEqual 1

src/commonTest/resources/companies.json

@@ -1,11 +1,13 @@
 [
   {
     "company": "Algolia",
-    "name": "Julien Lemoine"
+    "name": "Julien Lemoine",
+    "objectID": "julien-lemoine"
   },
   {
     "company": "Algolia",
-    "name": "Nicolas Dessaigne"
+    "name": "Nicolas Dessaigne",
+    "objectID": "nicolas-dessaigne"
   },
   {
     "company": "Amazon",