feat(delay): add higher-order lettable version of delay

src/operator/delay.ts

@@ -1,13 +1,7 @@
 import { async } from '../scheduler/async';
-import { isDate } from '../util/isDate';
-import { Operator } from '../Operator';
 import { IScheduler } from '../Scheduler';
-import { Subscriber } from '../Subscriber';
-import { Action } from '../scheduler/Action';
-import { Notification } from '../Notification';
 import { Observable } from '../Observable';
-import { PartialObserver } from '../Observer';
-import { TeardownLogic } from '../Subscription';
+import { delay as higherOrder } from '../operators';
 
 /**
  * Delays the emission of items from the source Observable by a given timeout or
@@ -50,99 +44,5 @@ import { TeardownLogic } from '../Subscription';
  */
 export function delay<T>(this: Observable<T>, delay: number|Date,
                          scheduler: IScheduler = async): Observable<T> {
-  const absoluteDelay = isDate(delay);
-  const delayFor = absoluteDelay ? (+delay - scheduler.now()) : Math.abs(<number>delay);
-  return this.lift(new DelayOperator(delayFor, scheduler));
-}
-
-class DelayOperator<T> implements Operator<T, T> {
-  constructor(private delay: number,
-              private scheduler: IScheduler) {
-  }
-
-  call(subscriber: Subscriber<T>, source: any): TeardownLogic {
-    return source.subscribe(new DelaySubscriber(subscriber, this.delay, this.scheduler));
-  }
-}
-
-interface DelayState<T> {
-  source: DelaySubscriber<T>;
-  destination: PartialObserver<T>;
-  scheduler: IScheduler;
-}
-
-/**
- * We need this JSDoc comment for affecting ESDoc.
- * @ignore
- * @extends {Ignored}
- */
-class DelaySubscriber<T> extends Subscriber<T> {
-  private queue: Array<DelayMessage<T>> = [];
-  private active: boolean = false;
-  private errored: boolean = false;
-
-  private static dispatch<T>(this: Action<DelayState<T>>, state: DelayState<T>): void {
-    const source = state.source;
-    const queue = source.queue;
-    const scheduler = state.scheduler;
-    const destination = state.destination;
-
-    while (queue.length > 0 && (queue[0].time - scheduler.now()) <= 0) {
-      queue.shift().notification.observe(destination);
-    }
-
-    if (queue.length > 0) {
-      const delay = Math.max(0, queue[0].time - scheduler.now());
-      this.schedule(state, delay);
-    } else {
-      source.active = false;
-    }
-  }
-
-  constructor(destination: Subscriber<T>,
-              private delay: number,
-              private scheduler: IScheduler) {
-    super(destination);
-  }
-
-  private _schedule(scheduler: IScheduler): void {
-    this.active = true;
-    this.add(scheduler.schedule<DelayState<T>>(DelaySubscriber.dispatch, this.delay, {
-      source: this, destination: this.destination, scheduler: scheduler
-    }));
-  }
-
-  private scheduleNotification(notification: Notification<T>): void {
-    if (this.errored === true) {
-      return;
-    }
-
-    const scheduler = this.scheduler;
-    const message = new DelayMessage(scheduler.now() + this.delay, notification);
-    this.queue.push(message);
-
-    if (this.active === false) {
-      this._schedule(scheduler);
-    }
-  }
-
-  protected _next(value: T) {
-    this.scheduleNotification(Notification.createNext(value));
-  }
-
-  protected _error(err: any) {
-    this.errored = true;
-    this.queue = [];
-    this.destination.error(err);
-  }
-
-  protected _complete() {
-    this.scheduleNotification(Notification.createComplete());
-  }
-}
-
-class DelayMessage<T> {
-  constructor(public readonly time: number,
-              public readonly notification: Notification<T>) {
-  }
+  return higherOrder<T>(delay, scheduler)(this);
 }

src/operators/delay.ts

