GitBook: [v28] 44 pages modified

Author: christianalfoni

README.md

@@ -4,9 +4,11 @@ description: frictionless state management
 
 # Overmind
 
-> Web application development is about **defining**, **changing** and **consuming state** to produce a user experience. Overmind aims for a developer experience where that is all you focus on, reducing the orchestration of state management to a minimum. Making you a **happier** and more **productive** developer!
+[![GitHub stars](https://img.shields.io/github/stars/cerebral/overmind.svg?style=social&label=Star&maxAge=2592000)](https://github.com/cerebral/overmind/stargazers/)
 
-{% embed url="https://overmindjs.changefeed.app/general/v26" caption="" %}
+> Web application development is about **defining**, **changing** and **consuming state** to produce a user experience. Overmind aims for a developer experience where that is all you focus on, reducing the orchestration of state management to a minimum. Making you a **happier** and more **productive** developer
+
+{% embed url="https://overmindjs.changefeed.app/general/v28" %}
 
 ## APPLICATION INSIGHT
 
@@ -57,7 +59,7 @@ export const loadApp = ({ state, effects }) => {
 
 ## SAFE AND PREDICTABLE CHANGES
 
-When you build applications that perform many state changes things can get out of hand. In Overmind you can only perform state changes from **actions** and all changes are tracked by the development tool. Even effects are tracked and reactions are tracked.
+When you build applications that perform many state changes things can get out of hand. In Overmind you can only perform state changes from **actions** and all changes are tracked by the development tool. Even effects and reactions are tracked.
 
 ```javascript
 export const getItems = async ({ state, effects }) => {
@@ -69,37 +71,34 @@ export const getItems = async ({ state, effects }) => {
 
 ## COMPLEXITY TOOLS
 
-Even though Overmind can create applications with plain **state** and **actions**, you can use **opt-in** tools like **functional operators**,**, statemachines** and state values defined as a **class,** to manage complexities of your application.
+Even though Overmind can create applications with plain **state** and **actions**, you can use **opt-in** tools like **functional operators**, **statemachines** and state values defined as a **class,** to manage complexities of your application.
 
 {% tabs %}
 {% tab title="Operators" %}
 ```javascript
 export const search = pipe(
-  mutate(({ state }, query) => {
+  ({ state }, query) => {
     state.query = query
-  }),
+  },
   filter((_, query) => query.length > 2),
   debounce(200),
-  mutate(async ({ state, effects }, query) => {
+  async ({ state, effects }, query) => {
     state.isSearching = true
     state.searchResult = await effects.getSearchResult(query)
     state.isSearching = false
-  })
+  }
 )
 ```
 {% endtab %}
 
 {% tab title="Statemachines" %}
 ```typescript
 export const state = statemachine({
-  unauthenticated: ['authenticating'],
-  authenticating: ['unauthenticated', 'authenticated'],
-  authenticated: ['unauthenticating'],
-  unauthenticating: ['unauthenticated', 'authenticated']
-}, {
-  state: 'unauthenticated',
-  user: null,
-  error: null
+  SIGN_IN: (state) => {
+    if (state.current === 'UNAUTHENTICATED') {
+      return { current: 'AUTHENTICATING' }
+    }
+  }
 })
 ```
 {% endtab %}

addons/graphql.md

@@ -31,6 +31,7 @@ export const config = {
 
 {% tab title="overmind/state.js" %}
 ```typescript
+
 export const state = {
   posts: []
 }
@@ -182,7 +183,7 @@ export const getPosts = async ({ state, effects, actions }) => {
   const { posts } = await effects.gql.queries.posts()
 
   state.posts = posts
-
+  
   effects.gql.subscriptions.onPostAdded(actions.onPostAdded)
 }
 
@@ -235,7 +236,7 @@ export const addPost = async ({ state, effects }, title) => {
 
 There are two points of options in the Graphql factory. The **headers** and the **options**.
 
-The headers option is a function which receives the state of the application. That means you can produce request headers dynamically. This can be useful related to authentciation.
+The headers option is a function that runs on every request, meaning you can dynamically change the headers based on the state of the application.
 
 {% tabs %}
 {% tab title="overmind/onInitialize.js" %}

api-1/createovermindmock.md

@@ -48,3 +48,26 @@ describe('Actions', () => {
 It is important that you separate your **config** from the instantiation of Overmind, meaning that **createOvermind** should not be used in the same file as the config you see imported here, it should rather be used where you render your application. This allows the config to be used for multiple purposes.
 {% endhint %}
 
+## Setting initial state
+
+Pass a function as the second or third argument to set initial state.
+
+{% tabs %}
+{% tab title="overmind/actions.test.js" %}
+```typescript
+import { createOvermindMock } from 'overmind'
+import { config } from './'
+
+describe('State', () => {
+  test('should derive authors of posts', async () => {
+    const overmind = createOvermindMock(config, (state) => {
+      state.posts = { 1: { id: 1, author: 'Janet' } }
+    })
+
+    expect(overmind.state.authors).toEqual(['Janet'])
+  })
+})
+```
+{% endtab %}
+{% endtabs %}
+

api-1/statemachine.md

@@ -2,78 +2,61 @@
 
 A statematchine allows you to wrap state with transitions. That means you can protect your logic from running in invalid states of the application.
 
+Please read the [**statemachine guide**](../guides-1/using-state-machines.md) ****to learn more about statemachines and typing them.
+
 ## Create a statemachine
 
 You define a whole namespace as a statemachine, you can have a nested statemachine or you can even put statemachines inside statemachines.
 
 ```javascript
 import { statemachine } from 'overmind'
 
-export const state = statemachine({
-  UNAUTHENTICATED: ['AUTHENTICATING'],
-  AUTHENTICATING: ['UNAUTHENTICATED', 'AUTHENTICATED'],
-  AUTHENTICATED: ['UNAUTHENTICATED']
-}, {
-  state: 'UNAUTHENTICATED'
+export const machine = statemachine({
+  TOGGLE: (state, payload) => {
+    return { current: state.current === 'FOO' ? 'BAR' : 'FOO' }
+  }
 })
 ```
 
-Instead of only defining state, you first define a set of transitions. The key represents a transition state, here **UNAUTHENTICATED**, **AUTHENTICATING** and **AUTHENTICATED**. Then we define an array which shows the next transition state can occur in the given transition state. When **UNAUTHENTICATED** we can move into the **AUTHENTICATING** state for example. When in **AUTHENTICATING** state we can move either back to **UNAUTHENTICATED** due to an error or we might move to **AUTHENTICATED**. The point is... when you are **UNAUTHENTICATED**, you can not run logic related to being **AUTHENTICATED**. And when **AUTHENTICATING** you can not run that logic again until you are back in **UNAUTHENTICATED**.
+You define a statemachine by setting up the events it should manage. Each even handler decides at what current state it should run its logic. It does this by checking the **current** state. The event handler can optionally return a new state, which transitions the machine.
 
-As actual state values we define the initial transition state of **UNAUTHENTICATED**.
+## Instantiate machine
 
-If we wanted we could extend the state with other values, as normal.
+You instantiate a machine by calinng its **create** method. This takes the initial state and any optional base state the lives across all states of the machine.
 
 ```javascript
-import { statemachine } from 'overmind'
+import { machine } from './myMachine'
 
-export const state = statemachine({
-  UNAUTHENTICATED: ['AUTHENTICATED'],
-  AUTHENTICATING: ['UNAUTHENTICATED', 'AUTHENTICATED'],
-  AUTHENTICATED: ['UNAUTHENTICATED']
-}, {
-  state: 'UNAUTHENTICATED',
-  todos: {},
-  filter: 'all'
-})
+export const state = {
+  myMachine: machine.create({ current: 'FOO' }, { list: [] })
+}
 ```
 
 ## Transition between states
 
-The transition states are also part of the resulting **state** object, in this case:
+You transition the state machine by sending events.
+
+That means you can send **TOGGLE** as an event to the machine. Think of sending events as actually changing the state, but in a controlled way. You can optionally pass a payload with the event.
 
 ```javascript
-// The resulting state object
-export const state = {
-  UNAUTHENTICATED: () => {...},
-  AUTHENTICATING: () => {...},
-  AUTHENTICATED: () => {...},
-  state: 'UNAUTHENTICATED',
-  todos: {},
-  filter: 'all'
+export const toggle = ({ state, effects }) => {
+  state.myMachine.send('TOGGLE', somePayload)
 }
 ```
 
-That means you can call **UNAUTHENTICATED**, **AUTHENTICATING** and **AUTHENTICATED** as functions to transition into the new states. And this is an example of how you would use them:
+## Matching state
+
+In actions you can check what state a machine is in by using the **matches** API.
 
 ```javascript
-export const login = ({ state, effects }) => {
-  return state.AUTHENTICATING(() => {
-    try {
-      const user = await effects.api.login()
-      return state.AUTHENTICATED(() => {
-        state.user = user
-      })
-    } catch (error) {
-      return state.UNAUTHENTICATED(() => {
-        state.error = error
-      })
-    }
-  })
+export const toggle = ({ state, effects }) => {
+  if (state.myMachine.matches('FOO')) {
+    state.myMachine.send('TOGGLE', 'Cool')
+  } else {
+    state.myMachine.send('TOGGLE', 'Not so cool')
+  }
 }
 ```
 
-When a component, or something else, calls the **login** action it will first try to move into the **AUTHENTICATING** state. If this is not possible, nothing else will happen. Then we go ahead an login, which returns a user. If we were to try to set the user immediately an error would be thrown, because it is being set "out of scope of the transition" \(asynchronously\). To actually set the user we first transition to **AUTHENTICATED** and given that is a valid transition the user will be set.
-
-What we accomplish in practice here is to ensure that changes to state is guarded by these transitions, which results in more predictable and safer code.
+You can also directly use `state.myMachine.current` , but please read the guide to understand the different between these two ways of checking.
 

core/defining-state.md

@@ -113,7 +113,7 @@ export const state = {
 The returned value here is indeed a function you call. The cool thing is that the function itself will never change, but whatever state you access when calling the function will be tracked by the caller of the function. So for example if a component uses **getUserById** during rendering it will track what is accessed in the function and continue tracking whatever you access on the returned value.
 
 {% hint style="info" %}
-You may use a derived for all sorts of calculations. But sometimes it's better to just use a plain action to manipulate some state than using a derived. Why? Imagine a table component having a lot of rows and columns. We assume the table component also takes care of sorting and filtering and is capable of adding new rows. Now if you solve the sorting and filtering using a derived the following could happen: User adds a new row but it is not displayed in the list because the derived immediately kicked in and filtered it out. Thats not a good user experience. Also in this case the filtering and sorting is clearly started by a simple user interaction \(setting a filter value, clicking on a column,...\) so why not just start an action which creates the new list of sorted and filtered keys? Also the heavy calculation is now very predictable and doesn't cause performance issues because the derived kickes in too often \(Because it could have many dependencies you might didn't think of\)
+You may use a derived for all sorts of calculations. But sometimes it's better to just use a plain action to manipulate some state than using a derived. Why? Imagine a table component having a lot of rows and columns. We assume the table component also takes care of sorting and filtering and is capable of adding new rows. Now if you solve the sorting and filtering using a derived the following could happen: User adds a new row but it is not displayed in the list because the derived immediately kicked in and filtered it out. Thats not a good user experience. Also in this case the filtering and sorting is clearly started by a simple user interaction \(setting a filter value, clicking on a column,...\) so why not just start an action which creates the new list of sorted and filtered keys? Also the heavy calculation is now very predictable and doesn't cause performance issues because the derived kickes in too often \(Because it could have many dependencies you did not think of\)
 {% endhint %}
 
 ### Class instances
@@ -153,7 +153,7 @@ export const state = {
 {% endtabs %}
 
 {% hint style="warning" %}
-It is import that you do **NOT** use arrow functions on your methods. The reason is that this binds the context of the method to the instance itself, meaning that Overmind is unable to proxy access and track mutations
+It is important that you do **NOT** use arrow functions on your methods. The reason is that this binds the context of the method to the instance itself, meaning that Overmind is unable to proxy access and track mutations
 {% endhint %}
 
 You can now use this instance as normal and of course create new ones.
@@ -197,7 +197,7 @@ The **SERIALIZE** symbol will not be part of the actual serialization done with
 
 #### Rehydrating classes
 
-The [**rehydrate**](../api-1/rehydrate.md) \_\*\*\_utility of Overmind allows you to rehydrate state either by a list of mutations or a state object, like the following:
+The [**rehydrate**](../api-1/rehydrate.md) _\*\*_utility of Overmind allows you to rehydrate state either by a list of mutations or a state object, like the following:
 
 {% tabs %}
 {% tab title="overmind/actions.js" %}
@@ -321,7 +321,7 @@ const state = {
 
 You can not be authenticating and be authenticated at the same time. This kind of logic very often causes bugs in applications. That is why Overmind allows you to define statemachines. It sounds complicated, but is actually very simple.
 
-To properly understand state machines, please read the guide [**Using state machines**](../guides-1/using-state-machines.md).
+To properly understand state machines, please read the guide [**Using state machines**](../guides-1/using-state-machines.md). 
 
 ## References
 

core/devtools.md

@@ -51,7 +51,7 @@ If you are using the **Insiders** version of VSCode the extension will not work.
 When you create your application it will automatically connect through **localhost:3031**, meaning that everything should just work out of the box. If you need to change the port, connect the application over a network \(mobile development\) or similar, you can configure how the application connects:
 
 ```javascript
-import { createOvermind } from 'overmind'
+import { createOvermind } from 'overmind'
 import { config } from './overmind'
 
 const overmind = createOvermind(config, {
@@ -63,7 +63,7 @@ const overmind = createOvermind(config, {
 
 ChromeOS does not expose localhost as normal. That means you need to connect with **penguin.termina.linux.test:3031**, or you can use the following plugin to forward **localhost:**
 
-{% embed url="https://chrome.google.com/webstore/detail/connection-forwarder/ahaijnonphgkgnkbklchdhclailflinn/related?hl=en-US" caption="" %}
+{% embed url="https://chrome.google.com/webstore/detail/connection-forwarder/ahaijnonphgkgnkbklchdhclailflinn/related?hl=en-US" %}
 
 ## Hot Module Replacement
 
@@ -104,6 +104,8 @@ import { Provider } from 'overmind-react'
 import { App } from './components/App'
 
 render(<Provider value={overmind}><App /></Provider>, document.querySelector('#app'))
+
+
 ```
 {% endtab %}