/
tap.ts
153 lines (150 loc) · 5.99 KB
/
tap.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
import { MonoTypeOperatorFunction, Observer } from '../types';
import { isFunction } from '../util/isFunction';
import { operate } from '../util/lift';
import { createOperatorSubscriber } from './OperatorSubscriber';
import { identity } from '../util/identity';
export interface TapObserver<T> extends Observer<T> {
subscribe: () => void;
unsubscribe: () => void;
finalize: () => void;
}
export function tap<T>(observerOrNext?: Partial<TapObserver<T>> | ((value: T) => void)): MonoTypeOperatorFunction<T>;
/** @deprecated Instead of passing separate callback arguments, use an observer argument. Signatures taking separate callback arguments will be removed in v8. Details: https://rxjs.dev/deprecations/subscribe-arguments */
export function tap<T>(
next?: ((value: T) => void) | null,
error?: ((error: any) => void) | null,
complete?: (() => void) | null
): MonoTypeOperatorFunction<T>;
/**
* Used to perform side-effects for notifications from the source observable
*
* <span class="informal">Used when you want to affect outside state with a notification without altering the notification</span>
*
* ![](tap.png)
*
* Tap is designed to allow the developer a designated place to perform side effects. While you _could_ perform side-effects
* inside of a `map` or a `mergeMap`, that would make their mapping functions impure, which isn't always a big deal, but will
* make it so you can't do things like memoize those functions. The `tap` operator is designed solely for such side-effects to
* help you remove side-effects from other operations.
*
* For any notification, next, error, or complete, `tap` will call the appropriate callback you have provided to it, via a function
* reference, or a partial observer, then pass that notification down the stream.
*
* The observable returned by `tap` is an exact mirror of the source, with one exception: Any error that occurs -- synchronously -- in a handler
* provided to `tap` will be emitted as an error from the returned observable.
*
* > Be careful! You can mutate objects as they pass through the `tap` operator's handlers.
*
* The most common use of `tap` is actually for debugging. You can place a `tap(console.log)` anywhere
* in your observable `pipe`, log out the notifications as they are emitted by the source returned by the previous
* operation.
*
* ## Examples
*
* Check a random number before it is handled. Below is an observable that will use a random number between 0 and 1,
* and emit `'big'` or `'small'` depending on the size of that number. But we wanted to log what the original number
* was, so we have added a `tap(console.log)`.
*
* ```ts
* import { of, tap, map } from 'rxjs';
*
* of(Math.random()).pipe(
* tap(console.log),
* map(n => n > 0.5 ? 'big' : 'small')
* ).subscribe(console.log);
* ```
*
* Using `tap` to analyze a value and force an error. Below is an observable where in our system we only
* want to emit numbers 3 or less we get from another source. We can force our observable to error
* using `tap`.
*
* ```ts
* import { of, tap } from 'rxjs';
*
* const source = of(1, 2, 3, 4, 5);
*
* source.pipe(
* tap(n => {
* if (n > 3) {
* throw new TypeError(`Value ${ n } is greater than 3`);
* }
* })
* )
* .subscribe({ next: console.log, error: err => console.log(err.message) });
* ```
*
* We want to know when an observable completes before moving on to the next observable. The system
* below will emit a random series of `'X'` characters from 3 different observables in sequence. The
* only way we know when one observable completes and moves to the next one, in this case, is because
* we have added a `tap` with the side effect of logging to console.
*
* ```ts
* import { of, concatMap, interval, take, map, tap } from 'rxjs';
*
* of(1, 2, 3).pipe(
* concatMap(n => interval(1000).pipe(
* take(Math.round(Math.random() * 10)),
* map(() => 'X'),
* tap({ complete: () => console.log(`Done with ${ n }`) })
* ))
* )
* .subscribe(console.log);
* ```
*
* @see {@link finalize}
* @see {@link Observable#subscribe}
*
* @param observerOrNext A next handler or partial observer
* @param error An error handler
* @param complete A completion handler
* @return A function that returns an Observable identical to the source, but
* runs the specified Observer or callback(s) for each item.
*/
export function tap<T>(
observerOrNext?: Partial<TapObserver<T>> | ((value: T) => void) | null,
error?: ((e: any) => void) | null,
complete?: (() => void) | null
): MonoTypeOperatorFunction<T> {
// We have to check to see not only if next is a function,
// but if error or complete were passed. This is because someone
// could technically call tap like `tap(null, fn)` or `tap(null, null, fn)`.
const tapObserver =
isFunction(observerOrNext) || error || complete
? // tslint:disable-next-line: no-object-literal-type-assertion
({ next: observerOrNext as Exclude<typeof observerOrNext, Partial<TapObserver<T>>>, error, complete } as Partial<TapObserver<T>>)
: observerOrNext;
return tapObserver
? operate((source, subscriber) => {
tapObserver.subscribe?.();
let isUnsub = true;
source.subscribe(
createOperatorSubscriber(
subscriber,
(value) => {
tapObserver.next?.(value);
subscriber.next(value);
},
() => {
isUnsub = false;
tapObserver.complete?.();
subscriber.complete();
},
(err) => {
isUnsub = false;
tapObserver.error?.(err);
subscriber.error(err);
},
() => {
if (isUnsub) {
tapObserver.unsubscribe?.();
}
tapObserver.finalize?.();
}
)
);
})
: // Tap was called with no valid tap observer or handler
// (e.g. `tap(null, null, null)` or `tap(null)` or `tap()`)
// so we're going to just mirror the source.
identity;
}