iron-redux

redux typescript perfect safe

Usage no npm install needed!

<script type="module">
  import ironRedux from 'https://cdn.skypack.dev/iron-redux';
</script>

README

iron-redux - Make your redux code completely typesafe and extremely tidy!

npm version npm downloads Gitter

features

  • iron-redux provides helper functions to create type-safe redux types, redux actions and redux state without any extra type difinitions power by the type infer ability of typescript. Try the example code in vscode.
  • The type of store (The state of your whole application) will be inferred by ReturnState<your root reducer map> in iron-redux.
  • Every action type case in reducer can get different corresponding payload type.
  • vscode IDE extension support.
  • The source code is only 300 lines! Zero dependence!
  • iron-redux is not only a library, it's also a best practise in Typescript Redux code. There are some rules you may must be obeyed

install

npm:

npm i -S iron-redux

yarn:

yarn add iron-redux

usage

install vscode extension: nelfe-toolkits.

nelfe-toolkits provide a

API

action types

There are two species of action types in iron-redux. Fetch action type(FetchTypes) and simple action type(BasicTypes).

add a type name in enum is enough for action type define:

enum BasicTypes {
  changeId
}
enum FetchTypes {
  loadData
}

Then use composeTypes function to get a type-safe Types object:

const prefix = "test/";
const Types = composeTypes({
  prefix,
  BasicTypes,
  FetchTypes
});

console.log(Types.changeId); // 'test/changeId';

console.log(Types.loadData.success); // test/changeId_SUCCESS';
console.log(Types.loadData.loading); // test/changeId_LOADING';
console.log(Types.loadData.error); // 'test/changeId_ERROR';

2、action creators

iron-redux provide createAction and createFetchAction functions to create actions.

createAction

provide a payload type, it's equals to the action creator argument type:

const actions = {
  changeId: createAction(Types.changeId)<number>()
};

console.log(actions.changeId(3));  // { type: 'test/chagneId', payload: 3 };

if the action creator arguments and payload is not equal, you can define a custom arguments => payload transfer function. Both the argument and the return action object are type-safe, the return action object type will be inferred.

const actions = {
  changeId: createAction(Types.changeId)((arg: { id: number, pre: string }) => {
    return arg.pre + arg.id;
  })
};

console.log(actions.changeId({ id: 3, pre: '_' }));
// { type: 'test/changeId', paylaod: '_3' }

You can specify the property name in State in createAction , and the property will be updated by default logic in handleAll of Reducer!

const actions = {
  changeId: createAction(Types.changeId, 'id')<number>(),
};

class InitialState {
  id = 3;
}

// then u don't need to handle this action in reducer

Also, if you don't like createAction, you can define action creator by yourself. But remember don't forget to define the arguments type!

const actions = {
  changeId(id: number) {
    return { type: Types.changeId, payload: id };
  }
};

createFetchAction

background:

FetchMiddleware in redux is very common. Dispatch a action as below:

{
  types: [loadingType, successType, failureType],
  url: '/api/data',
  method: 'GET',

}

FetchMiddleware will auto dispatch the loading action, success action and failure action depends on the API response.

usage:

const actions = {
  fetchData: createFetchAction(Types.fetchData, '/api/data', Method.Get)<Params, Response>(),
};

Note: if you are using pont, then all the fetch action will be auto generated.

3、initial state

  • 1、using comment specs as below
  • 2、use AsyncTuple to manage fetch data. Don't put any loading or error property in State class
  • 3、define initial state in State, it will generate the initial state and a state type.
class State {
  /** comment the property here */
  isDialogVisible = false;
  detailFuncInfo = new AsyncTuple(API.ideFunction.getDetailById.init);
  id = 0;
}

4、reducer

The snippets in IDE extension toolkits will generate all the redux code for you.

function reducer(state = new InitialState(), action: ActionType<typeof actions>): InitialState {
  switch (action.type) {
    case Types.addNum: {
      const num = action.payload;

      return {
        ...state,
        num
      };
    }
    default: {
      return AsyncTuple.handleAll(prefix, state, action);
    }
  }
}

note: in every action type case, you can enjoy the different corresponding action payload type.

5、AsyncTuple

AsyncTuple will manage the loading、error、message、data status for you.

class InitialState {
  data = new AsyncTuple(someResponse);
}

And there are some static method like AsyncTuple.handleLoading, AsyncTuple.handleError, AsyncTuple.handleSuccess which will process the API fetch logic for you.

case Types.loadData.loading: {
  return AsyncTuple.handleLoading("data", state);
}
case Types.loadData.success: {
  return AsyncTuple.handleSuccess("data", state, action);
}
case Types.loadData.error: {
  return AsyncTuple.handleError("data", state, action);
}

AsyncTuple provide a powerful function named handleAll to process all the API fetch logic for you. But only you must define the state field in fetch action and you are using AsyncTuple manage the field.

const actions = {
  // define state field
  fetchData: createFetchAction(Types.fetchData, '/api/data', Method.Get)<Params, Response>('listData'),
};

class InitialState {
  // using AsyncTuple
  listData = new AsyncTuple();
}

/**
 * reducer
 */
function reducer(
  state = new InitialState(),
  action: ActionType<typeof actions>
): InitialState {
  switch (action.type) {
    // you don't need write any API fetch logic here!
    default: {
      return AsyncTuple.handleAll(prefix, state, action);
    }
  }
}

get the Redux global state type

There must be a root reducer map which are combined by all the reducers in your App.

iron-redux provide a type infer interface called ReturnState, it will generate the fully type-safe global state type for you.

const rootReducers = {
  a: AReducer,
  b: BReducer,
};
const rootReducer = combineReducer(rootReducers);

export type RootState = ReturnState<typeof rootReducers>;

note: if it's not worked, check your Redux version! The old version Redux code define a totally wrong combineReducer type.

safeGet

the same as lodash get but type safe.

const deepObj = {
  obj: {
    arr: [
      {
        num: 3
      }
    ]
  },
  obj2: {
    str: ''
  }
};

// get data path is type safe
const num = safeGet(deepObj, ['obj', 'arr', 0, 'num'], defaultValueHere);
const str = safeGet(deepObj, ['obj2', 'str']);
// return type is type safe