Use FutureOr more and make Future.sync return the resulting Future directly.

sdk/lib/async/future.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.async;
 
 /// A type representing values that are either `Future<T>` or `T`.
 ///
 /// This class declaration is a public stand-in for an internal
 /// future-or-value generic type. References to this class are resolved to the
@@ skipping 19 matching lines @@
 /// `Future<int>`. This type union is defined in such a way that
 /// `FutureOr<Object>` is both a super- and sub-type of `Object` (sub-type
 /// because `Object` is one of the types of the union, super-type because
 /// `Object` is a super-type of both of the types of the union). Together it
 /// means that `FutureOr<Object>` is equivalent to `Object`.
 ///
 /// As a corollary, `FutureOr<Object>` is equivalent to
 /// `FutureOr<FutureOr<Object>>`, `FutureOr<Future<Object>> is equivalent to
 /// `Future<Object>`.
 abstract class FutureOr<T> {
-  // Private constructor, so that it is not subclassable, mixable, or
+  // Private generative constructor, so that it is not subclassable, mixable, or
   // instantiable.
   FutureOr._() {
     throw new UnsupportedError("FutureOr can't be instantiated");
   }
 }
 
 /**
  * An object representing a delayed computation.
  *
  * A [Future] is used to represent a potential value, or error,
@@ skipping 93 matching lines @@
    * If the result of executing [computation] throws, the returned future is
    * completed with the error.
    *
    * If the returned value is itself a [Future], completion of
    * the created future will wait until the returned future completes,
    * and will then complete with the same result.
    *
    * If a non-future value is returned, the returned future is completed
    * with that value.
    */
