Package: groovy.concurrent

## [Java] Class AwaitResult<T>

- groovy.concurrent.AwaitResult

-     public final class AwaitResult<T>
      extends Object

  Represents the outcome of an asynchronous computation that may have succeeded or failed. Returned by Awaitable.allSettled to report each individual task's result without short-circuiting on failure.

  An `AwaitResult` is either a {@linkplain #isSuccess() success} carrying a value, or a {@linkplain #isFailure() failure} carrying a Throwable.

  This type follows the value object pattern: two instances are {@linkplain #equals(Object) equal} if and only if they have the same success/failure state and carry equal values or errors. Immutability is enforced — all fields are final and no mutating methods are exposed.

  Functional composition is supported via map(Function), enabling transformation chains without unwrapping:

       AwaitResult<Integer> length = AwaitResult.success("hello").map(String::length)

  Inspired by Kotlin's `Result`, Rust's `Result<T, E>`, and C#'s pattern of structured success/error responses.

  Type Parameters:
    `T` - the value type
  Since:
    6.0.0

- - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public boolean` | `equals(Object o)` Compares this result to another object for equality.
    `<T>` | `public static AwaitResult<T>` | `failure(Throwable error)` Creates a failure result with the given exception.
    `` | `public Throwable` | `getError()` Returns the exception if failed.
    `` | `public T` | `getOrElse(Function<Throwable, ? extends T> fallback)` Returns the value if successful, or applies the given function to the error to produce a fallback value.
    `` | `public T` | `getValue()` Returns the value if successful.
    `` | `public int` | `hashCode()` Returns a hash code consistent with equals(Object).
    `` | `public boolean` | `isFailure()` Returns `true` if this result represents a failed completion.
    `` | `public boolean` | `isSuccess()` Returns `true` if this result represents a successful completion.
    `<U>` | `public AwaitResult<U>` | `map(Function<? super T, ? extends U> fn)` Transforms a successful result's value using the given function.
    `<T>` | `public static AwaitResult<T>` | `success(Object value)` Creates a successful result with the given value.
    `` | `public String` | `toString()` Returns a human-readable representation of this result: `AwaitResult.Success[value]` or `AwaitResult.Failure[error]`.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### public boolean equals(Object o)

      Compares this result to another object for equality.

      Two `AwaitResult` instances are equal if and only if they have the same success/failure state and carry {@linkplain Objects#equals(Object, Object) equal} values or errors.

      Parameters:
        `o` - the object to compare with
      Returns:
        `true` if the given object is an equal `AwaitResult`

    - #### <T> public static AwaitResult<T> failure(Throwable error)

      Creates a failure result with the given exception.

      throws:
        NullPointerException if `error` is `null`
      Parameters:
        `error` - the exception that caused the failure; must not be `null`
      Type Parameters:
        `T` - the value type (never actually used, since the result is a failure)
      Returns:
        a failure result wrapping the exception

    - #### public Throwable getError()

      Returns the exception if failed.

      throws:
        IllegalStateException if this result represents a success
      Returns:
        the exception that caused the failure

    - #### public T getOrElse(Function<Throwable, ? extends T> fallback)

      Returns the value if successful, or applies the given function to the error to produce a fallback value.

      Parameters:
        `fallback` - the function to apply to the error if this result is a failure; must not be `null`
      Returns:
        the value, or the fallback function's result

    - #### public T getValue()

      Returns the value if successful.

      throws:
        IllegalStateException if this result represents a failure
      Returns:
        the computation result

    - #### public int hashCode()

      Returns a hash code consistent with equals(Object).

      Returns:
        the hash code

    - #### public boolean isFailure()

      Returns `true` if this result represents a failed completion.

    - #### public boolean isSuccess()

      Returns `true` if this result represents a successful completion.

    - #### <U> public AwaitResult<U> map(Function<? super T, ? extends U> fn)

      Transforms a successful result's value using the given function. If this result is a failure, the error is propagated unchanged.

      This is the functor `map` operation, enabling value transformation without explicit unwrapping:

           AwaitResult<String>  name   = AwaitResult.success("Groovy")
           AwaitResult<Integer> length = name.map(String::length)
           assert length.value == 6

      throws:
        NullPointerException if `fn` is `null`
      Parameters:
        `fn` - the mapping function; must not be `null`
      Type Parameters:
        `U` - the type of the mapped value
      Returns:
        a new success result with the mapped value, or the original failure unchanged

    - #### <T> public static AwaitResult<T> success(Object value)

      Creates a successful result with the given value.

      Parameters:
        `value` - the computation result (may be `null`)
      Type Parameters:
        `T` - the value type
      Returns:
        a success result wrapping the value

    - #### public String toString()

      Returns a human-readable representation of this result: `AwaitResult.Success[value]` or `AwaitResult.Failure[error]`.