TypeScript FSA

Action Creator library for TypeScript. Its goal is to provide type-safe experience with Flux actions with minimum boilerplate. Created actions are FSA-compliant:

1interface Action<Payload> {
2  type: string;
3  payload: Payload;
4  error?: boolean;
5  meta?: Object;
6}

Installation

npm install --save typescript-fsa

Usage

Basic

1import actionCreatorFactory from 'typescript-fsa';
2
3const actionCreator = actionCreatorFactory();
4
5// Specify payload shape as generic type argument.
6const somethingHappened = actionCreator<{foo: string}>('SOMETHING_HAPPENED');
7
8// Get action creator type.
9console.log(somethingHappened.type);  // SOMETHING_HAPPENED
10
11// Create action.
12const action = somethingHappened({foo: 'bar'});
13console.log(action);  // {type: 'SOMETHING_HAPPENED', payload: {foo: 'bar'}}

Async Action Creators

Async Action Creators are objects with properties started, done and failed whose values are action creators. There is a number of Companion Packages that help with binding Async Action Creators to async processes.

1import actionCreatorFactory from 'typescript-fsa';
2
3const actionCreator = actionCreatorFactory();
4
5// specify parameters and result shapes as generic type arguments
6const doSomething =
7  actionCreator.async<{foo: string},   // parameter type
8                      {bar: number},   // success type
9                      {code: number}   // error type
10                     >('DO_SOMETHING');
11
12console.log(doSomething.started({foo: 'lol'}));
13// {type: 'DO_SOMETHING_STARTED', payload: {foo: 'lol'}}
14
15console.log(doSomething.done({
16  params: {foo: 'lol'},
17  result: {bar: 42},
18}));
19// {type: 'DO_SOMETHING_DONE', payload: {
20//   params: {foo: 'lol'},
21//   result: {bar: 42},
22// }}
23
24console.log(doSomething.failed({
25  params: {foo: 'lol'},
26  error: {code: 42},
27}));
28// {type: 'DO_SOMETHING_FAILED', payload: {
29//   params: {foo: 'lol'},
30//   error: {code: 42},
31// }, error: true}

Actions With Type Prefix

You can specify a prefix that will be prepended to all action types. This is useful to namespace library actions as well as for large projects where it's convenient to keep actions near the component that dispatches them.

1// MyComponent.actions.ts
2import actionCreatorFactory from 'typescript-fsa';
3
4const actionCreator = actionCreatorFactory('MyComponent');
5
6const somethingHappened = actionCreator<{foo: string}>('SOMETHING_HAPPENED');
7
8const action = somethingHappened({foo: 'bar'});
9console.log(action);
10// {type: 'MyComponent/SOMETHING_HAPPENED', payload: {foo: 'bar'}}

Redux

1// actions.ts
2import actionCreatorFactory from 'typescript-fsa';
3
4const actionCreator = actionCreatorFactory();
5
6export const somethingHappened =
7  actionCreator<{foo: string}>('SOMETHING_HAPPENED');
8export const somethingAsync =
9  actionCreator.async<{foo: string},
10                      {bar: string}
11                     >('SOMETHING_ASYNC');
12
13
14// reducer.ts
15import {Action} from 'redux';
16import {isType} from 'typescript-fsa';
17import {somethingHappened, somethingAsync} from './actions';
18
19type State = {bar: string};
20
21export const reducer = (state: State, action: Action): State => {
22  if (isType(action, somethingHappened)) {
23    // action.payload is inferred as {foo: string};
24
25    action.payload.bar;  // error
26
27    return {bar: action.payload.foo};
28  }
29
30  if (isType(action, somethingAsync.started)) {
31    return {bar: action.payload.foo};
32  }
33
34  if (isType(action, somethingAsync.done)) {
35    return {bar: action.payload.result.bar};
36  }
37
38  return state;
39};

redux-observable

1// epic.ts
2import {Action} from 'redux';
3import {Observable} from 'rxjs';
4import {somethingAsync} from './actions';
5
6export const epic = (actions$: Observable<Action>) =>
7  actions$.filter(somethingAsync.started.match)
8    .delay(2000)
9    .map(action => {
10      // action.payload is inferred as {foo: string};
11
12      action.payload.bar;  // error
13
14      return somethingAsync.done({
15        params: action.payload,
16        result: {
17          bar: 'bar',
18        },
19      });
20    });

Companion Packages

• typescript-fsa-redux-saga
• typescript-fsa-redux-observable
• typescript-fsa-redux-thunk
• typescript-fsa-reducers

Resources

• Type-safe Flux Standard Actions (FSA) in React Using TypeScript FSA
• Type-safe Asynchronous Actions (Redux Thunk) Using TypeScript FSA

API

actionCreatorFactory(prefix?: string, defaultIsError?: Predicate): ActionCreatorFactory

Creates Action Creator factory with optional prefix for action types.

• prefix?: string: Prefix to be prepended to action types as <prefix>/<type>.
• defaultIsError?: Predicate: Function that detects whether action is error given the payload. Default is payload => payload instanceof Error.

ActionCreatorFactory<Payload>#(type: string, commonMeta?: object, isError?: boolean): ActionCreator<Payload>

Creates Action Creator that produces actions with given type and payload of type Payload.

• type: string: Type of created actions.
• commonMeta?: object: Metadata added to created actions.
• isError?: boolean: Defines whether created actions are error actions.

ActionCreatorFactory#async<Params, Result, Error>(type: string, commonMeta?: object): AsyncActionCreators<Params, Result, Error>

Creates three Action Creators:

• started: ActionCreator<Params>
• done: ActionCreator<{params: Params, result: Result}>
• failed: ActionCreator<{params: Params, error: Error}>

Useful to wrap asynchronous processes.

• type: string: Prefix for types of created actions, which will have types ${type}_STARTED, ${type}_DONE and ${type}_FAILED.
• commonMeta?: object: Metadata added to created actions.

ActionCreator<Payload>#(payload: Payload, meta?: object): Action<Payload>

Creates action with given payload and metadata.

• payload: Payload: Action payload.
• meta?: object: Action metadata. Merged with commonMeta of Action Creator.

isType(action: Action, actionCreator: ActionCreator): boolean

Returns true if action has the same type as action creator. Defines Type Guard that lets TypeScript know payload type inside blocks where isType returned true:

1const somethingHappened = actionCreator<{foo: string}>('SOMETHING_HAPPENED');
2
3if (isType(action, somethingHappened)) {
4  // action.payload has type {foo: string}
5}

ActionCreator#match(action: Action): boolean

Identical to isType except it is exposed as a bound method of an action creator. Since it is bound and takes a single argument it is ideal for passing to a filtering function like Array.prototype.filter or RxJS's Observable.prototype.filter.

1const somethingHappened = actionCreator<{foo: string}>('SOMETHING_HAPPENED');
2const somethingElseHappened =
3  actionCreator<{bar: number}>('SOMETHING_ELSE_HAPPENED');
4
5if (somethingHappened.match(action)) {
6  // action.payload has type {foo: string}
7}
8
9const actionArray = [
10  somethingHappened({foo: 'foo'}),
11  somethingElseHappened({bar: 5}),
12];
13
14// somethingHappenedArray has inferred type Action<{foo: string}>[]
15const somethingHappenedArray = actionArray.filter(somethingHappened.match);

For more on using Array.prototype.filter as a type guard, see this github issue.