docs: update README and docs with complete operator coverage (#45)

Author: mrmans0n

README.md

@@ -38,14 +38,17 @@ Extensions for interoperability with Arrow's `Either` type:
 - **Conversion** - `toAsyncResult()` to convert `Either` to `AsyncResult`
 - **Binding** - `bind()` to flatten `AsyncResult<Either<L, R>>` to `AsyncResult<R>`
 - **Flow conversion** - `asAsyncResult()` to convert `Flow<Either<L, R>>` to `Flow<AsyncResult<R>>`, `toEither()` to convert `Flow<AsyncResult<T>>` to `Either`
+- **Arrow Raise** - `Raise<Error>.bind()` to use `AsyncResult` inside Arrow's `either { }` / `result { }` blocks
 
 ### asyncresult-test
 
 Testing utilities built on [assertk](https://github.com/willowtreeapps/assertk):
 
 - **State assertions** - `isNotStarted()`, `isLoading()`, `isIncomplete()`, `isSuccess()`, `isError()`
 - **Value assertions** - `isSuccessEqualTo()`, `isErrorWithMetadata()`, `isErrorWithMetadataEqualTo()`
-- **Flow assertions** - `assertSuccess()`, `assertError()` for testing flow emissions
+- **Error assertions** - `isErrorWithThrowable()`, `isErrorWithThrowableOfType()`, `isErrorWithThrowableMessage()`, `isErrorWithId()`, `isErrorWithIdEqualTo()`, `hasErrorId()`
+- **Flow assertions** - `assertSuccess()`, `assertError()`, `assertErrorWithMetadata()`, `assertErrorWithId()`, `assertFirstIsLoading()`, `assertFirstIsNotStarted()`, `assertFirstIsIncomplete()`
+- **Collection assertions** - `hasAnyLoading()`, `hasAnyIncomplete()`, `allErrors()`, `allErrorMetadata()`
 
 ## Usage
 

docs/core.md

@@ -27,6 +27,10 @@ val error = Error(
     metadata = NetworkFailure("timeout"),
     errorId = ErrorId("req-123")
 )
+
+// Compose errors with the + operator
+val error = Error(IOException()) + NetworkFailure("timeout") // adds metadata
+val error = Error(IOException()) + ErrorId("req-123")        // adds error ID
 ```
 
 ## Checking state
@@ -317,14 +321,21 @@ val combined = userResult.zipWith(permissionsResult) { user, permissions ->
 
 Supports up to 4 results.
 
-### Spreading
+### Spreading and destructuring
 
 Split a result containing a `Pair` or `Triple`:
 
 ```kotlin
 val (userResult, settingsResult) = pairResult.spread()
 ```
 
+You can also destructure directly without calling `spread()`:
+
+```kotlin
+val (first, second) = pairResult            // component1(), component2()
+val (a, b, c) = tripleResult                // component1(), component2(), component3()
+```
+
 ### Combining collections
 
 Convert a list of results into a result of a list:

docs/either.md

@@ -128,3 +128,18 @@ val either: Either<NetworkError, User> = flow.toEither { error ->
 ```
 
 By default, it attempts to extract the error type from the `Error.metadata`.
+
+## Arrow Raise integration
+
+Use `AsyncResult` inside Arrow's `Raise` context (e.g., `either { }` or `result { }` blocks):
+
+```kotlin
+import io.nlopez.asyncresult.either.bind
+
+val either: Either<Error, User> = either {
+    val user = fetchUser().bind()  // extracts Success or raises Error
+    user
+}
+```
+
+The `Raise<Error>.bind()` extension extracts the value from `Success`, or raises (`shift`) the `Error` for non-success states (`Loading` and `NotStarted` raise `Error.Empty`).

docs/index.md

@@ -33,16 +33,17 @@ The library provides a rich set of operators for transforming, combining, and ex
 
 The core module contains the type hierarchy and all essential utilities:
 
-- **Transformations** - `mapSuccess`, `mapError`, `flatMap`, `bimap`, `fold`, `orError`, `filterOrError`, `castOrError`, `flatten`
-- **Monad comprehension DSL** - `result { }`, `bind()`, `ensure()`, `ensureNotNull()`, `error()`, `loading()`
-- **Value extraction** - `getOrNull`, `getOrDefault`, `getOrElse`, `getOrThrow`, `getOrEmpty`
-- **Side effects** - `onSuccess`, `onLoading`, `onError`, `onNotStarted`
-- **Unwrapping** - `unwrap`, `unwrapError`, `expect`, `expectError` (Rust-style extraction)
+- **Transformations** - `mapSuccess`, `mapError`, `flatMap`, `flatten`, `bimap`, `fold`, `orError`, `filterOrError`, `castOrError`
+- **State checks** - `isSuccess`, `isError`, `isIncomplete`, `isSuccessAnd`, `isErrorAnd`, `isErrorWithMetadataAnd`, `contains`
+- **Value extraction** - `getOrNull`, `getOrDefault`, `getOrElse`, `getOrThrow`, `getOrEmpty`, `errorOrNull`, `errorWithMetadataOrNull`, `throwableOrNull`, `errorIdOrNull`
+- **Side effects** - `onSuccess`, `onLoading`, `onError`, `onErrorWithMetadata`, `onNotStarted`, `onIncomplete`
+- **Unwrapping** - `unwrap`, `unwrapError`, `unwrapThrowable`, `unwrapMetadata`, `unwrapErrorId`, `expect`, `expectError`, `expectThrowable`, `expectMetadata`, `expectErrorId` (Rust-style extraction)
 - **Combining** - `zip`, `zipWith`, `and`, `andThen`, `spread`, `combine`, `sequence`
 - **Recovery** - `recover`, `recoverIf`, `or`, `orElse`
 - **Validation** - `toErrorIf`, `toErrorUnless`
-- **Flow helpers** - `asAsyncResult`, `onLoading`, `onSuccess`, `onError`, `skipWhileLoading`, `cacheLatestSuccess`, `timeoutToError`, `retryOnError`, `retryOnErrorWithMetadata`
-- **Collection utilities** - `errors`, `successes`, `throwables`, `incompletes`, `metadata`, `errorsFrom`, `anyError`, `anyLoading`, `anyIncomplete`
+- **Monad DSL** - `result { }` comprehension with `bind()`, `error()`, `loading()`, `ensure()`, `ensureNotNull()`
+- **Flow helpers** - `asAsyncResult`, `onLoading`, `onSuccess`, `onError`, `onIncomplete`, `skipWhileLoading`, `filterNotLoading`, `cacheLatestSuccess`, `timeoutToError`, `retryOnError`, `retryOnErrorWithMetadata`, `getOrThrow`, `getOrNull`, `getOrElse`
+- **Collection utilities** - `errors`, `successes`, `throwables`, `incompletes`, `metadata`, `anyLoading`, `anyIncomplete`, `anyError`, `errorsFrom`, `combine`, `sequence`, `partition`
 
 [View full documentation](core.md)
 
@@ -53,6 +54,7 @@ Extensions for interoperability with Arrow's `Either` type:
 - **Conversion** - `toAsyncResult()` to convert `Either` to `AsyncResult`
 - **Binding** - `bind()` to flatten `AsyncResult<Either<L, R>>` to `AsyncResult<R>`
 - **Flow conversion** - `asAsyncResult()` to convert `Flow<Either<L, R>>` to `Flow<AsyncResult<R>>`, `toEither()` to convert `Flow<AsyncResult<T>>` to `Either`
+- **Arrow Raise** - `Raise<Error>.bind()` to use `AsyncResult` inside Arrow's `either { }` / `result { }` blocks
 
 [View full documentation](either.md)
 
@@ -62,7 +64,9 @@ Testing utilities built on [assertk](https://github.com/willowtreeapps/assertk):
 
 - **State assertions** - `isNotStarted()`, `isLoading()`, `isIncomplete()`, `isSuccess()`, `isError()`
 - **Value assertions** - `isSuccessEqualTo()`, `isErrorWithMetadata()`, `isErrorWithMetadataEqualTo()`
-- **Flow assertions** - `assertSuccess()`, `assertError()` for testing flow emissions
+- **Error assertions** - `isErrorWithThrowable()`, `isErrorWithThrowableOfType()`, `isErrorWithThrowableMessage()`, `isErrorWithId()`, `isErrorWithIdEqualTo()`, `hasErrorId()`
+- **Flow assertions** - `assertSuccess()`, `assertError()`, `assertErrorWithMetadata()`, `assertErrorWithId()`, `assertFirstIsLoading()`, `assertFirstIsNotStarted()`, `assertFirstIsIncomplete()`
+- **Collection assertions** - `hasAnyLoading()`, `hasAnyIncomplete()`, `allErrors()`, `allErrorMetadata()`
 
 [View full documentation](testing.md)
 

docs/testing.md

@@ -43,12 +43,25 @@ assertThat(result).isError()
 // Check the throwable
 assertThat(result).isError().isThrowableEqualTo(expectedException)
 
+// Check throwable type
+assertThat(result).isErrorWithThrowable()  // asserts Error has a non-null throwable
+assertThat(result).isErrorWithThrowableOfType<IOException>()  // asserts throwable is specific type
+assertThat(result).isErrorWithThrowableMessage("Network error")  // asserts throwable message
+
 // Check metadata
 assertThat(result).isErrorWithMetadata<T, NetworkError>()
 assertThat(result).isErrorWithMetadataEqualTo(NetworkError.Timeout)
 
 // Chain assertions on metadata
 assertThat(result).isError().isMetadataEqualTo(expectedMetadata)
+
+// Check error ID
+assertThat(result).isErrorWithId()  // asserts Error has a non-null errorId
+assertThat(result).isErrorWithIdEqualTo(ErrorId("req-123"))
+assertThat(result).hasErrorId(ErrorId("req-123"))
+
+// Chain assertions on error ID
+assertThat(result).isError().isErrorIdEqualTo(ErrorId("req-123"))
 ```
 
 ## Flow assertions
@@ -62,6 +75,40 @@ flow.assertSuccess(42)
 // Assert the first terminal emission is Error and get it for further checks
 val error: Error = flow.assertError()
 assertThat(error.throwable).isInstanceOf(IOException::class)
+
+// Assert error with typed metadata
+val metadata: NetworkError = flow.assertErrorWithMetadata<NetworkError>()
+
+// Assert error with throwable type
+flow.assertErrorWithThrowableOfType<IOException>()
+
+// Assert error with error ID
+flow.assertErrorWithId(ErrorId("req-123"))
+```
+
+### Initial state assertions
+
+Assert the very first emission (before terminal state):
+
+```kotlin
+flow.assertFirstIsLoading()
+flow.assertFirstIsNotStarted()
+flow.assertFirstIsIncomplete()  // Loading or NotStarted
 ```
 
-These suspend functions wait for the first `Success` or `Error` emission, ignoring `Loading` and `NotStarted` states.
+## Collection assertions
+
+Assert properties of a collection of results:
+
+```kotlin
+val results: List<AsyncResult<Int>> = listOf(Loading, Success(1), Error.Empty)
+
+assertThat(results).hasAnyLoading()
+assertThat(results).hasAnyIncomplete()
+
+// Extract and assert on all errors
+assertThat(results).allErrors().hasSize(1)
+
+// Extract and assert on all error metadata of a specific type
+assertThat(results).allErrorMetadata<NetworkError>().isEmpty()
+```