ts-action-operators

What is it?

The ts-action-operators package contains RxJS operators for action observables.

Why might you need it?

I created the ts-action package because I wanted a mechanism for declaring and consuming actions that involved writing as little boilerplate as possible. And I created this package so that I could apply the TypeScript narrowing mechanisms in ts-action to the composition of NgRx effects and redux-observable epics.

If you, too, want less cruft in your effects or epics, you might find this package useful.

For an in-depth look at TypeScript, Redux and ts-action, have a look at: How to Reduce Action Boilerplate.

Install

Install the package using npm:

npm install ts-action-operators --save

Usage

The package includes operators for filtering and narrowing actions and for selecting strongly typed payloads. The operators can be used in NgRx effects or redux-observable epics, like this:

import { ofType, toPayload } from "ts-action-operators";
const epic = actions => actions.pipe(
  ofType(foo),
  toPayload(),
  tap(payload => console.log(payload.foo)),
  ...
);

Using pipe is recommended; however, if you use a version of RxJS that does not include pipe, you can use let instead:

import { ofType, toPayload } from "ts-action-operators";
import "rxjs/add/operator/let";
const epic = actions => actions
  .let(ofType(foo))
  .let(toPayload())
  .do(payload => console.log(payload.foo))
  ...

act

The act operator is a convenience operator that facilitates the mapping of an input action to an output action with as little boilerplate as possible and with some sensible defaults. It also ensures that errors are handled and that catchError is called in the correct location.

act can be passed a project function and error selector, like this:

.pipe(
  ofType(thingRequested),
  act(
    ({ id }) => things.get(id).pipe(
      map(thing => thingFulfilled(thing))
    ),
    (error, { id }) => thingRejected(id, error)
  )
)

Which is equivalent to:

.pipe(
  ofType(thingRequested),
  concatMap(
    ({ id }) => things.get(id).pipe(
      map(thing => thingFulfilled(thing)),
      catchError(error => thingRejected(id, error))
    )
  )
)

act can also be passed a config object that includes optional complete, operator and unsubscribe properties:

.pipe(
  ofType(thingRequested),
  act({
    ({ id }) => things.get(id).pipe(
      map(thing => thingFulfilled(thing))
    ),
    error: (error, { id }) => thingRejected(id, error),
    unsubscribe: (_ , { id }) => thingCancelled(id),
    operator: switchMap
  })
)

The unsubscribe callback is called if the observable returned from project is unsubscribed before a complete or error notification is emitted. The complete and unsubscribe callbacks are passed the number of actions emitted by the observable returned from project and the input action.

ofType

The ofType operator can be passed ts-action-declared action creators. The operator will remove unwanted actions from the observable stream.

If only a single action creator is specified, the action's type will be narrowed. For example:

.pipe(
  ofType(foo),
  tap(action => {
    // Here, TypeScript has narrowed the type, so the action is strongly typed
    // and individual properties can be accessed in a type-safe manner.
  })
)

If multiple action creators are specified - in an array literal - the action's type will be narrowed to a union:

.pipe(
  ofType([foo, bar]),
  tap(action => {
    // Here, the action has been narrowed to either a FOO or a BAR action.
    // Common properties will be accessible, other will require further narrowing.
    if (isType(action, foo)) {
      // Here, the action has been narrowed to a FOO action.
    } else if (isType(action, bar)) {
      // Here, the action has been narrowed to a BAR action.
    }
  })
)

toPayload

The toPayload operator takes no parameters. It can be applied to an obserable stream that emits narrowed actions that contain payloads. For example:

.pipe(
  ofType(foo),
  toPayload()
  tap(payload => {
    // Here, TypeScript has narrowed the type, so the payload is strongly typed
    // and individual properties can be accessed in a type-safe manner.
  })
)