Consider a thrown AsyncError from a future/stream handler a rethrow.

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 [Future] is used to obtain a value sometime in the future.  Receivers of a
  * [Future] can obtain the value by passing a callback to [then]. For example:
  *
@@ skipping 18 matching lines @@
  */
 abstract class Future<T> {
   /** A future whose value is immediately available. */
   factory Future.immediate(T value) => new _FutureImpl<T>.immediate(value);
 
   /** A future that completes with an error. */
   factory Future.immediateError(var error, [Object stackTrace]) {
     return new _FutureImpl<T>.immediateError(error, stackTrace);
   }
 
+  factory Future.delayed(int milliseconds, dynamic value()) {
+    var completer = new Completer<T>();
+    new Timer(milliseconds, (_) => completer.complete(null));
+    return completer.future.then((_) => value());
+  }
+
   // TODO(floitsch): I don't think the typing is right here.
   // Otherwise new Future<int>.wait(...) would be a Future<List<int>>. Sounds
   // wrong.
   factory Future.wait(List<Future> futures)
     => new _FutureImpl<List<T>>.wait(futures);
 
-  factory Future.delayed(int milliseconds, dynamic value()) {
-    var completer = new Completer<T>();
-    new Timer(milliseconds, (_) => completer.complete(null));
-    return completer.future.then((_) => value());
-  }
-
   /**
    * When this future completes with a value, then [onValue] is called with this
    * value. If [this] future is already completed then the invocation of
    * [onValue] is delayed until the next event-loop iteration.
    *
    * Returns a new [Future] [:f:].
    *
    * If [this] is completed with an error then [:f:] is completed with the same
    * error. If [this] is completed with a value, then [:f:]'s completion value
    * depends on the result of invoking [onValue] with [this]' completion value.
    *
    * If [onValue] returns a [Future] [:f2:] then [:f:] and [:f2:] are chained.
    * That is, [:f:] is completed with the completion value of [:f2:].
    *
    * Otherwise [:f:] is completed with the return value of [onValue].
    *
    * If [onValue] throws an exception, the returned future will receive the
-   * exception.
+   * exception. If the value thrown is an [AsyncError], it is used directly,
+   * as the error result, otherwise it's wrapped in an [AsyncError] first.

[floitsch, 2013/01/10 16:38:10]

it is

[Lasse Reichstein Nielsen, 2013/01/11 07:02:05]

Done.

    *
    * If [onError] is provided, it is called if this future completes with an
    * error, and its return value/throw behavior is handled the same way as
-   * for [onValue].
+   * for [catchError] without a [:test:] argument.
    *
    * In most cases, it is more readable to use [catchError] separately, possibly
    * with a [:test:] parameter, instead of handling both value and error in a
    * single [then] call.
    */
   Future then(onValue(T value), { onError(AsyncError asyncError) });
 
   /**
-   * If this future is complete with an error, [test] is called with the error.
+   * Handles errors emitted by this [Future].
+   *
+   * When this future completes with an error, first [test] is called with the
+   * error's value.
+   *
    * If [test] returns [true], [onError] is called with the error
    * wrapped in an [AsyncError]. The result of [onError] is handled exactly as
-   * [then]'s [onValue]. If [test] returns false, the exception is not handled
-   * by [onError]. If [test] is omitted, it defaults to a function that always
-   * returns true.
+   * [then]'s [onValue].
+   *
+   * If [test] returns false, the exception is not handled by [onError], but is
+   * emitted by the returned Future unmodified.

[floitsch, 2013/01/10 16:38:10]

In theory it is, as if the handler was a 'then'-handler. But I'm not sure if
that simplifies the description.

[Lasse Reichstein Nielsen, 2013/01/11 07:02:05]

Not really, no.

+   *
+   * If [test] is omitted, it defaults to a function that always returns true.
    *
    * Example:
    * foo
    *   .catchError(..., test: (e) => e is ArgumentError)
    *   .catchError(..., test: (e) => e is NoSuchMethodError)
    *   .then((v) { ... });
    */
   Future catchError(onError(AsyncError asyncError),
                     {bool test(Object error)});
 
@@ skipping 59 matching lines @@
    * All listeners on the future will be immediately informed about the value.
    */
   void complete([T value]);
 
   /**
    * Complete [future] with an error.
    *
    * Completing a future with an error indicates that an exception was thrown
    * while trying to produce a value.
    *
-   * The argument [exception] should not be [:null:]. A [stackTrace]
-   * object can be provided as well, to give the user information about where
-   * the error occurred. If omitted, it will be [:null:].
+   * The argument [exception] should not be [:null:].
+   *
+   * If [exception] is an [AsyncError], it is used directly as the error
+   * message sent to the future's listeners, and [stackTrace] is ignored.
+   *
+   * Otherwise the [exception] and an optional [stackTrace] is combined and sent

[floitsch, 2013/01/10 16:38:10]

.. is combined into an [AsyncError] and ...

[Lasse Reichstein Nielsen, 2013/01/11 07:02:05]

Done.

+   * this future's listeners.
    */
   void completeError(Object exception, [Object stackTrace]);
 }
 
 class Futures {
   /**
    * Returns a future which will complete once all the futures in a list are
    * complete. If any of the futures in the list completes with an exception,
    * the resulting future also completes with an exception. (The value of the
    * returned future will be a list of all the values that were produced.)
@@ skipping 12 matching lines @@
    */
   static Future forEach(Iterable input, Future f(element)) {
     var iterator = input.iterator;
     Future nextElement(_) {
       if (!iterator.moveNext()) return new Future.immediate(null);
       return f(iterator.current).then(nextElement);
     }
     return nextElement(null);
   }
 }