Merge pull request #582 from skydoves/release/2.2.0

Prepare for release 2.2.0

Author: skydoves

README.md

@@ -28,8 +28,8 @@ Add the dependency below into your **module**'s `build.gradle` file:
 
 ```gradle
 dependencies {
-    implementation("com.github.skydoves:sandwich:2.1.3")
-    implementation("com.github.skydoves:sandwich-retrofit:2.1.3") // For Retrofit (Android)
+    implementation("com.github.skydoves:sandwich:2.2.0")
+    implementation("com.github.skydoves:sandwich-retrofit:2.2.0") // For Retrofit (Android)
 }
 ```
 
@@ -182,12 +182,12 @@ val apiResponse = suspendApiResponseOf { service.request() }
 
 #### ApiResponse Extensions
 
-You can effectively handling `ApiResponse` using the following extensions:
+You can effectively handle `ApiResponse` using the following extensions:
 
 - **onSuccess**: Executes when the `ApiResponse` is of type `ApiResponse.Success`. Within this scope, you can directly access the body data.
-- **onError**: Executes when the `ApiResponse` is of type `ApiResponse.Failure.Error`. Here, you can access the `messareOrNull` and `payload` here.
-- **onException**: Executes when the `ApiResponse` is of type `ApiResponse.Failure.Exception`. You can access the `messareOrNull` and `exception` here.
-- **onFailure**: Executes when the `ApiResponse` is either `ApiResponse.Failure.Error` or `ApiResponse.Failure.Exception`. You can access the `messareOrNull` here.
+- **onError**: Executes when the `ApiResponse` is of type `ApiResponse.Failure.Error`. You can access `messageOrNull` and `payload` here.
+- **onException**: Executes when the `ApiResponse` is of type `ApiResponse.Failure.Exception`. You can access `messageOrNull` and `exception` here.
+- **onFailure**: Executes when the `ApiResponse` is either `ApiResponse.Failure.Error` or `ApiResponse.Failure.Exception`. You can access `messageOrNull` here.
 
 Each scope operates according to its corresponding `ApiResponse` type:
 
@@ -270,6 +270,26 @@ response.toFlow { pokemons ->
 }.flowOn(Dispatchers.IO)
 ```
 
+#### Functional Extensions
+
+Sandwich provides a variety of functional extensions for transforming and composing `ApiResponse`:
+
+- **Recovery**: `recover`, `recoverWith` - Transform failures back into successes with fallback data
+- **Validation**: `validate`, `requireNotNull` - Validate success data and convert it to failure if invalid
+- **Filter**: `filter`, `filterNot` - Filter items in list data within a successful response
+- **Zip/Combine**: `zip`, `zip3` - Combine multiple `ApiResponse` instances into one
+- **Peek/Tap**: `peek`, `peekSuccess`, `peekFailure`, `peekError`, `peekException` - Observe responses without modifying them
+
+```kotlin
+val response = disneyService.fetchDisneyPosterList()
+  .validate({ it.isNotEmpty() }) { "List cannot be empty" }  // Validate data
+  .filter { poster -> poster.isActive }                       // Filter list items
+  .recover(emptyList())                                       // Recover with fallback
+  .peekSuccess { posters -> analytics.track(posters.size) }   // Side effects
+```
+
+All extensions have corresponding `suspend` variants (e.g., `suspendRecover`, `suspendValidate`) for coroutine support. For comprehensive details, refer to the [ApiResponse documentation](https://skydoves.github.io/sandwich/apiresponse/).
+
 ### Retrieving
 
 Sandwich provides effortless methods to directly extract the encapsulated body data from the `ApiResponse`. You can take advantage of the following functionalities:
@@ -540,7 +560,7 @@ interface NetworkEntryPoint {
 
 ##### 2. Provide Global Operator Dependency
 
-Next, provide your global operator with Hilt like the exambple below:
+Next, provide your global operator with Hilt like the example below:
 
 ```kotlin
 @Module

buildSrc/src/main/kotlin/com/github/skydoves/sandwich/Configuration.kt

