Most approaches capture whether something succeeded or failed, but do not have a mechanism for also indicating what the kind of success or failure it was. This is the primary gap that this library is aiming to solve.

kiit-result is a Result<T, E> with kiit-codes' closed status taxonomy built in. Success carries a Passed status, Failure carries a Failed status, and builders (restricted(), invalid(), ...) map each case to its matching category automatically. See Concepts and Builders for the full picture.

import kiit.codes.Err
import kiit.codes.Invalid
import kiit.codes.Rejected
import kiit.codes.Restricted
import kiit.codes.Succeeded
import kiit.result.Outcome
import kiit.result.Outcomes

class UserService {
    private val users = mutableMapOf<String, User>()

    // Alias Outcome<User> = Result<User, Err>
    // Err is an error type from kiit-codes.
    fun create(id: String, email: String): Outcome<User> = when {
        // Restricted: a reserved id, not allowed
        id == "admin" -> Outcomes.restricted(Restricted.DENIED)
        // Invalid: bad input
        email.isBlank() -> Outcomes.invalid(Err.on("email", email, "email is required"))
        // Rejected: already exists
        users.containsKey(id) -> Outcomes.rejected(Rejected.CONFLICT)
        // Succeeded: created
        else -> {
            val user = User(id, email)
            users[id] = user
            Outcomes.success(user)
        }
    }
}

val outcome: Outcome<User> = userService.create("alice", "alice@example.com")
when (val status = outcome.status) {
    is Succeeded -> println("created")
    is Restricted -> println("not allowed: ${status.name}")
    is Invalid -> println("bad input: ${status.name}")
    is Rejected -> println("conflict: ${status.name}")
    else -> println("failed: ${status.name}")
}

Gradle (Kotlin DSL):

dependencies {
    implementation("dev.kiit:kiit-result:1.0.2")
}

kiit-result depends on dev.kiit:kiit-codes transitively — you don't need to add it separately.

Return an Outcome<T> (Result<T, Err>) using the builder methods:

import kiit.result.Outcome
import kiit.result.Outcomes

fun createUser(email: String): Outcome<String> =
    if (email.isBlank()) Outcomes.invalid("email required") else Outcomes.success(email)

Compose with map/flatMap/fold:

createUser("alice@example.com")
    .map { it.uppercase() }
    .onSuccess { println("registered: $it") }
    .onFailure { err -> println("could not register: ${err.message}") }

See samples/sample-kotlin for a runnable end-to-end Kotlin example, or samples/sample-java for the same library used from plain Java.

Swift: not yet distributed via SPM/XCFramework, but SKIE already gives real, compiler-enforced Swift exhaustiveness over Success/Failure. See samples/sample-swift for a runnable example, or the Swift Interop guide for the full picture, including what doesn't work yet.

Result<T, E> = Success<T> | Failure<E>

Success<T>.status : Passed    (from kiit-codes)
Failure<E>.status : Failed    (from kiit-codes)
Result<T, E>.action : Action? (optional, both branches)

Every Result carries a status from kiit-codes' own taxonomy, not just Failure: Passed (Succeeded, Pending, Excluded, Information) or Failed (Restricted, Invalid, Rejected, Unserved). See the kiit-codes docs for the full set of groups and codes.

Option<T>, Try<T>, Outcome<T>, and Validated<T> are type aliases fixing E for common cases, each with a matching builder already wired up:

Composition operators mirror what you'd expect from Result/Either in other languages — map, flatMap/then, fold, getOrElse, recover, and friends, plus withStatus/withAction for attaching a status/operation context after construction. See the full operator reference for the complete list.

A List<Result<T, E>> adds its own operators: combine() sequences the list into one Result<List<T>, E>, short-circuiting on the first Failure; partition() splits it into successes and errors; allSuccess/allFailure/anySuccess/anyFailure check the batch without building a new Result.

Builder<E> provides status-aware factory methods so you rarely build Success/Failure directly. Outcomes/Options/Tries/Validations are the ready-made implementations, one per alias.

Note that excluded() builds a Success, not a Failure — an intentionally excluded item (deduplicated, disqualified, filtered out) is a kiit-codes Passed.Excluded status, not a failure. There's no separate conflict() — it's rejected(status = Rejected.CONFLICT), since a conflict is just a specific Rejected outcome, not its own category.

See the Builders docs for the full Builder<E> architecture, Options.some/none, and worked examples for Outcomes/Options/Tries/Validations.

• toOutcome() — converts any Result<T, E> to Outcome<T> (Result<T, Err>), building an Err from whatever the failure held (String, Exception, or an existing Err).
• toTry() — converts any Result<T, E> to Try<T> (Result<T, Throwable>). An Err-typed failure becomes a kiit-codes StatusException via Failed.toException(errors), so the exception still carries the original status and error detail.
• Tries.of { ... } — the reverse direction: if the block throws a StatusException (RestrictedException/InvalidException/RejectedException/UnservedException), the resulting Try is built with the matching restricted/invalid/rejected/unserved status instead of a generic failure.

1. Service layers — return Outcome<T> instead of throwing for expected failures.
2. Pipelines — map/flatMap chains compose without manual null/exception checks at each step.
3. Validation — Validated<T> (Result<T, Err.ErrorList>) collects multiple errors via Validations.
4. Exception boundaries — toTry()/Tries.of interop with StatusException when a caller only understands exceptions.
5. HTTP/gRPC responses — result.status converts via kiit-codes' CodesToHttp/CodesToGrpc.

Good fit if:

1. You want explicit, monadic return values instead of throw/catch for expected failures.
2. You're already using (or want) kiit-codes' status taxonomy and want a Result type layered on top of it, instead of a bespoke one.
3. You need to compose several fallible steps (map/flatMap) without nested try/catch.

Probably not necessary if:

1. Exceptions already communicate everything you need, and you don't want the monadic-return-value style.
2. You only need status classification, not a Result wrapper — in which case see kiit-codes on its own.

kiit-result has been extracted from the Kiit toolkit and polished as a standalone module. This has been used in production for over 4+ years to power mobile and server kotlin applications. Current work is focused on the Kotlin release, documentation, examples, and ecosystem integration.

See GitHub Issues for current work and discussions.

• Kotlin Multiplatform
• JVM, Android, JS (IR), iOS (arm64, simulator arm64, x64)
• Depends on dev.kiit:kiit-codes (transitively available to consumers via api)

Contributions and design feedback are welcome. See BUILD.md for build, test, and publish instructions.

Apache License 2.0