Line data Source code
1 : // Copyright (c) 2016, the Dart project authors. Please see the AUTHORS file
2 : // for details. All rights reserved. Use of this source code is governed by a
3 : // BSD-style license that can be found in the LICENSE file.
4 :
5 : import 'dart:async';
6 :
7 : import 'stream_sink_transformer/handler_transformer.dart';
8 : import 'stream_sink_transformer/stream_transformer_wrapper.dart';
9 : import 'stream_sink_transformer/typed.dart';
10 :
11 : /// A [StreamSinkTransformer] transforms the events being passed to a sink.
12 : ///
13 : /// This works on the same principle as a [StreamTransformer]. Each transformer
14 : /// defines a [bind] method that takes in the original [StreamSink] and returns
15 : /// the transformed version. However, where a [StreamTransformer] transforms
16 : /// events after they leave the stream, this transforms them before they enter
17 : /// the sink.
18 : ///
19 : /// Transformers must be able to have `bind` called used multiple times.
20 : abstract class StreamSinkTransformer<S, T> {
21 : /// Creates a [StreamSinkTransformer] that transforms events and errors
22 : /// using [transformer].
23 : ///
24 : /// This is equivalent to piping all events from the outer sink through a
25 : /// stream transformed by [transformer] and from there into the inner sink.
26 : const factory StreamSinkTransformer.fromStreamTransformer(
27 : StreamTransformer<S, T> transformer) = StreamTransformerWrapper<S, T>;
28 :
29 : /// Creates a [StreamSinkTransformer] that delegates events to the given
30 : /// handlers.
31 : ///
32 : /// The handlers work exactly as they do for [StreamTransformer.fromHandlers].
33 : /// They're called for each incoming event, and any actions on the sink
34 : /// they're passed are forwarded to the inner sink. If a handler is omitted,
35 : /// the event is passed through unaltered.
36 : factory StreamSinkTransformer.fromHandlers(
37 : {void handleData(S data, EventSink<T> sink),
38 : void handleError(Object error, StackTrace stackTrace, EventSink<T> sink),
39 : void handleDone(EventSink<T> sink)}) {
40 0 : return new HandlerTransformer<S, T>(handleData, handleError, handleDone);
41 : }
42 :
43 : /// Transforms the events passed to [sink].
44 : ///
45 : /// Creates a new sink. When events are passed to the returned sink, it will
46 : /// transform them and pass the transformed versions to [sink].
47 : StreamSink<S> bind(StreamSink<T> sink);
48 :
49 : /// Creates a wrapper that coerces the type of [transformer].
50 : ///
51 : /// This soundly converts a [StreamSinkTransformer] to a
52 : /// `StreamSinkTransformer<S, T>`, regardless of its original generic type.
53 : /// This means that calls to [StreamSink.add] on the returned sink may throw a
54 : /// [CastError] if the argument type doesn't match the reified type of the
55 : /// sink.
56 : static StreamSinkTransformer<S, T> typed<S, T>(
57 : StreamSinkTransformer transformer) =>
58 0 : transformer is StreamSinkTransformer<S, T>
59 : ? transformer
60 0 : : new TypeSafeStreamSinkTransformer(transformer);
61 : }
|