Add methods to Result. Bump version to 2.0 and remove deprecated features.

lib/src/result.dart

 // Copyright (c) 2016, 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.
 
 import 'dart:async';
 
 import 'result/capture_transformer.dart';
 import 'result/error.dart';
 import 'result/release_transformer.dart';
 import 'result/value.dart';
 import 'stream_sink_transformer.dart';
 
 /// The result of a computation.
 ///
 /// Capturing a result (either a returned value or a thrown error) means
 /// converting it into a [Result] - either a [ValueResult] or an [ErrorResult].
 ///
 /// This value can release itself by writing itself either to a [EventSink] or a
 /// [Completer], or by becoming a [Future].
+///
+/// A [Future] represents a potential result, one that might not have been
+/// computed yet, and a [Result] is always a completed and available result.
 abstract class Result<T> {
   /// A stream transformer that captures a stream of events into [Result]s.
   ///
   /// The result of the transformation is a stream of [Result] values and no
   /// error events. This is the transformer used by [captureStream].
   static const StreamTransformer<Object, Result> captureStreamTransformer =
       const CaptureStreamTransformer();
 
   /// A stream transformer that releases a stream of result events.
   ///
@@ skipping 18 matching lines @@
       const StreamSinkTransformer.fromStreamTransformer(
           const ReleaseStreamTransformer());
 
   /// Create a `Result` with the result of calling [computation].
   ///
   /// This generates either a [ValueResult] with the value returned by
   /// calling `computation`, or an [ErrorResult] with an error thrown by
   /// the call.
   factory Result(T computation()) {
     try {
-      return new ValueResult(computation());
+      return new ValueResult<T>(computation());
     } catch (e, s) {
       return new ErrorResult(e, s);
     }
   }
 
   /// Create a `Result` holding a value.
   ///
   /// Alias for [ValueResult.ValueResult].
   factory Result.value(T value) = ValueResult<T>;
 
   /// Create a `Result` holding an error.
   ///
   /// Alias for [ErrorResult.ErrorResult].
   factory Result.error(Object error, [StackTrace stackTrace]) =>
       new ErrorResult(error, stackTrace);
 
   /// Capture the result of a future into a `Result` future.
   ///
   /// The resulting future will never have an error.
   /// Errors have been converted to an [ErrorResult] value.
   static Future<Result<T>> capture<T>(Future<T> future) {
     return future.then((value) => new ValueResult(value),
         onError: (error, stackTrace) => new ErrorResult<T>(error, stackTrace));
   }
 
+  /// Capture each future in [elements],

[floitsch, 2017/08/17 15:29:22]

Dartdoc wants third person. Here and for all other methods.

+  ///
+  /// Returns a (future of) a list of results for each element in [elements],
+  /// in iteration order.
+  /// Each future in [elements] is [capture]d and each non-future is
+  /// wrapped as a [Result.value].
+  /// The returned future will never have an error.
+  static Future<List<Result<T>>> captureAll<T>(Iterable<FutureOr<T>> elements) {
+    var results = <T>[];
+    int pending = 0;
+    var completer;
+    for (var element in elements) {
+      if (element is Future<T>) {
+        int i = results.length;
+        results.add(null);
+        pending++;
+        Result.capture<T>(element).then((result) {
+          results[i] = result;
+          if (--pending == 0) {
+            completer.complete(results);
+          }
+        });
+      } else {
+        results.add(new Result<T>.value(element));
+      }
+    }
+    if (pending == 0) {
+      return new Future<List<Result<T>>>.value(results);
+    }
+    completer = Completer<List<Result<T>>>();
+    return completer.future;
+  }
+
   /// Release the result of a captured future.
   ///
   /// Converts the [Result] value of the given [future] to a value or error
   /// completion of the returned future.
   ///
   /// If [future] completes with an error, the returned future completes with
   /// the same error.
   static Future<T> release<T>(Future<Result<T>> future) =>
       future.then<T>((result) => result.asFuture);
 
@@ skipping 13 matching lines @@
       source.transform(new ReleaseStreamTransformer<T>());
 
   /// Converts a result of a result to a single result.
   ///
   /// If the result is an error, or it is a `Result` value
   /// which is then an error, then a result with that error is returned.
   /// Otherwise both levels of results are value results, and a single
   /// result with the value is returned.
   static Result<T> flatten<T>(Result<Result<T>> result) {
     if (result.isValue) return result.asValue.value;
-    return new ErrorResult<T>(result.asError.error, result.asError.stackTrace);
+    return result.asError;
+  }
+
+  /// Converts a sequence of results to a result of a list.
+  ///
+  /// Returns either a list of values if [results] doesn't contain any errors,
+  /// or the first error result in [results].
+  static Result<List<T>> flattenList(Iterable<Result<T>> results) {
+    var values = <T>[];
+    for (var result in results) {
+      if (result.isValue) {
+        values.add(result.asValue.value);
+      }
+      return result.asError;
+    }
+    return new Result<List<T>>.value(values);
   }
 
   /// Whether this result is a value result.
   ///
   /// Always the opposite of [isError].
   bool get isValue;
 
   /// Whether this result is an error result.
   ///
   /// Always the opposite of [isValue].
   bool get isError;
 
   /// If this is a value result, return itself.
   ///
   /// Otherwise return `null`.
   ValueResult<T> get asValue;
 
   /// If this is an error result, return itself.
   ///
   /// Otherwise return `null`.
-  ErrorResult<T> get asError;
+  ErrorResult get asError;
 
   /// Complete a completer with this result.
   void complete(Completer<T> completer);
 
   /// Add this result to an [EventSink].
   ///
   /// Calls the sink's `add` or `addError` method as appropriate.
   void addTo(EventSink<T> sink);
 
-  /// Creates a future completed with this result as a value or an error.
+  /// A future that has been completed with this result as a value or an error.
   Future<T> get asFuture;
 }