Prepare version 0.10.0

CHANGELOG.md

@@ -1,3 +1,22 @@
+## 0.10.0
+
+* Api Changes
+  * Observable
+    * Remove all deprecated methods, including:
+      * `observable` factory -- replaced by the constructor `new Observable()`
+      * `combineLatest` -- replaced by Strong-Mode versions `combineLatest2` - `combineLatest9`
+      * `zip` -- replaced by Strong-Mode versions `zip2` - `zip9`
+    * Support `asObservable` conversion from Future-returning methods. e.g. `new Observable.fromIterable([1, 2]).first.asObservable()`
+    * Max and Min now return a Future of the Max or Min value, rather than a stream of increasing or decreasing values.
+    * Add `cast` operator
+    * Remove `ConcatMapStreamTransformer` -- functionality is already supported by `asyncExpand`. Keep the `concatMap` method as an alias.
+  * Subjects
+    * BehaviourSubject has been renamed to BehaviorSubject
+    * The subjects have been rewritten and include far more testing
+    * In keeping with the Rx idea of Subjects, they are broadcast-only
+* Documentation -- extensive documentation has been added to the library with explanations and examples for each Future, Stream & Transformer.
+  * Docs detailing the differences between RxDart and raw Observables.
+
 ## 0.9.0
 
 * Api Changes:

lib/src/observable.dart

@@ -21,7 +21,6 @@ import 'package:rxdart/src/streams/zip.dart';
 import 'package:rxdart/src/transformers/cast.dart';
 import 'package:rxdart/src/transformers/buffer_with_count.dart';
 import 'package:rxdart/src/transformers/call.dart';
-import 'package:rxdart/src/transformers/concat_map.dart';
 import 'package:rxdart/src/transformers/debounce.dart';
 import 'package:rxdart/src/transformers/default_if_empty.dart';
 import 'package:rxdart/src/transformers/dematerialize.dart';
