\n\nIn this example we use the data API like the this.setState API, note that this example will persist over reloads and application crashes due to the persistor. You would probably not make a [controlled input](https://reactjs.org/docs/forms.html#controlled-components), using this library instead of setState, in most cases - this is just for the example.\n\n * [no hooks](./examples/simple)\n * [hooks](./examples/simplehooks)\n\n
\n\n\n\n| Property | Default | Description \n| --- | --- | ---\n| `setDebugWithCurlirize` | `false` | Will print all network out as curl commands\n| `networkExceptionCallback` | `(err) => {}` | Is called for any exceptions that occur in axios, *application order* can be seen [here](#network-request-flow)\n| `globalResponseIntercept` | `(obj) => {}` | Is called for all network responses with the obj formatted like this:
{
` type`: 'error' or 'success',
` insertData`: 'data after relevant formatters are applied',
` responseData`: 'the original network response data' or 'exception object if responseStatusCode is -1',
` responseStatusCode:` 'response status code' or '-1 if an exception',
` responseHeaders`: 'response headers' or 'empty object if an exception',
}
*application order* can be seen [here](#network-request-flow)\n| `globalErrorFormatter` | `(data) => data` | This is called for any error condition, see order [here](#network-request-flow), and should return any data format you want to use in subsequent items, this is useful because often you want to format your error data from an API in a specific, and global way.\n| `additionalReducers` | `[]` | Should contain any additional reducers that you want to include in the state, you can fire actions that will be picked up by these in any connected component.\n| `networkTestAction` | `{}` | If specified as some `NetworkActions.start***` action, this will be used to test for network connectivity changes once a downtime event is triggered. I.e.
`networkTestAction={NetworkActions.startGET({url: 'https://some-test-url'})}`.
All network connections that fail, with this specified, will be queued up if they have `autoRetryOnNetworkReconnection` set to true on their individual config and then will be actioned when this network request succeeds\n| `networkTestDelay` | `10000` | This is the delay between uptime checks on the `networkTestAction`\n| `persistorStorageOverride` | `null` | Provide an alternative storage method for the persistor, see more [here](#a-note-for-react-native)\n| `defaultContentTypes`| `defaultContentTypesObject` | For each type of request, this object specifies the default value for the `Content-Type` header. This value can and will be overwritten by other headers, see header order of priority [here](#header-order-priority). See below this table for the default values, null set for any method will not apply any value to `Content-Type`\n\n`defaultContentTypesObject` default value\n\n```\n{\n get: null,\n post: 'application/json',\n patch: 'application/json',\n delete: 'application/json',\n head: null,\n options: null,\n put: 'application/json',\n}\n```\n\n
\n\nYou can access methods on the ReduxWrapper like this:\n\n```\n
\n\n`DataActions.setData(location, data, keys = null)`\n\nOverrides any element at the current location with the data specified. See keys note below for description.\n\n
\n\n\n`DataActions.mergeData(location, data, keys = null)`\n\nUses `Object.assign({}, currentStateAtLocation, data)` to mutate the state\n\n
\n\n\n`DataActions.concatFirstData(location, data)`\n\nUses `locationState = data.concat(currentStateAtLocation);` to add the existing state (assuming it is an array) to the end of the data you are inserting, if the `data` value is not an array it will be converted to an array prior to concatenation.\n\n
\n\n\n`DataActions.concatLastData(location, data)`\n\nUses `locationState = currentStateAtLocation.concat(data);` to add your data to the end of the array at the location, if the data at the location is not an array, it will be overwritten with a blank array.\n\n
\n\n\nThe `keys` parameter is useful for putting array data with some unique ID into the global state so it can be referenced - the keyExtractor parameter in network requests is used to generate the `keys` array.\n\nIf the `keys` parameter is specified, it must be an array, and the `data` must be an array with the same length as keys.\n\nThe data in `data` is 'spread' onto the `location` with the keys as values - an example:\n\n```\nconst data = [{one: true}, {two: true}, {three: true}];\nconst keys = ['a', 'b', 'c'];\nconst location = 'some.location';\n\nsetData(location, data, keys);\n\n// the modified state would now have this value:\n\n{\n some: {\n location: {\n a: {one: true},\n b: {two: true},\n c: {three: true},\n }\n }\n}\n\n```\n\nin contrast, not using a keys array gives this behaviour:\n\n```\nconst data = [{one: true}, {two: true}, {three: true}];\nconst location = 'some.location';\n\nsetData(location, data);\n\n// the modified state would now have this value:\n\n{\n some: {\n location: [\n {one: true}, \n {two: true}, \n {three: true}\n ]\n }\n}\n```\n\n
\n\n\n`DataActions.unsetData(location)`\n\nRemoves data at a specific location from the state.\n\n
\n\n\n`DataActions.unsetKeysAtLocation(location, keys)`\n\nRemoves any keys in the keys array at the location.\n\n
\n\n\n`DataActions.clearWithIgnoreList(ignores)`\n\nRemoves everything from the state, while ignoring any keys in 'ignores'\n\nThis would remove all keys on the global data store except `userObject` and `applicationVersion`\n\n```\nDataActions.clearWithIgnoreList(['userObject', 'applicationVersion'])\n```\n\n
\n\n\n`DataActions.clearAllData()`\n\nRestores the state back to how it was when initialised. Useful for logout type events.\n\n
\n\n\n`DataSelectors.makeGetData(cacheName = null)`\n\nreturns a function with the signature\n\n* `(state, location, emptyReturnValue = {})`\n\nThe optional `cacheName` value instructs the selector to cache the returned function, and additional calls to makeGetData with the same cacheName value will return the same function, make sure that when doing this, the resulting function call also has the same location: **as a tip** use the location as the cacheName.\n\nThis returns a function that can be used to select data like this:\n\n```\nconst makeMapStateToProps = () => {\n const getData = DataSelectors.makeGetData();\n\n function mapStateToProps(state) {\n return {\n _alertsCounter: getData(state, 'user.alerts.counter', 0),\n };\n }\n\n return mapStateToProps;\n};\n```\n\nWhich will return the data in user.alerts.counter, or 0 if it does not exist.\n\nIt will appear on the component like this:\n\n```\nconsole.log(this.props.alertsCounter); // reads 0 if not defined, something else if it is \n```\n\n
\n\n\n`DataSelectors.getData()`\n\n\n```\nfunction mapStateToProps(state) {\n return {\n alertsCounter: DataSelectors.getData(state, 'user.alerts.counter', 0),\n };\n}\n```\n\nWhich will return the data in user.alerts.counter, or 0 if it does not exist.\n\nIt will appear on the component like this:\n\n```\nconsole.log(this.props.alertsCounter); // reads 0 if not defined, something else if it is \n```\n\n
\n\n\n`DataSelectors.makeGetDataMulti()`\n\nreturns a function with the signature\n\n* `(state, inputLocations)`\n\nwhere inputLocations is an array of object like this:\n\n```\n{\n name:
\n\n`DataSelectors.getDataMulti(state, inputLocations)`\n\nwhere inputLocations is an array of object like this:\n\n```\n{\n name:
\n\n * `NetworkActions.startGET(requestConfig)` \n * `NetworkActions.startPOST(requestConfig)` \n * `NetworkActions.startPATCH(requestConfig)`\n * `NetworkActions.startDELETE(requestConfig)`\n * `NetworkActions.startHEAD(requestConfig)`\n * `NetworkActions.startOPTIONS(requestConfig)`\n * `NetworkActions.startPUT(requestConfig)`\n\nThe `requestConfig` object has these parameters:\n\n**The request data**\n\n| Value | Required | Default | Description \n| --- | --- | --- | --- \n| `url` | `true` | `null` | This is the fully qualified domain name for the request\n| `data` | `false` | `{}` | The request data, ignored for GET requests\n| `multi` | `false` | `false` | if this is true, there can be more than 1 request for the same identifier, see `multiIdentifier`\n| `additionalHeaders` | `false` | `[]` | array of additional headers in the format of `{ name: 'header-name', value: 'header-value' }` to be added on, these are applied LAST so can override global headers\n\n\n**Where to put the response**\n\n| Value | Required | Default | Description \n| --- | --- | --- | --- \n| `responseTarget` | `false` | `null` | [see location documentation](#locations) - a string like `location.other.place` to target in the global data or null to not put it into the global data, use the `successFormatHandler` and `keyExtractor` to decide the format of what ends up here\n| `responseTargetMethod` | `false` | `set` | decides how to handle placement of the data onto the `responseTarget`, `merge` will shallow merge the object, `set` will just set it, `concatFirst` and `concatLast` will perform an array concatenation (start of end of the existing array) - note the concat values do not work with a value set on `keyExtractor` - the extractor will be ignored\n\n\n**How to listen to the status of the network request**\n\n| Value | Required | Default | Description \n| --- | --- | --- | --- \n| `identifier` | `false` | `null` | Identifier used to monitor the status of this request if you don't need to hook into the response at all set this to null, check out the [selectors section](#selectors-networkselectors) for more info\n| `multiIdentifier` | `false` | `null` | If this is not null, it will be used as a sub identifier (see selectors to understand how it is used), if null and multi is set to true, uuid will be generated, check out the [selectors section](#selectors-networkselectors) for more info\n| `dumpSuccessResponseToNetworkState` | `false` | `false` | if this is set to true, the data will be put onto the network state (specified by `identifier/multiIdentifier`). Setting this to true will not stop anything that happened with responseTarget and its chain of actions.\n\n\n**Lifecyle hooks**\n\n*application order* can be seen [here](#network-request-flow)\n\n| Value | Required | Default | Description \n| --- | --- | --- | --- \n| `successFormatHandler(data, statusCode, existingData, responseHeaders) => data` | `false` | `null` | a function that is called with any 200 <> 299 status code, can return an array of objects to be dumped into the `responseTarget` - the `keyExtractor` will be called to distribute them properly, if this does not return an array, it will not call the `keyExtractor` at all and just dump onto the `responseTarget`, if the `keyExtractor` is null, the response will just be dumped onto the `responseTarget` - `existingData` is NULL if no `responseTarget` specified, or is the current data in the store at that target\n| `errorFormatHandler(data, statusCode, err, responseHeaders) => { return data; }` | `false` | `null` | a function that is called with any other status code not captured by the success handler, whatever is returned by this function is returned as the data attribute when there is an error, note it is possible for this function to receive an exception (Error) type as well as an actual response, the statusCode will be -1 if this is the case with the error as the third argument, and the error.toString() value as the data\n| `successCallback(formattedData, originalData, statusCode, responseHeaders) => {}` | `false` | `null` | a function that is called with any 200 <> 299 status code after the sucessFormatHandler in case you need to do any side effects as a result of a success condition\n| `errorCallback(formattedData, originalData, statusCode, responseHeaders) => {}` | `false` | `null` | called when there is an error, inverse of `successCallback`\n| `preDataInsertCleanupHandler(existingData, modifiedKeys, networkState, responseHeaders) => {}` | `false` | `null` | this function is called right before successFormatHandler and the insert action for response target which can be used to remove / clean up old state changes\n| `keyExtractor(item, index) => 'key'` | `false` | `null` | this is called for every element returned by the `successFormatHandler` and should return a key that will be used to allocate the data to the `responseTarget.[key]` location. if it is null then it will not be used and the data will be just dumped onto the object, this will not be called if the data returned from `successFormatHandler` is not an array\n| `setGlobalHeaders(formattedData, originalData, statusCode) => {}` | `false` | `null` | This is called before the success format handler with the same conditions as success format handler (200 <> 299 status) - any thing return by this needs to be an array of `{ name: 'header-name', value: 'header-value' }` and will update the global headers so every subsequent request has this set of headers, useful for authentication. If it does not return an array then nothing happens.\n\n\n**Retrying, timeouts and multiple similar requests**\n\n| Value | Required | Default | Description \n| --- | --- | --- | --- \n| `autoRetryOnNetworkReconnection` | `false` | `false` | If autoRetryOnNetworkReconnection is true, we will retry this network request if it fails due to network connectivity once connectivity is re-established, tested with `networkTestAction` set on the `ReduxWrapper`. Make sure `networkTestAction` is specified or these network connections will not be retried.\n| `timeout` | `false` | `-1` | Once this many seconds have gone by, the network state will be set to EXPIRED, negative numbers are ignored entirely\n| `cancelInFlightWithSameIdentifiers` | `false` | `true` | If this is set to true, then we match against some identifier/multiIdentifier combo - if they are the same, any in flight request is cancelled and replaced with the new one.\n\n\n\n
\n\n\n`NetworkActions.clearNetworkData(identifier)`\n\nThis will clear all the network response data for a given identifier, regardless of if it is single or multi\n\n
\n\n\n`NetworkActions.clearAllNetworkData()`\n\nThis completely clears everything in the network state, setting the whole thing to default, including all headers and anything else.\n\n
\n\n\n`NetworkActions.setGlobalHeaders(headers)`\n\nYou can call this to set a global header, see how global headers are applied [here](#header-order-priority). \n\nFormat for `headers` parameter is\n\n```\n[\n {name: 'Content-Type', value :'application/json'}\n ....\n]\n```\n\nAny headers in the state with the same name will be overwritten.\n\n
\n\n\n\nThe object takes this form: \n\n```\n{\n state: NetworkStates.NOT_STARTED || NetworkStates.LOADING || NetworkStates.RELOADING || || NetworkStates.ERROR || NetworkStates.SUCCESS || NetworkStates.EXPIRED,\n statusCode: null ||
\n\nNetwork requests have a set of 'states' associated with them - you can compare the current state of a network request to the `NetworkStates` object\n\n```\nimport { NetworkStates } from 'react-redux-with-networking-helper';\n\nconsole.log(NetworkState);\n\n{\n NOT_STARTED: 'not-started', // not started - note this will never be seen for multi requests\n LOADING: 'loading', // we are loading something (for the first time)\n RELOADING: 'reloading', // we are 're' loading something\n ERROR: 'error', // there was an error\n SUCCESS: 'success', // there was success\n EXPIRED: 'timed-out', // a request has been expired because of the requestConfig.timeout value\n}\n```\n\n
\n\n\n`NetworkSelectors.makeGetNetworkData()`\n\nReturns a function with the signature\n\n* `(state, identifier)`\n\nWhere identifier matches whatever you used in the initial request config.\n\nThe usage is like this:\n\n```\nconst makeMapStateToProps = () => {\n const getNetworkData = NetworkSelectors.makeGetNetworkData();\n\n function mapStateToProps(state) {\n return {\n _networkData: getNetworkData(state, 'user-settings'),\n };\n }\n\n return mapStateToProps;\n};\n```\n\nWhich returns data in this format onto the `_networkData` property, details of which can be found [here](#network-response-object)\n\n\n
\n\n\n`NetworkSelectors.getNetworkData(state, identifier)`\n\nWhere identifier matches whatever you used in the initial request config.\n\nThe usage is like this:\n\n```\nfunction mapStateToProps(state) {\n return {\n _networkData: NetworkSelectors.getNetworkData(state, 'user-settings'),\n };\n}\n\nreturn mapStateToProps;\n```\n\nWhich returns data in this format onto the `_networkData` property, details of which can be found [here](#network-response-object)\n\n
\n\n\n`DataSelectors.makeGetNetworkDataMulti()`\n\nReturns a function with the signature\n\n* `(state, identifier)`\n\nWhere identifier matches whatever you used in the initial request config.\n\nThe usage is like this:\n\n```\nconst makeMapStateToProps = () => {\n const getNetworkDataMulti = NetworkSelectors.makeGetNetworkDataMulti();\n\n function mapStateToProps(state) {\n return {\n _networkData: getNetworkDataMulti(state, 'user-settings'),\n };\n }\n\n return mapStateToProps;\n};\n```\n\nWhich returns data in this format onto the `_networkData` property, details of which can be found [here](#network-response-object)\n\n
\n\n\n`DataSelectors.getNetworkDataMulti(state, identifier)`\n\nWhere identifier matches whatever you used in the initial request config.\n\nThe usage is like this:\n\n```\nfunction mapStateToProps(state) {\n return {\n _networkData: NetworkSelectors.getNetworkDataMulti(state, 'user-settings'),\n };\n}\n\nreturn mapStateToProps;\n```\n\nWhich returns data in this format onto the `_networkData` property, details of which can be found [here](#network-response-object)\n\n
\n\n\nYou can specify your own actions and reducers by passing in the appropriate reducers to the `additionalReducers` prop on the `ReduxWrapper` component. Once you have specified them, you can call dispatch whatever actions they respond to from any connected component.\n\n
\n\n\nTODO - not supported yet\n\n
\n