mergeMap / flatMap

Search…
mergeMap / flatMap
signature: mergeMap(project: function: Observable, resultSelector: function: any, concurrent: number): Observable
Map to observable, emit values.
💡 flatMap is an alias for mergeMap!
💡 If only one inner subscription should be active at a time, try switchMap!
💡 If the order of emission and subscription of inner observables is important, try concatMap!
Why use mergeMap?
This operator is best used when you wish to flatten an inner observable but want to manually control the number of inner subscriptions.
For instance, when using switchMap each inner subscription is completed when the source emits, allowing only one active inner subscription. In contrast, mergeMap allows for multiple inner subscriptions to be active at a time. Because of this, one of the most common use-case for mergeMap is requests that should not be canceled, think writes rather than reads. Note that if order must be maintained concatMap is a better option.
Be aware that because mergeMap maintains multiple active inner subscriptions at once it's possible to create a memory leak through long-lived inner subscriptions. A basic example would be if you were mapping to an observable with an inner timer, or a stream of dom events. In these cases, if you still wish to utilize mergeMap you may want to take advantage of another operator to manage the completion of the inner subscription, think take or takeUntil. You can also limit the number of active inner subscriptions at a time with the concurrent parameter, seen in example 5.
​​
​​
Examples
Example 1: mergeMap simulating save of click locations
( StackBlitz )
1
// RxJS v6+
2
import { fromEvent, of } from 'rxjs';
3
import { mergeMap, delay } from 'rxjs/operators';
4
​
5
// faking network request for save
6
const saveLocation = location => {
7
  return of(location).pipe(delay(500));
8
};
9
// streams
10
const click$ = fromEvent(document, 'click');
11
​
12
click$
13
  .pipe(
14
    mergeMap((e: MouseEvent) => {
15
      return saveLocation({
16
        x: e.clientX,
17
        y: e.clientY,
18
        timestamp: Date.now()
19
      });
20
    })
21
  )
22
  // Saved! {x: 98, y: 170, ...}
23
  .subscribe(r => console.log('Saved!', r));
Copied!
Example 2: mergeMap with ajax observable
( StackBlitz )
1
// RxJS v6+
2
import { fromEvent } from 'rxjs';
3
import { ajax } from 'rxjs/ajax';
4
import { mergeMap } from 'rxjs/operators';
5
​
6
// free api url
7
const API_URL = 'https://jsonplaceholder.typicode.com/todos/1';
8
​
9
// streams
10
const click$ = fromEvent(document, 'click');
11
​
12
click$
13
  .pipe(
14
    /*
15
     * Using mergeMap for example, but generally for GET requests
16
     * you will prefer switchMap.
17
     * Also, if you do not need the parameter like
18
     * below you could use mergeMapTo instead.
19
     * ex. mergeMapTo(ajax.getJSON(API_URL))
20
     */
21
    mergeMap(() => ajax.getJSON(API_URL))
22
  )
23
  // { userId: 1, id: 1, ...}
24
  .subscribe(console.log);
Copied!
Example 3: mergeMap with promise (could also use from to convert to observable)
( StackBlitz )
1
// RxJS v6+
2
import { of } from 'rxjs';
3
import { mergeMap } from 'rxjs/operators';
4
​
5
// helper to create promise
6
const myPromise = val =>
7
  new Promise(resolve => resolve(`${val} World From Promise!`));
8
​
9
// emit 'Hello'
10
const source$ = of('Hello');
11
​
12
// map to promise and emit result
13
source$
14
  .pipe(mergeMap(val => myPromise(val)))
15
  // output: 'Hello World From Promise'
16
  .subscribe(val => console.log(val));
Copied!
Example 4: mergeMap with resultSelector
( StackBlitz )
1
// RxJS v6+
2
import { of } from 'rxjs';
3
import { mergeMap } from 'rxjs/operators';
4
​
5
// helper to create promise
6
const myPromise = val =>
7
  new Promise(resolve => resolve(`${val} World From Promise!`));
8
​
9
// emit 'Hello'
10
const source$ = of('Hello');
11
​
12
source$
13
  .pipe(
14
    mergeMap(
15
      val => myPromise(val),
16
      /*
17
      you can also supply a second argument which receives the source value and emitted
18
      value of inner observable or promise
19
    */
20
      (valueFromSource, valueFromPromise) => {
21
        return `Source: ${valueFromSource}, Promise: ${valueFromPromise}`;
22
      }
23
    )
24
  )
25
  // output: "Source: Hello, Promise: Hello World From Promise!"
26
  .subscribe(val => console.log(val));
Copied!
Example 5: mergeMap with concurrent value
( StackBlitz )
1
// RxJS v6+
2
import { interval } from 'rxjs';
3
import { mergeMap, take } from 'rxjs/operators';
4
​
5
// emit value every 1s
6
const source$ = interval(1000);
7
​
8
source$
9
  .pipe(
10
    mergeMap(
11
      // project
12
      val => interval(5000).pipe(take(2)),
13
      // resultSelector
14
      (oVal, iVal, oIndex, iIndex) => [oIndex, oVal, iIndex, iVal],
15
      // concurrent
16
      2
17
    )
18
  )
19
  /*
20
        Output:
21
        [0, 0, 0, 0] <--1st inner observable
22
        [1, 1, 0, 0] <--2nd inner observable
23
        [0, 0, 1, 1] <--1st inner observable
24
        [1, 1, 1, 1] <--2nd inner observable
25
        [2, 2, 0, 0] <--3rd inner observable
26
        [3, 3, 0, 0] <--4th inner observable
27
*/
28
  .subscribe(val => console.log(val));
Copied!
Related Recipes
​Breakout Game​
​HTTP Polling​
​Save Indicator​
​Swipe To Refresh​
Additional Resources
​mergeMap 📰 - Official docs
​mergeMap - In Depth Dev Reference
​map vs flatMap 🎥 💵 -
Ben Lesh
​Async requests and responses in RxJS​
🎥 💵 - André Staltz
​Use RxJS mergeMap to map and merge higher order observables​
🎥 💵 - André Staltz
​Use RxJS mergeMap for fine grain custom behavior​
🎥 💵 - André Staltz
​Build your own mergeMap operator​
🎥 - Kwinten Pisman
📁 Source Code: https://github.com/ReactiveX/rxjs/blob/master/src/internal/operators/mergeMap.ts​
mapTo
mergeScan
Last modified 6mo ago
Copy link
Contents
Map to observable, emit values.
signature: `mergeMap(project: function: Observable, resultSelector: function: any, concurrent: number): Observable`

Map to observable, emit values.

Why use `mergeMap`?

Examples

Additional Resources
