Added a `ResultFuture` class.

lib/src/result_future.dart

Index: lib/src/result_future.dart
diff --git a/lib/src/result_future.dart b/lib/src/result_future.dart
new file mode 100644
index 0000000000000000000000000000000000000000..39f0f840d0543a4a3d12e5aa1d79ac0a6a82f909
--- /dev/null
+++ b/lib/src/result_future.dart
@@ -0,0 +1,38 @@
+// Copyright (c) 2015, 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.
+
+library async.result_future;
+
+import 'dart:async';
+
+import '../result.dart';
+import 'delegate/future.dart';
+
+/// A [Future] wrapper that provides synchronous access to the result of the
+/// wrapped [Future] once it's completed.
+class ResultFuture<T> extends DelegatingFuture<T> {

[Lasse Reichstein Nielsen, 2015/07/08 11:01:56]

I think I'd prefer if this was not a Future itself. It doesn't seem to be
necessary for the "capturing a future's result" part.

Maybe name it FutureResult (not perfect, because it's not a Result) and let it
be:

class FutureResult<T> {
  final Future<T> future;
  Result _result;
  bool get hasResult => _result != null;
  Result get result => _result;
  factory FutureResult(Future<T> future) {
    var futureResult;
    // The [newFuture] has the same result as [future], but only
    // completes after 
    var newFuture = Result.capture(future).then((result) { 
      futureResult_result = result; 
      return result.asFuture;
    });
    futureResult = new FutureResult._(newFuture);
    return futureResult;
  }
  FutureResult._(this.future);
}

That is: Make a box on the side that stores the result when it's ready.

Or maybe just:
Future interceptResult(Future future, setResult(Result result)) {
  return Result.capture(future).then((result) { 
    setResult(result);
    return result.asFuture;
  });
}

Then you can use it as:
  Result result;
  var future = interceptFuture(otherFuture, (v) { result = v; }); 


Hmm, I begin to see a pattern in my comments - I oppose classes that do multiple
things that don't need to be combined in one class, even if it's only
implicitly.

Here you want capture the result of a future when it's ready.
You have another future complete with the same result when 
the result is ready (does it need to be the same result? Or is that actually a
problem if it's an error and you have to handle it?)

Then this is combined into both being the other future and holding the captured
result.

So, what is the problem that you are trying to solve here, and does it need to
be one class that is both a Future and more?

[nweiz, 2015/07/09 01:18:38]

This is designed for the use-case of a class that has asynchronous state and
needs to react to external events that may occur at any time. It's often more
important to know *whether* the future is complete (I should add a getter for
this), and only secondarily important to get its value synchronously.

For example, scheduled_test has a ScheduledProcess class that uses the original
version of this class to track the process's exit code. If the test fails before
the process has finished running, ScheduledProcess checks whether the exit code
exists to know whether to kill the process.

I put this on a Future for several reasons. First, it's more ergonomic, in the
sense that these are often used as instance variables. Initializing two instance
variables based on the same value (like with your interceptResult function) is
very difficult and verbose, whereas keeping them together reads nicely: "if
(_exitCode.hasResult)", for example.

Second, it feels like the existence of a result and its value are aspects of the
future itself. Granted this is pretty subjective, but just like you don't like
having a single object doing unrelated things, I don't like having two objects
doing tightly-coupled things. Having a FutureResult whose state is intrinsically
entangled with another Future seems weird to me.

Finally, only accessing the future methods through the ResultFuture gives
stronger timing guarantees. No matter how it's set up, you can be sure that the
ResultFuture's fields will be set correctly by the time its callbacks fire.

[Lasse Reichstein Nielsen, 2015/07/09 11:18:20]

I can see the argument - whether a future is completed and what it completed
with *are* properties of the future. It's just properties that we usually don't
expose because it tends to cause users to write half-async/half-sync code where
pure async code is usually safer.

Here you want to know if a future is complete because it tells you that a
process is complete.
It seem like a question you should be asking the process (are you done?), not
its result (are you there yet?). If you can kill the process, you should have
access to it.

Still, the problem is probably not unique - you need to do something if
something else has *not* happened - and a future not completing isn't easy to
detect.

I think I would be easier to convince if it only has an [isComplete] getter, not
the [result] getter. Using the result of an asynchronous computation
synchronously has some dangers (mostly not handling errors correctly, which is
hard because you can't retain the stack-trace if you rethrow the error
synchronously).

[nweiz, 2015/07/13 20:05:52]

I'd be okay with changing this to just have an [isComplete] getter, but it would
need a new name, and I'm having trouble thinking of a good one.

+  /// The wrapped [Future].
+  Future<T> _future;

[Lasse Reichstein Nielsen, 2015/07/09 11:18:20]

I don't think this field is used at all.

[nweiz, 2015/07/13 20:05:52]

Done.

+
+  /// The result of the wrapped [Future], if it's completed.
+  ///
+  /// If it hasn't completed yet, this will be `null`.
+  Result<T> get result => _result;
+  Result<T> _result;
+
+  factory ResultFuture(Future<T> future) {
+    var resultFuture;
+    resultFuture = new ResultFuture._(future.then((value) {
+      resultFuture._result = new Result.value(value);
+      return value;
+    }).catchError((error, stackTrace) {
+      resultFuture._result = new Result.error(error, stackTrace);
+      throw error;
+    }));

[Lasse Reichstein Nielsen, 2015/07/08 11:01:57]

The `Result.capture(Future future)` can handle this for you.
For this code you could do:
 
 Result.capture(future).then((result) { 
   resultFuture._result = result;
   return result.asFuture;
 });

[nweiz, 2015/07/09 01:18:38]

Done.

+    return resultFuture;
+  }
+
+  ResultFuture._(Future<T> future)
+      : super(future);
+}