okay

Typed Error-handling for dart.

Result<T, E> is a type used for returning and propagating Errors. It is a type with the variants, Ok(T), representing success and containing a value, and Err(E), representing Error and containing an Error value.

ci pub package style: very good analysis License: MIT

Installation

In the dependencies: section of your pubspec.yaml, add the following line:

dependencies:
  okay: <latest_version>

Basic Usage

import 'package:okay/okay.dart';

class FallibleOpFailure {}

final result = fallibleOp();

final goodString = switch(result) {
  Ok(v: final value) => value,
  Err(e: final error) => error,
};

// ------------- OR --------------

final goodString = result.when(
  ok: (value) {
    print('Success with value: $value');
    return value;
  },
  err: (error) {
    print('Failure with Error: $Error');
    return 'Fallback string';
  },
);

useString(goodString);

void useString(String value) {
  //
}

Result<String, FallibleOpFailure> fallibleOp() {
  if (true) {
    return Ok('Very good string');
  } else {
    return Err(FallibleOpFailure());
  }
}

Methods and Getters Overview

Extracting Contained Values

  • expect returns contained value if Ok, throws an exception with provided message if Err.
  • unwrap returns contained value if Ok, throws an exception if Err.
  • unwrapOr returns contained value if Ok, returns the provided fallback value if Err.
  • unwrapOrElse returns contained value if Ok, returns the result of function provided if Err (function takes in the contained Error type and returns a value type).
  • expectErr returns contained Error if Err, throws an exception with provided message if Ok.
  • unwrapErr returns contained Error if Err, throws an exception if Ok.

Inspect, use the contained values without consuming the result

  • inspect Calls the provided closure with the contained value (if Ok) without consuming the result
  • inspectErr Calls the provided closure with the contained Error (if Err) without consuming the result.

Querying the variant

  • isOk Returns true if of Ok variant, false if not.
  • isOkAnd Returns true if the result is Ok and the contained value matches the provided predicate function, otherwise returns false.
  • isErr Returns true if of Err variant, false if not.
  • isErrAnd Returns true if the result is Err and the contained value matches the provided predicate function, otherwise returns false.

Adapters

  • Ok converts a Result<T, E> to a T?, i.e, if Ok, T, if Err, null.

Transforming contained values

  • when Converts a Result<T, E> to a U given a U ErrMap(E) and a U okMap(T)
  • mapOrElse Converts a Result<T, E> to a U given a U ErrMap(E) and a U okMap(T)
  • mapOr Converts a Result<T, E> to a U, given a U fallback and U okMap(T)
  • map Converts a Result<T, E> to Result<U, E> by applying the provided function if to contained value if ok, or returning the original Error if Err.
  • mapErr Converts a Result<T, E> to Result<T, F> by applying the provided function if to contained Error if Err, or returning the original ok if ok.

Compare contained ok or Err values

  • contains Returns true if the result is an Ok value containing the given value, otherwise returns false
  • containsErr Returns true if the result is an Err value containing the given value, otherwise returns false

Boolean operators

These methods treat the Result as a boolean value, where the Ok variant is acts like true and Err acts like false.

The and andor take another Result as input, and produce Result as output. The and method can produce a Result<U, E> value having a different inner type U than Result<T, E>. The or method can produce a Result<T, F> value having a different Error type F than Result<T, E>.

method this input output
and ) Err(e) -- Err(e)
and ) Ok(x) Err(d) Err(d)
and ) Ok(x) Ok(y) Ok(y)
or Err(e) Err(d) Err(d)
or Err(e) Ok(y) Ok(y)
or Ok(x) -- Ok(x)

The andThen and orElse methods take a function as input, and only evaluate the function when they need to produce a new value. The andThen method can produce a Result<U, E> value having a different inner type U than Result<T, E>. The orElse method can produce a Result<T, F> value having a different Error type F than Result<T, E>.

method this function input function result output
andThen Err(e) -- -- Err(e)
andThen Ok(x) x Err(d) Err(d)
andThen Ok(x) x Ok(y) Ok(y)
orElse Err(e) e Err(d) Err(d)
orElse Err(e) e Ok(y) Ok(y)
orElse Ok(x) -- -- Ok(x)

Extension methods on Iterable<Result<T, E>>

  • collect Convert an Iterable<Result<T, E>> to a Result<Iterable<T>, E>. If there is an Err in the iterable, the first Err is returned.
  • collectOr Converts an Iterable<Result<T, E>> to a <Iterable<T>. All Err values are replaced by the provided fallback.
  • collectOrElse Converts an Iterable<Result<T, E>> to a <Iterable<T>. All Err values are replaced by the result of the provided function.
  • sieve Converts an Iterable<Result<T, E>> to a <Iterable<T>. All Err values skipped.
  • sieveErr Converts an Iterable<Result<T, E>> to a <Iterable<E>. All ok values skipped.

Libraries

okay