result_monad

NOTE 1: This release has some breaking changes and an increased minimum SDK version bump from the 2.3.2 release.

NOTE 2: Many thanks to the contributions to the ADT-related updates and StackTrace functionality updates contributed by Daniel Gomez Rico (danielgomezrico@gmail.com). Some of the changes were taken through Pull Request acceptance while others were back-ported with some changes from his fork of this project

• Underlying architecture now uses Algebraic Data Type (ADT) functionality introduced with class modifiers and patterns in Dart 3.0.0 in May 2023.
  • This made the syntax for creating Results more compact (and preferred way to create Results now):
    • Result.ok('Good') => Ok('Good)
    • Result.error('Bad') => Error('Bad')
  • This also makes it so you can use switch statements, if statements, et cetera on return values directly, although somewhat redudant with the various aggregation operations in the library.
  • Example:

// The below fold function...
final value = invert(2).fold(
  onSuccess: (v) => v,
  onError: (e, trace) => e,
);

// Can be expressed:
final value = switch (invert(2)) {
  Ok o => o.value,
  Error e => e.cause,
  Result _ => throw UnimplementedError(), // there since Result isn't sealed
};

• Breaking change: Minimum Dart version bumped up from 2.14.4 to 3.0.0
• Breaking change: Added Stack Trace following functionality so can get insight into where the error occurred in a chain of calls. This changed the function signatures on the following method to add access to stack traces when processing errors
  • On Result: fold, match, withError, withErrorAsync
  • On FutureResult: fold, match, withError, withErrorAsync
• Add optional StackTrace parameter on Error result creation Error('Bad', StackTrace.current)
• Result has a stackTrace property that can be called if and only if the type is an Error. Result can be null.
• Result has asOk and asError properties for casting to specific type. This will throw an Exception if is against the underlying type for that instance.
• Thanks to GitLab User DoodleSchrank for adding additional pass-through methods on FutureResult to their corresponding Result methods: getErrorOrElse, getValueOrElse, getErrorOrElseAsync, getValueOrElseAsync
• Updated examples and documentation to reflect the syntax updates.

• Tweak to documentation headers to avoid lint error

• Tweak to README to include withError and withErrorAsync

• Examples and documentation updates for the new syntax.
• Add to FutureResult: andThen, errorCast, mapError, mapValue, withResult, withError, match, fold
• Add withError to Result and withError and withErrorAsync to FutureResult

• Add pass through methods withResult and withResultAsync on Result and Future extension method

• Add exception catching on addThen and addThenSuccess and FutureResult extension methods.

• Tweaks to the README only.

• Allow nullable types for success and failure types
• Add andThenSuccess and andThenSuccessAsync methods for allowing returning results without explicit Result.ok wrapping to allow more concise syntax
• Add extension methods on FutureResult to make async chaining syntax much more concise
• Add errorCast method for when need to pass up an error Result with the same error type with different success type.

• Tweaks to API documentation
• Added temp file "intermediate" level example and added it to example.md as well

• Added an example.md file for pub.dev.

• Initial version.