@@ -0,0 +1,149 @@
+import { async } from '../scheduler/async';
+import { isDate } from '../util/isDate';
+import { Operator } from '../Operator';
+import { IScheduler } from '../Scheduler';
+import { Subscriber } from '../Subscriber';
+import { Action } from '../scheduler/Action';
+import { Notification } from '../Notification';
+import { Observable } from '../Observable';
+import { PartialObserver } from '../Observer';
+import { TeardownLogic } from '../Subscription';
+import { MonoTypeOperatorFunction } from '../interfaces';
+
+/**
+ * Delays the emission of items from the source Observable by a given timeout or
+ * until a given Date.
+ *
+ * <span class="informal">Time shifts each item by some specified amount of
+ * milliseconds.</span>
+ *
+ * <img src="./img/delay.png" width="100%">
+ *
+ * If the delay argument is a Number, this operator time shifts the source
+ * Observable by that amount of time expressed in milliseconds. The relative
+ * time intervals between the values are preserved.
+ *
+ * If the delay argument is a Date, this operator time shifts the start of the
+ * Observable execution until the given date occurs.
+ *
+ * @example <caption>Delay each click by one second</caption>
+ * var clicks = Rx.Observable.fromEvent(document, 'click');
+ * var delayedClicks = clicks.delay(1000); // each click emitted after 1 second
+ * delayedClicks.subscribe(x => console.log(x));
+ *
+ * @example <caption>Delay all clicks until a future date happens</caption>
+ * var clicks = Rx.Observable.fromEvent(document, 'click');
+ * var date = new Date('March 15, 2050 12:00:00'); // in the future
+ * var delayedClicks = clicks.delay(date); // click emitted only after that date
+ * delayedClicks.subscribe(x => console.log(x));
+ *
+ * @see {@link debounceTime}
+ * @see {@link delayWhen}
+ *
+ * @param {number|Date} delay The delay duration in milliseconds (a `number`) or
+ * a `Date` until which the emission of the source items is delayed.
+ * @param {Scheduler} [scheduler=async] The IScheduler to use for
+ * managing the timers that handle the time-shift for each item.
+ * @return {Observable} An Observable that delays the emissions of the source
+ * Observable by the specified timeout or Date.
+ * @method delay
+ * @owner Observable
+ */
+export function delay<T>(delay: number|Date,
+                         scheduler: IScheduler = async): MonoTypeOperatorFunction<T> {
+  const absoluteDelay = isDate(delay);
+  const delayFor = absoluteDelay ? (+delay - scheduler.now()) : Math.abs(<number>delay);
+  return (source: Observable<T>) => source.lift(new DelayOperator(delayFor, scheduler));
+}
+
+class DelayOperator<T> implements Operator<T, T> {
+  constructor(private delay: number,
+              private scheduler: IScheduler) {
+  }
+
+  call(subscriber: Subscriber<T>, source: any): TeardownLogic {
+    return source.subscribe(new DelaySubscriber(subscriber, this.delay, this.scheduler));
+  }
+}
+
+interface DelayState<T> {
+  source: DelaySubscriber<T>;
+  destination: PartialObserver<T>;
+  scheduler: IScheduler;
+}
+
+/**
+ * We need this JSDoc comment for affecting ESDoc.
+ * @ignore
+ * @extends {Ignored}
+ */
+class DelaySubscriber<T> extends Subscriber<T> {
+  private queue: Array<DelayMessage<T>> = [];
+  private active: boolean = false;
+  private errored: boolean = false;
+
+  private static dispatch<T>(this: Action<DelayState<T>>, state: DelayState<T>): void {
+    const source = state.source;
+    const queue = source.queue;
+    const scheduler = state.scheduler;
+    const destination = state.destination;
+
+    while (queue.length > 0 && (queue[0].time - scheduler.now()) <= 0) {
+      queue.shift().notification.observe(destination);
+    }
+
+    if (queue.length > 0) {
+      const delay = Math.max(0, queue[0].time - scheduler.now());
+      this.schedule(state, delay);
+    } else {
+      source.active = false;
+    }
+  }
+
+  constructor(destination: Subscriber<T>,
+              private delay: number,
+              private scheduler: IScheduler) {
+    super(destination);
+  }
+
+  private _schedule(scheduler: IScheduler): void {
+    this.active = true;
+    this.add(scheduler.schedule<DelayState<T>>(DelaySubscriber.dispatch, this.delay, {
+      source: this, destination: this.destination, scheduler: scheduler
+    }));
+  }
+
+  private scheduleNotification(notification: Notification<T>): void {
+    if (this.errored === true) {
+      return;
+    }
+
+    const scheduler = this.scheduler;
+    const message = new DelayMessage(scheduler.now() + this.delay, notification);
+    this.queue.push(message);
+
+    if (this.active === false) {
+      this._schedule(scheduler);
+    }
+  }
+
+  protected _next(value: T) {
+    this.scheduleNotification(Notification.createNext(value));
+  }
+
+  protected _error(err: any) {
+    this.errored = true;
+    this.queue = [];
+    this.destination.error(err);
+  }
+
+  protected _complete() {
+    this.scheduleNotification(Notification.createComplete());
+  }
+}
+
+class DelayMessage<T> {
+  constructor(public readonly time: number,
+              public readonly notification: Notification<T>) {
+  }
+}

src/operators/index.ts

@@ -14,6 +14,7 @@ export { count } from './count';
 export { debounce } from './debounce';
 export { debounceTime } from './debounceTime';
 export { defaultIfEmpty } from './defaultIfEmpty';
+export { delay } from './delay';
 export { dematerialize } from './dematerialize';
 export { filter } from './filter';
 export { ignoreElements } from './ignoreElements';