Skip to main content

Typed errors (guide)
Run a computation with potential errors

For any given value of val program: Raise<E>.() -> A, the following functions are available:

Handle any potential outcomes​

  • recover(program, error) to recover from any error.
  • fold(program, error, success) to handle error and success case, and re-throw any exceptions.
  • fold(program, exception, error, success) to handle exception, error and success case.

Obtain the result as a wrapper type​

These functions create a Raise scope where all the operators in this section become available.

  • either(program) to obtain Either<E, A>.
  • result(program) to obtain Result<A>, the error type is fixed to Throwable.
  • nullable(program) to obtain A?, the error type is fixed to Null.
  • option(program) to obtain Option<A>, the error type is fixed to None.

Embed any potential errors in the block​

  • If the call has Raise<E> as receiver, nothing is needed.
  • If the call returns a wrapper type (Result, Either, ...), call .bind().
Indicate that an error occurred

DSL syntax​

  • raise to raise a typed error of E meaning that the computation has failed.
  • ensure to raise a typed error of E when predicate is false.
  • ensureNotNull to raise a typed error of E when value is null.

Wrapper types​

  • Either.Left and .left() to wrap a value as error in Either
  • Ior.Left and .leftIor() to wrap a value as error in Ior
Handle potential errors (guide)

These functions allow raising errors of the same type that the surrounding block.

  • recover(program, error) to recover from any error.
  • catch(program, exception) to perform some action when the block throws an exception.
Accumulate errors (guide)

These functions use NonEmptyList<E> as the surrounding error type, or take (E, E) -> E as the error accumulator.

  • zipOrAccumulate to operate over independent blocks, with potentially different types.
  • mapOrAccumulate to operate over a collection of items.
Coroutines / suspended actions (guide)
Run several of them

Independently in parallel​

  • parMap to operate over a collection of items.
  • parZip to combine the result of independent actions, with potentially different return types.

Race (only the fastest is returned)​

  • raceN to race 2 or 3 computations.
Protect from potential problems
  • Schedule.retry to repeat an action until successful.
  • Schedule.repeat to repeat an action, correctly handling problems.
  • resourceScope for correct acquisition and release of resources.

For more resilience options check the corresponding section in the docs.

Immutable data (guide)
Generate optics
  • User-defined data: mark the class with the @optics annotation and apply the KSP plug-in.
  • Collections: traversals that work on every element of a collections are available in the Every object.
Obtain data
  • get obtains the single focused element. (Available for Lens.)
  • getOrNull obtains an optional focused element as nullable. (Available for Optional, Prism, Lens.)
  • getAll obtains all focused elements as List. (Available for every optic.)
  • foldMap combines all the focused elements in a single element. (Available for every optic.)

The Traversal type offers an API closely matching that of Iterable.

Copy value with modified data
  • modify applies an operation to every focused element.
  • set changes the value of every focused element.
  • copy provides a DSL to perform several modifications over the same value.
Generate a new value
  • reverseGet constructs a value by means of a Prism.