either dart ·

The library for error handling and railway oriented programming.

This library supports async "map" and async "then" hiding the boilerplate of working with asynchronous computations Future[Either].

Installation

Add to pubspec.yml:

dependencies:
  either_dart: ... // latest package version

Documentation

https://pub.dev/documentation/either_dart/latest/either/either-library.html

Pub dev

https://pub.dev/packages/either_dart

How to use it?

Sections:

• Basic usage
• Advanced usage
• Case - Solution

Basic usage

Create two entities for example, you can use your own abstractions for your project.

enum AppError {
  NotFound,
  // some errors codes
}

class MyError {
  final AppError key;
  final String? message;

  const MyError({
    required this.key, 
    this.message,
  });
}

We can use Either as shown below:

Either<MyError, String> getCityNameByCode(int code) {
  const cities = <int, String>{
    /// some cities
  };

  if (cities.contains(code)) {
    return Right(cities[code]!);
  } else {
    return Left(
      key: AppError.NotFound, 
      message: '[getCityNameByCode] can`t convert code:$code to city name',
    );
  }
}

Too, you can use Either.cond and Either.condLazy for simple cases:

  return Either.condLazy(cities.contains(code), 
    () => cities[code]!, 
    () => MyError(
      key: AppError.NotFound, 
      message: '[getCityNameByCode] can`t convert code:$code to city name',
    ),
  );

Either has the following methods:

note:
L - current Left type
TL - new generic Left type
R - current Right type
TR - new generic Right type

Advanced usage

This library provides an FutureEither extension which is designed to handle asynchronous computation with ease.

You don't need to import or use new classes to use it - just use Future<Either<L, R>>

Example:

/// --- helpers ---

import 'package:either_dart/either.dart';
import 'package:http/http.dart' as http;
import 'package:flutter/foundation.dart';
import 'dart:convert';

Future<Either<AppError, http.Response>> safe(Future<http.Response> request) async {
  try {
    return Right(await request);
  } catch (e) {
    return Left(MyError(
        key: AppError.BadRequest,
        message: "Request executing with errors:$e"));
  }
}

Either<AppError, http.Response> checkHttpStatus(http.Response response) {
  if (response.statusCode == 200)
    return Right(response);
  if (response.statusCode >= 500)
    return Left(MyError(
        key: AppError.ServerError,
        message: "Server error with http status ${response.statusCode}"));
  return Left(MyError(
      key: AppError.BadResponse,
      message: "Bad http status ${response.statusCode}"));
}

Future<Either<AppError, dynamic>> parseJson(http.Response response) async {
  try {
    
    return Right(await compute((body) {
      final json = JsonCodec();
      return json.decode(body)); 
    }, response.body);
  } catch (e) {
    return Left(MyError(
      key: AppError.JsonParsing, 
      message: 'failed on json parsing'));
  }
}

/// --- app code ---

//// network
Future<Either<AppError, Data>> getDataFromServer() {
  return 
    safe(http.get(Uri('some uri')))
      .thenRight(checkHttpStatus)
      .thenRight(parseJson) 
      .mapRight(Data.fromJson)
}

Case - Solution

• How I can use the value of Either?

You can use right or left getters, but you should check what value is stored inside (isLeft or isRight)

Also, my favorite methods fold, either

• fold - used when you need to transform two rails to one type
• either - used for two situations: 1. when you need transform left and right. 2. when you need to use stored value without next usage (see example).

Example:

/// either method
showNotification(Either<MyError, String> value) {
  return value.either(
    (left) => showWarning(left.message ?? left.key.toString()),
    (right) => showInfo(right.toString()),
  );
  /// equal
  if (value.isLeft) {
    final left = value.left;
    showWarning(left.message ?? left.key.toString()
  } else {
    showInfo(value.right.toString())
  }
}

/// fold method
class MyWidget {
  final Either<MyError, List<String>> value;

  const MyWidget(this.value);

  Widget build(BuildContext context) {
    return Text(
      value.fold(
        (left) => left.message, 
        (right) => right.join(', ')),
    );
    /// or
    return value.fold(
      (left) => _buildSomeErrorWidget(context, left),
      (right) => _buildSomeRightWidget(context, right),
    );
  }
}