BLE-X/io.github.romantsisyk.blex.result/BleResult

BleResult

sealed class BleResult<out T>

A discriminated union that encapsulates the result of a BLE operation.

This sealed class provides a type-safe way to handle both successful results and failures from BLE operations without using nullable types or exceptions for control flow.

Design Philosophy

BleResult is inspired by Kotlin's Result class but is specifically designed for BLE operations with BleException as the failure type. This provides:

Type safety: The compiler ensures all failure cases are handled
Explicit error handling: Errors are part of the return type, not hidden
Functional composition: Chain operations with map, flatMap, etc.
No exceptions for control flow: Cleaner code without try-catch blocks

Usage Examples

Basic Usage

val result = connection.readCharacteristicResult(serviceUuid, charUuid)

when (result) {
    is BleResult.Success -> {
        val data = result.data
        processData(data)
    }
    is BleResult.Failure -> {
        val error = result.error
        handleError(error)
    }
}

Functional Style

connection.readCharacteristicResult(serviceUuid, charUuid)
    .map { bytes -> String(bytes, Charsets.UTF_8) }
    .onSuccess { text -> displayText(text) }
    .onFailure { error -> showError(error.message) }

Chaining Operations

connection.readCharacteristicResult(serviceUuid, charUuid)
    .flatMap { data ->
        parseResponse(data)?.let { bleSuccess(it) }
            ?: bleFailure(BleCharacteristicException("Invalid response format"))
    }
    .onSuccess { parsedData -> process(parsedData) }

Extracting Values

// Safe extraction (returns null on failure)
val data: ByteArray? = result.getOrNull()

// With default value
val data: ByteArray = result.getOrDefault(byteArrayOf())

// Throws on failure
val data: ByteArray = result.getOrThrow()

Parameters

T

The type of the success value.

See also

Inheritors

Types

data class Failure(val error: BleException) : BleResult<Nothing>

Represents a failed BLE operation result.

data class Success<T>(val data: T) : BleResult<T>

Represents a successful BLE operation result.

Properties

val isFailure: Boolean

Returns true if this result represents a failed operation.

val isSuccess: Boolean

Returns true if this result represents a successful operation.

Functions

exceptionOrNull

fun exceptionOrNull(): BleException?

Returns the exception if this is a Failure, or null if this is a Success.

inline fun <R> flatMap(transform: (T) -> BleResult<R>): BleResult<R>

Transforms the success value using a function that returns a BleResult.

inline fun <R> fold(onSuccess: (T) -> R, onFailure: (BleException) -> R): R

Folds the result into a single value by applying the appropriate function.

fun getOrDefault(defaultValue: @UnsafeVariance T): T

Returns the success value if this is a Success, or the defaultValue if this is a Failure.

inline fun getOrElse(defaultValue: (BleException) -> @UnsafeVariance T): T

Returns the success value if this is a Success, or the result of defaultValue if this is a Failure.

fun getOrNull(): T?

Returns the success value if this is a Success, or null if this is a Failure.

fun getOrThrow(): T

Returns the success value if this is a Success, or throws the exception if this is a Failure.

inline fun <R> map(transform: (T) -> R): BleResult<R>

Transforms the success value using the given transform function.

inline fun mapError(transform: (BleException) -> BleException): BleResult<T>

Transforms the error using the given transform function.

inline fun onFailure(action: (BleException) -> Unit): BleResult<T>

Performs the given action if this is a Failure.

inline fun onSuccess(action: (T) -> Unit): BleResult<T>

Performs the given action if this is a Success.

inline fun recover(recovery: (BleException) -> @UnsafeVariance T): BleResult<T>

Recovers from a failure by providing an alternative success value.

inline fun recoverWith(recovery: (BleException) -> BleResult<@UnsafeVariance T>): BleResult<T>

Attempts to recover from a failure using another BleResult.

fun <T, R> BleResult<T>.zip(other: BleResult<R>): BleResult<Pair<T, R>>

Combines two BleResult instances into a single result containing a Pair.