kiit.result is a Result<T, E> type for Kotlin Multiplatform — similar to Result in Rust and Swift, or Try in Scala. It models the outcome of an operation as one of two branches, Success<T> or Failure<E>, each carrying an optional kiit-codes Status so a caller can inspect why, not just whether.

Modeling an operation this way means answering four separable questions, not one:

1. Did it work? — Success<T> or Failure<E>.
2. What kind of outcome was it? — status: Status, a closed taxonomy from kiit-codes (Succeeded, Restricted, Invalid, Rejected, ...).
3. What went wrong, specifically? — the Failure branch's error: E, most commonly kiit-codes' Err, carrying per-instance detail a fixed status can't.
4. What was being done, and under what circumstances? — an optional action: Action?, naming the operation and any correlation id/attributes, attached via withAction.

It builds directly on kiit-codes rather than reimplementing status classification:

1. A monadic Result<T, E> — map, flatMap/then, fold, onSuccess/onFailure, getOrElse, and friends, so success/failure handling composes without manual if/else branching.
2. A flexible error type — the Failure branch's error type E can be anything: String, Throwable, kiit-codes' Err, or your own domain type. Type aliases (Try<T>, Option<T>, Outcome<T>) cover the common cases.
3. Status-aware builders — restricted/invalid/rejected/unserved/excluded build a Result pre-populated with the matching kiit-codes status category, so you rarely construct Success/Failure by hand.

val outcome: Outcome<User> = userService.create("alice", "alice@example.com")
outcome.fold(
    { user -> println("created ${user.id}") },
    { err -> println("failed: ${err.message} (${outcome.status.name})") },
)

Returning null for "not found" loses the reason. Throwing for expected, recoverable failures (validation, a conflict, an unauthorized caller) is expensive and easy to over- or under-catch. And once you do return a status/error pair by convention, every caller ends up re-deriving the same success/failure branching logic by hand.

A Result<T, E> that composes the usual monadic operations with kiit-codes' closed status taxonomy, instead of a bespoke or numeric status of its own. Success carries a kiit-codes Passed status (Succeeded, Pending, Excluded, Information); Failure carries a Failed status (Restricted, Invalid, Rejected, Unserved). Builders map each common case to its matching category, so restricted() gives you Restricted.DENIED, invalid() gives you Invalid.INVALID_VALUE, and so on — without hand-rolling a status object at every call site.

Gradle (Kotlin DSL):

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

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.codes.Invalid
import kiit.codes.Rejected
import kiit.result.Outcome
import kiit.result.OutcomeBuilder

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

    fun create(id: String, email: String): Outcome<User> {
        if (email.isBlank()) return invalid(Invalid.BAD_REQUEST)
        if (users.containsKey(id)) return rejected(Rejected.CONFLICT)
        val user = User(id, email)
        users[id] = user
        return success(user)
    }
}

Compose with map/flatMap/fold:

import kiit.result.flatMap

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

Convert to a Try<T> to cross an exception-only boundary:

// Wraps a Failure<Err> into a Failure<StatusException> from kiit-codes
val asTry = userService.fetch("missing").toTry()
asTry.onFailure { ex -> println("caught: ${ex.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 (the framework is .framework-only today, built locally). Companion-less members like Outcomes/Options/Tries get clean .shared access out of the box, and this module uses SKIE for real, compiler-enforced Swift exhaustiveness over Success/Failure — a genuinely flat switch, simpler than kiit-codes' nested Status case, since Result<T, E> is only one sealed level deep:

import KiitResult

let result = Success(value: KotlinInt(value: 42))

func describe<T, E>(_ r: Result<T, E>) -> String {
    switch onEnum(of: r) {
    case .success(let s): return "ok: \(String(describing: s.value))"
    case .failure(let f): return "err: \(String(describing: f.error))"
    }
}

Generic type params require AnyObject (box Int/String as KotlinInt/NSString), and Kotlin's Nothing doesn't widen to a concrete error type in Swift — see samples/sample-swift for the full, verified-working subset and exactly what does and doesn't work (including a confirmed-broken case: flatMap can't be used from Swift to construct new results).

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)

Composition operators mirror what you'd expect from Result/Either in other languages: map, mapError, flatMap/then, fold, exists, getOrNull, getOrElse, onSuccess, onFailure, transform, contains, inner (flattens a nested Result), plus or/and/operate for combining two Results, and withStatus/withAction for attaching a status/operation context after construction. Once attached, action survives map/mapError/toOutcome()/toTry(), the same as status does.

Builder<E> provides status-aware factory methods so you rarely build Success/Failure directly. It's composed from two smaller interfaces, one per branch, so each stays scoped to its own category constants (the same reason kiit-codes keeps Succeeded/Restricted/etc. constants on their own companions rather than one shared object):

• PassedBuilder<E> — success/pending/excluded, each with 3 overloads: no-arg, (value, message: String? = null), and (value, status).
• FailedBuilder<E> — restricted/invalid/rejected/unserved, each with 5 overloads: no-arg, (message), (ex, status?), (err, status?), (status).

Builder/PassedBuilder/FailedBuilder live in kiit.result.builders — they're the extensible machinery you implement (directly, or via Outcomes/Options/Tries), not something most callers import directly. Outcomes/Options/Tries themselves stay in kiit.result, alongside Result/Success/Failure, since those are the ready-made, everyday API.

Note that excluded() builds a Success, not a Failure — an intentionally excluded/skipped 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.

Options also adds some(value)/none(...) on top of the generic builders above — a discoverable Some/None-style pair for Option<T> specifically (see Core concepts). none() defaults to Rejected.NOT_EXISTS, distinct from the generic Unserved.UNEXPECTED fallback:

import kiit.result.Options

val a = Options.some(42)                    // Option<Int> — present
val b = Options.none<Int>()                 // Option<Int> — absent, Rejected.NOT_EXISTS
val c = Options.none<Int>(Rejected.CONFLICT) // Option<Int> — absent, custom status

Outcomes/Options/Tries are the three ready-made Builder implementations, one per common error type:

import kiit.result.Outcomes
import kiit.result.Options
import kiit.result.Tries

val a = Outcomes.attempt { riskyCall() }  // Outcome<T>  — catches Throwable, wraps as Err
val b = Options.of { riskyCall() }        // Option<T>   — catches Throwable, discards detail
val c = Tries.attempt { riskyCall() }     // Try<T>      — catches Throwable, re-derives status
                                            //               from a thrown kiit-codes StatusException

• 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.
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.

Note: this FAQ predates the multiplatform export work — @JsExport/@JsName (JS/TS) and SKIE (iOS/Swift) are both applied now; see the JS/iOS answer below for current status.

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

• [ ] npm publish pipeline for JS consumers (@kiit/result)
• [ ] SPM / XCFramework pipeline for Swift consumers — SKIE is now applied for real Swift exhaustiveness (see Quick Start above and samples/sample-swift), but distribution itself (an actual .xcframework + SPM package, publishing to kiit-spm) is still unbuilt
• [ ] Diagrams and a fuller FAQ, matching kiit-codes' README
• [ ] Raise<E>-style DSL (result { } + .bind()) as a flat, non-nested alternative to .then { } chaining for multi-step composition — needs Kotlin context parameters, which are experimental as of 2.3.x and reach Stable in 2.4.0

Track progress or open a discussion in Issues.

Contributions are welcome — see BUILD.md for build, test, and publish instructions.

Apache License 2.0