@@ -603,7 +602,7 @@ class Observable<T> extends Stream<T> {
   ///
   /// If the retry count is not specified, it retries indefinitely. If the retry
   /// count is met, but the Stream has not terminated successfully, a
-  /// `RetryError` will be thrown.
+  /// [RetryError] will be thrown.
   ///
   /// ### Example
   ///
@@ -993,19 +992,27 @@ class Observable<T> extends Stream<T> {
       new Observable<T>(
           stream.asBroadcastStream(onListen: onListen, onCancel: onCancel));
 
-  /// Creates an Observable with the events of a stream per original event.
+  /// Maps each emitted item to a new [Stream] using the given mapper, then
+  /// subscribes to each new stream one after the next until all values are
+  /// emitted.
   ///
-  /// This acts like expand, except that convert returns a Stream instead of an
-  /// Iterable. The events of the returned stream becomes the events of the
-  /// returned stream, in the order they are produced.
+  /// asyncExpand is similar to flatMap, but ensures order by guaranteeing that
+  /// all items from the created stream will be emitted before moving to the
+  /// next created stream. This process continues until all created streams have
+  /// completed.
   ///
-  /// If convert returns null, no value is put on the output stream, just as if
-  /// it returned an empty stream.
+  /// This is functionally equivalent to `concatMap`, which exists as an alias
+  /// for a more fluent Rx API.
   ///
-  /// The returned stream is a broadcast stream if this stream is.
+  /// ### Example
+  ///
+  ///     Observable.range(4, 1)
+  ///       .asyncExpand((i) =>
+  ///         new Observable.timer(i, new Duration(minutes: i))
+  ///       .listen(print); // prints 4, 3, 2, 1
   @override
-  Observable<S> asyncExpand<S>(Stream<S> convert(T value)) =>
-      new Observable<S>(stream.asyncExpand(convert));
+  Observable<S> asyncExpand<S>(Stream<S> mapper(T value)) =>
+      new Observable<S>(stream.asyncExpand(mapper));
 
   /// Creates an Observable with each data event of this stream asynchronously
   /// mapped to a new event.
@@ -1093,10 +1100,13 @@ class Observable<T> extends Stream<T> {
   /// in a [TypeToken] as the generic parameter.
   ///
   /// Given the way Dart generics work, one cannot simply use `as T`
-  /// checks and castings within `CastStreamTransformer` itself. Therefore, the
+  /// checks and castings within [CastStreamTransformer] itself. Therefore, the
   /// [TypeToken] class was introduced to capture the type of class you'd
   /// like `cast` to convert to.
   ///
+  /// Note: Unlike `ofType`, this operator performs no filtering, and you
+  /// may run into a [CastError] if not used wisely.
+  ///
   /// ### Examples
   ///
   ///     // A Stream of num, but we know the data is an int
@@ -1110,7 +1120,7 @@ class Observable<T> extends Stream<T> {
   ///
   ///     // A Stream of num, but we know the data is an int
   ///     new Stream<num>.fromIterable(<int>[1, 2, 3])
-  ///       .cast(kInt) // Use the `kInt` constant as a shortcut
+  ///       .cast(kInt) // Use the [kInt] constant as a shortcut
   ///       .map((i) => i.isEven)
   ///       .listen(print); // prints "false", "true", "false"
   ///
@@ -1131,14 +1141,17 @@ class Observable<T> extends Stream<T> {
   /// next created stream. This process continues until all created streams have
   /// completed.
   ///
+  /// This is a simple alias for Dart Stream's `asyncExpand`, but is included to
+  /// ensure a more consistent Rx API.
+  ///
   /// ### Example
   ///
   ///     Observable.range(4, 1)
   ///       .concatMap((i) =>
   ///         new Observable.timer(i, new Duration(minutes: i))
   ///       .listen(print); // prints 4, 3, 2, 1
   Observable<S> concatMap<S>(Stream<S> mapper(T value)) =>
-      transform(new ConcatMapStreamTransformer<T, S>(mapper));
+      new Observable<S>(stream.asyncExpand(mapper));
 
   /// Returns an Observable that emits all items from the current Observable,
   /// then emits all items from the given observable, one after the next.
@@ -1529,7 +1542,7 @@ class Observable<T> extends Stream<T> {
   /// in a [TypeToken] as the generic parameter.
   ///
   /// Given the way Dart generics work, one cannot simply use the `is T` / `as T`
-  /// checks and castings within `OfTypeObservable` itself. Therefore, the
+  /// checks and castings with this method alone. Therefore, the
   /// [TypeToken] class was introduced to capture the type of class you'd
   /// like `ofType` to filter down to.
   ///

lib/src/transformers/of_type.dart

@@ -8,7 +8,7 @@ import 'package:rxdart/src/utils/type_token.dart';
 /// in a [TypeToken] as the generic parameter.
 ///
 /// Given the way Dart generics work, one cannot simply use the `is T` / `as T`
-/// checks and castings within `OfTypeObservable` itself. Therefore, the
+/// checks and castings within `OfTypeStreamTransformer` itself. Therefore, the
 /// [TypeToken] class was introduced to capture the type of class you'd
 /// like `ofType` to filter down to.
 ///

lib/transformers.dart

@@ -3,7 +3,6 @@ library rx_transformers;
 export 'package:rxdart/src/transformers/buffer_with_count.dart';
 export 'package:rxdart/src/transformers/call.dart';
 export 'package:rxdart/src/transformers/cast.dart';
-export 'package:rxdart/src/transformers/concat_map.dart';
 export 'package:rxdart/src/transformers/debounce.dart';
 export 'package:rxdart/src/transformers/default_if_empty.dart';
 export 'package:rxdart/src/transformers/dematerialize.dart';

pubspec.yaml

@@ -1,5 +1,5 @@
 name: rxdart
-version: 0.9.0
+version: 0.10.0
 author: Frank Pepermans <[email protected]>
 description: Native Dart rx implementation
 homepage: https://github.com/ReactiveX/rxdart

test/transformers/concat_map_test.dart

@@ -16,38 +16,6 @@ void main() {
     }));
   });
 
-  test('rx.Observable.concatMap.reusable', () async {
-    final ConcatMapStreamTransformer<int, int> transformer = new ConcatMapStreamTransformer<int, int>(_getOtherStream);
-    const List<int> expectedOutput = const <int>[1, 1, 2, 2, 3, 3];
-    int countA = 0, countB = 0;
-
-    new Observable<int>(_getStream()).transform(transformer).listen(
-        expectAsync1((int result) {
-          expect(result, expectedOutput[countA++]);
-        }, count: expectedOutput.length), onDone: expectAsync0(() {
-      expect(true, true);
-    }));
-
-    new Observable<int>(_getStream()).transform(transformer).listen(
-        expectAsync1((int result) {
-          expect(result, expectedOutput[countB++]);
-        }, count: expectedOutput.length), onDone: expectAsync0(() {
-      expect(true, true);
-    }));
-  });
-
-  test('rx.Observable.concatMap.asBroadcastStream', () async {
-    Stream<num> stream = new Observable<int>(_getStream())
-        .concatMap(_getOtherStream)
-        .asBroadcastStream();
-
-    // listen twice on same stream
-    stream.listen((_) {});
-    stream.listen((_) {});
-    // code should reach here
-    await expect(stream.isBroadcast, isTrue);
-  });
-
   test('rx.Observable.concatMap.error.shouldThrow', () async {
     Stream<int> observableWithError =
         new Observable<int>(new ErrorStream<int>(new Exception()))