@focuson/poster is a project to help with 'post' commands in react applications.

Many react applications can be split up as follows:

* Getting data from an api to display it
* Rendering the data
* Editing the data
* Doing things with the data (checkout / payment )

This project addresses the last goal. It provides a declarative mechanism, that is very easy to test, that controls when
data is sent to the backend. i.e. the 'doing things'.

Post Commands

The react application communicates with the 'poster' only through state. In the state there is a place that has an array
of post commands. The exact place is configurable using a lens. Typically there will be only one post command.

The post command has the signature

``typescript
interface PostCommand, K extends keyof Details> {
poster: K,
args: any
}
`

That's complicated until it is realised that K is just a 'legal post name'. The list of legal post names is in the
PostDetails (see below).

An example that represents a single call to 'updateAccountDetails' could be

`json lines
{postCommands: [{poster: "updateAccountDetails", args: {id: 12335, accountDetails: {some: "accountDetails"}}}]}
`

Note how easy it is now to test the react components. The 'event' that would normally do the side effect, instead just
updates the state. This is very easy to test without complex mocks, containers or an acceptance environment

From a mental concept point of view this is very similar to 'dispatching' in redux. The only difference is that instead of
'calling dispatch' (which causes an immediate side effect) this simply writes to the state the parameters that would be sent
to the dipatcher.

Life cycle

* The post method is called
* For each post command
* the fetch parameters are calculated
* fetch is called. this returns a status and body
* If the status is a 2xx,
* the body is 'shaped' (i.e. turned into a format suitable to go into the state)
* and added at the location defined by the targetLens (typically this will result in a message, but could hold concrete data that is needed)
* If the status isn't 2xx
* The errorFn is called and added to the status (typically this will result in an error message)

PostDetails

`typescript
export interface Posters {
[name: string]: PostDetails
}
export interface PostDetails {
urlFn: (args: Args) => [RequestInfo, RequestInit | undefined],
shaper: (r: Returned) => Result,
errorFn: ErrorFn,
targetLn: Optional
}
`
* urlFn the arguments come from PostCommand (i.e. typically the react component that triggers this)
* shaper turns the Returned value from the api into Result. This is needed because quite often the values returned from the API need to be turned into a message or reshaped
* errorFn what to do if there is an error (either a failed promise, or a non 200 status code)
* targetLn Where to put the returned result

Example

`typescript
interface UpdateAccountDetails {
//here we have the type of the data that will be sent to the api
}
interface UpdateAccountResult{
//This is the type that is returned from the api. It might be empty, or it might has a message like 'succeeded'
}
//This is the actual configuration of the poster for updateAccountDetails
const updateAccountDetails = (targetLens: Optional): PostDetails => ({
urlFn: (accountId: string) => [/someapi/updateAccount/${accountId}, { method: 'post' }],
errorFn: addDebugErrorMessage(errorLens),
shape: s => s,
targetLens
})
`
In this example the data from the API was directly inserted into the state because of shape: s => s. Other options include setting a string such as 'succeeded'

Posters

This is were we 'tie it all together'. All the posters in the application are added here, giving each action a unique name. The is the type of
the global state

`typescript
const allPosters : Posters = {
updateAccountDetails: updateAccountDetails
}
`
At this point updateAccountDetails (the key) can be used in a post command with some arguments

Using the Poster

Given a state MainState with postCommands in it somewhere (postCommand points to them) the following updates the state with the results of the post commands

`typescript
const poster = post>(fetchFn, postDetails, postCommandsL, postDebugL)
`
* fetchFn delegates to fetch
* postDetails is the structure shown above that links the names of post commands to the details of how to implement them
* postCommandsL is a lens from the MainState to the list of post commands
* postDebugL is an optional lens from the MainState` to a place where the postDebug data structure can be find. This turns on and off console.log messages about the posting