Add StreamExtensions.firstOrNull

[nex3]

By analogy to IterableExtensions.firstOrNull in the collection package.

[natebosch]

I think we need to hold off on this until we have resolved dart-lang/core#330, and then we can put this in that library.

In the short term we could add this in package:stream_transform which will have a (hopefully) smooth transition once we do incorporate it here.

[nex3]

I don't think this would make sense in stream_transformer, since it's not representable as a transformer—it's a stream-to-future transformation, not a stream-to-stream transformation. Also, there's precedent for adding new features here rather than there in #175.

[natebosch]

it's not representable as a transformer—it's a stream-to-future transformation, not a stream-to-stream transformation

That's a good point.

@lrhn - which library would you prefer this goes into?

[lrhn]

I see no problem with adding it to StreamExtensions in package:async. It's the perfect place. The corresponding collection method was in package:collection, so the analogy is perfect.

Code looks fine too.

We could consider adding more extensions along with this, perhaps before releasing 2.9.0, but starting here seems fine.

[lrhn]

Can use cancelOnError: true. Then you can just tear off completer.completeErrorinstead of creating a new closure. It can even be:

  var subscription = listen(null, 
    onError: completer.completeError,
    onDone: completer.complete, // The argument is optional if the type is nullable!
    cancelOnError: true);
  subscription.onData((event) {
    subscription.cancel();
    completer.complete(event);
  });

[nex3]

I considered doing it that way, but I think the symmetry between the onData and onError events is easier to follow than having one of them manually cancel the subscription and the other cancel it through cancelOnError.