@@ -22,10 +22,10 @@ object Configuration {
   const val minSdk = 21
   const val minSdkDemo = 21
   const val majorVersion = 2
-  const val minorVersion = 1
-  const val patchVersion = 3
+  const val minorVersion = 2
+  const val patchVersion = 0
   const val versionName = "$majorVersion.$minorVersion.$patchVersion"
-  const val versionCode = 46
+  const val versionCode = 47
   const val snapshotVersionName = "$majorVersion.$minorVersion.${patchVersion + 1}-SNAPSHOT"
   const val artifactGroup = "com.github.skydoves"
 }

docs/apiresponse.md

@@ -111,12 +111,12 @@ val apiResponse = suspendApiResponseOf { service.request() }
 
 ## ApiResponse Extensions
 
-You can effectively handling `ApiResponse` using the following extensions:
+You can effectively handle `ApiResponse` using the following extensions:
 
 - **onSuccess**: Executes when the `ApiResponse` is of type `ApiResponse.Success`. Within this scope, you can directly access the body data.
-- **onError**: Executes when the `ApiResponse` is of type `ApiResponse.Failure.Error`. Here, you can access the `messareOrNull` and `payload` here.
-- **onException**: Executes when the `ApiResponse` is of type `ApiResponse.Failure.Exception`. You can access the `messareOrNull` and `exception` here.
-- **onFailure**: Executes when the `ApiResponse` is either `ApiResponse.Failure.Error` or `ApiResponse.Failure.Exception`. You can access the `messareOrNull` here.
+- **onError**: Executes when the `ApiResponse` is of type `ApiResponse.Failure.Error`. You can access `messageOrNull` and `payload` here.
+- **onException**: Executes when the `ApiResponse` is of type `ApiResponse.Failure.Exception`. You can access `messageOrNull` and `exception` here.
+- **onFailure**: Executes when the `ApiResponse` is either `ApiResponse.Failure.Error` or `ApiResponse.Failure.Exception`. You can access `messageOrNull` here.
 
 Each scope operates according to its corresponding `ApiResponse` type:
 
@@ -197,4 +197,220 @@ response.toFlow { pokemons ->
   pokemonDao.insertPokemonList(pokemons)
   pokemonDao.getAllPokemonList(page)
 }.flowOn(Dispatchers.IO)
