kmartins / result_kt

Encapsulate a value as a success or an error as a failure using Result and execute a function using runCatching that returns a Result, both similar to those found in Kotlin.

Result Kt

A Dart package with the type Result and the runCatching function that are similar to those found in Kotlin.

You can use it with the Stream too 🙌

Why?

I needed something as is done in Kotlin and did not want to add other functions that not are used in my projects.

There is another package similar, result, however, it was discontinued.

Usage

Add it in your pubspec.yaml:

dependencies:
  result_kt:

Import it where you want to use it e.g, in your main file.

import 'package:result_kt/result_kt.dart';

Overview

Result

You can encapsulate a successful outcome with a value or a failure with an error and stack trace It is similar to an Either that you see in other packages as dartz, fpdart...

Result.success(0)
    .onSuccess(
        action: print,
    )
    .onFailure(
    action: (failure) => print(
            failure.error.toString(),
        ),
    );

Result<int>.failure(Exception(), StackTrace.current)
    .onSuccess(
        action: print,
    )
    .onFailure(
        action: (failure) => print(
            failure.error.toString(),
        ),
    );

Methods available:

• isSuccess
• isFailure
• getOrNull
• failureOrNull
• getOrThrow
• getOrDefault
• getOrElse
• onSuccess
• onFailure
• fold
• map
• mapCatching
• recover
• recoverCatching

See the API documentation.

runCatching

Execute a passed function and catches any error that is thrown from this execution, if the invocation is successful, then returns your value encapsulated in the Result, otherwise, returns your error and stack trace encapsulated in the Result.

final result = runCatching(() => 1);
result
    .onSuccess(
        action: print,
    )
    .onFailure(
        action: (failure) => print(
            failure.error.toString(),
        ),
    );

Note: You can be passed what error type you want catching, if the same, then return the Result, otherwise, the error is rethrown.

final result = runCatching<int>(
    () => throw 'exception',
    test: (error) => error is Exception,
),
// `onFailure` is never called
result
    .onFailure(
        action: (failure) => print(
            failure.error.toString(),
        ),
    );

Stream

Transform the stream value into a result:

final streamController = StreamController<int>();
final resultStream = streamController.stream.toResult();
resultStream.listen(print); // Success(0)
streamController.add(0);

Like the runCatching you can be passed what error type you want transforming, if the same, then return the Result, otherwise, then the error and StackTrace are added using the EventSink.addError.

final streamController = StreamController<int>();
final resultStream = streamController.stream.toResult(
    test: (error) => error is Exception,
);
resultStream.listen(print); // Failure(error: Exception, stackTrace: null)
streamController.addError(Exception());

Other similar packages

The dartz package offers many functional programming helpers, including the Either type, which is similar to Result, with the difference being that it represents any two types of values.

The fpdart similar to the package dartz, however with a better documentation. Do you desire to use all the power of functional programming? If yes, then use it.

The either_option package has Either and Option and supports all of the typical functional operations.

The result package offers a few basic operations and may be adequate for simple cases (This package has been two years without any updates).

The rust_like_result offers a simple Result type similar to the one in Rust.

The simple_result package provides a Result type based on the type of the same name in Swift.

The oxidized with types similar to those found in Rust, such as the Result which represents either a value or an error, and Option which either contains Some value or None.

📝 Maintainers

Kauê Martins

🤝 Support

You liked this package? Then give it a ⭐️. If you want to help then:

• Fork this repository
• Send a Pull Request with new features
• Share this package
• Create issues if you find a bug or want to suggest a new extension

Pull Request title follows Conventional Commits.

📝 License

Copyright © 2022 Kauê Martins.
This project is MIT licensed.