rxdart_ext 0.2.3

Some extension methods and classes built on top of RxDart - RxDart extension.

rxdart_ext

Author: Petrus Nguyễn Thái Học

Some extension methods and classes built on top of RxDart - RxDart extension.

Buy me a coffee

Liked some of my work? Buy me a coffee (or more likely a beer)

RxDart compatibility

rxdart	rxdart_ext
0.26.0	below 0.0.1
from 0.27.0 to 0.27.1	from 0.1.0 to 0.1.1
0.27.2	0.1.2
0.27.3	from 0.1.3 to 0.2.0
from 0.27.4 to 0.27.5	from 0.2.1 to 0.2.3

API

1. Single

A Stream which emits single event, either data or error, and then close with a done-event.

Success case: ------------(*)|------
                         data done

Failure case: ------------(x)|------
                        error done

NOTE: Single extends Stream, so all operators and transformers for Stream are available for Single as well.

Single is suitable for one-shot operations (likes Future but lazy - executes when listening), eg. making API request, reading local storage, ...

import 'package:http/http.dart' as http;

Single<User> fetchUser(String id) {
  return Single.fromCallable(() => http.get(Uri.parse('$baseUrl/users/$id')))
      .flatMapSingle((res) => res.statusCode == HttpStatus.ok
          ? Single.value(res.body)
          : Single.error(Exception('Cannot fetch user with id=$id')))
      .map((body) => User.fromJson(jsonEncode(body)));
}

• Create Single

  • Factory constructors.

    • Single.fromStream
    • Single.value
    • Single.error
    • Single.fromFuture
    • Single.fromCallable
    • Single.timer
    • Single.defer
    • Single.retry

  • Static methods provided by RxSingles class

    • RxSingles.zip2
    • RxSingles.forkJoin2

  • Convert others to Single via extensions.

    • Stream.singleOrError
    • Future.asSingle
    • (FutureOr<T> Function()).asSingle

• Operators for Single (returns a Single instead of Stream)

  • flatMapSingle
  • asyncExpandSingle
  • switchMapSingle
  • exhaustMapSingle
  • debug
  • delay
  • doOnCancel
  • doOnData
  • doOnError
  • doOnListen
  • onErrorReturn
  • onErrorReturnWith
  • onErrorResumeSingle
  • onErrorResumeNextSingle
  • mapTo
  • asVoid

2. Operators for Stream

• debug, collect
• distinctUniqueBy
• distinctBy
• doOn
• doneOnError
• flatMapBatches
• flatMapBatchesSingle
• ignoreErrors
• mapNotNull (moved to rxdart 0.27.4 as standard operator: mapNotNull)
• toSingleSubscription
• asVoid
• whereNotNull (moved to rxdart 0.27.4 as standard operator: whereNotNull)

3. StateStream

A Stream that provides synchronous access to the last emitted item, and two consecutive values are not equal. The equality between previous data event and current data event is determined by StateStream.equals. This Stream always has no error.

• Broadcast
  • StateSubject
  • StateConnectableStream
    • publishState
    • shareState
• Single-subscription
  • toStateStream

Example

Useful for Flutter BLoC pattern - StreamBuilder, expose broadcast state stream to UI, can synchronous access to the last emitted item, and distinct until changed

• Distinct: distinct until changed.
• Value: can synchronous access to the last emitted item.
• NotReplay: not replay the latest value.
• Connectable: broadcast stream - can be listened to multiple time.

                                Stream (dart:core)
                                   ^
                                   |
                                   |
            |--------------------------------------------|
            |                                            |
            |                                            |
        ValueStream (rxdart)                             |
            ^                                            |
            |                                            |
            |                                            |
    NotReplayValueStream (rxdart_ext)                    |
            ^                                    ConnectableStream (rxdart)
            |                                            ^
            |                                            |
       StateStream (rxdart_ext)                          |
            ^                                            |
            |                                            |
            |------------                     -----------|
                        |                     |
                        |                     |
                     StateConnectableStream (rxdart_ext)

class UiState { ... }

final Stream<UiState> state$ = ...;

final StateConnectableStream<UiState> state$ = state$.publishState(UiState.initial());
final connection = state$.connect();

StreamBuilder<UiState>(
  initialData: state$.value,
  stream: state$,
  builder: (context, snapshot) {
    final UiState state = snapshot.requireData;
    
    return ...;
  },
);

4. NotReplayValueStream

A Stream that provides synchronous access to the last emitted item, but not replay the latest value.

• Broadcast
  • ValueSubject
  • NotReplayValueConnectableStream
    • publishValueNotReplay
    • shareValueNotReplay
• Single-subscription
  • ValueStreamController
  • toNotReplayValueStream

5. Utils

DisposableMixin

A mixin that makes it easy to dispose streams without having to store and close a StreamSubscription variable.

Typical usage is as follows:

class DisposableExample with DisposableMixin {
  DisposableExample({
    required Stream<DateTime> dateTimeStream,
  }) {
    dateTimeStream.takeUntil(dispose$).listen(
          (value) => print('Disposable example: $value'),
        );
  }
}

License

MIT License

Copyright (c) 2020-2022 Petrus Nguyễn Thái Học