docs(operators): add documentation for concatMap #272
Conversation
Codecov Report
@@ Coverage Diff @@
## master #272 +/- ##
=========================================
Coverage ? 79.62%
=========================================
Files ? 17
Lines ? 216
Branches ? 9
=========================================
Hits ? 172
Misses ? 42
Partials ? 2Continue to review full report at Codecov.
|
| // the MergeMap's project function is executed just on time! | ||
| $click.mergeMap(() => $interval, | ||
| (fromSource, fromInterval, iSource, IInterval) => fromInterval(iSource, IInterval)) | ||
| .subscribe(console.log); |
There was a problem hiding this comment.
Hi, could you add the expected output. Maybe take a look at the documentation guidelines. There are some tipps and tricks for documenting operators. Thanks for PR!!!
| import 'rxjs/add/observable/interval'; | ||
| import 'rxjs/add/operator/mapTo'; | ||
| import 'rxjs/add/operator/mergeMap'; | ||
| const $click = Observable.fromEvent(document, 'click'); |
There was a problem hiding this comment.
Could you use es6 import and pipe operator
| const $interval = Observable.interval(3000) | ||
| .mapTo((iClick, IInterval) => Click(iClick), Interval(IInterval); | ||
| // the MergeMap's project function is executed just on time! | ||
| $click.mergeMap(() => $interval, |
There was a problem hiding this comment.
This example should use concatMap. I can't find any concatMap in this example
| these inner Observables using <a href="#/operators/concatAll">concatAll</a>.</span>` | ||
| }, | ||
| walkthrough: { | ||
| description: `You have to be care of managing the subscriptions of inner Observables |
There was a problem hiding this comment.
I would add this as a warning in the short description. You could add a warning with the operatorextra object. LMK if you need some help!
| 'operatorType': 'transformation' | ||
| name: 'concatMap', | ||
| operatorType: 'transformation', | ||
| signature: `concatMap(project: (value: T, index: number) => ObservableInput<I>, |
There was a problem hiding this comment.
I think we are going without generic signature, correct?
There was a problem hiding this comment.
I am not sure about it, It was based on the switchMap docs, https://github.com/ReactiveX/rxjs-docs/blob/master/src/operator-docs/transformation/switchMap.ts.
There was a problem hiding this comment.
I am changing to the not generic version. 👍
| const $click = fromEvent(document, 'click'); | ||
| const $interval = interval(3000) | ||
| .pipe(mapTo((iClick, iInterval) => 'Click('+iClick+')'+', '+'Interval('+iInterval+')')); | ||
| // the ConcatMap's project function is executed just one time! |
There was a problem hiding this comment.
Would update to:
concatMap's project function is executed just one time!
| in a serialized fashion waiting for each one to complete before merging the next one | ||
| <span class="informal">Maps each value to an Observable, then flattens all of | ||
| these inner Observables using <a href="#/operators/concatAll">concatAll</a>.</span>` | ||
| }, |
There was a problem hiding this comment.
Just a few updates:
Project each source value to an Observable which is then merged with the output observable in a serialized fashion. The previous subscription must complete before the next begins. Inner Observables are flattened using <a href="#/operators/concatAll">concatAll</a>.</span>
| const $interval = interval(3000) | ||
| .pipe(mapTo((iClick, iInterval) => 'Click('+iClick+')'+', '+'Interval('+iInterval+')')); | ||
| // the ConcatMap's project function is executed just one time! | ||
| // Even if you make aditional cliks the ConcatMap's project function is not longer executed |
There was a problem hiding this comment.
Small typo, additional, clicks, no longer
| is only executed once. the second parameter 'resultFunction', allows you to access to the index of | ||
| source observable and inner observable (besides the items)` | ||
| }, | ||
| examples: [ |
There was a problem hiding this comment.
I'm wondering if a better starting example for concatMap would be showing delayed observables executing in order, after completion. Generally, questions I see about concatMap are about why you would want to use this vs mergeMap or switchMap. I think we need to emphasize the difference between these three in the primary examples. What do you all think? @sumitarora @ashwin-sureshkumar @ladyleet
There was a problem hiding this comment.
But I think this example could works to prove the singularity of concatMap:
with concatMap the project Function is executed just one time:
Click(0), Interval(0) -> Click(0), Interval(1) -> Click(0), Interval(2) etc
with mergeMap the project Function is executed every time I make a click (it could produce memory leaks):
Click(0), Interval(0) -> (click) Click(0), Interval(1) - Click(1), Interval(0) -> etc
with switchMap the project Function is executed every time I make a click but it ends the active subscription until switch to another observable:
Click(0), Interval(1) -> (click) Click(1), Interval(0) -> (click) Click(2), Interval(0)
Please check the live example, https://stackblitz.com/edit/concatmap?file=index.ts
There was a problem hiding this comment.
I'm 🤔 about this one. I think this example shows how concatMap works, but I'm not sure it would clearly show it's use versus mergeMap or switchMap, to a novice, like @btroncone mentioned.
The first time concatMap's use became apparent to me was when I saw ajax results being returned in order of pagination. I tried switching to a mergeMap and saw results returning out of order, because some paginated results were able to return faster than others. That's when concatMap clicked for me, as well as concurrency with mergeMap.
The example also uses a resultSelector function, and it looks like those are probably going to get the axe: ReactiveX/rxjs#3304 It might be best to omit them from examples on the docs here.
No description provided.