Skip to content
This repository was archived by the owner on Oct 1, 2018. It is now read-only.

Commit f38fac7

Browse files
Merge pull request #198 from sumitarora/docs-forkJoin
docs(operators): add documentation for forkJoin
2 parents 4150bd8 + e247f65 commit f38fac7

File tree

1 file changed

+135
-2
lines changed

1 file changed

+135
-2
lines changed
Lines changed: 135 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,139 @@
11
import { OperatorDoc } from '../operator.model';
22

33
export const forkJoin: OperatorDoc = {
4-
'name': 'forkJoin',
5-
'operatorType': 'combination'
4+
name: 'forkJoin',
5+
operatorType: 'combination',
6+
signature: 'public static forkJoin(sources: *): any',
7+
parameters: [
8+
{
9+
name: 'sources',
10+
type: '*',
11+
attribute: '',
12+
description: ''
13+
}
14+
],
15+
marbleUrl: 'http://reactivex.io/rxjs/img/forkJoin.png',
16+
shortDescription: {
17+
description: 'Joins last values emitted by passed Observables.',
18+
extras: [
19+
{
20+
type: 'Tip',
21+
text:
22+
'Wait for Observables to complete and then combine last values they emitted.'
23+
}
24+
]
25+
},
26+
walkthrough: {
27+
description: `
28+
<p>
29+
<span class="markdown-code">forkJoin</span> is an operator that takes any number of
30+
Observables which can be passed either as an array or directly as arguments. If no input
31+
Observables are provided, resulting stream will complete immediately.
32+
</p>
33+
<p>
34+
<span class="markdown-code">forkJoin</span> will wait for all passed Observables to complete
35+
and then it will emit an array with last values from corresponding Observables. So if you
36+
pass "n" Observables to the operator, resulting array will have "n" values, where first
37+
value is the last thing emitted by the first Observable, second value is the last thing
38+
emitted by the second Observable and so on. That means <span class="markdown-code">forkJoin</span> will
39+
not emit more than once and it will complete after that. If you need to emit combined values not only
40+
at the end of lifecycle of passed Observables, but also throughout it, try out
41+
<a href='/#/operators/combineLatest' class='markdown-code'>combineLatest</a>
42+
or <a href='/#/operators/zip' class='markdown-code'>zip</a> instead.
43+
</p>
44+
<p>
45+
In order for resulting array to have the same length as the number of input Observables, whenever any of that
46+
Observables completes without emitting any value,
47+
<span class="markdown-code">forkJoin</span> will complete at that moment as well and it will not
48+
emit anything either, even if it already has some last values from other Observables.
49+
</p>
50+
51+
<p>
52+
Conversely, if there is an Observable that never completes,
53+
<span class="markdown-code">forkJoin</span> will never complete as well, unless at
54+
any point some other Observable completes without emitting value, which brings us back to the previous case.
55+
Overall, in order for <span class="markdown-code">forkJoin</span> to emit a value, all Observables passed as arguments
56+
have to emit something at least once and complete.
57+
</p>
58+
<p>
59+
If any input Observable errors at some point, <span class="markdown-code">forkJoin</span>
60+
will error as well and all other Observables
61+
will be immediately unsubscribed.
62+
</p>
63+
<p>
64+
Optionally <span class="markdown-code">forkJoin</span> accepts project function, that will be
65+
called with values which normally would land in emitted array. Whatever is returned by project function,
66+
will appear in output Observable instead. This means that default project can be thought of as a
67+
function that takes all its arguments and puts them into an array. Note that project function will be called only
68+
when output Observable is supposed to emit a result.
69+
</p>
70+
`
71+
},
72+
examples: [
73+
{
74+
name: 'Use forkJoin with operator emitting immediately',
75+
code: `
76+
const observable = Rx.Observable.forkJoin(
77+
Rx.Observable.of(1, 2, 3, 4),
78+
Rx.Observable.of(5, 6, 7, 8)
79+
);
80+
observable.subscribe(
81+
value => console.log(value),
82+
err => {},
83+
() => console.log('This is how it ends!')
84+
);
85+
// Logs:
86+
// [4, 8]
87+
// "This is how it ends!"
88+
`,
89+
externalLink: {
90+
platform: 'JSBin',
91+
url: 'http://jsbin.com/kinilaruki/1/embed?js,console'
92+
}
93+
},
94+
{
95+
name: 'Use forkJoin with operator emitting after some time',
96+
code: `
97+
const observable = Rx.Observable.forkJoin(
98+
Rx.Observable.interval(1000).take(3), // emit 0, 1, 2 every second and complete
99+
Rx.Observable.interval(500).take(4) // emit 0, 1, 2, 3 every half a second and complete
100+
);
101+
observable.subscribe(
102+
value => console.log(value),
103+
err => {},
104+
() => console.log('This is how it ends!')
105+
);
106+
// Logs:
107+
// [2, 3] after 3 seconds
108+
// "This is how it ends!" immediately after
109+
`,
110+
externalLink: {
111+
platform: 'JSBin',
112+
url: 'http://jsbin.com/rewivubuqi/1/embed?js,console'
113+
}
114+
},
115+
{
116+
name: 'Use forkJoin with project function',
117+
code: `
118+
const observable = Rx.Observable.forkJoin(
119+
Rx.Observable.interval(1000).take(3), // emit 0, 1, 2 every second and complete
120+
Rx.Observable.interval(500).take(4), // emit 0, 1, 2, 3 every half a second and complete
121+
(n, m) => n + m
122+
);
123+
observable.subscribe(
124+
value => console.log(value),
125+
err => {},
126+
() => console.log('This is how it ends!')
127+
);
128+
// Logs:
129+
// 5 after 3 seconds
130+
// "This is how it ends!" immediately after
131+
`,
132+
externalLink: {
133+
platform: 'JSBin',
134+
url: 'http://jsbin.com/wayomumike/1/embed?js,console'
135+
}
136+
}
137+
],
138+
relatedOperators: ['combineLatest', 'zip']
6139
};

0 commit comments

Comments
 (0)