Add a LazyStream class.

lib/src/lazy_stream.dart

Index: lib/src/lazy_stream.dart
diff --git a/lib/src/lazy_stream.dart b/lib/src/lazy_stream.dart
new file mode 100644
index 0000000000000000000000000000000000000000..545e93d0ec8bb5d5123ac01b020657fb3f4c27b3
--- /dev/null
+++ b/lib/src/lazy_stream.dart
@@ -0,0 +1,48 @@
+// 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.lazy_stream;
+
+import "dart:async";
+
+import "stream_completer.dart";
+
+/// A [Stream] wrapper that forwards to another [Stream] that's initialized
+/// lazily.
+///
+/// This class allows a concrete `Stream` to be created only once it has a
+/// listener. It's useful to wrapping APIs that do expensive computation to
+/// produce a `Stream`.
+class LazyStream<T> extends Stream<T> {
+  /// The callback that's called to create the inner stream.
+  ZoneCallback _callback;
+
+  /// Creates a single-subscription `Stream` that calls [callback] when it gets
+  /// a listener and forwards to the returned stream.
+  ///
+  /// The [callback] may return a `Stream` or a `Future<Stream>`.

[Lasse Reichstein Nielsen, 2015/12/03 11:44:19]

We generally recommend against creating a Future<Stream> because a Stream is
already asynchronous. That's why we have the StreamCompleter, to make it
possible to never create a Future<Stream> directly.

Could we at least make a comment to that effect: creating a Future<Stream> is
generally discouraged, please use StreamCompleter to create the stream instead.

[nweiz, 2015/12/11 00:06:57]

The idea is to allow people to use `async` in `callback`, not to have a
synchronous callback that returns a `Future<Stream>`. There are also plenty of
core library functions that return Future<Stream>s—WebSocket.connect and
HttpClientRequest.close, for example. Being able to use those directly rather
than manually wrapping them in a StreamCompleter seems useful.

[Lasse Reichstein Nielsen, 2015/12/11 12:33:21]

Acknowledged.

+  LazyStream(callback())
+      : _callback = callback;

[Lasse Reichstein Nielsen, 2015/12/03 11:44:19]

I would put this on the previous line, there's plenty of room.

[Lasse Reichstein Nielsen, 2015/12/03 11:44:19]

Check that callback isn't null:
  : _callback = callback ?? throw new ArgumentError.notNull("callback");

 

[nweiz, 2015/12/11 00:06:57]

This is contrary to how we treat basically any other parameter anywhere except
maybe the core libraries. 

[nweiz, 2015/12/11 00:06:57]

Done.

+
+  StreamSubscription<T> listen(void onData(T event),
+                               {Function onError,
+                                void onDone(),
+                                bool cancelOnError}) {
+    if (_callback == null) {
+      throw new StateError("Stream has already been listened to.");
+    }
+
+    // Null out the callback before we invoke it to ensure that even while
+    // running it this can't be double-listened.

[Lasse Reichstein Nielsen, 2015/12/03 11:44:20]

comma before "this"? The sentence is hard to read.
be double-listened -> called twice?

[nweiz, 2015/12/11 00:06:57]

Done.

+    var callback = _callback;
+    _callback = null;
+    var result = callback();
+
+    var stream = result is Future ? StreamCompleter.fromFuture(result) : result;
+    assert(stream is Stream);

[Lasse Reichstein Nielsen, 2015/12/03 11:44:19]

Just make it "Stream stream = ...".
No need to introduce an extra assertion doing the same thing (well, it also
checks against null, but we don't generally do that this way).

Also, don't use assert for errors that a user can hit by providing bad
arguments. Especially when the valid arguments are not even visible in the type
of "callback". Either do validation or let the program fail later.

[nweiz, 2015/12/11 00:06:57]

Done.

+
+    return stream.listen(onData,
+        onError: onError, onDone: onDone, cancelOnError: cancelOnError);
+  }
+}