UNPKG

10.9 kBTypeScriptView Raw
1import { MonoTypeOperatorFunction, SchedulerLike, OperatorFunction, ObservableInput, ObservedValueOf } from '../types';
2export interface TimeoutConfig<T, O extends ObservableInput<unknown> = ObservableInput<T>, M = unknown> {
3 /**
4 * The time allowed between values from the source before timeout is triggered.
5 */
6 each?: number;
7 /**
8 * The relative time as a `number` in milliseconds, or a specific time as a `Date` object,
9 * by which the first value must arrive from the source before timeout is triggered.
10 */
11 first?: number | Date;
12 /**
13 * The scheduler to use with time-related operations within this operator. Defaults to {@link asyncScheduler}
14 */
15 scheduler?: SchedulerLike;
16 /**
17 * A factory used to create observable to switch to when timeout occurs. Provides
18 * a {@link TimeoutInfo} about the source observable's emissions and what delay or
19 * exact time triggered the timeout.
20 */
21 with?: (info: TimeoutInfo<T, M>) => O;
22 /**
23 * Optional additional metadata you can provide to code that handles
24 * the timeout, will be provided through the {@link TimeoutError}.
25 * This can be used to help identify the source of a timeout or pass along
26 * other information related to the timeout.
27 */
28 meta?: M;
29}
30export interface TimeoutInfo<T, M = unknown> {
31 /** Optional metadata that was provided to the timeout configuration. */
32 readonly meta: M;
33 /** The number of messages seen before the timeout */
34 readonly seen: number;
35 /** The last message seen */
36 readonly lastValue: T | null;
37}
38/**
39 * An error emitted when a timeout occurs.
40 */
41export interface TimeoutError<T = unknown, M = unknown> extends Error {
42 /**
43 * The information provided to the error by the timeout
44 * operation that created the error. Will be `null` if
45 * used directly in non-RxJS code with an empty constructor.
46 * (Note that using this constructor directly is not recommended,
47 * you should create your own errors)
48 */
49 info: TimeoutInfo<T, M> | null;
50}
51export interface TimeoutErrorCtor {
52 /**
53 * @deprecated Internal implementation detail. Do not construct error instances.
54 * Cannot be tagged as internal: https://github.com/ReactiveX/rxjs/issues/6269
55 */
56 new <T = unknown, M = unknown>(info?: TimeoutInfo<T, M>): TimeoutError<T, M>;
57}
58/**
59 * An error thrown by the {@link timeout} operator.
60 *
61 * Provided so users can use as a type and do quality comparisons.
62 * We recommend you do not subclass this or create instances of this class directly.
63 * If you have need of a error representing a timeout, you should
64 * create your own error class and use that.
65 *
66 * @see {@link timeout}
67 *
68 * @class TimeoutError
69 */
70export declare const TimeoutError: TimeoutErrorCtor;
71/**
72 * If `with` is provided, this will return an observable that will switch to a different observable if the source
73 * does not push values within the specified time parameters.
74 *
75 * <span class="informal">The most flexible option for creating a timeout behavior.</span>
76 *
77 * The first thing to know about the configuration is if you do not provide a `with` property to the configuration,
78 * when timeout conditions are met, this operator will emit a {@link TimeoutError}. Otherwise, it will use the factory
79 * function provided by `with`, and switch your subscription to the result of that. Timeout conditions are provided by
80 * the settings in `first` and `each`.
81 *
82 * The `first` property can be either a `Date` for a specific time, a `number` for a time period relative to the
83 * point of subscription, or it can be skipped. This property is to check timeout conditions for the arrival of
84 * the first value from the source _only_. The timings of all subsequent values from the source will be checked
85 * against the time period provided by `each`, if it was provided.
86 *
87 * The `each` property can be either a `number` or skipped. If a value for `each` is provided, it represents the amount of
88 * time the resulting observable will wait between the arrival of values from the source before timing out. Note that if
89 * `first` is _not_ provided, the value from `each` will be used to check timeout conditions for the arrival of the first
90 * value and all subsequent values. If `first` _is_ provided, `each` will only be use to check all values after the first.
91 *
92 * ## Examples
93 *
94 * Emit a custom error if there is too much time between values
95 *
96 * ```ts
97 * import { interval, timeout, throwError } from 'rxjs';
98 *
99 * class CustomTimeoutError extends Error {
100 * constructor() {
101 * super('It was too slow');
102 * this.name = 'CustomTimeoutError';
103 * }
104 * }
105 *
106 * const slow$ = interval(900);
107 *
108 * slow$.pipe(
109 * timeout({
110 * each: 1000,
111 * with: () => throwError(() => new CustomTimeoutError())
112 * })
113 * )
114 * .subscribe({
115 * error: console.error
116 * });
117 * ```
118 *
119 * Switch to a faster observable if your source is slow.
120 *
121 * ```ts
122 * import { interval, timeout } from 'rxjs';
123 *
124 * const slow$ = interval(900);
125 * const fast$ = interval(500);
126 *
127 * slow$.pipe(
128 * timeout({
129 * each: 1000,
130 * with: () => fast$,
131 * })
132 * )
133 * .subscribe(console.log);
134 * ```
135 * @param config The configuration for the timeout.
136 */
137export declare function timeout<T, O extends ObservableInput<unknown>, M = unknown>(config: TimeoutConfig<T, O, M> & {
138 with: (info: TimeoutInfo<T, M>) => O;
139}): OperatorFunction<T, T | ObservedValueOf<O>>;
140/**
141 * Returns an observable that will error or switch to a different observable if the source does not push values
142 * within the specified time parameters.
143 *
144 * <span class="informal">The most flexible option for creating a timeout behavior.</span>
145 *
146 * The first thing to know about the configuration is if you do not provide a `with` property to the configuration,
147 * when timeout conditions are met, this operator will emit a {@link TimeoutError}. Otherwise, it will use the factory
148 * function provided by `with`, and switch your subscription to the result of that. Timeout conditions are provided by
149 * the settings in `first` and `each`.
150 *
151 * The `first` property can be either a `Date` for a specific time, a `number` for a time period relative to the
152 * point of subscription, or it can be skipped. This property is to check timeout conditions for the arrival of
153 * the first value from the source _only_. The timings of all subsequent values from the source will be checked
154 * against the time period provided by `each`, if it was provided.
155 *
156 * The `each` property can be either a `number` or skipped. If a value for `each` is provided, it represents the amount of
157 * time the resulting observable will wait between the arrival of values from the source before timing out. Note that if
158 * `first` is _not_ provided, the value from `each` will be used to check timeout conditions for the arrival of the first
159 * value and all subsequent values. If `first` _is_ provided, `each` will only be use to check all values after the first.
160 *
161 * ### Handling TimeoutErrors
162 *
163 * If no `with` property was provided, subscriptions to the resulting observable may emit an error of {@link TimeoutError}.
164 * The timeout error provides useful information you can examine when you're handling the error. The most common way to handle
165 * the error would be with {@link catchError}, although you could use {@link tap} or just the error handler in your `subscribe` call
166 * directly, if your error handling is only a side effect (such as notifying the user, or logging).
167 *
168 * In this case, you would check the error for `instanceof TimeoutError` to validate that the error was indeed from `timeout`, and
169 * not from some other source. If it's not from `timeout`, you should probably rethrow it if you're in a `catchError`.
170 *
171 * ## Examples
172 *
173 * Emit a {@link TimeoutError} if the first value, and _only_ the first value, does not arrive within 5 seconds
174 *
175 * ```ts
176 * import { interval, timeout } from 'rxjs';
177 *
178 * // A random interval that lasts between 0 and 10 seconds per tick
179 * const source$ = interval(Math.round(Math.random() * 10_000));
180 *
181 * source$.pipe(
182 * timeout({ first: 5_000 })
183 * )
184 * .subscribe({
185 * next: console.log,
186 * error: console.error
187 * });
188 * ```
189 *
190 * Emit a {@link TimeoutError} if the source waits longer than 5 seconds between any two values or the first value
191 * and subscription.
192 *
193 * ```ts
194 * import { timer, timeout, expand } from 'rxjs';
195 *
196 * const getRandomTime = () => Math.round(Math.random() * 10_000);
197 *
198 * // An observable that waits a random amount of time between each delivered value
199 * const source$ = timer(getRandomTime())
200 * .pipe(expand(() => timer(getRandomTime())));
201 *
202 * source$
203 * .pipe(timeout({ each: 5_000 }))
204 * .subscribe({
205 * next: console.log,
206 * error: console.error
207 * });
208 * ```
209 *
210 * Emit a {@link TimeoutError} if the source does not emit before 7 seconds, _or_ if the source waits longer than
211 * 5 seconds between any two values after the first.
212 *
213 * ```ts
214 * import { timer, timeout, expand } from 'rxjs';
215 *
216 * const getRandomTime = () => Math.round(Math.random() * 10_000);
217 *
218 * // An observable that waits a random amount of time between each delivered value
219 * const source$ = timer(getRandomTime())
220 * .pipe(expand(() => timer(getRandomTime())));
221 *
222 * source$
223 * .pipe(timeout({ first: 7_000, each: 5_000 }))
224 * .subscribe({
225 * next: console.log,
226 * error: console.error
227 * });
228 * ```
229 */
230export declare function timeout<T, M = unknown>(config: Omit<TimeoutConfig<T, any, M>, 'with'>): OperatorFunction<T, T>;
231/**
232 * Returns an observable that will error if the source does not push its first value before the specified time passed as a `Date`.
233 * This is functionally the same as `timeout({ first: someDate })`.
234 *
235 * <span class="informal">Errors if the first value doesn't show up before the given date and time</span>
236 *
237 * ![](timeout.png)
238 *
239 * @param first The date to at which the resulting observable will timeout if the source observable
240 * does not emit at least one value.
241 * @param scheduler The scheduler to use. Defaults to {@link asyncScheduler}.
242 */
243export declare function timeout<T>(first: Date, scheduler?: SchedulerLike): MonoTypeOperatorFunction<T>;
244/**
245 * Returns an observable that will error if the source does not push a value within the specified time in milliseconds.
246 * This is functionally the same as `timeout({ each: milliseconds })`.
247 *
248 * <span class="informal">Errors if it waits too long between any value</span>
249 *
250 * ![](timeout.png)
251 *
252 * @param each The time allowed between each pushed value from the source before the resulting observable
253 * will timeout.
254 * @param scheduler The scheduler to use. Defaults to {@link asyncScheduler}.
255 */
256export declare function timeout<T>(each: number, scheduler?: SchedulerLike): MonoTypeOperatorFunction<T>;
257//# sourceMappingURL=timeout.d.ts.map
\No newline at end of file