First-class, functional-style `Result<E, T>` types with built-in operators

[Levi-Lesches]

Proposal

With sealed classes and exhaustive pattern matching, I think we've hit a natural time to add first-class result types to the language, or at least the first-party libraries (the ones published by dart.dev):

sealed class Result<E, T> {
  R match<R>({
    required R Function(E) onError,
    required R Function(T) onValue, 
  }) => switch (this) {
    Failure(error: final error) => onError(error),
    Success(value: final value) => onValue(value),
  };
  
  T onError(T Function(E) onError) => switch (this) {
    Failure(error: final error) => onError(error),
    Success(value: final value) => value,
  };
  
  T assertErrors() => switch (this) {
    Failure(error: final error) => throw StateError("Result type had an error value: $error"),
    Success(value: final value) => value,
  };
}

class Failure<E, T> extends Result<E, T> {
  final E error;
  Failure(this.error);
}

class Success<E, T> extends Result<E, T> {
  final T value;
  Success(this.value);
}

Usage would look like:

Result<String, int> getNum() => 
  Random().nextBool() ? Success(123) : Failure("Oops!");

void main() {
  // Simply handle each case
  getNum().match(
    onError: (reason) => print("Couldn't get number because $reason"),
    onValue: (value) => print("Got number! ${value + 1}"),
  );
  
  // Use a value based on the presence of an error
  final number = getNum().match(
    onError: (error) => 0,
    onValue: (value) => value + 1,
  );
  
  // or if you just want to handle errors (like ?? in null safety)
  final num2 = getNum().onError((error) => 0);
  
  // if you believe there are no errors (like ! in null safety)
  final num3 = getNum().assertErrors();
}

Possible lints

Seeing as you could forget to handle an error, this should probably come with a lint against cases like the following:

void main() { 
  getNum();  // Warning: Avoid using Result types without handling the error case
}

Another lint could be

Warning: Avoid returning nullable Result types. Use a nullable T type instead

BAD:

Result<ErrorType, User>? getUser() => isPresent(user) ? Success(user) : null;

GOOD:

Result<ErrorType, User?> getUser() => Success(isPresent(user) ? user : null);

Motivation

Besides the fact that this style is a pretty popular alternative to try/catch-ing errors that functions may throw, this solves the concrete problem of "how can I be sure this function won't crash my app?". By returning a Result type, you're signaling to the caller that all error cases can be handled safely by using pattern matching or a method like .onError. With more and more of the ecosystem using a style like this, code will be safer at runtime. As mentioned above, sealed classes and exhaustive pattern matching allow us to handle this safely for the first time, so this would be a natural time to officially adopt the Result pattern.

In fact, code in the wild already does use this style:

• package:fpdart's Either class
• package:either's Either class
• package:async's Result class
• ...and the countless other packages seen by searching either, result, or option

As much as this "could be handled by a package", right now the ecosystem is fragmented because it is being handled by packages, and each package is making their own, meaning the chances of any two packages being compatible are slim to none. Sure, we could make a "better" package, but that probably wouldn't help,. By making this first-party, it is more likely that other packages will contribute and migrate to the canonical implementation, increasing compatibility across the ecosystem.

Another thing is that without being a language feature or recognized first-party package, we miss out on valuable lints.

Possible language/syntax improvements

If this is made a first-class language feature, not just package, we can go a little further. Above, I noted that Result.onError was like ?? in the sense that it says "if there is an error/null, ignore it and use this value instead". Result.assertErrors is like ! in that it says "I don't expect there to be an error/null, so if there is, please throw an actual error and stop execution".

I believe those concepts are similar enough to null safety that they shouldn't be considered semantic overloading, while also being different enough to not be confused with actual null safety (the above lints would protect against Result? messiness).

To further demonstrate, compare these two getUser functions, which return a Result<String, User> and a User?:

class User {
  String get name => "John Smith";
}

Result<String, User> getUser1() => 
  Random().nextBool() ? Success(User()) : Failure("Could not get user");

User? getUser2() => Random().nextBool() ? User() : null;

void main() {
  final name1 = getUser1().assertErrors().name;
  final user1 = getUser1().onError((_) => User());
  
  final name2 = getUser2()!.name;
  final user2 = getUser2() ?? "Default name";
}

By thinking a little harder, we can get an analog to the ?. operator:

sealed class Result<E, T> {
  Result<E, R> chain<R>(R Function(T) func) => switch (this) {
    Failure(error: final error) => Failure(error),
    Success(value: final value) => Success(func(value)),
  };
}

// Same getUser1 and getUser2 as above

void main() {
  final name3 = getUser1().chain((user) => user.name);
  final name4 = getUser2()?.name;
}

Thoughts?

[lrhn]

It's similar to nullability because both are union types, and both have a second part which is mostly untyped. (You could type the error, but most of the time you just want to know that it's not the value. And you don't really want the supertype to have to carry an error type too.)

Which is a different way of saying that they're both monads. The null monad and the error monad are both classical monads.

The difference is that null has always been a value in Dart, not part of control flow. We don't have a "no value" type, like fx C's void type, which null would be a reflection of.