+```
+
+## Recovery
+
+Sandwich provides recovery extensions to transform a failed `ApiResponse` back into a successful one with fallback data.
+
+### recover
+
+Returns an `ApiResponse.Success` with the fallback value if the response is a failure, otherwise returns the original success:
+
+```kotlin
+val response = disneyService.fetchDisneyPosterList()
+  .recover(emptyList()) // Returns empty list if the request fails
+
+// With a lambda for lazy evaluation
+val response = disneyService.fetchDisneyPosterList()
+  .recover { cachedPosters }
+```
+
+### recoverWith
+
+Recovers the failure by executing an alternative `ApiResponse`:
+
+```kotlin
+val response = disneyService.fetchDisneyPosterList()
+  .recoverWith { failure ->
+    // Try an alternative data source on failure
+    localDatabase.fetchCachedPosters()
+  }
+```
+
+For coroutines, use `suspendRecover` and `suspendRecoverWith`:
+
+```kotlin
+val response = disneyService.fetchDisneyPosterList()
+  .suspendRecoverWith { failure ->
+    backupService.fetchPosters() // suspend function
+  }
+```
+
+## Validation
+
+Validation extensions allow you to validate success data and convert it to a failure if the validation fails.
+
+### validate
+
+Validates the success data with a predicate. If the predicate returns false, the response is converted to `ApiResponse.Failure.Error`:
+
+```kotlin
+val response = disneyService.fetchDisneyPosterList()
+  .validate(
+    predicate = { it.isNotEmpty() },
+    errorMessage = { "Poster list cannot be empty" }
+  )
+```
+
+### requireNotNull
+
+Requires a non-null value from the success data. If the selected value is null, the response is converted to `ApiResponse.Failure.Error`:
+
+```kotlin
+val response = userService.fetchUser()
+  .requireNotNull(
+    selector = { it.profileImage },
+    errorMessage = { "Profile image is required" }
+  )
+```
+
+For coroutines, use `suspendValidate` and `suspendRequireNotNull`:
+
+```kotlin
+val response = userService.fetchUser()
+  .suspendValidate { user ->
+    userValidator.isValid(user) // suspend function
+  }
+```
+
+## Filter
+
+Filter extensions allow you to filter items in list data within an `ApiResponse`.
+
+### filter
+
+Filters the items in the success data list, keeping only items that match the predicate:
+
+```kotlin
+val response = disneyService.fetchDisneyPosterList()
+  .filter { poster -> poster.isActive }
+```
+
+### filterNot
+
+Filters the items in the success data list, excluding items that match the predicate:
+
+```kotlin
+val response = disneyService.fetchDisneyPosterList()
+  .filterNot { poster -> poster.isDeprecated }
+```
+
+For coroutines, use `suspendFilter` and `suspendFilterNot`:
+
+```kotlin
+val response = disneyService.fetchDisneyPosterList()
+  .suspendFilter { poster ->
+    posterValidator.isValid(poster) // suspend function
+  }
+```
+
+## Zip / Combine
+
+Zip extensions allow you to combine multiple `ApiResponse` instances into a single response.
+
+### zip
+
+Combines two `ApiResponse` instances. If both are successful, the transform function is applied. If either is a failure, the first failure is returned:
+
+```kotlin
+val usersResponse = userService.fetchUsers()
+val postersResponse = disneyService.fetchPosters()
+
+val combined = usersResponse.zip(postersResponse) { users, posters ->
+  HomeData(users = users, posters = posters)
+}
+
+// Or combine into a Pair
+val paired = usersResponse.zip(postersResponse) // Returns ApiResponse<Pair<Users, Posters>>
+```
+
+### zip3
+
+Combines three `ApiResponse` instances:
+
+```kotlin
+val response1 = service.fetchUsers()
+val response2 = service.fetchPosters()
+val response3 = service.fetchSettings()
+
+val combined = response1.zip3(response2, response3) { users, posters, settings ->
+  AppData(users = users, posters = posters, settings = settings)
+}
+```
+
+For coroutines, use `suspendZip` and `suspendZip3`:
+
+```kotlin
+val combined = response1.suspendZip(response2) { data1, data2 ->
+  processData(data1, data2) // suspend function
+}
+```
+
+## Peek / Tap
+
+Peek extensions allow you to observe the `ApiResponse` without modifying it. This is useful for logging, analytics, or side effects.
+
+### peek
+
+Performs an action on the `ApiResponse` regardless of its type:
+
+```kotlin
+val response = disneyService.fetchDisneyPosterList()
+  .peek { response ->
+    logger.log("Response received: $response")
+  }
+```
+
+### peekSuccess
+
+Performs an action only if the response is successful:
+
+```kotlin
+val response = disneyService.fetchDisneyPosterList()
+  .peekSuccess { posters ->
+    analytics.trackPostersLoaded(posters.size)
+  }
+```
+
+### peekFailure
+
+Performs an action only if the response is a failure (either error or exception):
+
+```kotlin
+val response = disneyService.fetchDisneyPosterList()
+  .peekFailure { failure ->
+    logger.error("Request failed: ${failure.message()}")
+  }
+```
+
+### peekError
+
+Performs an action only if the response is `ApiResponse.Failure.Error`:
+
+```kotlin
+val response = disneyService.fetchDisneyPosterList()
+  .peekError { error ->
+    errorTracker.trackApiError(error.statusCode)
+  }
+```
+
+### peekException
+
+Performs an action only if the response is `ApiResponse.Failure.Exception`:
+
+```kotlin
+val response = disneyService.fetchDisneyPosterList()
+  .peekException { exception ->
+    crashReporter.recordException(exception.throwable)
+  }
+```
+
+For coroutines, use `suspendPeek`, `suspendPeekSuccess`, `suspendPeekFailure`, `suspendPeekError`, and `suspendPeekException`:
+
+```kotlin
+val response = disneyService.fetchDisneyPosterList()
+  .suspendPeekSuccess { posters ->
+    cache.savePosters(posters) // suspend function
+  }
 ```

docs/operator.md

@@ -196,7 +196,7 @@ interface NetworkEntryPoint {
 
 ### 2. Provide Global Operator Dependency
 
-Next, provide your global operator with Hilt like the exambple below:
+Next, provide your global operator with Hilt like the example below:
 
 ```kotlin
 @Module