feat: Mark APIs that return operations with @discardableResult (#633)

refs:#628

Author: palpatim

Amplify/Categories/API/ClientBehavior/APICategoryGraphQLBehavior.swift

@@ -17,6 +17,7 @@ public protocol APICategoryGraphQLBehavior: class {
     ///   - request: The GraphQL request containing apiName, document, variables, and responseType
     ///   - listener: The event listener for the operation
     /// - Returns: The AmplifyOperation being enqueued
+    @discardableResult
     func query<R: Decodable>(request: GraphQLRequest<R>,
                              listener: GraphQLOperation<R>.ResultListener?) -> GraphQLOperation<R>
 
@@ -27,6 +28,7 @@ public protocol APICategoryGraphQLBehavior: class {
     ///   - request: The GraphQL request containing apiName, document, variables, and responseType
     ///   - listener: The event listener for the operation
     /// - Returns: The AmplifyOperation being enqueued
+    @discardableResult
     func mutate<R: Decodable>(request: GraphQLRequest<R>,
                               listener: GraphQLOperation<R>.ResultListener?) -> GraphQLOperation<R>
 

Amplify/Categories/API/ClientBehavior/APICategoryRESTBehavior.swift

@@ -14,35 +14,41 @@ public protocol APICategoryRESTBehavior {
     ///
     /// - Parameter request: Contains information such as path, query parameters, body.
     /// - Returns: An operation that can be observed for its value
+    @discardableResult
     func get(request: RESTRequest, listener: RESTOperation.ResultListener?) -> RESTOperation
 
     /// Perform an HTTP PUT operation
     ///
     /// - Parameter request: Contains information such as path, query parameters, body.
     /// - Returns: An operation that can be observed for its value
+    @discardableResult
     func put(request: RESTRequest, listener: RESTOperation.ResultListener?) -> RESTOperation
 
     /// Perform an HTTP POST operation
     ///
     /// - Parameter request: Contains information such as path, query parameters, body.
     /// - Returns: An operation that can be observed for its value
+    @discardableResult
     func post(request: RESTRequest, listener: RESTOperation.ResultListener?) -> RESTOperation
 
     /// Perform an HTTP DELETE operation
     ///
     /// - Parameter request: Contains information such as path, query parameters, body.
     /// - Returns: An operation that can be observed for its value
+    @discardableResult
     func delete(request: RESTRequest, listener: RESTOperation.ResultListener?) -> RESTOperation
 
     /// Perform an HTTP HEAD operation
     ///
     /// - Parameter request: Contains information such as path, query parameters, body.
     /// - Returns: An operation that can be observed for its value
+    @discardableResult
     func head(request: RESTRequest, listener: RESTOperation.ResultListener?) -> RESTOperation
 
     /// Perform an HTTP PATCH operation
     ///
     /// - Parameter request: Contains information such as path, query parameters, body.
     /// - Returns: An operation that can be observed for its value
+    @discardableResult
     func patch(request: RESTRequest, listener: RESTOperation.ResultListener?) -> RESTOperation
 }

Amplify/Categories/Auth/AuthCategoryBehavior.swift

@@ -24,6 +24,7 @@ public protocol AuthCategoryBehavior: AuthCategoryUserBehavior, AuthCategoryDevi
     ///   - password: password as per the password policy of the provider
     ///   - options: Parameters specific to plugin behavior
     ///   - listener: Triggered when the operation completes.
+    @discardableResult
     func signUp(username: String,
                 password: String?,
                 options: AuthSignUpOperation.Request.Options?,
@@ -39,6 +40,7 @@ public protocol AuthCategoryBehavior: AuthCategoryUserBehavior, AuthCategoryDevi
     ///   - confirmationCode: Confirmation code received to the user.
     ///   - options: Parameters specific to plugin behavior
     ///   - listener: Triggered when the operation completes.
+    @discardableResult
     func confirmSignUp(for username: String,
                        confirmationCode: String,
                        options: AuthConfirmSignUpOperation.Request.Options?,
@@ -50,6 +52,7 @@ public protocol AuthCategoryBehavior: AuthCategoryUserBehavior, AuthCategoryDevi
     ///   - username: Username of the user to be confirmed.
     ///   - options: Parameters specific to plugin behavior.
     ///   - listener: Triggered when the operation completes.
+    @discardableResult
     func resendSignUpCode(for username: String,
                           options: AuthResendSignUpCodeOperation.Request.Options?,
                           listener: AuthResendSignUpCodeOperation.ResultListener?) -> AuthResendSignUpCodeOperation
@@ -64,6 +67,7 @@ public protocol AuthCategoryBehavior: AuthCategoryUserBehavior, AuthCategoryDevi
     ///   - password: Password to signIn the user
     ///   - options: Parameters specific to plugin behavior
     ///   - listener: Triggered when the operation completes.
+    @discardableResult
     func signIn(username: String?,
                 password: String?,
                 options: AuthSignInOperation.Request.Options?,
@@ -77,6 +81,7 @@ public protocol AuthCategoryBehavior: AuthCategoryUserBehavior, AuthCategoryDevi
     ///   - presentationAnchor: Anchor on which the UI is presented.
     ///   - options: Parameters specific to plugin behavior.
     ///   - listener: Triggered when the operation completes.
+    @discardableResult
     func signInWithWebUI(presentationAnchor: AuthUIPresentationAnchor,
                          options: AuthWebUISignInOperation.Request.Options?,
                          listener: AuthWebUISignInOperation.ResultListener?) -> AuthWebUISignInOperation
@@ -92,6 +97,7 @@ public protocol AuthCategoryBehavior: AuthCategoryUserBehavior, AuthCategoryDevi
     ///   - presentationAnchor: Anchor on which the UI is presented.
     ///   - options: Parameters specific to plugin behavior.
     ///   - listener: Triggered when the operation completes.
+    @discardableResult
     func signInWithWebUI(for authProvider: AuthProvider,
                          presentationAnchor: AuthUIPresentationAnchor,
                          options: AuthSocialWebUISignInOperation.Request.Options?,
@@ -103,10 +109,12 @@ public protocol AuthCategoryBehavior: AuthCategoryUserBehavior, AuthCategoryDevi
     ///   - challengeResponse: Challenge response required to confirm the next step in signIn flow
     ///   - options: Parameters specific to plugin behavior.
     ///   - listener: Triggered when the operation completes.
+    @discardableResult
     func confirmSignIn(challengeResponse: String,
                        options: AuthConfirmSignInOperation.Request.Options?,
                        listener: AuthConfirmSignInOperation.ResultListener?) -> AuthConfirmSignInOperation
 
+    @discardableResult
     func signOut(options: AuthSignOutOperation.Request.Options?,
                  listener: AuthSignOutOperation.ResultListener?) -> AuthSignOutOperation
 
@@ -115,6 +123,7 @@ public protocol AuthCategoryBehavior: AuthCategoryUserBehavior, AuthCategoryDevi
     /// - Parameters:
     ///   - options: Parameters specific to plugin behavior
     ///   - listener: Triggered when the operation completes.
+    @discardableResult
     func fetchAuthSession(options: AuthFetchSessionOperation.Request.Options?,
                           listener: AuthFetchSessionOperation.ResultListener?) -> AuthFetchSessionOperation
 
@@ -124,6 +133,7 @@ public protocol AuthCategoryBehavior: AuthCategoryUserBehavior, AuthCategoryDevi
     ///   - username: username whose password need to reset
     ///   - options: Parameters specific to plugin behavior
     ///   - listener: Triggered when the operation completes
+    @discardableResult
     func resetPassword(for username: String,
                        options: AuthResetPasswordOperation.Request.Options?,
                        listener: AuthResetPasswordOperation.ResultListener?) -> AuthResetPasswordOperation
@@ -136,6 +146,7 @@ public protocol AuthCategoryBehavior: AuthCategoryUserBehavior, AuthCategoryDevi
     ///   - confirmationCode: Received confirmation code
     ///   - options: Parameters specific to plugin behavior
     ///   - listener: Triggered when the operation completes
+    @discardableResult
     func confirmResetPassword(for username: String,
                               with newPassword: String,
                               confirmationCode: String,

Amplify/Categories/Auth/AuthCategoryDeviceBehavior.swift

@@ -13,6 +13,7 @@ public protocol AuthCategoryDeviceBehavior: class {
     /// - Parameters:
     ///   - options: Parameters specific to plugin behavior.
     ///   - listener: Triggered when the operation completes.
+    @discardableResult
     func fetchDevices(
         options: AuthFetchDevicesOperation.Request.Options?,
         listener: AuthFetchDevicesOperation.ResultListener?) -> AuthFetchDevicesOperation
@@ -23,6 +24,7 @@ public protocol AuthCategoryDeviceBehavior: class {
     ///   - authDevice: Device to be forgotten
     ///   - options: Parameters specific to plugin behavior.
     ///   - listener: Triggered when the operation completes.
+    @discardableResult
     func forgetDevice(
         _ device: AuthDevice?,
         options: AuthForgetDeviceOperation.Request.Options?,
@@ -33,6 +35,7 @@ public protocol AuthCategoryDeviceBehavior: class {
     /// - Parameters:
     ///   - options: Parameters specific to plugin behavior.
     ///   - listener: Triggered when the operation completes.
+    @discardableResult
     func rememberDevice(
         options: AuthRememberDeviceOperation.Request.Options?,
         listener: AuthRememberDeviceOperation.ResultListener?) -> AuthRememberDeviceOperation

Amplify/Categories/Auth/AuthCategoryUserBehavior.swift

@@ -18,6 +18,7 @@ public protocol AuthCategoryUserBehavior: class {
     /// - Parameters:
     ///   - options: Parameters specific to plugin behavior
     ///   - listener: Triggered when the operation completes.
+    @discardableResult
     func fetchUserAttributes(options: AuthFetchUserAttributeOperation.Request.Options?,
                              listener: AuthFetchUserAttributeOperation.ResultListener?)
         -> AuthFetchUserAttributeOperation
@@ -28,6 +29,7 @@ public protocol AuthCategoryUserBehavior: class {
     ///   - userAttribute: Attribute that need to be updated
     ///   - options: Parameters specific to plugin behavior
     ///   - listener: Triggered when the operation completes.
+    @discardableResult
     func update(userAttribute: AuthUserAttribute,
                 options: AuthUpdateUserAttributeOperation.Request.Options?,
                 listener: AuthUpdateUserAttributeOperation.ResultListener?) -> AuthUpdateUserAttributeOperation
@@ -38,6 +40,7 @@ public protocol AuthCategoryUserBehavior: class {
     ///   - userAttributes: List of attribtues that need ot be updated
     ///   - options: Parameters specific to plugin behavior
     ///   - listener: Triggered when the operation completes.
+    @discardableResult
     func update(userAttributes: [AuthUserAttribute],
                 options: AuthUpdateUserAttributesOperation.Request.Options?,
                 listener: AuthUpdateUserAttributesOperation.ResultListener?) -> AuthUpdateUserAttributesOperation
@@ -48,6 +51,7 @@ public protocol AuthCategoryUserBehavior: class {
     ///   - attributeKey: Attribute to be verified
     ///   - options: Parameters specific to plugin behavior
     ///   - listener: Triggered when the operation completes.
+    @discardableResult
     func resendConfirmationCode(for attributeKey: AuthUserAttributeKey,
                                 options: AuthAttributeResendConfirmationCodeOperation.Request.Options?,
                                 listener: AuthAttributeResendConfirmationCodeOperation.ResultListener?)
@@ -60,6 +64,7 @@ public protocol AuthCategoryUserBehavior: class {
     ///   - confirmationCode: Confirmation code received
     ///   - options: Parameters specific to plugin behavior
     ///   - listener: Triggered when the operation completes.
+    @discardableResult
     func confirm(userAttribute: AuthUserAttributeKey,
                  confirmationCode: String,
                  options: AuthConfirmUserAttributeOperation.Request.Options?,
@@ -73,6 +78,7 @@ public protocol AuthCategoryUserBehavior: class {
     ///   - newPassword: New password to be updated
     ///   - options: Parameters specific to plugin behavior
     ///   - listener: Triggered when the operation completes.
+    @discardableResult
     func update(oldPassword: String,
                 to newPassword: String,
                 options: AuthChangePasswordOperation.Request.Options?,

Amplify/Categories/Predictions/PredictionsCategoryBehavior.swift

@@ -16,6 +16,7 @@ public protocol PredictionsCategoryBehavior {
     /// - Parameter targetLanguage: The language to which the text should be translated
     /// - Parameter options: Parameters to specific plugin behavior
     /// - Parameter listener: Triggered when the event occurs
+    @discardableResult
     func convert(textToTranslate: String,
                  language: LanguageType?,
                  targetLanguage: LanguageType?,
@@ -25,13 +26,15 @@ public protocol PredictionsCategoryBehavior {
     /// - Parameter textToSpeech: The text to be synthesized to audio
     /// - Parameter listener: Triggered when the event occurs
     /// - Parameter options: Parameters to specific plugin behavior
+    @discardableResult
     func convert(textToSpeech: String,
                  options: PredictionsTextToSpeechRequest.Options?,
                  listener: PredictionsTextToSpeechOperation.ResultListener?) -> PredictionsTextToSpeechOperation
 
     /// - Parameter speechToText: The url of the audio to be transcribed
     /// - Parameter listener: Triggered when the event occurs
     /// - Parameter options: Parameters to specific plugin behavior
+    @discardableResult
     func convert(speechToText: URL,
                  options: PredictionsSpeechToTextRequest.Options?,
                  listener: PredictionsSpeechToTextOperation.ResultListener?) -> PredictionsSpeechToTextOperation
@@ -41,6 +44,7 @@ public protocol PredictionsCategoryBehavior {
     /// - Parameter image: The image you are sending
     /// - Parameter options: Parameters to specific plugin behavior
     /// - Parameter listener: Triggered when the event occurs
+    @discardableResult
     func identify(type: IdentifyAction,
                   image: URL,
                   options: PredictionsIdentifyRequest.Options?,
@@ -51,6 +55,7 @@ public protocol PredictionsCategoryBehavior {
     /// - Parameter text: Text to interpret
     /// - Parameter options:Parameters to specific plugin behavior
     /// - Parameter options:Parameters to specific plugin behavior
+    @discardableResult
     func interpret(text: String,
                    options: PredictionsInterpretRequest.Options?,
                    listener: PredictionsInterpretOperation.ResultListener?) -> PredictionsInterpretOperation

Amplify/Categories/Storage/StorageCategoryBehavior.swift

@@ -16,6 +16,7 @@ public protocol StorageCategoryBehavior {
     ///   - options: Parameters to specific plugin behavior
     ///   - resultListener: Triggered when the operation is complete
     /// - Returns: An operation object that provides notifications and actions related to the execution of the work
+    @discardableResult
     func getURL(key: String,
                 options: StorageGetURLOperation.Request.Options?,
                 resultListener: StorageGetURLOperation.ResultListener?) -> StorageGetURLOperation
@@ -28,6 +29,7 @@ public protocol StorageCategoryBehavior {
     ///   - progressListener: Triggered intermittently to represent the ongoing progress of this operation
     ///   - resultListener: Triggered when the download is complete
     /// - Returns: An operation object that provides notifications and actions related to the execution of the work
+    @discardableResult
     func downloadData(key: String,
                       options: StorageDownloadDataOperation.Request.Options?,
                       progressListener: ProgressListener?,
@@ -42,6 +44,7 @@ public protocol StorageCategoryBehavior {
     ///   - progressListener: Triggered intermittently to represent the ongoing progress of this operation
     ///   - resultListener: Triggered when the download is complete
     /// - Returns: An operation object that provides notifications and actions related to the execution of the work
+    @discardableResult
     func downloadFile(key: String,
                       local: URL,
                       options: StorageDownloadFileOperation.Request.Options?,
@@ -57,6 +60,7 @@ public protocol StorageCategoryBehavior {
     ///   - progressListener: Triggered intermittently to represent the ongoing progress of this operation
     ///   - resultListener: Triggered when the upload is complete
     /// - Returns: An operation object that provides notifications and actions related to the execution of the work
+    @discardableResult
     func uploadData(key: String,
                     data: Data,
                     options: StorageUploadDataOperation.Request.Options?,
@@ -72,6 +76,7 @@ public protocol StorageCategoryBehavior {
     ///   - progressListener: Triggered intermittently to represent the ongoing progress of this operation
     ///   - resultListener: Triggered when the upload is complete
     /// - Returns: An operation object that provides notifications and actions related to the execution of the work
+    @discardableResult
     func uploadFile(key: String,
                     local: URL,
                     options: StorageUploadFileOperation.Request.Options?,
@@ -85,6 +90,7 @@ public protocol StorageCategoryBehavior {
     ///   - options: Parameters to specific plugin behavior
     ///   - resultListener: Triggered when the remove is complete
     /// - Returns: An operation object that provides notifications and actions related to the execution of the work
+    @discardableResult
     func remove(key: String,
                 options: StorageRemoveOperation.Request.Options?,
                 resultListener: StorageRemoveOperation.ResultListener?) -> StorageRemoveOperation
@@ -95,6 +101,7 @@ public protocol StorageCategoryBehavior {
     ///   - options: Parameters to specific plugin behavior
     ///   - resultListener: Triggered when the list is complete
     /// - Returns: An operation object that provides notifications and actions related to the execution of the work
+    @discardableResult
     func list(options: StorageListOperation.Request.Options?,
               resultListener: StorageListOperation.ResultListener?) -> StorageListOperation
 }

AmplifyTests/CategoryTests/API/APICategoryClientRESTTests.swift

@@ -34,7 +34,7 @@ class APICategoryClientRESTTests: XCTestCase {
             }
         }
 
-        _ = Amplify.API.get(request: RESTRequest()) { _ in }
+        Amplify.API.get(request: RESTRequest()) { _ in }
 
         waitForExpectations(timeout: 0.5)
     }