What changed?
Methods receiving error-handlers now accept callbacks of arity 1 or 2. For example Future.catchError can now be invoked with either handleError(error) or handleError(error, stackTrace).
We modified the constructor of StreamTransformer.
We removed StreamEventTransformer and EventTransformStream.
We have deprecated getAttachedStackTrace.
We have renamed runAsync to scheduleMicrotask.
Who is affected?
This is an immediately-breaking change for users of the StreamTransformer-constructor and the removed StreamEventTransform and EventTransformStream classes.
Other users should be ok for a few weeks (but at most until the end of October), but are encouraged to update their asynchronous error-handling code as soon as possible.
How do I update my code?
Error Handling:
All asynchronous error-handling function can now receive the stack trace as second argument. If you want to have a stack trace, change your current error-handler to accept a second argument.
For example:
future.catchError((error) {
print(error);
print(getAttachedStackTrace(error));
}
becomes
future.catchError((e, stackTrace) {
print(e);
print(stackTrace);
}
StreamTransformer constructor:
Switch to the StreamTransformer.fromHandlers, and add a `stackTrace` argument to your error-handler:
new StreamTransformer(handleData: f1, handleError: (e, sink) => ..., handleDone: f3)
becomes:
new StreamTransformer.fromHandlers(handleData: f1, handleError: (e, stackTrace, sink) => ..., handleDone: f3)
Also note that the EventSink now takes an optional stackTrace argument.
Users of StreamEventTransformer and EventTransformStream:
Ideally you should switch to the updated StreamTransformer constructor, or use the Stream.eventTransformed constructor. In most cases the StreamTransformers can be adapted in a relatively straight-forward way. You can also copy the code we removed into your project.
Feel free to ask for help on the mailing-list.
Why did this change happen?
Before this change asynchronous error handlers didn't receive stack traces with their errors. Instead the stack traces were attached to the objects and could be retrieved with `getAttachedStackTrace`. This always was a temporary solution (and the method was marked as "experimental" for this reason) since it comes with severe restrictions like not being able to get the stack trace of String errors.
For these reasons we decided to change the error-handling in dart:async: all error-handling callbacks (arguments to Future.catchError, Stream.handleError, ...) are now typed as "Function" and can take either one or two arguments. If the callback takes two arguments, it receives the stack trace (or `null` if there is none) when it is invoked.
This change is mostly non-breaking, except for Stream transformers: the `handleError` of the `StreamTransformer` constructor was typed as `handleError(error, EventSink sink)` and `StreamEventTransformer` had an `addError(Object error, EventSink<T> sink)` method. Since updating this method breaks user code we decided to go one step further and clean these areas of the library.
This involved removing `StreamEventTransformer` and `EventTransformStream`. In return we added the Stream.eventTransformed and StreamTransformer constructors.
The runAsync renaming was triggered by standardization efforts in Html5, W3C, which uses this name for similar callbacks. We considered renaming "Future" to "Promise" but, contrary to "runAsync", futures are used *much* more frequently and would break many more programs.
When will the change take effect?
The changes were committed a few minutes ago.
--
Give a man a fire and he's warm for the whole day,
but set fire to him and he's warm for the rest of his life. - Terry Pratchett