okay 1.1.0

Typesafe error-handling for dart . An implementation of rust's `Result` type in dart.

okay

Typed error-handling for dart. An implementation of rust's Result type.

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.

---

Note: This package was heavily inspired by rustlang's result type.

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 {}

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

final result = fallibleOp();

final goodString = result.inspect((value) {
  print('Success with value: $value');
}).inspectErr((error) {
  print('Failure with error: $error');
}).unwrapOr('Fallback string');

useString(goodString);




void useString(String value) {
  //
}

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).

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.

OkOrErr on Result<T, T>

• okOrErr Returns value if ok or error if err (as the most precise same type T).

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 andandor 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.