Improvements to consistency (#152)

* lint fix

* improve docs

* minor improvement to types

* rationalise manage-resource-state into a smaller number of api functions with clear abstraction

* consistent API for all actions of resource and context arguments

* more precise variable names for slices

* clearly demarcate private and public actions and stub public action dependencies

* minor fix to test label for consistency

* ensure resource slice always represents correct future state, docs, tests

* reinstate async function

Author: bholloway

docs/api/hooks.md

@@ -35,17 +35,24 @@ export const Feed = () => {
 
 As well as returning actions that act on the resource (i.e. update and refresh), `useResource` returns four different properties that indicate the state of the resource. These four are `data`, `loading`, `error` and `promise`. `useResource` will return different combinations of these four properties depending on the state of the resource. The table below shows all the possible combinations.
 
-|           state           |    data    | loading |     error     | promise |
-| :-----------------------: | :--------: | :-----: | :-----------: | :-----: |
-|           idle            |    null    |  false  |     null      |  null   |
-|          loading          | null or {} |  true   | null or Error | Promise |
-| loading after ssr timeout |    null    |  true   | TimeoutError  |  null   |
-|     fetch successful      |     {}     |  false  |     null      | Promise |
-|        fetch error        | null or {} |  false  |     Error     | Promise |
-
-It is important to note that loading can be true even when there is an error. In that case, promise will be null because there is no Suspense support on the server. Developers should give priority to loading when deciding between loading or error states for their components. Promises/errors should only ever be thrown on the client
-
-It also acceps some options as second argument to customise the behaviour, like `routerContext`.
+|       state        |   data   | loading |    error     |              promise              |
+| :----------------: | :------: | :-----: | :----------: | :-------------------------------: |
+|      initial       |   null   |  false  |     null     |               null                |
+|  data (from SSR)   |    {}    |  false  |     null     |     Promise (resolves `data`)     |
+| timeout (from SSR) |   null   |  true   | TimeoutError |               null                |
+|   async loading    | _-prev-_ |  true   |   _-prev-_   |         Promise (pending)         |
+|  async successful  |    {}    |  false  |     null     |     Promise (resolves `data`)     |
+|    async error     | _-prev-_ |  false  |    Error     |     Promise (rejects `error`)     |
+|      cleared       |   null   |  false  |     null     |               null                |
+|     updated {}     |    {}    |  false  |     null     | Promise (resolves updated `data`) |
+
+Where `-prev-` indicates the field will remain unchanged from any previous state, possibly the inital state.
+
+It is important to note 
+* The timeout state is essentially a hung loading state, with the difference that `promise = null` and `error != null`. Developers should give priority to `loading` when deciding between loading or error states for their components. Promises/errors should only ever be thrown on the client.
+* The `promise` reflects the last operation, either async or explicit update. Update will clear `error`, set `data`. It will also set a `promise` consistent with that `data` so long as no async is `loading`. When `loading` the `promise` will always reflect the future `data` or `error` from the pending async. 
+
+Additionaly `useResource` accepts additional arguments to customise behaviour, like `routerContext`.
 Check out [this section](../resources/usage.md) for more details on how to use the `useResource` hook.
 
 ## useRouter