Add a StreamSinkTransformer class.

lib/src/stream_sink_transformer.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.
+
+library async.stream_sink_transformer;
+
+import 'dart:async';
+
+import 'stream_sink_transformer/handler_transformer.dart';
+import 'stream_sink_transformer/stream_transformer_wrapper.dart';
+
+/// A [StreamSinkTransformer] transforms the events being passed to a sink.
+///
+/// This works on the same principle as a [StreamTransformer]. Each transformer
+/// defines a [bind] method that takes in the original [StreamSink] and returns
+/// the transformed version. However, where a [StreamTransformer] transforms
+/// events after they leave the stream, this transforms them before they enter
+/// the sink.
+///
+/// It's good practice to write transformers that can be used multiple times.

[Lasse Reichstein Nielsen, 2016/01/07 07:37:01]

Not sure what this line says?
I *think* it means that you should be able to call the bind function multiple
times on the same transformer. If so, I would drop the "good practice" and say
"must".

[nweiz, 2016/01/07 21:32:26]

Done.

I copied this line almost verbatim from the StreamTransformer docs, so those
should probably get updated as well.

[Lasse Reichstein Nielsen, 2016/01/08 07:23:06]

Good point, I'll look at that.

+abstract class StreamSinkTransformer<S, T> {

[Lasse Reichstein Nielsen, 2016/01/07 07:37:01]

Do we really need a class?
It has exactly one instance method, so I think
https://www.dartlang.org/effective-dart/design/#avoid-defining-a-one-member-a...
applies.

That is:

  typedef StreamSink<S> StreamSinkTransformer<S, T>(StreamSink<T> sink);

then have functions returning such a function instead of constructors returning
instances.
You can keep the implementation classes and rename "bind" to "call".

[nweiz, 2016/01/07 21:32:26]

My biggest worry with that is how inconsistent it is with StreamTransformer.
Even if we consider the core API design a mistake in retrospect, I think it's
really useful to make core-adjacent packages like this very closely mirror the
core design. Users tend to be much more familiar with the core than with
adjacent packages, *and* they expect those packages to feel like "extra core
libraries", so any inconsistencies have an outsized effect on their experience.

It also has ripple effects on APIs that use this. With StreamTransformer,
there's a strong pattern both in and out of core of const-declared transformers,
transformers with constructor parameters, and other patterns that don't work
with a typedef'd function.
Unfortunately, classes can't implement function types, even if they could be
called like those functions.

[Lasse Reichstein Nielsen, 2016/01/08 07:23:06]

True. StreamTransformer is used on other classes too (like Encoder), but
it's also used as stand-alone, so there is precedent.
I would consider it that.
That's a valid argument. Keep the class.
They would, if they had a call method.
Actually, they can and do. If a class has a call method, it also has the
function type that the call method has.


class C {
  int call(int x) => 42;
}

typedef int IntFunc(int _);

main() {
  print(new C() is IntFunc);  // true!
}

+  /// Creates a [StreamSinkTransformer] that transforms events and errors
+  /// using [transformer].
+  ///
+  /// This is equivalent to piping all events from the outer sink through a
+  /// stream transformed by [transformer] and from there into the inner sink.
+  const factory StreamSinkTransformer.fromStreamTransformer(
+          StreamTransformer<S, T> transformer) =
+      StreamTransformerWrapper<S, T>;
+
+  /// Creates a [StreamSinkTransformer] that delegates events to the given
+  /// handlers.
+  ///
+  /// The handlers work exactly as they do for [StreamTransformer.fromHandlers].
+  /// They're called for each incoming event, and any actions on the sink
+  /// they're passed are forwarded to the inner sink.

[Lasse Reichstein Nielsen, 2016/01/07 07:37:01]

Specify what happens if a handler is omitted (it should default to just passing
the value through).

[nweiz, 2016/01/07 21:32:26]

Done.

+  factory StreamSinkTransformer.fromHandlers({
+      void handleData(S data, EventSink<T> sink),
+      void handleError(Object error, StackTrace stackTrace, EventSink<T> sink),
+      void handleDone(EventSink<T> sink)}) {
+    return new HandlerTransformer<S, T>(handleData, handleError, handleDone);
+  }
+
+  /// Transforms the events passed to [sink].
+  ///
+  /// Creates a new sink. When events are passed to the returned sink, it will
+  /// transform them and pass the transformed versions to [sink].
+  StreamSink<S> bind(StreamSink<T> sink);
+}