Typesafe utilities designed to reduce typesverbosityandcomplexity in Redux Architecture.

This library is part of theReact & Redux TypeScript Guide ecosystem 📖

Found it useful? Want more updates?

Show your support by giving a ⭐

🎉Now updated to supportTypeScript v3.7 🎉

⚠️ Library was recently updated to v5⚠️
Current API Docs and Tutorial are outdated (from v4), so temporarily please use this issue asv5.x.x API Docs.

Features

Examples

Goals

Table of Contents

Installation

# NPMnpm install typesafe-actions# YARNyarn add typesafe-actions

Tutorial v4 (v5 is WIP#188)

Constants

// Example file: './constants.ts'// WARNING: Incorrect usageexportconstADD=prefix+'ADD';// => stringexportconstADD=`${prefix}/ADD`;// => stringexportdefault{ADD:'@prefix/ADD',// => string}// Correct usageexportconstADD='@prefix/ADD';// => '@prefix/ADD'exportconstTOGGLE='@prefix/TOGGLE';// => '@prefix/TOGGLE'exportdefault({ADD:'@prefix/ADD',// => '@prefix/ADD'}asconst)// working in TS v3.4 and above => https://github.com/Microsoft/TypeScript/pull/29510

Actions

1. Basic actions

import{action,createAction}from'typesafe-actions';exportconstadd=(title:string)=>action('todos/ADD',{id:cuid(), title,completed:false});// add: (title: string) => { type: "todos/ADD"; payload: { id: string, title: string, completed: boolean; }; }exportconstadd=createAction('todos/ADD',action=>{// Note: "action" callback does not need "type" parameterreturn(title:string)=>action({id:cuid(), title,completed:false});});// add: (title: string) => { type: "todos/ADD"; payload: { id: string, title: string, completed: boolean; }; }

2. FSA compliant actions

import{createStandardAction}from'typesafe-actions';exportconsttoggle=createStandardAction('todos/TOGGLE')<string>();// toggle: (payload: string) => { type: "todos/TOGGLE"; payload: string; }exportconstadd=createStandardAction('todos/ADD').map((title:string)=>({payload:{id:cuid(), title,completed:false},}));// add: (payload: string) => { type: "todos/ADD"; payload: { id: string, title: string, completed: boolean; }; }

3. Custom actions (non-standard use-cases)

import{createCustomAction}from'typesafe-actions';constadd=createCustomAction('todos/ADD',type=>{return(title:string)=>({ type,id:cuid(), title,completed:false});});// add: (title: string) => { type: "todos/ADD"; id: string; title: string; completed: boolean; }

// types.d.ts// example of including `react-router` actions in `RootAction`import{RouterAction,LocationChangeAction}from'react-router-redux';import{TodosAction}from'../features/todos';typeReactRouterAction=RouterAction|LocationChangeAction;exporttypeRootAction=|ReactRouterAction|TodosAction;

Action Helpers

Using action-creators instances instead of type-constants

switch(action.type){casegetType(todos.add):// below action type is narrowed to: { type: "todos/ADD"; payload: Todo; }return[...state,action.payload];    ...

// epics.tsimport{isActionOf}from'typesafe-actions';import{add}from'./actions';constaddTodoToast:Epic<RootAction,RootAction,RootState,Services>=(action$,state$,{ toastService})=>action$.pipe(filter(isActionOf(add)),tap(action=>{// here action type is narrowed to: { type: "todos/ADD"; payload: Todo; }toastService.success(...);})...// Works with multiple actions! (with type-safety up to 5)action$.pipe(filter(isActionOf([add,toggle]))// here action type is narrowed to a smaller union:// { type: "todos/ADD"; payload: Todo; } | { type: "todos/TOGGLE"; payload: string; }

Using regular type-constants

// epics.tsimport{isOfType}from'typesafe-actions';import{ADD}from'./constants';constaddTodoToast:Epic<RootAction,RootAction,RootState,Services>=(action$,state$,{ toastService})=>action$.pipe(filter(isOfType(ADD)),tap(action=>{// here action type is narrowed to: { type: "todos/ADD"; payload: Todo; }    ...// Works with multiple actions! (with type-safety up to 5)action$.pipe(filter(isOfType([ADD,TOGGLE]))// here action type is narrowed to a smaller union:// { type: "todos/ADD"; payload: Todo; } | { type: "todos/TOGGLE"; payload: string; }

import{isActionOf,isOfType}from'typesafe-actions';if(isActionOf(actions.add,action)){// here action is narrowed to: { type: "todos/ADD"; payload: Todo; }}// or with type constantsif(isOfType(types.ADD,action)){// here action is narrowed to: { type: "todos/ADD"; payload: Todo; }}

Reducers

Extending internal types to enable type-free syntax withcreateReducer

// types.d.tsimport{ActionType}from'typesafe-actions';exporttypeRootAction=ActionType<typeofimport('./actions').default>;declare module'typesafe-actions'{interfaceTypes{RootAction:RootAction;}}// now you can usecreateReducer(...)// instead ofcreateReducer<State,Action>(...)

Using createReducer API with type-free syntax

// using action-creatorsconstcounterReducer=createReducer(0)// state and action type is automatically inferred and return type is validated to be exact type.handleAction(add,(state,action)=>state+action.payload).handleAction(add, ...// <= error is shown on duplicated or invalid actions.handleAction(increment,(state,_)=>state+1).handleAction(...// <= error is shown when all actions are handled// or handle multiple actions using array.handleAction([add,increment],(state,action)=>state+(action.type==='ADD' ?action.payload :1));// all the same scenarios are working when using type-constantsconstcounterReducer=createReducer(0).handleAction('ADD',(state,action)=>state+action.payload).handleAction('INCREMENT',(state,_)=>state+1);counterReducer(0,add(4));// => 4counterReducer(0,increment());// => 1

Alternative usage with regular switch reducer

import{ActionType}from'typesafe-actions';import*astodosfrom'./actions';exporttypeTodosAction=ActionType<typeoftodos>;

exportdefault(state:Todo[]=[],action:TodosAction)=>{

switch(action.type){casegetType(add):// below action type is narrowed to: { type: "todos/ADD"; payload: Todo; }return[...state,action.payload];    ...

Async-Flows

Withredux-observable epics

// actions.tsimport{createAsyncAction}from'typesafe-actions';constfetchTodosAsync=createAsyncAction('FETCH_TODOS_REQUEST','FETCH_TODOS_SUCCESS','FETCH_TODOS_FAILURE','FETCH_TODOS_CANCEL')<string,Todo[],Error,string>();// epics.tsimport{fetchTodosAsync}from'./actions';constfetchTodosFlow:Epic<RootAction,RootAction,RootState,Services>=(action$,state$,{ todosApi})=>action$.pipe(filter(isActionOf(fetchTodosAsync.request)),switchMap(action=>from(todosApi.getAll(action.payload)).pipe(map(fetchTodosAsync.success),catchError((message:string)=>of(fetchTodosAsync.failure(message))),takeUntil(action$.pipe(filter(isActionOf(fetchTodosAsync.cancel)))),)));

Withredux-saga sagas

import{createAsyncAction,createReducer}from'typesafe-actions';import{put,call,takeEvery,all}from'redux-saga/effects';// Create the set of async actionsconstfetchTodosAsync=createAsyncAction('FETCH_TODOS_REQUEST','FETCH_TODOS_SUCCESS','FETCH_TODOS_FAILURE')<string,Todo[],Error>();// Handle request sagafunction*addTodoSaga(action:ReturnType<typeoffetchTodosAsync.request>):Generator{try{constresponse:Todo[]=yieldcall(todosApi.getAll,action.payload);yieldput(fetchTodosAsync.success(response));}catch(err){yieldput(fetchTodosAsync.failure(err));}}// Main sagafunction*mainSaga(){yieldall([takeEvery(fetchTodosAsync.request,addTodoSaga),]);}// Handle success reducerexportconsttodoReducer=createReducer({}).handleAction(fetchTodosAsync.success,(state,action)=>({ ...state,todos:action.payload}));

API Docs v4 (v5 is WIP#189)

Action-Creators API

action

action(type,payload?,meta?,error?)

constincrement=()=>action('INCREMENT');// { type: 'INCREMENT'; }constcreateUser=(id:number,name:string)=>action('CREATE_USER',{ id, name});// { type: 'CREATE_USER'; payload: { id: number; name: string };}constgetUsers=(params?:string)=>action('GET_USERS',undefined,params);// { type: 'GET_USERS'; meta: string | undefined; }

constincrement=()=>({type:'INCREMENT'}asconst);

createAction

createAction(type)createAction(type,actionCallback=>{return(namedArg1,namedArg2, ...namedArgN)=>actionCallback(payload?,meta?)})

import{createAction}from'typesafe-actions';// - with type onlyconstincrement=createAction('INCREMENT');dispatch(increment());// { type: 'INCREMENT' };// - with type and payloadconstadd=createAction('ADD',action=>{return(amount:number)=>action(amount);});dispatch(add(10));// { type: 'ADD', payload: number }// - with type and metaconstgetTodos=createAction('GET_TODOS',action=>{return(params:Params)=>action(undefined,params);});dispatch(getTodos('some_meta'));// { type: 'GET_TODOS', meta: Params }// - and finally with type, payload and metaconstgetTodo=createAction('GET_TODO',action=>{return(id:string,meta:string)=>action(id,meta);});dispatch(getTodo('some_id','some_meta'));// { type: 'GET_TODO', payload: string, meta: string }

createStandardAction

createStandardAction(type)()createStandardAction(type)<TPayload,TMeta?>()createStandardAction(type).map((payload,meta)=>({ customProp1, customProp2, ...customPropN}))

import{createStandardAction}from'typesafe-actions';// Very concise with use of generic type arguments// - with type onlyconstincrement=createStandardAction('INCREMENT')();constincrement=createStandardAction('INCREMENT')<undefined>();increment();// { type: 'INCREMENT' } (no parameters are required)// - with type and payloadconstadd=createStandardAction('ADD')<number>();add(10);// { type: 'ADD', payload: number }// - with type and metaconstgetData=createStandardAction('GET_DATA')<undefined,string>();getData(undefined,'meta');// { type: 'GET_DATA', meta: string }// - and finally with type, payload and metaconstgetData=createStandardAction('GET_DATA')<number,string>();getData(1,'meta');// { type: 'GET_DATA', payload: number, meta: string }// Can map payload and meta arguments to a custom action objectconstnotify=createStandardAction('NOTIFY').map((payload:string,meta:Meta)=>({from:meta.username,message:`${meta.username}:${payload}`,messageType:meta.type,datetime:newDate(),}));dispatch(notify('Hello!',{username:'Piotr',type:'announcement'}));// { type: 'NOTIFY', from: string, message: string, messageType: MessageType, datetime: Date }

createCustomAction

createCustomAction(type,type=>{return(namedArg1,namedArg2, ...namedArgN)=>({ type, customProp1, customProp2, ...customPropN})})

import{createCustomAction}from'typesafe-actions';constadd=createCustomAction('CUSTOM',type=>{return(first:number,second:number)=>({ type,customProp1:first,customProp2:second});});dispatch(add(1));// { type: "CUSTOM"; customProp1: number; customProp2: number; }

createAsyncAction

createAsyncAction(requestType,successType,failureType,cancelType?)<TRequestPayload,TSuccessPayload,TFailurePayload,TCancelPayload?>()

AsyncActionCreator

typeAsyncActionCreator<[TRequestType,TRequestPayload],[TSuccessType,TSuccessPayload],[TFailureType,TFailurePayload],[TCancelType,TCancelPayload]?>={request:StandardActionCreator<TRequestType,TRequestPayload>,success:StandardActionCreator<TSuccessType,TSuccessPayload>,failure:StandardActionCreator<TFailureType,TFailurePayload>,cancel?:StandardActionCreator<TCancelType,TCancelPayload>,}

import{createAsyncAction,AsyncActionCreator}from'typesafe-actions';constfetchUsersAsync=createAsyncAction('FETCH_USERS_REQUEST','FETCH_USERS_SUCCESS','FETCH_USERS_FAILURE')<string,User[],Error>();dispatch(fetchUsersAsync.request(params));dispatch(fetchUsersAsync.success(response));dispatch(fetchUsersAsync.failure(err));constfn=(a:AsyncActionCreator<['FETCH_USERS_REQUEST',string],['FETCH_USERS_SUCCESS',User[]],['FETCH_USERS_FAILURE',Error]>)=>a;fn(fetchUsersAsync);// There is 4th optional argument to declare cancel actionconstfetchUsersAsync=createAsyncAction('FETCH_USERS_REQUEST','FETCH_USERS_SUCCESS','FETCH_USERS_FAILURE''FETCH_USERS_CANCEL')<string,User[],Error,string>();dispatch(fetchUsersAsync.cancel('reason'));constfn=(a:AsyncActionCreator<['FETCH_USERS_REQUEST',string],['FETCH_USERS_SUCCESS',User[]],['FETCH_USERS_FAILURE',Error],['FETCH_USERS_CANCEL',string]>)=>a;fn(fetchUsersAsync);

Reducer-Creators API

createReducer

createReducer<TState,TRootAction>(initialState,handlersMap?)// orcreateReducer<TState,TRootAction>(initialState).handleAction(actionCreator,reducer).handleAction([actionCreator1,actionCreator2, ...actionCreatorN],reducer).handleType(type,reducer).handleType([type1,type2, ...typeN],reducer)

// type-free syntax doesn't require generic type argumentsconstcounterReducer=createReducer(0,{ADD:(state,action)=>state+action.payload,[getType(increment)]:(state,_)=>state+1,})

import{createReducer,getType}from'typesafe-actions'typeState=number;typeAction={type:'ADD',payload:number}|{type:'INCREMENT'};constcounterReducer=createReducer<State,Action>(0,{ADD:(state,action)=>state+action.payload,[getType(increment)]:(state,_)=>state+1,})

// using action-creatorsconstcounterReducer=createReducer<State,Action>(0).handleAction(add,(state,action)=>state+action.payload).handleAction(increment,(state,_)=>state+1)// handle multiple actions by using array.handleAction([add,increment],(state,action)=>state+(action.type==='ADD' ?action.payload :1));// all the same scenarios are working when using type-constantsconstcounterReducer=createReducer<State,Action>(0).handleType('ADD',(state,action)=>state+action.payload).handleType('INCREMENT',(state,_)=>state+1);

constnewCounterReducer=createReducer<State,Action>(0).handleAction('SUBTRACT',(state,action)=>state-action.payload).handleAction('DECREMENT',(state,_)=>state-1);constbigReducer=createReducer<State,Action>(0,{  ...counterReducer.handlers,// typesafe  ...newCounterReducer.handlers,// typesafeSUBTRACT:decrementReducer.handlers.DECREMENT,// <= error, wrong type})

Action-Helpers API

getType

getType(actionCreator)

import{getType,createStandardAction}from'typesafe-actions';constadd=createStandardAction('ADD')<number>();// In switch reducerswitch(action.type){casegetType(add):// action type is { type: "ADD"; payload: number; }returnstate+action.payload;default:returnstate;}// or with conditional statementsif(action.type===getType(add)){// action type is { type: "ADD"; payload: number; }}

isActionOf

// can be used as a binary functionisActionOf(actionCreator,action)// or as a curried functionisActionOf(actionCreator)(action)// also accepts an arrayisActionOf([actionCreator1,actionCreator2, ...actionCreatorN],action)// with its curried equivalentisActionOf([actionCreator1,actionCreator2, ...actionCreatorN])(action)

import{addTodo,removeTodo}from'./todos-actions';// Works with any filter type function (`Array.prototype.filter`, lodash, ramda, rxjs, etc.)// - single action[action1,action2, ...actionN].filter(isActionOf(addTodo))// only actions with type `ADD` will pass.map((action)=>{// action type is { type: "todos/ADD"; payload: Todo; }    ...// - multiple actions[action1,action2, ...actionN].filter(isActionOf([addTodo,removeTodo]))// only actions with type `ADD` or 'REMOVE' will pass.do((action)=>{// action type is { type: "todos/ADD"; payload: Todo; } | { type: "todos/REMOVE"; payload: Todo; }    ...// With conditional statements// - single actionif(isActionOf(addTodo,action)){returniAcceptOnlyTodoType(action.payload);// action type is { type: "todos/ADD"; payload: Todo; }}// - multiple actionsif(isActionOf([addTodo,removeTodo],action)){returniAcceptOnlyTodoType(action.payload);// action type is { type: "todos/ADD"; payload: Todo; } | { type: "todos/REMOVE"; payload: Todo; }}

isOfType

// can be used as a binary functionisOfType(type,action)// or as curried functionisOfType(type)(action)// also accepts an arrayisOfType([type1,type2, ...typeN],action)// with its curried equivalentisOfType([type1,type2, ...typeN])(action)

import{ADD,REMOVE}from'./todos-types';// Works with any filter type function (`Array.prototype.filter`, lodash, ramda, rxjs, etc.)// - single action[action1,action2, ...actionN].filter(isOfType(ADD))// only actions with type `ADD` will pass.map((action)=>{// action type is { type: "todos/ADD"; payload: Todo; }    ...// - multiple actions[action1,action2, ...actionN].filter(isOfType([ADD,REMOVE]))// only actions with type `ADD` or 'REMOVE' will pass.do((action)=>{// action type is { type: "todos/ADD"; payload: Todo; } | { type: "todos/REMOVE"; payload: Todo; }    ...// With conditional statements// - single actionif(isOfType(ADD,action)){returniAcceptOnlyTodoType(action.payload);// action type is { type: "todos/ADD"; payload: Todo; }}// - multiple actionsif(isOfType([ADD,REMOVE],action)){returniAcceptOnlyTodoType(action.payload);// action type is { type: "todos/ADD"; payload: Todo; } | { type: "todos/REMOVE"; payload: Todo; }}

Type-Helpers API

ActionType

import{ActionType}from'typesafe-actions';// with "import * as ..."import*astodosfrom'./actions';exporttypeTodosAction=ActionType<typeoftodos>;// TodosAction: { type: 'action1' } | { type: 'action2' } | { type: 'action3' }// with nested action-creator map caseconstactions={action1:createAction('action1'),nested:{action2:createAction('action2'),moreNested:{action3:createAction('action3'),},},};exporttypeRootAction=ActionType<typeofactions>;// RootAction: { type: 'action1' } | { type: 'action2' } | { type: 'action3' }

StateType

import{combineReducers}from'redux';import{StateType}from'typesafe-actions';// with reducer functionconsttodosReducer=(state:Todo[]=[],action:TodosAction)=>{switch(action.type){casegetType(todos.add):return[...state,action.payload];    ...exporttypeTodosState=StateType<typeoftodosReducer>;// with nested/combined reducersconstrootReducer=combineReducers({router:routerReducer,counters:countersReducer,});exporttypeRootState=StateType<typeofrootReducer>;

Migration Guides

v4.x.x tov5.x.x

// beforeimport{createAction,createStandardAction,createCustomAction}from"typesafe-actions"// afterimport{deprecated}from"typesafe-actions"const{ createAction, createStandardAction, createCustomAction}=deprecated;

// beforeconstwithMappedPayloadAndMeta=createStandardAction('CREATE_STANDARD_ACTION').map(({ username, message}:Notification)=>({payload:`${username}:${message}`,meta:{ username, message},}));// afterconstwithMappedPayloadAndMeta=createAction('CREATE_STANDARD_ACTION',({ username, message}:Notification)=>`${username}:${message}`,// payload creator({ username, message}:Notification)=>({ username, message})// meta creator)();

// beforeconstwithPayloadAndMeta=createAction('CREATE_ACTION',resolve=>{return(id:number,token:string)=>resolve(id,token);});// afterconstwithPayloadAndMeta=createAction('CREATE_ACTION',(id:number,token:string)=>id,// payload creator(id:number,token:string)=>token// meta creator})();

// beforeconstadd=createCustomAction('CUSTOM',type=>{return(first:number,second:number)=>({ type,customProp1:first,customProp2:second});});// afterconstadd=createCustomAction('CUSTOM',(first:number,second:number)=>({customProp1:first,customProp2:second}));

// beforeimport{AsyncActionCreator}from"typesafe-actions"//afterimport{AsyncActionCreatorBuilder}from"typesafe-actions"

v3.x.x tov4.x.x

v2.x.x tov3.x.x

v1.x.x tov2.x.x

// in v1 we created action-creator like this:constgetTodo=createAction('GET_TODO',(id:string,meta:string)=>({type:'GET_TODO',payload:id,meta:meta,}));getTodo('some_id','some_meta');// { type: 'GET_TODO', payload: 'some_id', meta: 'some_meta' }// in v2 we offer few different options - please choose your preferenceconstgetTodoNoHelpers=(id:string,meta:string)=>action('GET_TODO',id,meta);constgetTodoWithHelpers=createAction('GET_TODO',action=>{return(id:string,meta:string)=>action(id,meta);});constgetTodoFSA=createStandardAction('GET_TODO')<string,string>();constgetTodoCustom=createStandardAction('GET_TODO').map(({ id, meta}:{id:string;meta:string;})=>({payload:id,    meta,}));

Migrating fromredux-actions totypesafe-actions

createAction(type,payloadCreator,metaCreator)=>createStandardAction(type)()||createStandardAction(type).map(payloadMetaCreator)createActions()=>// COMING SOON!

handleAction(type,reducer,initialState)=>createReducer(initialState).handleAction(type,reducer)handleActions(reducerMap,initialState)=>createReducer(initialState,reducerMap)

Compatibility Notes

Recipes

Restrict Meta type inaction creator

exporttypeMetaType={analytics?:{eventName:string;};};exportconstactionWithRestrictedMeta=<Textendsstring,P>(type:T,payload:P,meta:MetaType)=>action(type,payload,meta);exportconstvalidAction=(payload:string)=>actionWithRestrictedMeta('type',payload,{analytics:{eventName:'success'}});// OK!exportconstinvalidAction=(payload:string)=>actionWithRestrictedMeta('type',payload,{analytics:{excessProp:'no way!'}});// Error// Object literal may only specify known properties, and 'excessProp' does not exist in type '{ eventName: string; }

Compare to others

redux-actions

redux-actions

constnotify1=createAction('NOTIFY');// resulting type:// () => {//   type: string;//   payload: void | undefined;//   error: boolean | undefined;// }

typesafe-actions

constnotify1=()=>action('NOTIFY');// resulting type:// () => {//   type: "NOTIFY";// }

redux-actions

constnotify2=createAction('NOTIFY',(username:string,message?:string)=>({message:`${username}:${message||'Empty!'}`,}));// resulting type:// (t1: string) => {//   type: string;//   payload: { message: string; } | undefined;//   error: boolean | undefined;// }

typesafe-actions

constnotify2=(username:string,message?:string)=>action('NOTIFY',{message:`${username}:${message||'Empty!'}`},);// resulting type:// (username: string, message?: string | undefined) => {//   type: "NOTIFY";//   payload: { message: string; };// }

redux-actions

constnotify3=createAction('NOTIFY',(username:string,message?:string)=>({message:`${username}:${message||'Empty!'}`}),(username:string,message?:string)=>({ username, message}));// resulting type:// (...args: any[]) => {//   type: string;//   payload: { message: string; } | undefined;//   meta: { username: string; message: string | undefined; };//   error: boolean | undefined;// }

typesafe-actions

/** * typesafe-actions */constnotify3=(username:string,message?:string)=>action('NOTIFY',{message:`${username}:${message||'Empty!'}`},{ username, message},);// resulting type:// (username: string, message?: string | undefined) => {//   type: "NOTIFY";//   payload: { message: string; };//   meta: { username: string; message: string | undefined; };// }

Motivation

Contributing

Funding Issues

License