package tezos-lwt-result-stdlib

Lwt, result, and Lwt-result monad operators

This module provides the necessary functions and operators to use Lwt, Result and Lwt-Result as monads.

Basics

The three, tiered monads have each their own syntax module with

• a return function,
• preallocated return_unit, return_none, etc. values,
• let* and let+ bindind operators.

In addition, the Lwt_syntax module has and* and and+ binding operators to allow concurrent evaluation of two or more promises, and the Result_syntax and Lwt_result_syntax have fail functions to error-out.

Joins

The Lwt_syntax.join function takes a list of promises ps and returns a single promise p that resolves with () when all the promises of ps have resolved.

The Lwt_syntax.all function takes a list of promises ps and returns a single promise p that resolves when all the promises of ps have resolved. The value p resolves to is the list of values the promises of ps resolve to. The order is preserved.

The Lwt_syntax.both function takes two promises p1 and p2 and returns a single promise p that resolves when both promises p1 and p2 have resolved. The value p resolves to is the tuple of values the promises p1 and p2 resolve to.

These Lwt-joining functions have a best-effort semantic: they only resolve once all the underlying promises have resolved.

The Result_syntax variants are equivalent for the result monad: the final result is Ok if all the underlying results are Ok.

The Lwt_result_syntax variants are equivalent for the Lwt-result monad: the final promise resolves to Ok if all the underlying promise resolve to Ok.

Lifting

Finally, the Lwt_result_syntax module includes two facilities for lifting values from the more specilaised Lwt-only and Result-only monads.

let*! binds a plain Lwt promise into an Lwt-Result promise.

let open Lwt_result_syntax in
let*! x = f a b c in
…

let*? binds a plain result into an Lwt-Result promise.

let open Lwt_result_syntax in
let*? y = f u v w in
…

In the cases where performance is not a grave concern, it is also possible to use Lwt_result.ok to lift Lwt-only expressions and Lwt.return to lift result-only expressions. More details on the matter within the documentation of Lwt_result_syntax.(let*!) and Lwt_result_syntax.(let*?) themselves.