kotlin-result

The Result<V, E> type is a monadic type used for modelling success or failure operations. It follows the concept of Railway Oriented Programming, where execution follows a clear happy path or an unhappy path.

• Ok(value): Represents a successful operation containing the successful value.
• Err(error): Represents a failed operation containing the error that caused the failure.

You can manually create results using Ok and Err, or use helper functions to wrap existing logic:

1. Manual creation: Return Ok(value) for success and Err(error) for failure.
2. runCatching: Wrap code that may throw exceptions to capture the result as a Result<T, Throwable>.
3. toResultOr: Convert nullable types into a Result by providing an error value if the type is null.

Add the following dependency to your build.gradle file to use the core Result monad. Ensure mavenCentral() is included in your repositories.

Note: If you require coroutine support, you must also install the kotlin-result-coroutines artifact.

repositories {
    mavenCentral()
}

dependencies {
    implementation("com.michael-bull.kotlin-result:kotlin-result:2.3.1")
}

Use these functions to transform the contents of a Result without manually unwrapping it:

• map: Transforms the success value.
• mapError: Transforms the error value into a different type.
• mapBoth (or fold): Handles both success and error cases to produce a single value (e.g., mapping a Result to an HTTP response).

Use these functions to combine multiple independent results:

• zip: Returns the combined result or returns early with the first error encountered.
• zipOrAccumulate: Combines results but collects all errors instead of stopping at the first one.

Both support 2-5 arity.

// zip (stops at first error)
fun validate(dto: CustomerDto): Result<Customer, DomainMessage> {
    return zip(
        { PersonalNameParser.parse(dto.firstName, dto.lastName) },
        { EmailAddressParser.parse(dto.email) },
        ::Customer
    )
}

// zipOrAccumulate (collects all errors)
fun validate(dto: CustomerDto): Result<Customer, List<DomainMessage>> {
    return zipOrAccumulate(
        { PersonalNameParser.parse(dto.firstName, dto.lastName) },
        { EmailAddressParser.parse(dto.email) },
        ::Customer
    )
}

When a chain is not linear and later steps need access to intermediate values from earlier steps, use the binding function. This provides an imperative-style block where .bind() unwraps a Result into a named variable. If any .bind() call fails, the entire block short-circuits immediately.

fun save(id: Long, dto: CustomerDto): Result<Event?, DomainMessage> = binding {
    val customerId = parseCustomerId(id).bind()
    val existing = findById(customerId).bind()
    val validated = validate(dto).bind()
    updateEntity(customerId, existing, validated)
}

Use andThen to chain operations where each step depends on the success of the previous one. This is ideal for linear pipelines where the output of one step is the input for the next.

val (status, body) = call.parameters
    .readId()
    .andThen(::parseCustomerId)
    .andThen(::findById)
    .map(::entityToDto)
    .mapBoth(::customerToResponse, ::messageToResponse)

The library provides extension functions for Iterable<Result<V, E>>:

• combine(): Turns a List<Result<V, E>> into a Result<List<V>, E>, returning early with the first error.
• partition(): Splits results into a Pair<List<V>, List<E>> (valid values and errors).
• filterOk(): Extracts only the successful values.
• filterErr(): Extracts only the errors.
• Other functions: allOk, anyOk, countOk, countErr, onEachOk, onEachErr.