# @focuson/poster > This allows for declarative 'posting' Latest version **1.44.3** (published 2024-02-23) · MIT license · 0 weekly downloads ## Install ```sh npm install @focuson/poster pnpm add @focuson/poster yarn add @focuson/poster bun add @focuson/poster ``` ## Health **Score 25/100 (F)** — status: abandoned. Positive: has types; no vulnerabilities; high quality score. Warnings: low downloads; no esm support. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 1.44.3 | | Published | 2024-02-23 | | First published | 2022-01-16 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | CommonJS | | Dependencies | 3 | | Unpacked size | 13.2 KB | | Known vulnerabilities | 0 | | Install scripts | no | | Maintainers | phil-rice | | Keywords | runbook | ## Links - npm: https://www.npmjs.com/package/@focuson/poster - npm.io page: https://npm.io/package/@focuson/poster ## Dependencies (3) - [debug](https://npm.io/package/debug.md) ^4.3.4 - [@focuson/lens](https://npm.io/package/@focuson/lens.md) 1.44.3 - [@focuson/fetcher](https://npm.io/package/@focuson/fetcher.md) 1.44.3 ## Recent versions - 1.44.3 (latest) — 2024-02-23 - 1.44.2 — 2024-02-23 - 1.44.1 — 2022-12-09 - 1.44.0 — 2022-12-09 - 1.43.49 — 2022-12-08 - 1.43.48 — 2022-12-06 - 1.43.47 — 2022-12-06 - 1.43.46 — 2022-12-06 - 1.43.45 — 2022-12-06 - 1.43.44 — 2022-12-05 - 1.43.43 — 2022-12-05 - 1.43.42 — 2022-12-02 - 1.43.41 — 2022-12-02 - 1.43.40 — 2022-12-01 - 1.43.39 — 2022-12-01 - … 522 more at https://npm.io/package/@focuson/poster/versions ## README @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 --- _Source: https://npm.io/package/@focuson/poster · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._