Result Library for Dart #

A robust utility for handling success and error states in a functional style.

Features #

• Encapsulate success and failure states using Result.
• Transform values with map and flatMap.
• Handle errors gracefully with mapError.
• Combine multiple Result objects.
• Simplify async operations with fromAsync.
• Convenient extensions for ergonomics.

Installation #

Add the following dependency to your pubspec.yaml:

dependencies:
  resultfy: ^1.0.0

Then, run:

flutter pub get

Getting Started #

Basic Usage #

import 'package:resultfy/resultfy.dart';

void main() {
  // Creating a success result
  final success = Result.success("Operation completed successfully");
  print(success); // Output: Result<String>.success(Operation completed successfully)

  // Creating a failure result
  final failure = Result.failure(Exception("An error occurred"));
  print(failure); // Output: Result<String>.failure(Exception: An error occurred)

  // Handling results
  success.fold(
    (value) => print("Success: $value"),
    (error) => print("Failure: $error"),
  );

  failure.fold(
    (value) => print("Success: $value"),
    (error) => print("Failure: $error"),
  );
}

Mapping Success and Failure #

final success = Result.success(42);
final transformedSuccess = success.map((value) => "Value is \$value");
print(transformedSuccess); // Output: Result<String>.success(Value is 42)

final failure = Result.failure("Initial Error");
final transformedFailure = failure.mapError((error) => "Updated Error: \$error");
print(transformedFailure); // Output: Result<String>.failure(Updated Error: Initial Error)

Combining Results #

final results = [
  Result.success(1),
  Result.success(2),
  Result.success(3),
];

final combined = Result.combine(results);
print(combined); // Output: Result<List<int>>.success([1, 2, 3])

final resultsWithFailure = [
  Result.success(1),
  Result.failure("Error"),
];

final combinedWithFailure = Result.combine(resultsWithFailure);
print(combinedWithFailure); // Output: Result<List<int>>.failure(Error)

Asynchronous Usage #

Future<Result<String>> fetchData() async {
  return await Result.fromAsync(() async {
    if (DateTime.now().millisecondsSinceEpoch % 2 == 0) {
      return "Fetched data";
    } else {
      throw Exception("Fetch error");
    }
  });
}

void main() async {
  final result = await fetchData();

  result.fold(
    (value) => print("Success: \$value"),
    (error) => print("Failure: \$error"),
  );
}

Extensions for Improved Ergonomics #

final result = Result.success(10);
final mapped = result.mapSuccess((value) => value * 2);
print(mapped); // Output: Result<int>.success(20)

final errorHandled = result.mapFailure((error) => "Handled: \$error");
print(errorHandled); // Output: Result<int>.success(20)

Testing #

Mocking Success and Failure #

import 'package:test/test.dart';
import 'package:resultfy/resultfy.dart';

void main() {
  test('Success result works correctly', () {
    final result = Result.success(100);

    expect(result.isSuccess, true);
    expect(result.getOrNull(), 100);
    expect(result.exceptionOrNull(), null);
  });

  test('Failure result works correctly', () {
    final result = Result.failure(Exception("Test error"));

    expect(result.isFailure, true);
    expect(result.getOrNull(), null);
    expect(result.exceptionOrNull(), isA<Exception>());
  });

  test('Mapping success works correctly', () {
    final result = Result.success(50);
    final mapped = result.map((value) => value * 2);

    expect(mapped.getOrNull(), 100);
  });

  test('Handling failure works correctly', () {
    final result = Result.failure("Error");
    final handled = result.mapError((error) => "Handled: \$error");

    expect(handled.exceptionOrNull(), "Handled: Error");
  });
}

API Reference #

Result<T> #

Utility Methods #

Extensions #

Contributing #

Contributions are welcome! Please open issues or submit pull requests on the GitHub repository.

License #

This library is licensed under the MIT License. See the LICENSE file for details.