Add StreamChannel.withCloseGuarantee.

lib/stream_channel.dart

 // Copyright (c) 2016, 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.
 
 import 'dart:async';
 
 import 'package:async/async.dart';
 
 import 'src/guarantee_channel.dart';
+import 'src/close_guarantee_channel.dart';
 import 'src/stream_channel_transformer.dart';
 
 export 'src/delegating_stream_channel.dart';
 export 'src/disconnector.dart';
 export 'src/isolate_channel.dart';
 export 'src/json_document_transformer.dart';
 export 'src/multi_channel.dart';
 export 'src/stream_channel_completer.dart';
 export 'src/stream_channel_controller.dart';
 export 'src/stream_channel_transformer.dart';
@@ skipping 60 matching lines @@
   /// just wrapping a stream and a sink directly, so [new StreamChannel] should
   /// be used when the guarantees are provided natively.
   ///
   /// If [allowSinkErrors] is `false`, errors are not allowed to be passed to
   /// [sink]. If any are, the connection will close and the error will be
   /// forwarded to [Sink.done].
   factory StreamChannel.withGuarantees(Stream<T> stream, StreamSink<T> sink,
           {bool allowSinkErrors: true}) =>
       new GuaranteeChannel(stream, sink, allowSinkErrors: allowSinkErrors);
 
+  /// Creates a new [StreamChannel] that communicates over [stream] and [sink].
+  ///
+  /// This specifically enforces the second guarantee: closing the sink causes
+  /// the stream to close before it emits any more events. This guarantee is
+  /// invalidated when an asynchronous gap is added between the original
+  /// stream's event dispatch and the returned stream's, for example by
+  /// transforming it with a [StreamTransformer]. This is a lighter-weight way
+  /// of preserving that guarantee in particular than
+  /// [StreamChannel.withGuarantees].
+  factory StreamChannel.withCloseGuarantee(Stream<T> stream,
+          StreamSink<T> sink) =>
+      new CloseGuaranteeChannel(stream, sink);
+
   /// Connects [this] to [other], so that any values emitted by either are sent
   /// directly to the other.
   void pipe(StreamChannel<T> other);
 
   /// Transforms [this] using [transformer].
   ///
   /// This is identical to calling `transformer.bind(channel)`.
   StreamChannel transform(StreamChannelTransformer<T, dynamic> transformer);
 
   /// Transforms only the [stream] component of [this] using [transformer].
@@ skipping 41 matching lines @@
   StreamChannel transform(StreamChannelTransformer<T, dynamic> transformer) =>
       transformer.bind(this);
 
   StreamChannel<T> transformStream(StreamTransformer<T, T> transformer) =>
       changeStream(transformer.bind);
 
   StreamChannel<T> transformSink(StreamSinkTransformer<T, T> transformer) =>
       changeSink(transformer.bind);
 
   StreamChannel<T> changeStream(Stream<T> change(Stream<T> stream)) =>
-      new StreamChannel(change(stream), sink);
+      new StreamChannel.withCloseGuarantee(change(stream), sink);
 
   StreamChannel<T> changeSink(StreamSink<T> change(StreamSink<T> sink)) =>
-      new StreamChannel(stream, change(sink));
+      new StreamChannel.withCloseGuarantee(stream, change(sink));
 
   StreamChannel/*<S>*/ cast/*<S>*/() => new StreamChannel(
       DelegatingStream.typed(stream), DelegatingStreamSink.typed(sink));
 }