Line data    Source code

       1             : /// A generic class for representing the result of an API operation.
       2             : ///
       3             : /// The `ARoResult` class is a generic wrapper that holds the outcome of an API
       4             : /// operation. It can represent either a successful result or a failure. This
       5             : /// class helps in managing and handling responses from API calls more effectively
       6             : /// by providing a unified way to handle both success and failure cases.
       7             : ///
       8             : /// **Generic Type Parameters**:
       9             : /// - `Failure`: The type of the failure result, if the operation fails.
      10             : /// - `Success`: The type of the success result, if the operation succeeds.
      11             : ///
      12             : /// **Properties**:
      13             : /// - `failure`: An instance of `Failure` representing the error result, or `null` if the operation was successful.
      14             : /// - `success`: An instance of `Success` representing the successful result, or `null` if the operation failed.
      15             : /// - `isFailure`: A boolean indicating whether the result represents a failure (`true`) or a success (`false`).
      16             : ///
      17             : /// **Factory Constructors**:
      18             : /// - `ARoResult.failure(Failure failure)`
      19             : ///    Creates an `ARoResult` instance representing a failure.
      20             : ///
      21             : /// - `ARoResult.success(Success success)`
      22             : ///    Creates an `ARoResult` instance representing a success.
      23             : ///
      24             : /// **Methods**:
      25             : /// - `when<T>(T Function(Failure) failure, T Function(Success) success)`
      26             : ///    Executes the appropriate function based on whether the result is a failure or a success.
      27             : ///
      28             : ///   - `failure`: A function to handle the failure case, taking a `Failure` parameter and returning a value of type `T`.
      29             : ///
      30             : ///   - `success`: A function to handle the success case, taking a `Success` parameter and returning a value of type `T`.
      31             : ///
      32             : ///   - Returns the result of the function that matches the current state (`failure` or `success`).
      33             : ///
      34             : /// **Example**:
      35             : /// ```dart
      36             : ///     ARoResult<String, int> result = ARoResult.success(42);
      37             : ///
      38             : ///     result.when(
      39             : ///       (failure) => print('Failure: $failure'),
      40             : ///       (success) => print('Success: $success'),
      41             : ///     ); // Output: Success: 42
      42             : ///
      43             : ///     ARoResult<String, int> errorResult = ARoResult.failure('An error occurred');
      44             : ///
      45             : ///     errorResult.when(
      46             : ///       (failure) => print('Failure: $failure'),
      47             : ///       (success) => print('Success: $success'),
      48             : ///     ); // Output: Failure: An error occurred
      49             : /// ```
      50             : class ARoResult<Failure, Success> {
      51           2 :   ARoResult._(this.failure, this.success, this.isFailure);
      52             : 
      53             :   final Failure? failure;
      54             :   final Success? success;
      55             :   final bool isFailure;
      56             : 
      57           2 :   factory ARoResult.failure(Failure failure) {
      58             :     /// Creates an `ARoResult` instance representing a failure.
      59             :     ///
      60             :     /// This factory constructor initializes an `ARoResult` with the provided
      61             :     /// failure value and sets `isFailure` to `true`.
      62           2 :     return ARoResult._(failure, null, true);
      63             :   }
      64             : 
      65           2 :   factory ARoResult.success(Success success) {
      66             :     /// Creates an `ARoResult` instance representing a success.
      67             :     ///
      68             :     /// This factory constructor initializes an `ARoResult` with the provided
      69             :     /// success value and sets `isFailure` to `false`.
      70           2 :     return ARoResult._(null, success, false);
      71             :   }
      72             : 
      73           1 :   T when<T>(T Function(Failure) failure, T Function(Success) success) {
      74             :     /// Executes the appropriate function based on whether the result is a failure or a success.
      75             :     ///
      76             :     /// - `failure`: A function to handle the failure case, taking a `Failure` parameter and returning a value of type `T`.
      77             :     /// - `success`: A function to handle the success case, taking a `Success` parameter and returning a value of type `T`.
      78             :     ///
      79             :     /// Returns the result of the function that matches the current state (`failure` or `success`).
      80           1 :     if (isFailure) {
      81           2 :       return failure(this.failure as Failure);
      82             :     } else {
      83           2 :       return success(this.success as Success);
      84             :     }
      85             :   }
      86             : }