1 |
|
2 |
|
3 |
|
4 |
|
5 |
|
6 |
|
7 |
|
8 | import { Observer, TeardownLogic } from './internal/types';
|
9 | import { Observable } from './internal/Observable';
|
10 | import './internal/observable/dom/MiscJSDoc';
|
11 |
|
12 |
|
13 |
|
14 |
|
15 |
|
16 |
|
17 | export class ObservableDoc {
|
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 | static create<T>(onSubscription: <R>(observer: Observer<R>) => TeardownLogic): Observable<T> {
|
139 | return new Observable<T>(onSubscription);
|
140 | }
|
141 | }
|
142 |
|
143 | /**
|
144 | * An interface for a consumer of push-based notifications delivered by an
|
145 | * {@link Observable}.
|
146 | *
|
147 | * ```ts
|
148 | * interface Observer<T> {
|
149 | * closed?: boolean;
|
150 | * next: (value: T) => void;
|
151 | * error: (err: any) => void;
|
152 | * complete: () => void;
|
153 | * }
|
154 | * ```
|
155 | *
|
156 | * An object conforming to the Observer interface is usually
|
157 | * given to the `observable.subscribe(observer)` method, and the Observable will
|
158 | * call the Observer's `next(value)` method to provide notifications. A
|
159 | * well-behaved Observable will call an Observer's `complete()` method exactly
|
160 | * once or the Observer's `error(err)` method exactly once, as the last
|
161 | * notification delivered.
|
162 | *
|
163 | * @interface
|
164 | * @name Observer
|
165 | * @noimport true
|
166 | */
|
167 | export class ObserverDoc<T> {
|
168 | /**
|
169 | * An optional flag to indicate whether this Observer, when used as a
|
170 | * subscriber, has already been unsubscribed from its Observable.
|
171 | * @type {boolean}
|
172 | */
|
173 | closed: boolean = false;
|
174 | /**
|
175 | * The callback to receive notifications of type `next` from the Observable,
|
176 | * with a value. The Observable may call this method 0 or more times.
|
177 | * @param {T} value The `next` value.
|
178 | * @return {void}
|
179 | */
|
180 | next(value: T): void {
|
181 | return void 0;
|
182 | }
|
183 | /**
|
184 | * The callback to receive notifications of type `error` from the Observable,
|
185 | * with an attached {@link Error}. Notifies the Observer that the Observable
|
186 | * has experienced an error condition.
|
187 | * @param {any} err The `error` exception.
|
188 | * @return {void}
|
189 | */
|
190 | error(err: any): void {
|
191 | return void 0;
|
192 | }
|
193 | /**
|
194 | * The callback to receive a valueless notification of type `complete` from
|
195 | * the Observable. Notifies the Observer that the Observable has finished
|
196 | * sending push-based notifications.
|
197 | * @return {void}
|
198 | */
|
199 | complete(): void {
|
200 | return void 0;
|
201 | }
|
202 | }
|
203 |
|
204 | /**
|
205 | * `SubscribableOrPromise` interface describes values that behave like either
|
206 | * Observables or Promises. Every operator that accepts arguments annotated
|
207 | * with this interface, can be also used with parameters that are not necessarily
|
208 | * RxJS Observables.
|
209 | *
|
210 | * Following types of values might be passed to operators expecting this interface:
|
211 | *
|
212 | * ## Observable
|
213 | *
|
214 | * RxJS {@link Observable} instance.
|
215 | *
|
216 | * ## Observable-like (Subscribable)
|
217 | *
|
218 | * This might be any object that has `Symbol.observable` method. This method,
|
219 | * when called, should return object with `subscribe` method on it, which should
|
220 | * behave the same as RxJS `Observable.subscribe`.
|
221 | *
|
222 | * `Symbol.observable` is part of https://github.com/tc39/proposal-observable proposal.
|
223 | * Since currently it is not supported natively, and every symbol is equal only to itself,
|
224 | * you should use https://github.com/blesh/symbol-observable polyfill, when implementing
|
225 | * custom Observable-likes.
|
226 | *
|
227 | * **TypeScript Subscribable interface issue**
|
228 | *
|
229 | * Although TypeScript interface claims that Subscribable is an object that has `subscribe`
|
230 | * method declared directly on it, passing custom objects that have `subscribe`
|
231 | * method but not `Symbol.observable` method will fail at runtime. Conversely, passing
|
232 | * objects with `Symbol.observable` but without `subscribe` will fail at compile time
|
233 | * (if you use TypeScript).
|
234 | *
|
235 | * TypeScript has problem supporting interfaces with methods defined as symbol
|
236 | * properties. To get around that, you should implement `subscribe` directly on
|
237 | * passed object, and make `Symbol.observable` method simply return `this`. That way
|
238 | * everything will work as expected, and compiler will not complain. If you really
|
239 | * do not want to put `subscribe` directly on your object, you will have to type cast
|
240 | * it to `any`, before passing it to an operator.
|
241 | *
|
242 | * When this issue is resolved, Subscribable interface will only permit Observable-like
|
243 | * objects with `Symbol.observable` defined, no matter if they themselves implement
|
244 | * `subscribe` method or not.
|
245 | *
|
246 | * ## ES6 Promise
|
247 | *
|
248 | * Promise can be interpreted as Observable that emits value and completes
|
249 | * when it is resolved or errors when it is rejected.
|
250 | *
|
251 | * ## Promise-like (Thenable)
|
252 | *
|
253 | * Promises passed to operators do not have to be native ES6 Promises.
|
254 | * They can be implementations from popular Promise libraries, polyfills
|
255 | * or even custom ones. They just need to have `then` method that works
|
256 | * as the same as ES6 Promise `then`.
|
257 | *
|
258 | * @example <caption>Use merge and then map with non-RxJS observable</caption>
|
259 | * const nonRxJSObservable = {
|
260 | * subscribe(observer) {
|
261 | * observer.next(1000);
|
262 | * observer.complete();
|
263 | * },
|
264 | * [Symbol.observable]() {
|
265 | * return this;
|
266 | * }
|
267 | * };
|
268 | *
|
269 | * Rx.Observable.merge(nonRxJSObservable)
|
270 | * .map(value => "This value is " + value)
|
271 | * .subscribe(result => console.log(result)); // Logs "This value is 1000"
|
272 | *
|
273 | *
|
274 | * @example <caption>Use combineLatest with ES6 Promise</caption>
|
275 | * Rx.Observable.combineLatest(Promise.resolve(5), Promise.resolve(10), Promise.resolve(15))
|
276 | * .subscribe(
|
277 | * value => console.log(value),
|
278 | * err => {},
|
279 | * () => console.log('the end!')
|
280 | * );
|
281 | * // Logs
|
282 | * // [5, 10, 15]
|
283 | * // "the end!"
|
284 | *
|
285 | *
|
286 | * @interface
|
287 | * @name SubscribableOrPromise
|
288 | * @noimport true
|
289 | */
|
290 | export class SubscribableOrPromiseDoc<T> {
|
291 |
|
292 | }
|
293 |
|
294 | /**
|
295 | * `ObservableInput` interface describes all values that are either an
|
296 | * {@link SubscribableOrPromise} or some kind of collection of values that
|
297 | * can be transformed to Observable emitting that values. Every operator that
|
298 | * accepts arguments annotated with this interface, can be also used with
|
299 | * parameters that are not necessarily RxJS Observables.
|
300 | *
|
301 | * `ObservableInput` extends {@link SubscribableOrPromise} with following types:
|
302 | *
|
303 | * ## Array
|
304 | *
|
305 | * Arrays can be interpreted as observables that emit all values in array one by one,
|
306 | * from left to right, and then complete immediately.
|
307 | *
|
308 | * ## Array-like
|
309 | *
|
310 | * Arrays passed to operators do not have to be built-in JavaScript Arrays. They
|
311 | * can be also, for example, `arguments` property available inside every function,
|
312 | * [DOM NodeList](https://developer.mozilla.org/pl/docs/Web/API/NodeList),
|
313 | * or, actually, any object that has `length` property (which is a number)
|
314 | * and stores values under non-negative (zero and up) integers.
|
315 | *
|
316 | * ## ES6 Iterable
|
317 | *
|
318 | * Operators will accept both built-in and custom ES6 Iterables, by treating them as
|
319 | * observables that emit all its values in order of iteration and then complete
|
320 | * when iteration ends. Note that contrary to arrays, Iterables do not have to
|
321 | * necessarily be finite, so creating Observables that never complete is possible as well.
|
322 | *
|
323 | * Note that you can make iterator an instance of Iterable by having it return itself
|
324 | * in `Symbol.iterator` method. It means that every operator accepting Iterables accepts,
|
325 | * though indirectly, iterators themselves as well. All native ES6 iterators are instances
|
326 | * of Iterable by default, so you do not have to implement their `Symbol.iterator` method
|
327 | * yourself.
|
328 | *
|
329 | * **TypeScript Iterable interface issue**
|
330 | *
|
331 | * TypeScript `ObservableInput` interface actually lacks type signature for Iterables,
|
332 | * because of issues it caused in some projects (see [this issue](https://github.com/ReactiveX/rxjs/issues/2306)).
|
333 | * If you want to use Iterable as argument for operator, cast it to `any` first.
|
334 | * Remember of course that, because of casting, you have to yourself ensure that passed
|
335 | * argument really implements said interface.
|
336 | *
|
337 | *
|
338 | * @example <caption>Use merge with arrays</caption>
|
339 | * Rx.Observable.merge([1, 2], [4], [5, 6])
|
340 | * .subscribe(
|
341 | * value => console.log(value),
|
342 | * err => {},
|
343 | * () => console.log('ta dam!')
|
344 | * );
|
345 | *
|
346 | * // Logs
|
347 | * // 1
|
348 | * // 2
|
349 | * // 3
|
350 | * // 4
|
351 | * // 5
|
352 | * // 6
|
353 | * // "ta dam!"
|
354 | *
|
355 | *
|
356 | * @example <caption>Use merge with array-like</caption>
|
357 | * Rx.Observable.merge({0: 1, 1: 2, length: 2}, {0: 3, length: 1})
|
358 | * .subscribe(
|
359 | * value => console.log(value),
|
360 | * err => {},
|
361 | * () => console.log('nice, huh?')
|
362 | * );
|
363 | *
|
364 | * // Logs
|
365 | * // 1
|
366 | * // 2
|
367 | * // 3
|
368 | * // "nice, huh?"
|
369 | *
|
370 | * @example <caption>Use merge with an Iterable (Map)</caption>
|
371 | * const firstMap = new Map([[1, 'a'], [2, 'b']]);
|
372 | * const secondMap = new Map([[3, 'c'], [4, 'd']]);
|
373 | *
|
374 | * Rx.Observable.merge(
|
375 | * firstMap, // pass Iterable
|
376 | * secondMap.values() // pass iterator, which is itself an Iterable
|
377 | * ).subscribe(
|
378 | * value => console.log(value),
|
379 | * err => {},
|
380 | * () => console.log('yup!')
|
381 | * );
|
382 | *
|
383 | * // Logs
|
384 | * // [1, "a"]
|
385 | * // [2, "b"]
|
386 | * // "c"
|
387 | * // "d"
|
388 | * // "yup!"
|
389 | *
|
390 | * @example <caption>Use from with generator (returning infinite iterator)</caption>
|
391 | * // infinite stream of incrementing numbers
|
392 | * const infinite = function* () {
|
393 | * let i = 0;
|
394 | *
|
395 | * while (true) {
|
396 | * yield i++;
|
397 | * }
|
398 | * };
|
399 | *
|
400 | * Rx.Observable.from(infinite())
|
401 | * .take(3) // only take 3, cause this is infinite
|
402 | * .subscribe(
|
403 | * value => console.log(value),
|
404 | * err => {},
|
405 | * () => console.log('ta dam!')
|
406 | * );
|
407 | *
|
408 | * // Logs
|
409 | * // 0
|
410 | * // 1
|
411 | * // 2
|
412 | * // "ta dam!"
|
413 | *
|
414 | * @interface
|
415 | * @name ObservableInput
|
416 | * @noimport true
|
417 | */
|
418 | export class ObservableInputDoc<T> {
|
419 |
|
420 | }
|
421 |
|
422 | /**
|
423 | *
|
424 | * This interface describes what should be returned by function passed to Observable
|
425 | * constructor or static {@link create} function. Value of that interface will be used
|
426 | * to cancel subscription for given Observable.
|
427 | *
|
428 | * `TeardownLogic` can be:
|
429 | *
|
430 | * ## Function
|
431 | *
|
432 | * Function that takes no parameters. When consumer of created Observable calls `unsubscribe`,
|
433 | * that function will be called
|
434 | *
|
435 | * ## AnonymousSubscription
|
436 | *
|
437 | * `AnonymousSubscription` is simply an object with `unsubscribe` method on it. That method
|
438 | * will work the same as function
|
439 | *
|
440 | * ## void
|
441 | *
|
442 | * If created Observable does not have any resources to clean up, function does not have to
|
443 | * return anything.
|
444 | *
|
445 | * @interface
|
446 | * @name TeardownLogic
|
447 | * @noimport true
|
448 | */
|
449 | export class TeardownLogicDoc {
|
450 |
|
451 | }
|
452 |
|
\ | No newline at end of file |