And errors have always, mostly, been control flow, even when we capture them in async, they're intended to be reified as control flow and caught by catch.

So this is, effectively, asking for an official ErrorOr union type, and monadic operations on it, probably similar to those of both nullable types and FutureOr.

• e?.useValue preserves the error, or operates on the value.
• e ?? e2 uses the value of e, or ignores the error and uses the value of e2.
• awaitish e evaluates to the value or re-raises the error (reifies the capture control flow).

Not sure we really do need language features for most of these. The ?. is the one that I haven't found a good way to do (in the time writing this).
The rest are easy to get to without to much extra writing.

(Also, package:async is published by dart.dev.)

[benthillerkus]

An official implementation should also ensure that it integrates nicely with the existing language:

• The error variant should carry stack traces -- maybe allow the Error variant to only contain types that inherit from Dart exceptions?
• There should be a function that maps a throwing function to one that returns a Result
• There should be a function that maps a result to a nullable
• Unwrapping the Error variant should make in the StackTrace / error clear, where the original Error happened and where the unwrap took place
• Documentation should clarify where Result / Either makes sense and where exceptions make more sense (stuff like division by zero for example)

In Rust a problem with Results is that your custom error types often need an Any variant for errors you just want to bubble up.
Fortunately Dart already has a solution for that: throwing Exceptions.

[benthillerkus]

It's similar to nullability because both are union types, and both have a second part which is mostly untyped. (You could type the error, but most of the time you just want to know that it's not the value. And you don't really want the supertype to have to carry an error type too.)

I would use Results exactly when the Error type is not untyped, but either an enum or a sealed class that allows me to handle the errors. If I don't care about the error type, in Dart I'd either use nullables directly or throw exceptions.

And errors have always, mostly, been control flow, even when we capture them in async, they're intended to be reified as control flow and caught by catch.

Not sure what you mean, but I'd argue that Results are much better for control flow as they work with the new pattern matching features, traditional if statements and could also be integrated with the collection APIs

In general: Exceptions work pretty badly with collections and iterators (will the iterator continue running after an exception was thrown or will it throw itself? will it return the first exception or all exceptions)) -- A Result type would be great here!

So this is, effectively, asking for an official ErrorOr union type, and monadic operations on it, probably similar to those of both nullable types and FutureOr.

• e?.useValue preserves the error, or operates on the value.
• e ?? e2 uses the value of e, or ignores the error and uses the value of e2.
• awaitish e evaluates to the value or re-raises the error (reifies the capture control flow).

No, to the contrary, FutureOr shouldn't exist

(Also, package:async is published by dart.dev.)

The language features, like the ? and ! operators would be pretty important and the lint when ignoring error cases would be absolutely critical.
If it was added as a package it should be included in the sdk by default.

[Levi-Lesches]

@lrhn

It's similar to nullability because both are union types, and both have a second part which is mostly untyped. (You could type the error, but most of the time you just want to know that it's not the value. And you don't really want the supertype to have to carry an error type too.)

Pretty much, yeah. In cases where you do need to know the error type, you couldn't use the ?? operator and its friends -- you'd have to use .match()

And errors have always, mostly, been control flow, even when we capture them in async, they're intended to be reified as control flow and caught by catch.

I see a difference here. Errors are meant to be thrown and stop the flow of the program. Those are control flow entities. But Exceptions were always meant to be handled. I'd argue the fact that you throw them isn't as important as the fact that you hope someone else will eventually catch it. In an ideal user-facing application, all or most Exceptions would be handled.

I see Result types as corresponding to Exceptions, and therefore a value, while I still see throw as a tool to surface Errors, which therefore affects control flow.

So this is, effectively, asking for an official ErrorOr union type, and monadic operations on it, probably similar to those of both nullable types and FutureOr.

• e?.useValue preserves the error, or operates on the value.
• e ?? e2 uses the value of e, or ignores the error and uses the value of e2.
• awaitish e evaluates to the value or re-raises the error (reifies the capture control flow).

Yes to the first two but probably not the last one (unless you mean e!), because again I don't see exceptions as needing to stop control flow, I see them as signals that need to be interpreted, like how nulls once were. The only reason I'd suggest e! is because someone will want to eg, make an HTTP request and just crash the program if the status code isn't a clean 200. But in the ideal case, e! should never be used, and the exception should instead be handled (eg, a print statement or a Flutter Text).

I guess in that way, i see Exceptions as similar to nullables for another reason: we used to have lots of null checks everywhere and throw an error if we found once, but post null-safety we can simply ?. and ?? it away. What once greatly affected control flow is now just an expression. I believe if Result types catch on, the same would be true for Exceptions. Yes, IndexErrors should probably still break your program, but now server errors won't.

Not sure we really do need language features for most of these. The ?. is the one that I haven't found a good way to do (in the time writing this).

