Add FutureOr<T>

[floitschG]

Informal specification: https://gist.github.com/lrhn/d6815f9556acb3dc8f91d2c680ea0e54

A lot of asynchronous code in Dart allows the use of a T or a Future<T>. For example, the callback to Future.then is declared to take a T but it doesn't specify the return type, since it could be an S or a Future<S>:

Future<S> then<S>(onValue(T value), { Function onError });

We will add FutureOr<T> to support this use case. In strong mode and DDC FutureOr<T> represents the union of Future<T> and T. In Dart1, FutureOr<T> is interpreted as dynamic.

• Informal spec
• Analyzer Support FutureOr<T> in the analyzer #28008
• DDC Support FutureOr<T> in DDC #28009
• VM Support FutureOr<T> in the VM #28010
• Dart2Js Support FutureOr<T> in dart2js #28011
• Library Add FutureOr<T> to the core libraries #28029
• Make sure changelog has an entry for this (pending https://codereview.chromium.org/2648203003/)

In a following release:

• Full specification Specify FutureOr<T> #28007
• Update libraries to use it Update core libraries to use FutureOr<T> #28122

[floitschG]

Assigning to @lrhn so he can update the description with more details.

[bwilkerson]

We will add FutureOr<T> to support this use case.

Does that mean that there will be an explicit class defined in the SDK?

[floitschG]

We are open for suggestions. The type/class is magical, since it's a union type.

We can add a class or a typedef (for example to simplify dartdoc generation), but the tools would need to treat it specially.

Conceptually, FutureOr<T> lives in dart:async.

[bwilkerson]

If we have an explicit declaration, then we don't need to special case navigation (there's someplace with documentation we can take the user), hover text, completions (we don't have to insert a fake class name into the list) and probably a few other features I'm not thinking of immediately. So, it would be much cleaner from server's perspective if there were an actual class, no matter how different the semantics of that class are.

Given that it isn't the name of a function, class seems like a better choice than typedef to me.

[floitschG]

Sounds reasonable. I created a bug for it.
(Hopefully today or tomorrow)

[a-siva]

Could we add some tests cases for this so that the implementations can be verified.

[floitschG]

I started writing some tests:
https://codereview.chromium.org/2564563003/

[mit-mit]

Informal specification is done: https://gist.github.com/lrhn/d6815f9556acb3dc8f91d2c680ea0e54

Moving to 1.22 for implementation.

[crelier]

The current language spec has a special type rule when returning a value from an async function. See section "17.12 Return":

If the body of f is marked async (9) it is a dynamic type error if o is
not null (16.2) and Future<S> is not a subtype of the actual return type
(19.8.1) of f.

Is any of this changing with the introduction of FutureOr<T>?
The VM supports this special type rule in checked mode, which is very similar to what would be needed to support the FutureOr union type prescribed here, and I am wondering whether it would not be simpler to support FutureOr in the VM, rather than mapping it to dynamic, especially since this mapping is not specified at all (e.g. how do you map FutureOr<Malformed>? or FutureOr<U, V>? etc...).

[lrhn]

No change for the VM's checked mode, for two reasons.

One is that it's a requirement on the dynamic type, and there are no objects that has type FutureOr<X>. It's still ether a future or a non-future, so there is no change to the dynamic type of o.

Also, in spec mode, any occurrence of FutureOr should be treated as dynamic, so even if the return type of the async function is written as FutureOr<X>[1], then it's effectively just returning dynamic, so there is no need to check anything.

So all in all, no matter where FutureOr occurs, it doesn't make a difference to this rule, because it won't occur anyway, it's just dynamic.

For strong mode, where FutureOr doesn't mean dynamic, there shouldn't be a change as such, but Future<S> is a subtype of FutureOr<S>, so you can get away with writing FutureOr<S>foo() async { ... }. You just shouldn't.
There is the question of what Flatten(FutureOr<S>) is, and if it wasn't because I want to get rid of flatten, we would probably have to extend it so that Flatten(FutureOr<S>) := Flatten(S).

[1] It shouldn't be, it should just be Future! We should have a lint for that!

[mit-mit]

Marking informal spec and dart2js complete

[mit-mit]

Marking VM done.

[mit-mit]

Updating checklist to mention that core library usage of this will follow in 1.23.

[mit-mit]

Changelog underway: https://codereview.chromium.org/2648203003/

[kevmoo]

Landed! c3f1212