Skip to content

Commit

Permalink
docs(observeOn): create the documentation (ReactiveX#2541)
Browse files Browse the repository at this point in the history
Create documentation for the operator, describing
what it can be used for, what parameters accepts and returns.
Add example of typical usage and compare the operator with delay
operator.
  • Loading branch information
mpodlasin authored and benlesh committed May 3, 2017
1 parent ace553c commit 83ebe90
Showing 1 changed file with 41 additions and 4 deletions.
45 changes: 41 additions & 4 deletions src/operator/observeOn.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,48 @@ import { TeardownLogic } from '../Subscription';
import { Action } from '../scheduler/Action';

/**
* @see {@link Notification}
*
* @param scheduler
* @param delay
* @return {Observable<R>|WebSocketSubject<T>|Observable<T>}
* Re-emits all notifications from source Observable with specified scheduler.
*
* <span class="informal">Ensure a specific scheduler is used, from outside of an Observable.</span>
*
* `observeOn` is an operator that accepts a scheduler as a first parameter, which will be used to reschedule
* notifications emitted by the source Observable. It might be useful, if you do not have control over
* internal scheduler of a given Observable, but want to control when its values are emitted nevertheless.
*
* Returned Observable emits the same notifications (nexted values, complete and error events) as the source Observable,
* but rescheduled with provided scheduler. Note that this doesn't mean that source Observables internal
* scheduler will be replaced in any way. Original scheduler still will be used, but when the source Observable emits
* notification, it will be immediately scheduled again - this time with scheduler passed to `observeOn`.
* An anti-pattern would be calling `observeOn` on Observable that emits lots of values synchronously, to split
* that emissions into asynchronous chunks. For this to happen, scheduler would have to be passed into the source
* Observable directly (usually into the operator that creates it). `observeOn` simply delays notifications a
* little bit more, to ensure that they are emitted at expected moments.
*
* As a matter of fact, `observeOn` accepts second parameter, which specifies in milliseconds with what delay notifications
* will be emitted. The main difference between {@link delay} operator and `observeOn` is that `observeOn`
* will delay all notifications - including error notifications - while `delay` will pass through error
* from source Observable immediately when it is emitted. In general it is highly recommended to use `delay` operator
* for any kind of delaying of values in the stream, while using `observeOn` to specify which scheduler should be used
* for notification emissions in general.
*
* @example <caption>Ensure values in subscribe are called just before browser repaint.</caption>
* const intervals = Rx.Observable.interval(10); // Intervals are scheduled
* // with async scheduler by default...
*
* intervals
* .observeOn(Rx.Scheduler.animationFrame) // ...but we will observe on animationFrame
* .subscribe(val => { // scheduler to ensure smooth animation.
* someDiv.style.height = val + 'px';
* });
*
* @see {@link delay}
*
* @param {IScheduler} scheduler Scheduler that will be used to reschedule notifications from source Observable.
* @param {number} [delay] Number of milliseconds that states with what delay every notification should be rescheduled.
* @return {Observable<T>} Observable that emits the same notifications as the source Observable,
* but with provided scheduler.
*
* @method observeOn
* @owner Observable
*/
Expand Down

0 comments on commit 83ebe90

Please sign in to comment.