The operators would be nice to have, and as I demonstrated they can all be written as methods today including ?., but IMO the standardization is way more important. Yes, package:async is first-party but its Result class is not advertised as a true Result class (and even if it were, I'd be happy to pretty much just move it somewhere more broad than async.

@benthillerkus

• The error variant should carry stack traces -- maybe allow the Error variant to only contain types that inherit from Dart exceptions?

I'd disagree again and say that Result types should almost never translate to thrown errors in the ideal case (barring a quick-and-dirty e! syntax), but the whole point of them is to always be guaranteed to be handled safely in-app, in a way that makes sense for your specific use-case.

I agree with throwing --> Result, but I don't see the need for Result --> nullable (especially if you could just do e ?? null).

[lrhn]

I see a difference here. Errors are meant to be thrown and stop the flow of the program. Those are control flow entities. But Exceptions were always meant to be handled

That's a convention, the language doesn't care. The only special casing is for objects which extend the Error class.
After throwing, they're all just objects.

A language feature should be able to handle any object that is thrown, so anything other than null.

[lrhn]

I think that with extension types, we'll see new implementations of the existing Result (and Option) types, and probably other stable helper types.

Consider something like this (slightly hackish) version;
https://dartpad.dev/?id=4daa370e9f33c8562ca3efe06e8e5adf&channel=master

[Levi-Lesches]

Not sure I see the practical difference between extension types over sealed types in terms of actual handling (other than that devs can make their extension types off of Result I guess), but yes the point is that with exhaustive pattern matching we've reached a point where these classes are possible idiomatically.

And it's precisely because packages can and have been implementing their own versions that I feel it should be standardized as early as possible. Because with the current fragmentation, the result types from two packages are very unlikely to be compatible.

Also just a note that Optional<T> types isn't what I'm looking for here as I believe null safety is enough in these cases. It's Result<E, T> that handles a possible error value. And to address

A language feature should be able to handle any object that is thrown, so anything other than null.

I don't think the E type necessarily needs to or should be thrown. I can imagine

Result<String?, User> getUser();  // returns the reason this failed, or null if some unknown error occurred
void main() => getUser().match(
  onError: (reason) => print(reason ?? "Something happened"),
  onValue: (user) => print(user.value),
);

The point of my distinction between Errors and Exceptions wasn't to constrain it to the E extends Exception, but more philosophically about how Result types turn a control-based throw/try/catch into an expression-based .match,/.onError (or even simpler, ??/?./!). That's also why I didn't get what you meant by awaitish earlier -- I'm not saying "defer this exception but maybe throw it", but rather "this Result subclass will definitely be a Success type, but if it's a Failure then throw".

[jakemac53]

Not sure I see the practical difference between extension types over sealed types in terms of actual handling (other than that devs can make their extension types off of Result I guess), but yes the point is that with exhaustive pattern matching we've reached a point where these classes are possible idiomatically.

The difference is it is free (wrapperless), much more similar to FutureOr today.

Here is your example converted roughly https://dartpad.dev/?id=12c5ce9064357d6bb370cb2027612aa8&channel=master

[Reprevise]

I've been writing more and more Rust lately due to Advent of Code and it really makes me appreciate a strong Result type and I definitely would love to see an official version with language support in Dart. This would require changing official APIs like num.parse, jsonDecode/Encode, etc. A migration period might look like num.parseResult() or num.parseWithResult(), etc but that's probably for another issue.

[lrhn]

With full language support, there is no need to change APIs.

Let's say we introduce a postfix operator, strawman syntax catch, which converts an expression of type T to an expression of type Result<T>, and captures either a value or a throw.
And we allow ! to convert Result<T> to T like suggested.

Then we don't need to change int.parse, you just write var r = int.parse(string) catch;.
(Hmm, might look better as prefix, like catch(e).)

[Reprevise]

(Hmm, might look better as prefix, like catch(e).)

I'm more fond of a prefix like try. So for example, you'd do var r = try int.parse(string).

I think the goal of having a core Result class should be to remove the ambiguity of determining whether or not a method can "throw" an exception. People would just shove try (or whatever the syntax becomes) for every method, even when unnecessary. I think that'd be fine for a migration period while the APIs are updated (then a lint would come along like unnecessary_try, but if there would be no plans to do so, then I fail to see the point.

[lrhn]

I don't see us changing existing APIs to return a Result<T> rather than T+throwing.

And I don't see us writing new APIs that way either, to be honest.
Mainly because I don't actually expect us to add a language supported Result type.

It would be a massive change of direction to do that.
Not necessarily a bad direction, if one had started going that way from the start, but a very large change to make at this time.

Which is a way of saying that a feature like this doesn't just need to argue for its usability and advantage over the status quo, it also needs to show a migration path with a cost that doesn't outweigh the benefits.

And adding the type won't remove any ambiguity over whether a function can throw an exception, not unless we also remove the ability to throw anything but errors.
And then the function would still not be able to declare which exceptions it can throw, if it can throw more than one kind.
If it could, it would effectively be Java's checked exceptions, just with, hopefully, nice syntax.

[benthillerkus]

Just adding a Result with the expected basic operations would be enough as a first step imo.
It solves the specific problem of lots of incompatible Result types proliferating on pub.dev and the ? and ! operators and must-use lints solve ergonomics issues that cannot be addressed by the community.

More isn't needed for now imo. If the community adopts this and starts using it everywhere, there could still be a discussion about migrating things or adding features to ease migration.