-  factory Future(computation()) {
+  factory Future(FutureOr<T> computation()) {
     _Future<T> result = new _Future<T>();
     Timer.run(() {
       try {
         result._complete(computation());
       } catch (e, s) {
         _completeWithErrorCallback(result, e, s);
       }
     });
     return result;
   }
 
   /**
    * Creates a future containing the result of calling [computation]
    * asynchronously with [scheduleMicrotask].
    *
    * If executing [computation] throws,
    * the returned future is completed with the thrown error.
    *
    * If calling [computation] returns a [Future], completion of
    * the created future will wait until the returned future completes,
    * and will then complete with the same result.
    *
    * If calling [computation] returns a non-future value,
    * the returned future is completed with that value.
    */
-  factory Future.microtask(computation()) {
+  factory Future.microtask(FutureOr<T> computation()) {
     _Future<T> result = new _Future<T>();
     scheduleMicrotask(() {
       try {
         result._complete(computation());
       } catch (e, s) {
         _completeWithErrorCallback(result, e, s);
       }
     });
     return result;
   }
 
   /**
-   * Creates a future containing the result of immediately calling
+   * Returns a future containing the result of immediately calling
    * [computation].
    *
    * If calling [computation] throws, the returned future is completed with the
    * error.
    *
-   * If calling [computation] returns a [Future], completion of
-   * the created future will wait until the returned future completes,
-   * and will then complete with the same result.
+   * If calling [computation] returns a `Future<T>`, that future is returned.
    *
    * If calling [computation] returns a non-future value,
-   * the returned future is completed with that value.
+   * a future is returned which has been completed with that value.
    */
-  factory Future.sync(computation()) {
+  factory Future.sync(FutureOr<T> computation()) {
     try {
       var result = computation();
-      return new Future<T>.value(result);
+      if (result is Future<T>) {
+        return result;
+      } else if (result is Future) {
+        // TODO(lrn): Remove this case for Dart 2.0.
+        return new _Future<T>.immediate(result);
+      } else {
+        return new _Future<T>.value(result);
+      }
     } catch (error, stackTrace) {
-      return new Future<T>.error(error, stackTrace);
+      var future = new _Future<T>();
+      AsyncError replacement = Zone.current.errorCallback(error, stackTrace);
+      if (replacement != null) {
+        future._asyncCompleteError(
+            _nonNullError(replacement.error), replacement.stackTrace);
+      } else {
+        future._asyncCompleteError(error, stackTrace);
+      }
+      return future;
     }
   }
 
   /**
    * A future whose value is available in the next event-loop iteration.
    *
-   * If [value] is not a [Future], using this constructor is equivalent
-   * to [:new Future<T>.sync(() => value):].
+   * If [result] is not a [Future], using this constructor is equivalent
+   * to `new Future<T>.sync(() => result)`.
    *
-   * Use [Completer] to create a Future and complete it later.
+   * Use [Completer] to create a future and complete it later.
    */
-  factory Future.value([value]) {
-    return new _Future<T>.immediate(value);
+  factory Future.value([FutureOr<T> result]) {
+    return new _Future<T>.immediate(result);
   }
 
   /**
    * A future that completes with an error in the next event-loop iteration.
    *
    * If [error] is `null`, it is replaced by a [NullThrownError].
    *
    * Use [Completer] to create a future and complete it later.
    */
   factory Future.error(Object error, [StackTrace stackTrace]) {
@@ skipping 180 matching lines @@
    * Runs [f] for each element in [input] in order, moving to the next element
    * only when the [Future] returned by [f] completes. Returns a [Future] that
    * completes when all elements have been processed.
    *
    * The return values of all [Future]s are discarded. Any errors will cause the
    * iteration to stop and will be piped through the returned [Future].
    *
    * If [f] returns a non-[Future], iteration continues immediately. Otherwise
    * it waits for the returned [Future] to complete.
    */
-  static Future forEach<T>(Iterable<T> input, dynamic f(T element)) {
+  static Future forEach<T>(Iterable<T> input, FutureOr f(T element)) {
     var iterator = input.iterator;
     return doWhile(() {
       if (!iterator.moveNext()) return false;
       return new Future.sync(() => f(iterator.current)).then((_) => true);
     });
   }
 
   /**
    * Performs an async operation repeatedly until it returns `false`.
    *
    * The function [f] is called repeatedly while it returns either the [bool]
    * value `true` or a [Future] which completes with the value `true`.
    *
    * If a call to [f] returns `false` or a [Future] that completes to `false`,
-   * iteration ends and the future returned by [doWhile] is completed.
+   * iteration ends and the future returned by [doWhile] is completed with
+   * a `null` value.
    *
-   * If a future returned by [f] completes with an error, iteration ends and
-   * the future returned by [doWhile] completes with the same error.
-   *
-   * The [f] function must return either a `bool` value or a [Future] completing
-   * with a `bool` value.
+   * If a call to [f] throws or a future returned by [f] completes with
+   * an error, iteration ends and the future returned by [doWhile]
+   * completes with the same error.
    */
   static Future doWhile(FutureOr<bool> f()) {
     _Future doneSignal = new _Future();
     var nextIteration;
     // Bind this callback explicitly so that each iteration isn't bound in the
     // context of all the previous iterations' callbacks.
     nextIteration = Zone.current.bindUnaryCallback((bool keepGoing) {
       if (keepGoing) {
         new Future.sync(f)
             .then(nextIteration, onError: doneSignal._completeError);
@@ skipping 145 matching lines @@
    *         var f2 = action();
    *         if (f2 is Future) return f2.then((_) => v);
    *         return v
    *       }, onError: (e) {
    *         var f2 = action();
    *         if (f2 is Future) return f2.then((_) { throw e; });
    *         throw e;
    *       });
    *     }
    */
-  Future<T> whenComplete(dynamic action());
+  Future<T> whenComplete(FutureOr action());
 
   /**
    * Creates a [Stream] containing the result of this future.
    *
    * The stream will produce single data or error event containing the
    * completion result of this future, and then it will close with a
    * done event.
    *
    * If the future never completes, the stream will not produce any events.
    */
@@ skipping 206 matching lines @@
   AsyncError replacement = Zone.current.errorCallback(error, stackTrace);
   if (replacement != null) {
     error = _nonNullError(replacement.error);
     stackTrace = replacement.stackTrace;
   }
   result._completeError(error, stackTrace);
 }
 
 /** Helper function that converts `null` to a [NullThrownError]. */
 Object _nonNullError(Object error) => error ?? new NullThrownError();