pkgs/stream_transform/README.md - tools.git - Git at Google

 [![Build Status](https://github.com/dart-lang/tools/actions/workflows/stream_transform.yaml/badge.svg)](https://github.com/dart-lang/tools/actions/workflows/stream_transform.yaml)
 [![pub package](https://img.shields.io/pub/v/stream_transform.svg)](https://pub.dev/packages/stream_transform)
 [![package publisher](https://img.shields.io/pub/publisher/stream_transform.svg)](https://pub.dev/packages/stream_transform/publisher)

 Extension methods on `Stream` adding common transform operators.

 ## Operators

 ### asyncMapBuffer, asyncMapSample, concurrentAsyncMap

 Alternatives to `asyncMap`. `asyncMapBuffer` prevents the callback from
 overlapping execution and collects events while it is executing.
 `asyncMapSample` prevents overlapping execution and discards events while it is
 executing. `concurrentAsyncMap` allows overlap and removes ordering guarantees
 for higher throughput.

 Like `asyncMap` but events are buffered in a List until previous events have
 been processed rather than being called for each element individually.

 ### asyncWhere

 Like `where` but allows an asynchronous predicate.

 ### audit

 Waits for a period of time after receiving a value and then only emits the most
 recent value.

 ### buffer

 Collects values from a source stream until a `trigger` stream fires and the
 collected values are emitted.

 ### combineLatest, combineLatestAll

 Combine the most recent event from multiple streams through a callback or into a
 list.

 ### debounce, debounceBuffer

 Prevents a source stream from emitting too frequently by dropping or collecting
 values that occur within a given duration.

 ### followedBy

 Appends the values of a stream after another stream finishes.

 ### merge, mergeAll, concurrentAsyncExpand

 Interleaves events from multiple streams into a single stream.

 ### scan

 Scan is like fold, but instead of producing a single value it yields each
 intermediate accumulation.

 ### startWith, startWithMany, startWithStream

 Prepend a value, an iterable, or a stream to the beginning of another stream.

 ### switchMap, switchLatest

 Flatten a Stream of Streams into a Stream which forwards values from the most
 recent Stream

 ### takeUntil

 Let values through until a Future fires.

 ### tap

 Taps into a single-subscriber stream to react to values as they pass, without
 being a real subscriber.

 ### throttle

 Blocks events for a duration after an event is successfully emitted.

 ### whereType

 Like `Iterable.whereType` for a stream.

 ## Comparison to Rx Operators

 The semantics and naming in this package have some overlap, and some conflict,
 with the [ReactiveX](https://reactivex.io/) suite of libraries. Some of the
 conflict is intentional - Dart `Stream` predates `Observable` and coherence with
 the Dart ecosystem semantics and naming is a strictly higher priority than
 consistency with ReactiveX.

 Rx Operator Category      | variation                                              | `stream_transform`
 ------------------------- | ------------------------------------------------------ | ------------------
 [`sample`][rx_sample]     | `sample/throttleLast(Duration)`                        | `sample(Stream.periodic(Duration), longPoll: false)`
 &#x200B;                  | `throttleFirst(Duration)`                              | [`throttle`][throttle]
 &#x200B;                  | `sample(Observable)`                                   | `sample(trigger, longPoll: false)`
 [`debounce`][rx_debounce] | `debounce/throttleWithTimeout(Duration)`               | [`debounce`][debounce]
 &#x200B;                  | `debounce(Observable)`                                 | No equivalent
 [`buffer`][rx_buffer]     | `buffer(boundary)`, `bufferWithTime`,`bufferWithCount` | No equivalent
 &#x200B;                  | `buffer(boundaryClosingSelector)`                      | `buffer(trigger, longPoll: false)`
 RxJs extensions           | [`audit(callback)`][rxjs_audit]                        | No equivalent
 &#x200B;                  | [`auditTime(Duration)`][rxjs_auditTime]                | [`audit`][audit]
 &#x200B;                  | [`exhaustMap`][rxjs_exhaustMap]                        | No equivalent
 &#x200B;                  | [`throttleTime(trailing: true)`][rxjs_throttleTime]    | `throttle(trailing: true)`
 &#x200B;                  | `throttleTime(leading: false, trailing: true)`         | No equivalent
 No equivalent?            |                                                        | [`asyncMapBuffer`][asyncMapBuffer]
 &#x200B;                  |                                                        | [`asyncMapSample`][asyncMapSample]
 &#x200B;                  |                                                        | [`buffer`][buffer]
 &#x200B;                  |                                                        | [`sample`][sample]
 &#x200B;                  |                                                        | [`debounceBuffer`][debounceBuffer]
 &#x200B;                  |                                                        | `debounce(leading: true, trailing: false)`
 &#x200B;                  |                                                        | `debounce(leading: true, trailing: true)`

 [rx_sample]:https://reactivex.io/documentation/operators/sample.html
 [rx_debounce]:https://reactivex.io/documentation/operators/debounce.html
 [rx_buffer]:https://reactivex.io/documentation/operators/buffer.html
 [rxjs_audit]:https://rxjs.dev/api/operators/audit
 [rxjs_auditTime]:https://rxjs.dev/api/operators/auditTime
 [rxjs_throttleTime]:https://rxjs.dev/api/operators/throttleTime
 [rxjs_exhaustMap]:https://rxjs.dev/api/operators/exhaustMap
 [asyncMapBuffer]:https://pub.dev/documentation/stream_transform/latest/stream_transform/AsyncMap/asyncMapBuffer.html
 [asyncMapSample]:https://pub.dev/documentation/stream_transform/latest/stream_transform/AsyncMap/asyncMapSample.html
 [audit]:https://pub.dev/documentation/stream_transform/latest/stream_transform/RateLimit/audit.html
 [buffer]:https://pub.dev/documentation/stream_transform/latest/stream_transform/RateLimit/buffer.html
 [sample]:https://pub.dev/documentation/stream_transform/latest/stream_transform/RateLimit/sample.html
 [debounceBuffer]:https://pub.dev/documentation/stream_transform/latest/stream_transform/RateLimit/debounceBuffer.html
 [debounce]:https://pub.dev/documentation/stream_transform/latest/stream_transform/RateLimit/debounce.html
 [throttle]:https://pub.dev/documentation/stream_transform/latest/stream_transform/RateLimit/throttle.html

 ## Getting a `StreamTransformer` instance

 It may be useful to pass an instance of `StreamTransformer` so that it can be
 used with `stream.transform` calls rather than reference the specific operator
 in place. Any operator on `Stream` that returns a `Stream` can be modeled as a
 `StreamTransformer` using the [`fromBind` constructor][fromBind].

 ```dart
 final debounce = StreamTransformer.fromBind(
     (s) => s.debounce(const Duration(milliseconds: 100)));
 ```

 [fromBind]: https://api.dart.dev/stable/dart-async/StreamTransformer/StreamTransformer.fromBind.html
	[![Build Status](https://github.com/dart-lang/tools/actions/workflows/stream_transform.yaml/badge.svg)](https://github.com/dart-lang/tools/actions/workflows/stream_transform.yaml)
	[![pub package](https://img.shields.io/pub/v/stream_transform.svg)](https://pub.dev/packages/stream_transform)
	[![package publisher](https://img.shields.io/pub/publisher/stream_transform.svg)](https://pub.dev/packages/stream_transform/publisher)

	Extension methods on `Stream` adding common transform operators.

	## Operators

	### asyncMapBuffer, asyncMapSample, concurrentAsyncMap

	Alternatives to `asyncMap`. `asyncMapBuffer` prevents the callback from
	overlapping execution and collects events while it is executing.
	`asyncMapSample` prevents overlapping execution and discards events while it is
	executing. `concurrentAsyncMap` allows overlap and removes ordering guarantees
	for higher throughput.

	Like `asyncMap` but events are buffered in a List until previous events have
	been processed rather than being called for each element individually.

	### asyncWhere

	Like `where` but allows an asynchronous predicate.

	### audit

	Waits for a period of time after receiving a value and then only emits the most
	recent value.

	### buffer

	Collects values from a source stream until a `trigger` stream fires and the
	collected values are emitted.

	### combineLatest, combineLatestAll

	Combine the most recent event from multiple streams through a callback or into a
	list.

	### debounce, debounceBuffer

	Prevents a source stream from emitting too frequently by dropping or collecting
	values that occur within a given duration.

	### followedBy

	Appends the values of a stream after another stream finishes.

	### merge, mergeAll, concurrentAsyncExpand

	Interleaves events from multiple streams into a single stream.

	### scan

	Scan is like fold, but instead of producing a single value it yields each
	intermediate accumulation.

	### startWith, startWithMany, startWithStream

	Prepend a value, an iterable, or a stream to the beginning of another stream.

	### switchMap, switchLatest

	Flatten a Stream of Streams into a Stream which forwards values from the most
	recent Stream

	### takeUntil

	Let values through until a Future fires.

	### tap

	Taps into a single-subscriber stream to react to values as they pass, without
	being a real subscriber.

	### throttle

	Blocks events for a duration after an event is successfully emitted.

	### whereType

	Like `Iterable.whereType` for a stream.

	## Comparison to Rx Operators

	The semantics and naming in this package have some overlap, and some conflict,
	with the [ReactiveX](https://reactivex.io/) suite of libraries. Some of the
	conflict is intentional - Dart `Stream` predates `Observable` and coherence with
	the Dart ecosystem semantics and naming is a strictly higher priority than
	consistency with ReactiveX.

	Rx Operator Category \| variation \| `stream_transform`
	------------------------- \| ------------------------------------------------------ \| ------------------
	[`sample`][rx_sample] \| `sample/throttleLast(Duration)` \| `sample(Stream.periodic(Duration), longPoll: false)`
	\| `throttleFirst(Duration)` \| [`throttle`][throttle]
	\| `sample(Observable)` \| `sample(trigger, longPoll: false)`
	[`debounce`][rx_debounce] \| `debounce/throttleWithTimeout(Duration)` \| [`debounce`][debounce]
	\| `debounce(Observable)` \| No equivalent
	[`buffer`][rx_buffer] \| `buffer(boundary)`, `bufferWithTime`,`bufferWithCount` \| No equivalent
	\| `buffer(boundaryClosingSelector)` \| `buffer(trigger, longPoll: false)`
	RxJs extensions \| [`audit(callback)`][rxjs_audit] \| No equivalent
	\| [`auditTime(Duration)`][rxjs_auditTime] \| [`audit`][audit]
	\| [`exhaustMap`][rxjs_exhaustMap] \| No equivalent
	\| [`throttleTime(trailing: true)`][rxjs_throttleTime] \| `throttle(trailing: true)`
	\| `throttleTime(leading: false, trailing: true)` \| No equivalent
	No equivalent? \| \| [`asyncMapBuffer`][asyncMapBuffer]
	\| \| [`asyncMapSample`][asyncMapSample]
	\| \| [`buffer`][buffer]
	\| \| [`sample`][sample]
	\| \| [`debounceBuffer`][debounceBuffer]
	\| \| `debounce(leading: true, trailing: false)`
	\| \| `debounce(leading: true, trailing: true)`

	[rx_sample]:https://reactivex.io/documentation/operators/sample.html
	[rx_debounce]:https://reactivex.io/documentation/operators/debounce.html
	[rx_buffer]:https://reactivex.io/documentation/operators/buffer.html
	[rxjs_audit]:https://rxjs.dev/api/operators/audit
	[rxjs_auditTime]:https://rxjs.dev/api/operators/auditTime
	[rxjs_throttleTime]:https://rxjs.dev/api/operators/throttleTime
	[rxjs_exhaustMap]:https://rxjs.dev/api/operators/exhaustMap
	[asyncMapBuffer]:https://pub.dev/documentation/stream_transform/latest/stream_transform/AsyncMap/asyncMapBuffer.html
	[asyncMapSample]:https://pub.dev/documentation/stream_transform/latest/stream_transform/AsyncMap/asyncMapSample.html
	[audit]:https://pub.dev/documentation/stream_transform/latest/stream_transform/RateLimit/audit.html
	[buffer]:https://pub.dev/documentation/stream_transform/latest/stream_transform/RateLimit/buffer.html
	[sample]:https://pub.dev/documentation/stream_transform/latest/stream_transform/RateLimit/sample.html
	[debounceBuffer]:https://pub.dev/documentation/stream_transform/latest/stream_transform/RateLimit/debounceBuffer.html
	[debounce]:https://pub.dev/documentation/stream_transform/latest/stream_transform/RateLimit/debounce.html
	[throttle]:https://pub.dev/documentation/stream_transform/latest/stream_transform/RateLimit/throttle.html

	## Getting a `StreamTransformer` instance

	It may be useful to pass an instance of `StreamTransformer` so that it can be
	used with `stream.transform` calls rather than reference the specific operator
	in place. Any operator on `Stream` that returns a `Stream` can be modeled as a
	`StreamTransformer` using the [`fromBind` constructor][fromBind].

	```dart
	final debounce = StreamTransformer.fromBind(
	(s) => s.debounce(const Duration(milliseconds: 100)));
	```

	[fromBind]: https://api.dart.dev/stable/dart-async/StreamTransformer/StreamTransformer.fromBind.html