refactor: rename replaceExistingSynonyms into clearExistingSynonyms (#696)

Author: VladislavFitz

Sources/AlgoliaSearchClient/Command/Command+Synonym.swift

@@ -34,7 +34,7 @@ extension Command {
       init(indexName: IndexName, synonyms: [AlgoliaSearchClient.Synonym], forwardToReplicas: Bool?, clearExistingSynonyms: Bool?, requestOptions: RequestOptions?) {
         var parameters: [HTTPParameterKey: String] = [:]
         forwardToReplicas.flatMap { parameters[.forwardToReplicas] = String($0) }
-        clearExistingSynonyms.flatMap { parameters[.clearExistingSynonyms] = String($0) }
+        clearExistingSynonyms.flatMap { parameters[.replaceExistingSynonyms] = String($0) }
         self.requestOptions = requestOptions.updateOrCreate(parameters)
         let path = .indexesV1 >>> .index(indexName) >>> .synonyms >>> SynonymCompletion.batch
         urlRequest = .init(method: .post, path: path, body: synonyms.httpBody, requestOptions: self.requestOptions)

Sources/AlgoliaSearchClient/Index/Index+Synonym.swift

@@ -42,7 +42,7 @@ public extension Index {
      By making this true, the method will also send the synonym to all replicas.
      Thus, if you want to forward your synonyms to replicas you will need to specify that.
    - Parameter requestOptions: Configure request locally with RequestOptions
-   - Returns: SynonymRevision  object
+   - Returns: SynonymRevision object
    */
   @discardableResult func saveSynonym(_ synonym: Synonym,
                                       forwardToReplicas: Bool? = nil,
@@ -74,9 +74,10 @@ public extension Index {
    - Parameter completion: Result completion
    - Returns: Launched asynchronous operation
    */
+  @available(*, deprecated, renamed: "saveSynonyms(_:forwardToReplicas:clearExistingSynonyms:requestOptions:completion:)")
   @discardableResult func saveSynonyms(_ synonyms: [Synonym],
                                        forwardToReplicas: Bool? = nil,
-                                       replaceExistingSynonyms: Bool? = nil,
+                                       replaceExistingSynonyms: Bool?,
                                        requestOptions: RequestOptions? = nil,
                                        completion: @escaping ResultCallback<IndexRevision>) -> Operation {
     let command = Command.Synonym.SaveList(indexName: name, synonyms: synonyms, forwardToReplicas: forwardToReplicas, clearExistingSynonyms: replaceExistingSynonyms, requestOptions: requestOptions)
@@ -101,15 +102,74 @@ public extension Index {
      This parameter tells the engine to delete all existing synonyms before recreating a new list from the synonyms listed in the current call.
      This is the only way to avoid having no synonyms, ensuring that your index will always provide a full list of synonyms to your end-users.
    - Parameter requestOptions: Configure request locally with RequestOptions
-   - Returns: SynonymRevision  object
+   - Returns: IndexRevision  object
    */
+  @available(*, deprecated, renamed: "saveSynonyms(_:forwardToReplicas:clearExistingSynonyms:requestOptions:)")
   @discardableResult func saveSynonyms(_ synonyms: [Synonym],
                                        forwardToReplicas: Bool? = nil,
-                                       replaceExistingSynonyms: Bool? = nil,
+                                       replaceExistingSynonyms: Bool?,
                                        requestOptions: RequestOptions? = nil) throws -> WaitableWrapper<IndexRevision> {
     let command = Command.Synonym.SaveList(indexName: name, synonyms: synonyms, forwardToReplicas: forwardToReplicas, clearExistingSynonyms: replaceExistingSynonyms, requestOptions: requestOptions)
     return try execute(command)
   }
+  
+  /**
+   Create or update multiple synonym.
+   This method enables you to create or update one or more synonym in a single call.
+   You can also recreate your entire set of synonym by using the clearExistingSynonyms parameter.
+   Note that each synonym object counts as a single indexing operation.
+   
+   - Parameter synonyms: List of synonym to save.
+   - Parameter forwardToReplicas: By default, this method applies only to the specified index.
+     By making this true, the method will also send the synonym to all replicas.
+     Thus, if you want to forward your synonyms to replicas you will need to specify that.
+   - Parameter clearExistingSynonyms: Forces the engine to replace all synonyms, using an atomic save.
+     Normally, to replace all synonyms on an index, you would first clear the synonyms, using clearAllSynonyms, and then create a new list.
+     However, between the clear and the add, your index will have no synonyms.
+     This is where clearExistingSynonyms comes into play.
+     By adding this parameter, you do not need to use clearSynonyms, it’s done for you.
+     This parameter tells the engine to delete all existing synonyms before recreating a new list from the synonyms listed in the current call.
+     This is the only way to avoid having no synonyms, ensuring that your index will always provide a full list of synonyms to your end-users.
+   - Parameter requestOptions: Configure request locally with RequestOptions
+   - Parameter completion: Result completion
+   - Returns: Launched asynchronous operation
+   */
+  @discardableResult func saveSynonyms(_ synonyms: [Synonym],
+                                       forwardToReplicas: Bool? = nil,
+                                       clearExistingSynonyms: Bool? = nil,
+                                       requestOptions: RequestOptions? = nil,
+                                       completion: @escaping ResultCallback<IndexRevision>) -> Operation {
+    let command = Command.Synonym.SaveList(indexName: name, synonyms: synonyms, forwardToReplicas: forwardToReplicas, clearExistingSynonyms: clearExistingSynonyms, requestOptions: requestOptions)
+    return execute(command, completion: completion)
+  }
+
+  /**
+   Create or update multiple synonym.
+   This method enables you to create or update one or more synonym in a single call.
+   You can also recreate your entire set of synonym by using the clearExistingSynonyms parameter.
+   Note that each synonym object counts as a single indexing operation.
+   
+   - Parameter synonyms: List of synonym to save.
+   - Parameter forwardToReplicas: By default, this method applies only to the specified index.
+     By making this true, the method will also send the synonym to all replicas.
+     Thus, if you want to forward your synonyms to replicas you will need to specify that.
+   - Parameter clearExistingSynonyms: Forces the engine to replace all synonyms, using an atomic save.
+     Normally, to replace all synonyms on an index, you would first clear the synonyms, using clearAllSynonyms, and then create a new list.
+     However, between the clear and the add, your index will have no synonyms.
+     This is where clearExistingSynonyms comes into play.
+     By adding this parameter, you do not need to use clearSynonyms, it’s done for you.
+     This parameter tells the engine to delete all existing synonyms before recreating a new list from the synonyms listed in the current call.
+     This is the only way to avoid having no synonyms, ensuring that your index will always provide a full list of synonyms to your end-users.
+   - Parameter requestOptions: Configure request locally with RequestOptions
+   - Returns: IndexRevision  object
+   */
+  @discardableResult func saveSynonyms(_ synonyms: [Synonym],
+                                       forwardToReplicas: Bool? = nil,
+                                       clearExistingSynonyms: Bool? = nil,
+                                       requestOptions: RequestOptions? = nil) throws -> WaitableWrapper<IndexRevision> {
+    let command = Command.Synonym.SaveList(indexName: name, synonyms: synonyms, forwardToReplicas: forwardToReplicas, clearExistingSynonyms: clearExistingSynonyms, requestOptions: requestOptions)
+    return try execute(command)
+  }
 
   // MARK: - Get synonym
 
@@ -133,7 +193,7 @@ public extension Index {
 
    - Parameter objectID: ObjectID of the synonym to retrieve.
    - Parameter requestOptions: Configure request locally with RequestOptions
-   - Returns: Synonym  object
+   - Returns: Synonym object
    */
   @discardableResult func getSynonym(withID objectID: ObjectID,
                                      requestOptions: RequestOptions? = nil) throws -> Synonym {
@@ -164,7 +224,7 @@ public extension Index {
 
    - Parameter objectID: ObjectID of the synonym to delete.
    - Parameter requestOptions: Configure request locally with RequestOptions
-   - Returns: DeletionIndex  object
+   - Returns: IndexDeletion object
    */
   @discardableResult func deleteSynonym(withID objectID: ObjectID,
                                         forwardToReplicas: Bool? = nil,
@@ -209,7 +269,7 @@ public extension Index {
    Remove all synonyms from an index. This is a convenience method to delete all synonyms at once.
    This Clear All method should not be used on a production index to push a new list of synonyms because it will
    result in a short down period during which the index would have no synonyms at all.
-   Instead, use the saveSynonyms method (with replaceExistingSynonyms set to true) to atomically replace all synonyms of an index with no down time.
+   Instead, use the saveSynonyms method (with clearExistingSynonyms set to true) to atomically replace all synonyms of an index with no down time.
 
    - Parameter forwardToReplicas: Also replace synonyms on replicas.
    - Parameter requestOptions: Configure request locally with RequestOptions
@@ -227,11 +287,11 @@ public extension Index {
    Remove all synonyms from an index. This is a convenience method to delete all synonyms at once.
    This Clear All method should not be used on a production index to push a new list of synonyms because it will
    result in a short down period during which the index would have no synonyms at all.
-   Instead, use the saveSynonyms method (with replaceExistingSynonyms set to true) to atomically replace all synonyms of an index with no down time.
+   Instead, use the saveSynonyms method (with clearExistingSynonyms set to true) to atomically replace all synonyms of an index with no down time.
 
    - Parameter forwardToReplicas: Also replace synonyms on replicas.
    - Parameter requestOptions: Configure request locally with RequestOptions
-   - Returns: RevisionIndex object
+   - Returns: IndexRevision object
    */
   @discardableResult func clearSynonyms(forwardToReplicas: Bool? = nil,
                                         requestOptions: RequestOptions? = nil) throws -> WaitableWrapper<IndexRevision> {
@@ -256,7 +316,7 @@ public extension Index {
                                              forwardToReplicas: Bool? = nil,
                                              requestOptions: RequestOptions? = nil,
                                              completion: @escaping ResultCallback<IndexRevision>) -> Operation {
-    saveSynonyms(synonyms, forwardToReplicas: forwardToReplicas, replaceExistingSynonyms: true, requestOptions: requestOptions, completion: completion)
+    saveSynonyms(synonyms, forwardToReplicas: forwardToReplicas, clearExistingSynonyms: true, requestOptions: requestOptions, completion: completion)
   }
 
   /**
@@ -267,12 +327,12 @@ public extension Index {
    - Parameter synonyms: A list of synonym.
    - Parameter forwardToReplicas: Also replace synonyms on replicas.
    - Parameter requestOptions: Configure request locally with RequestOptions
-   - Returns: RevisionIndex  object
+   - Returns: IndexRevision  object
    */
   @discardableResult func replaceAllSynonyms(with synonyms: [Synonym],
                                              forwardToReplicas: Bool? = nil,
                                              requestOptions: RequestOptions? = nil) throws -> WaitableWrapper<IndexRevision> {
-    try saveSynonyms(synonyms, forwardToReplicas: forwardToReplicas, replaceExistingSynonyms: true, requestOptions: requestOptions)
+    try saveSynonyms(synonyms, forwardToReplicas: forwardToReplicas, clearExistingSynonyms: true, requestOptions: requestOptions)
   }
 
 }

Sources/AlgoliaSearchClient/Models/Common/RequestOptions.swift

@@ -86,7 +86,7 @@ extension HTTPParameterKey {
   static var attributesToRetreive: HTTPParameterKey { #function }
   static var forwardToReplicas: HTTPParameterKey { #function }
   static var clearExistingRules: HTTPParameterKey { #function }
-  static var clearExistingSynonyms: HTTPParameterKey { #function }
+  static var replaceExistingSynonyms: HTTPParameterKey { #function }
   static var createIfNotExists: HTTPParameterKey { #function }
   static var cursor: HTTPParameterKey { #function }
   static var indexName: HTTPParameterKey { #function }

Tests/AlgoliaSearchClientTests/Doc/Methods/SynonymsSnippets.swift

@@ -93,7 +93,7 @@ extension SynonymsSnippets {
   index.saveSynonyms(
     _ #{synonyms}: __[Synonym]__,
     #{forwardToReplicas}: __Bool?__ = nil,
-    #{replaceExistingSynonyms}: __Bool?__ = nil,
+    #{clearExistingSynonyms}: __Bool?__ = nil,
     requestOptions: __RequestOptions?__ = nil,
     completion: __Result<IndexRevision> -> Void__
   )
@@ -105,7 +105,7 @@ extension SynonymsSnippets {
       .multiWay(objectID: "myID2", synonyms: ["street", "st"])
     ]
 
-    index.saveSynonyms(synonyms, forwardToReplicas: true, replaceExistingSynonyms: false) { result in
+    index.saveSynonyms(synonyms, forwardToReplicas: true, clearExistingSynonyms: false) { result in
       if case .success(let response) = result {
         print("Response: \(response)")
       }

Tests/AlgoliaSearchClientTests/Unit/Command/SynonymCommandTests.swift

@@ -89,7 +89,7 @@ class SynonymCommandTests: XCTestCase, AlgoliaCommandTest {
           queryItems: [
               .init(name: "testParameter", value: "testParameterValue"),
               .init(name: "forwardToReplicas", value: "true"),
-              .init(name: "clearExistingSynonyms", value: "true")
+              .init(name: "replaceExistingSynonyms", value: "true")
           ],
           body: synonyms.httpBody,
           requestOptions: test.requestOptions)