Result

A Kotlin library that is explicit about success and failure.

not under active development

The team in which the Result library originated has moved on to use the excellent Arrow library. Therefore Result is not under active development anymore. It still can serve as an example how to create, structure and foster an open source library.

Rationale

Kotlin is explicit about which values can be null. This null-safety is achieved via nullable and non-nullable types. The distinction is made for type T with a question mark: T? means that values can be null, T does not allow null values.

Some developers use nullable types to signify that a computation could fail. A returned null signals that a computation has failed. Even though Kotlin has special syntax to work with nullable types, this is problematic for a number of reasons, among them

• The syntax for working with nullable types is markedly different from the syntax for regular methods.
• By using null to indicate failure we lose all context of what failure occurred.
• By using null clients of the computation are forced to do null-checks, cluttering the code.

These shortcomings resulted in creation of the Result library. It allows a developer to signal that a computation might fail and provide details about the failure.

What about kotlin.Result?

The Kotlin standard library provides a kotlin.Result. It has a similar intent as the Result library but misses the mark for our use-cases. In particular, kotlin.Result failures are restricted to be Throwable. Result library on the other hand does not restrict failures in any way.

Furthermore, kotlin.Result provides methods to inspect the actual kind of result. These invites developers to constantly check if a result is a success or a failure, negating any benefits of wrapping the computation. Result instead provides a rich interface to work with results without the need to know which kind of result it is.

Design

The crux of the Result library is the sealed class Result<Error, Value>. It has two subclasses Success and Failure.

Success is a data class that contains the result of a successful computation as data. Failure is a data class that contains the reason why a computation failed.

Although the sealed Result class allows one to safely switch over a result, that should be avoided. Instead, one should use the various methods on Result to transform data into a desired shape.

Documentation

The API of Result is documented on our wiki. The KDocs can be found on the website.

Development

This project uses Gradle as a build tool. To see which tasks are available run

./gradlew tasks