fix(Effects): Deprecate toPayload utility function (#266)

Author: karptonite

docs/effects/api.md

@@ -55,7 +55,7 @@ export class SomeEffectsClass {
 
 ### ofType
 
-Filter actions by action types.
+Filter actions by action types. Specify the action type to allow type-safe mapping to other data on the action, including payload.
 
 Usage:
 ```ts
@@ -67,7 +67,7 @@ import { Actions, Effect } from '@ngrx/effects';
 export class SomeEffectsClass {
   constructor(private actions$: Actions) {}
 
-  @Effect() authActions$ = this.action$.ofType('LOGIN', 'LOGOUT')
+  @Effect() authActions$ = this.action$.ofType<LoginAction | LogoutAction>('LOGIN', 'LOGOUT')
     .do(action => {
       console.log(action);
     });
@@ -128,8 +128,8 @@ export class UserEffects implements OnRunEffects {
 
 ## Utilities
 
-### toPayload
-Maps an action to its payload.
+### toPayload (DEPRECATED)
+Maps an action to its payload. This function is deprecated, and will be removed in version 5.0.
 
 Usage:
 ```ts
@@ -150,6 +150,15 @@ export class SomeEffectsClass {
 }
 ```
 
+Recommended alternative to deprecated toPayload function. Note that the type
+of the action is specified so that mapping to payload (or whatever data is available in the action) is type-safe.
+```ts
+  @Effect() authActions$ = this.action$.ofType<LoadingAction | LogoutAction>('LOGIN', 'LOGOUT')
+    .map(action => action.payload)
+    .do(payload => {
+      console.log(payload);
+```
+
 ### mergeEffects
 Manually merges all decorated effects into a combined observable.
 

example-app/app/books/effects/book.ts

@@ -5,7 +5,7 @@ import 'rxjs/add/operator/debounceTime';
 import 'rxjs/add/operator/skip';
 import 'rxjs/add/operator/takeUntil';
 import { Injectable, InjectionToken, Optional, Inject } from '@angular/core';
-import { Effect, Actions, toPayload } from '@ngrx/effects';
+import { Effect, Actions } from '@ngrx/effects';
 import { Action } from '@ngrx/store';
 import { Observable } from 'rxjs/Observable';
 import { Scheduler } from 'rxjs/Scheduler';
@@ -25,12 +25,6 @@ export const SEARCH_SCHEDULER = new InjectionToken<Scheduler>(
 /**
  * Effects offer a way to isolate and easily test side-effects within your
  * application.
- * The `toPayload` helper function returns just
- * the payload of the currently dispatched action, useful in
- * instances where the current state is not necessary.
- *
- * Documentation on `toPayload` can be found here:
- * https://github.com/ngrx/platform/blob/master/docs/effects/api.md#topayload
  *
  * If you are unfamiliar with the operators being used in these examples, please
  * check out the sources below:
@@ -43,9 +37,9 @@ export const SEARCH_SCHEDULER = new InjectionToken<Scheduler>(
 export class BookEffects {
   @Effect()
   search$: Observable<Action> = this.actions$
-    .ofType(book.SEARCH)
+    .ofType<book.SearchAction>(book.SEARCH)
     .debounceTime(this.debounce, this.scheduler || async)
-    .map(toPayload)
+    .map(action => action.payload)
     .switchMap(query => {
       if (query === '') {
         return empty();

modules/effects/src/util.ts

@@ -1,5 +1,8 @@
 import { Action } from '@ngrx/store';
 
+/**
+ * @deprecated Since version 4.1. Will be deleted in version 5.0.
+ */
 export function toPayload(action: Action): any {
   return (action as any).payload;
 }