feat(inspect): added inspect operator

changed name of current `sample` operator to `inspect`. This is because it
deviated from the behavior expected in other implementations of Rx sample.

BREAKING CHANGE: RxJS 5 `sample` behavior is now `inspect`

Author: benlesh

spec/operators/sample-spec.js renamed to spec/operators/inspect-spec.js

@@ -2,27 +2,27 @@
 var Rx = require('../../dist/cjs/Rx');
 var Observable = Rx.Observable;
 
-describe('Observable.prototype.sample', function () {
-  it('should get samples when the notifier emits', function () {
+describe('Observable.prototype.inspect', function () {
+  it('should get inspections when the notifier emits', function () {
     var e1 =   hot('----a-^--b----c----d----e----f----|          ');
     var e1subs =         '^                           !          ';
     var e2 =   hot(      '-----x----------x----------x----------|');
     var e2subs =         '^                           !          ';
     var expected =       '-----b----------d----------f|          ';
 
-    expectObservable(e1.sample(e2)).toBe(expected);
+    expectObservable(e1.inspect(e2)).toBe(expected);
     expectSubscriptions(e1.subscriptions).toBe(e1subs);
     expectSubscriptions(e2.subscriptions).toBe(e2subs);
   });
 
-  it('should sample nothing if source has not nexted yet', function () {
+  it('should inspect nothing if source has not nexted yet', function () {
     var e1 =   hot('----a-^-------b----|');
     var e1subs =         '^            !';
     var e2 =   hot(      '-----x-------|');
     var e2subs =         '^            !';
     var expected =       '-------------|';
 
-    expectObservable(e1.sample(e2)).toBe(expected);
+    expectObservable(e1.inspect(e2)).toBe(expected);
     expectSubscriptions(e1.subscriptions).toBe(e1subs);
     expectSubscriptions(e2.subscriptions).toBe(e2subs);
   });
@@ -34,7 +34,7 @@ describe('Observable.prototype.sample', function () {
     var e2subs =   '^       !                         ';
     var expected = '------a---------------------------';
 
-    expectObservable(e1.sample(e2)).toBe(expected);
+    expectObservable(e1.inspect(e2)).toBe(expected);
     expectSubscriptions(e1.subscriptions).toBe(e1subs);
     expectSubscriptions(e2.subscriptions).toBe(e2subs);
   });
@@ -46,7 +46,7 @@ describe('Observable.prototype.sample', function () {
     var e2subs =   '^       !                         ';
     var expected = '------a--------------------------|';
 
-    expectObservable(e1.sample(e2)).toBe(expected);
+    expectObservable(e1.inspect(e2)).toBe(expected);
     expectSubscriptions(e1.subscriptions).toBe(e1subs);
     expectSubscriptions(e2.subscriptions).toBe(e2subs);
   });
@@ -59,7 +59,7 @@ describe('Observable.prototype.sample', function () {
     var e2subs =         '^             !                        ';
     var expected =       '-----b---------                        ';
 
-    expectObservable(e1.sample(e2), unsub).toBe(expected);
+    expectObservable(e1.inspect(e2), unsub).toBe(expected);
     expectSubscriptions(e1.subscriptions).toBe(e1subs);
     expectSubscriptions(e2.subscriptions).toBe(e2subs);
   });
@@ -74,22 +74,22 @@ describe('Observable.prototype.sample', function () {
 
     var result = e1
       .mergeMap(function (x) { return Observable.of(x); })
-      .sample(e2)
+      .inspect(e2)
       .mergeMap(function (x) { return Observable.of(x); });
 
     expectObservable(result, unsub).toBe(expected);
     expectSubscriptions(e1.subscriptions).toBe(e1subs);
     expectSubscriptions(e2.subscriptions).toBe(e2subs);
   });
 
-  it('should sample multiple times according to the notifier', function () {
+  it('should inspect multiple times according to the notifier', function () {
     var e1 =   hot('----a----b----c----d----e----f----|  ');
     var e1subs =   '^                                 !  ';
     var e2 =   hot('------x-x------xx-x---x-------------|');
     var e2subs =   '^                                 !  ';
     var expected = '------a-a------cc-c---d-----------|  ';
 
-    expectObservable(e1.sample(e2)).toBe(expected);
+    expectObservable(e1.inspect(e2)).toBe(expected);
     expectSubscriptions(e1.subscriptions).toBe(e1subs);
     expectSubscriptions(e2.subscriptions).toBe(e2subs);
   });
@@ -101,7 +101,7 @@ describe('Observable.prototype.sample', function () {
     var e2subs =         '^                 !                    ';
     var expected =       '-----b----------d-#                    ';
 
-    expectObservable(e1.sample(e2)).toBe(expected);
+    expectObservable(e1.inspect(e2)).toBe(expected);
     expectSubscriptions(e1.subscriptions).toBe(e1subs);
     expectSubscriptions(e2.subscriptions).toBe(e2subs);
   });
@@ -113,7 +113,7 @@ describe('Observable.prototype.sample', function () {
     var e1subs =   '(^!)';
     var e2subs =   '(^!)';
 
-    expectObservable(e1.sample(e2)).toBe(expected);
+    expectObservable(e1.inspect(e2)).toBe(expected);
     expectSubscriptions(e1.subscriptions).toBe(e1subs);
     expectSubscriptions(e2.subscriptions).toBe(e2subs);
   });
@@ -125,7 +125,7 @@ describe('Observable.prototype.sample', function () {
     var e1subs =   '(^!)';
     var e2subs =   '(^!)';
 
-    expectObservable(e1.sample(e2)).toBe(expected);
+    expectObservable(e1.inspect(e2)).toBe(expected);
     expectSubscriptions(e1.subscriptions).toBe(e1subs);
     expectSubscriptions(e2.subscriptions).toBe(e2subs);
   });
@@ -137,7 +137,7 @@ describe('Observable.prototype.sample', function () {
     var e1subs =   '^   !';
     var e2subs =   '^   !';
 
-    expectObservable(e1.sample(e2)).toBe(expected);
+    expectObservable(e1.inspect(e2)).toBe(expected);
     expectSubscriptions(e1.subscriptions).toBe(e1subs);
     expectSubscriptions(e2.subscriptions).toBe(e2subs);
   });
@@ -149,31 +149,31 @@ describe('Observable.prototype.sample', function () {
     var e2subs =   '^             !';
     var expected = '-';
 
-    expectObservable(e1.sample(e2)).toBe(expected);
+    expectObservable(e1.inspect(e2)).toBe(expected);
     expectSubscriptions(e1.subscriptions).toBe(e1subs);
     expectSubscriptions(e2.subscriptions).toBe(e2subs);
   });
 
-  it('should sample only until source completes', function () {
+  it('should inspect only until source completes', function () {
     var e1 =   hot('----a----b----c----d-|');
     var e1subs =   '^                    !';
     var e2 =   hot('-----------x----------x------------|');
     var e2subs =   '^                    !';
     var expected = '-----------b---------|';
 
-    expectObservable(e1.sample(e2)).toBe(expected);
+    expectObservable(e1.inspect(e2)).toBe(expected);
     expectSubscriptions(e1.subscriptions).toBe(e1subs);
     expectSubscriptions(e2.subscriptions).toBe(e2subs);
   });
 
-  it('should complete sampling if sample observable completes', function () {
+  it('should complete sampling if inspect observable completes', function () {
     var e1 =   hot('----a----b----c----d-|');
     var e1subs =   '^                    !';
     var e2 =   hot('|');
     var e2subs =   '(^!)';
     var expected = '---------------------|';
 
-    expectObservable(e1.sample(e2)).toBe(expected);
+    expectObservable(e1.inspect(e2)).toBe(expected);
     expectSubscriptions(e1.subscriptions).toBe(e1subs);
     expectSubscriptions(e2.subscriptions).toBe(e2subs);
   });

src/CoreOperators.ts

@@ -39,6 +39,7 @@ export interface CoreOperators<T> {
                 elementSelector?: (value: T) => R,
                 durationSelector?: (group: GroupedObservable<R>) => Observable<any>) => Observable<GroupedObservable<R>>;
   ignoreElements?: () => Observable<T>;
+  inspect?: (notifier: Observable<any>) => Observable<T>;
   last?: <R>(predicate?: (value: T, index: number) => boolean,
              resultSelector?: (value: T, index: number) => R,
              defaultValue?: any) => Observable<T> | Observable<R>;
@@ -62,7 +63,6 @@ export interface CoreOperators<T> {
   repeat?: (count?: number) => Observable<T>;
   retry?: (count?: number) => Observable<T>;
   retryWhen?: (notifier: (errors: Observable<any>) => Observable<any>) => Observable<T>;
-  sample?: (notifier: Observable<any>) => Observable<T>;
   sampleTime?: (delay: number, scheduler?: Scheduler) => Observable<T>;
   scan?: <R>(project: (acc: R, x: T) => R, acc?: R) => Observable<R>;
   share?: () => Observable<T>;

src/Observable.ts

@@ -220,6 +220,7 @@ export class Observable<T> implements CoreOperators<T>  {
                elementSelector?: (value: T) => R,
                durationSelector?: (group: GroupedObservable<R>) => Observable<any>) => Observable<GroupedObservable<R>>;
   ignoreElements: () => Observable<T>;
+  inspect: (notifier: Observable<any>) => Observable<T>;
   last: <R>(predicate?: (value: T, index: number) => boolean,
             resultSelector?: (value: T, index: number) => R,
             thisArg?: any, defaultValue?: any) => Observable<T> | Observable<R>;
@@ -244,7 +245,6 @@ export class Observable<T> implements CoreOperators<T>  {
   repeat: (count?: number) => Observable<T>;
   retry: (count?: number) => Observable<T>;
   retryWhen: (notifier: (errors: Observable<any>) => Observable<any>) => Observable<T>;
-  sample: (notifier: Observable<any>) => Observable<T>;
   sampleTime: (delay: number, scheduler?: Scheduler) => Observable<T>;
   scan: <R>(accumulator: (acc: R, x: T) => R, seed?: T | R) => Observable<R>;
   share: () => Observable<T>;

src/Rx.KitchenSink.ts

@@ -74,6 +74,7 @@ import './add/operator/finally';
 import './add/operator/first';
 import './add/operator/groupBy';
 import './add/operator/ignoreElements';
+import './add/operator/inspect';
 import './add/operator/extended/isEmpty';
 import './add/operator/every';
 import './add/operator/last';
@@ -98,7 +99,6 @@ import './add/operator/reduce';
 import './add/operator/repeat';
 import './add/operator/retry';
 import './add/operator/retryWhen';
-import './add/operator/sample';
 import './add/operator/sampleTime';
 import './add/operator/scan';
 import './add/operator/share';

src/Rx.ts

@@ -54,6 +54,7 @@ import './add/operator/finally';
 import './add/operator/first';
 import './add/operator/groupBy';
 import './add/operator/ignoreElements';
+import './add/operator/inspect';
 import './add/operator/every';
 import './add/operator/last';
 import './add/operator/map';
@@ -74,7 +75,6 @@ import './add/operator/reduce';
 import './add/operator/repeat';
 import './add/operator/retry';
 import './add/operator/retryWhen';
-import './add/operator/sample';
 import './add/operator/sampleTime';
 import './add/operator/scan';
 import './add/operator/share';

src/add/operator/inspect.ts

@@ -0,0 +1,5 @@
+import {Observable} from '../../Observable';
+import {inspect} from '../../operator/inspect';
+Observable.prototype.inspect = inspect;
+
+export var _void: void;

src/add/operator/sample.ts

@@ -2,20 +2,20 @@ import {Observable} from '../Observable';
 import {Operator} from '../Operator';
 import {Subscriber} from '../Subscriber';
 
-export function sample<T>(notifier: Observable<any>): Observable<T> {
-  return this.lift(new SampleOperator(notifier));
+export function inspect<T>(notifier: Observable<any>): Observable<T> {
+  return this.lift(new InspectOperator(notifier));
 }
 
-class SampleOperator<T, R> implements Operator<T, R> {
+class InspectOperator<T, R> implements Operator<T, R> {
   constructor(private notifier: Observable<any>) {
   }
 
   call(subscriber: Subscriber<R>) {
-    return new SampleSubscriber(subscriber, this.notifier);
+    return new InspectSubscriber(subscriber, this.notifier);
   }
 }
 
-class SampleSubscriber<T> extends Subscriber<T> {
+class InspectSubscriber<T> extends Subscriber<T> {
   private lastValue: T;
   private hasValue: boolean = false;
 
@@ -37,7 +37,7 @@ class SampleSubscriber<T> extends Subscriber<T> {
 }
 
 class SampleNotificationSubscriber<T> extends Subscriber<T> {
-  constructor(private parent: SampleSubscriber<T>) {
+  constructor(private parent: InspectSubscriber<T>) {
     super(null);
   }