\n\n## Table of contents \n\n1. [Lexicon](#lexicon)\n2. [How to use](#how-to-use)\n 1. [Create cup](#create-cup)\n 2. [Read cup's tea](#read-cups-tea)\n 3. [Update cup's tea](#update-cups-tea)\n 4. [Flavoring](#flavoring)\n 1. [Simple flavors](#simple-flavors)\n 2. [Transformations](#transformations)\n 3. [Adding flavors based on the previous flavors](#adding-flavors-based-on-the-previous-flavors)\n 5. [Cup's waiters](#cups-waiters)\n 1. [Calling a waiter](#calling-a-waiter)\n 2. [Firing a waiter](#firing-a-waiter)\n 6. [Derived cup](#derived-cup)\n\n## Lexicon\n\n`Manatea` uses weird and funny names because this project is mostly for fun. And also we can do whatever we want with it.\n\nHere is the reason behind all our names:\n\n> First you `order a cup` of `tea` filled with your `first tea`. Then you can place a new `order` and the `waiter` will `refill` your `cup` with a new tea.\\\n> Depending on whether or not the tea suits you, you can add flavor to it with a `flavoring`.\n\nBut as those can be confusing, he is an equivalent to all our names in more usual words:\n\n| In `manatea` | More generic names | Explanation |\n| --------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `orderCup` | create atom (store) | Create an object that can contain a value, gives access to read or modify this value, and provides a way to add listeners that will get called when the value changes. |\n| `flavoredTea` | value | Value stored within the _cup_ |\n| `firstTea` | initial value | Value present within the _cup_ when it was first created |\n| `Order` | value setter | When the _cup_ needs to be updated, we can either provide a new value, or a function that will give access to the current value in order to compute the new one. |\n| `unflavoredTea` | new value | New value provided to the _cup_ that will be used as the new internal value (after going through the `flavoring` phase). Either the value of the _order_, or its returned value if it was a function. |\n| `flavoring` | transformer | When a _unflavoredTea_ (dirty value) is passed to the _cup_, you may want to restrict it to a range of allowed values. The _flavoring_ can transform this provided _unflavoredTea_ to a _flavoredTea_ one (a clean value). |\n| `waiter` | listener | When the internal _tea_ changes, _waiters_ will get called with the new value. |\n\n## How to use\n\n### Create cup\n\n```js\nimport { orderCup } from 'manatea';\n\n// Define (order) a cup with a default value (tea) of 0\nconst cup = orderCup(0);\n```\n\n### Read cup's tea\n\n```js\n// Return current value (tea) of the cup\ncup(); // 0;\n```\n\n### Update cup's tea\n\n```js\n// Set value (tea) to 1\ncup(1);\n\n// increment the stored value (tea) by 1\ncup(tea => tea + 1);\n\n// Supports async functions\n// wait 1 second and then increment the tea by 5\ncup(async tea => {\n await sleep(1);\n return tea + 5;\n});\n\n// You can also read from cup to set another cup's value\ncup(tea => {\n const otherTea = otherCup();\n return tea + otherTea;\n});\n```\n\nEvery update made to a cup returns a promise:\n\n```js\n// wait for the value to be stored and dispatched\nawait cup(1);\n\n// you can also use the regular .then() method\ncup(tea => tea + 1).then(tea => console.log(tea));\n```\n\n### Flavoring\n\n#### Simple flavors\n\nWhen a new unflavored tea is passed to the cup, you may want to apply restrictions to it.\n\nFor instance, if your `flavoredTea` is a number, you may want to set bounds to it:\n\n```js\nconst cup = createCup(0, unflavoredTea =>\n Math.min(10, Math.max(0, unflavoredTea)),\n);\n\ncup(12);\n\n// clamp to 10 as we set an upper bound to 10 above\ncup(); // 10\n```\n\n#### Transformations\n\nIn addition simple restrictions that have the same type as the flavored tea, you can fully transform it:\n\n```ts\ninterface FlavoredTea {\n value: number;\n label: string;\n}\n\nconst cup = createCup(0, unflavored => {\n return {\n value: unflavored,\n label: `Value of: ${unflavored}`,\n };\n});\n\n// even the initialTea will get flavored\ncup(); // { value: 0, label: 'Value of: 0' }\n\ncup(5);\n\n// even the initialTea will get flavored\ncup(); // { value: 5, label: 'Value of: 5' }\n```\n\n#### Adding flavors based on the previous flavors\n\nThe `flavoring` function have a second parameters (not passed for the `initialTea`) that give to you the previously `flavoredTea`:\n\n```js\nconst cup = createCup(\n 0,\n (unflavored, previouslyFlavoredTea = 0) => unflavored + previouslyFlavoredTea,\n);\n\ncup(); // 0\n\ncup(2);\ncup(); // 2 – because 2 + 0 = 2\n\ncup(5);\ncup(); // 7 – because 5 + 2 = 7\n```\n\n### Cup's waiters\n\nFrom any cup, you can call waiters that will alert you when the tea stored in the cup changes (they are like event listeners).\n\n#### Calling a waiter\n\n```js\n// Call the waiter\nconst waiter = cup.on(tea => console.log(tea));\n```\n\n#### Firing a waiter\n\nYou can fire a waiter (stop the listener) by calling it:\n\n```js\nconst waiter = cup.on(console.log);\n// here the waiter will be called on each update of the cup\n\n// but by calling `waiter()`, it won't receive any update anymore\nwaiter();\n```\n\n### Derived cup\n\nYou can create a cup based on another one, or multiple other ones:\n\n```js\nconst cup1 = orderCup(0);\nconst cup2 = orderCup(0);\nconst derivedCup = orderCup(sip => sip(cup1) + sip(cup2));\n\nderivedCup(); // 0\n\nawait cup1(1);\nawait cup1(4);\nderivedCup(); // 5\n```\n\nAnd it supports the same feature are regular cup:\n\n- flavoring\n- waiters\n- it's tea can be updated\n\n```js\nconst countString = orderCup('0');\nconst cumulatedCountNumber = orderCup(\n sip => sip(countString),\n (newValue, previousTotal = 0) => {\n return Number(newValue) + previousTotal;\n },\n);\n\ncumulatedCountNumber.on(newTotal => console.log(newTotal));\nawait countString('5');\ncumulatedCountNumber(); // 5 (0 + 5)\n\n// you can also call `cumulatedCountNumber` directly if you want:\nawait cumulatedCountNumber('12');\n\ncumulatedCountNumber(); // 17 (5 + 12)\n```\n","readmeFilename":"README.md","description":"Predictable micro state manager."}
![\"Manatea\"](\"https://raw.githubusercontent.com/Ayc0/Manatea/ocean/docs/manatea-emoji.png\")
\n