Making a stream transformer involves a lot of boilerplate

[Hixie]

Edit: this comment is wrong, see below.

As far as I can tell, the simplest way to write a StreamTransformer is something like this (untested):

class CloudBitStreamParser extends StreamTransformer<String, dynamic> {
  @override
  Stream<dynamic> bind(Stream<String> stream) {
    Stream<dynamic> output;
    StreamSubscription<String> input;
    output = StreamController<dynamic>(
      onListen: () {
        input = stream.listen(
          onData: (String event) {
            if (event.isEmpty)
              return;
            if (event.startsWith('data:')) {
              output.add(JSON.decode(event.substring(5))); // 5 is the length of the string 'data:'
              return;
            }
            output.addError('Unexpected data from CloudBit stream: "$event"');
          },
          onError: (dynamic exception, StackTrace stack) {
            output.addError(exception, stack);
          },
          onDone: () {
            output.close();
          },
        );
      },
      onPause: () {
        input.pause();
      },
      onResume: () {
        input.resume();
      },
      onCancel: () {
        input.cancel();
      },
    );
    return output;
  }
}

It seems like the above could be simplified to:

class CloudBitStreamParser extends FooStreamTransformer<String, dynamic> {
  @override
  void convert(String event, StreamSubscription<String> input, Stream<dynamic> output) {
    if (event.isEmpty)
      return;
    if (event.startsWith('data:')) {
      output.add(JSON.decode(event.substring(5))); // 5 is the length of the string 'data:'
      return;
    }
    output.addError('Unexpected data from CloudBit stream: "$event"');
  }
}

...where FooStreamTransformer is a subclass of StreamTransformer that does all the boilerplate logic.

(Alternatively, if the code above is wrong, then the dartdocs for StreamTransformer should be expanded to explain how to actually implement a StreamTransformer.)

[lrhn]

You can use StreamTransformer.fromHandlers to easily create transformers that just convert input events to output events.

Example:

new StreamTransformer.fromHandlers(handleData: (String event, EventSink output) {
  if (event.startsWith('data:')) {
    output.add(JSON.decode(event.substring('data:'.length)));
  } else if (event.isNotEmpty) {
    output.addError('Unexpected data from CloudBit stream: "$event"');
  }
});

[Hixie]

Turns out the code I have in the original comment won't work at all because you just can't extend StreamTransformer at all.

The documentation for StreamTransformer:

• Should explain that you can't extend it and should just implement it instead.
• Should explain why you can't extend it.
• Should explain how to implement a StreamTransformer, e.g. pointing to its fromHandlers constructor.

The docs for fromHandlers should explain:

• What the default behaviour for errors on the incoming stream is.
• What it handles for you (e.g. forwarding paused state, cancellation).
• How to cancel the stream in response to an event.

[lrhn]

That is reasonable. It's clearly under-documented.
The "why" you can't extend it is simple - it's an interface, it has no implementation to inherit, so there is no reason to extend it.

(The StreamTransformer class is really a mistake - it's a single-method-interface so it should just have been a function type, but too late to fix that now).

[Hixie]

Ah, yes, I was confused by the other classes around here and thought this one had some implementation logic you would want to inherit.

[Hixie]

(The StreamTransformer class is really a mistake - it's a single-method-interface so it should just have been a function type, but too late to fix that now).

It's cleaner to use a class when you have long-lived state (the alternative is jumping through hoops to get the closure to capture the state you want to keep, which can be somewhat ugly). In fact in doing the work I'm doing now, I rather wish there was a class that implemented the fromHandlers stuff so I could inherit from that rather than using fromHandlers...

[Hixie]

...though I guess since StreamTransformer wants to be re-usable, that doesn't really work here anyway.