client/io.github.octaviusframework.client/DataResult

DataResult

sealed class DataResult<out T>

The outcome of a database operation, which either carries a value or the failure that replaced it.

Every terminal method on a client query returns one of these rather than throwing, for the class of failures the database itself reports: a constraint the row violated, a deadlock, a RAISE EXCEPTION from a routine, a statement that ran out of time. Those are conditions an application is expected to have an answer for, and a return type says so where a catch two frames up does not.

It does not cover every way a call can fail. A query the database refused to parse, a row that does not fit the class it was asked for, a type the registry has never heard of - those are bugs in the calling code, and they are thrown. OctaviusClient names the split exactly.

Type Parameters

T

The type of the value carried on success.

Inheritors

Constructors

protected constructor()

Types

data class Failure(val error: OctaviusException) : DataResult<Nothing>

The database reported error and the operation produced no value.

data class Success<out T>(val value: T) : DataResult<T>

The operation completed and produced value.

Functions

inline fun <R, T : R> DataResult<T>.getOrElse(onFailure: (DataResult.Failure) -> R): R

Returns the carried value, or what onFailure makes of the failure.

fun <T> DataResult<T>.getOrNull(): T?

Returns the carried value, or null where the operation failed.

fun <T> DataResult<T>.getOrThrow(): T

Returns the carried value, throwing the failure in its place.

inline fun <T, R> DataResult<T>.map(transform: (T) -> R): DataResult<R>

Applies transform to the value of a DataResult.Success, and returns a DataResult.Failure as it stands.

inline fun <T> DataResult<T>.onFailure(action: (OctaviusException) -> Unit): DataResult<T>

Runs action on the failure if this is a DataResult.Failure, and returns this result either way.

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

Runs action on the carried value if this is a DataResult.Success, and returns this result either way.