ih-black-lion/lib/actions/ActionDocs.md

State handler for Arus projects

# Redux Actions

The files in this directory provide functions that describe actions that are dispatched by the client.

Once these actions are dispatched they're return values are then passed to the reducer so that a state change can be made (or not made depending on the action).

There are two types of actions that can be dispatched. The first are Synchronous actions and the second are Asynchronous actions.

## Synchronous Actions

You can tell an action is synchronous if it returns an Object. That Object will contain the field `type` which is assigned a String value (usually ALL_CAPS and SNAKE_CASED) that describes the action. The Object may also contain other fields that provide other useful information about the action or describe parameters that were passed to the action.

The following example shows how a synchronous action might be created.

```js
/**
 * Describes a dispatched REQUEST_PROFILE action.
 *
 * @param  {Object} serviceParams Contains the parameters that will be used to make the service
 *   call.
 * @return {Object}               An Object describing the dispatched action. This will be passed
 *   along to the Reducer so that a state change can be made.
 */
function requestProfile(serviceParams) {
  return {
    type: 'REQUEST_PROFILE',
    serviceParams: serviceParams,
  };
}
```

## Asynchronous Actions

You can tell an action is asynchronous if it returns another function. Usually, asynchronous actions consist of several synchronous actions chained together. Specifically, an action to describe the start of an asynchronous action, and one to describe the end at least.

The function that is returned by an asynchronous action takes one parameter: `dispatch` which allows you to dispatch actions from within that action. It also conventionally returns a `Promise` that, when it resolves, calls the synchronous action that describes the end of the asynchronous action.

```js
/**
 * Describes a dispatched FETCH_PROFILE action.
 *
 * @param  {Object} connector     The Object that handles the web service call.
 * @param  {Object} serviceParams The parameters that will be used to make the web service call.
 * @return {Function}             A function that handles dispatching all the actions that this
 *   asynchronous action is composed of.
 */
function fetchProfile( serviceParams) {
  return function(dispatch) {
    dispatch(requestProfile(serviceParams));

    var requestParams = serviceParams.requestParams;
    var  = serviceParams. || undefined;

    return connector.getProfile(requestParams, )
      .then(function(res) {
        dispatch(receiveProfile(res));
      }).catch(function(err) {
        throw new Error('Error: Could not fetch Profile\n', err.stack);
      });
  };
}
```

If you want you can also chain asynchronous actions together by returning a function that returns the result of another asynchronous action.

```js
/**
 * Describes a dispatched INVALIDATE_PROFILE action.
 * @param  {Object} connector   The Object that handles the web service call.
 * @param  {Object} fetchParams The parameters that will be used by the dispatched `fetchProfile`
 *   action.
 * @return {Function}           A function that handles dispatching all the actions that this
 *   asynchronous action is composed of.
 */
function invalidateProfile( fetchParams) {
  return function(dispatch) {
    dispatch({ type: 'INVALIDATE_PROFILE' });

    /**
     * Notice that I'm passing in `dispatch` to the result of the `fetchProfile` call so that I can
     * get result of the function that `fetchProfile` returns.
     */
    return fetchProfile( fetchParams)(dispatch);
  };
}
```

#### Examples

The example code for this file was from the [ProfileActions.js file](./ProfileActions.js) that is contained in this directory.