docs(website): improve running side effects doc

Author: christianalfoni

packages/overmind-website/examples/guide/runningsideeffects/changestate.ts

@@ -0,0 +1,24 @@
+export default (ts) =>
+  ts
+    ? [
+        {
+          fileName: 'overmind/actions.ts',
+          code: `
+import { Action } from 'overmind'
+
+export const getCurrentUser: Action = async ({ api, state }) => {
+  state.currentUser = await api.getCurrentUser()
+}
+  `,
+        },
+      ]
+    : [
+        {
+          fileName: 'overmind/actions.js',
+          code: `
+export const getCurrentUser = async ({ api, state }) => {
+  state.currentUser = await api.getCurrentUser()
+}
+  `,
+        },
+      ]

packages/overmind-website/examples/guide/runningsideeffects/class.ts

@@ -7,24 +7,24 @@ export default (ts) =>
 import axios from 'axios'
 import { User } from './state'
 
-interface IHttp {
+interface IRequest {
   get<T>(url: string): Promise<T>
 }
 
-class Http {
+export class Api {
   private baseUrl: string
-  private request: IHttp
-  constructor (baseUrl: string, request: IHttp) {
+  private request: IRequest
+  constructor (baseUrl: string, request: IRequest) {
     this.baseUrl = baseUrl
     this.request = request
   }
-  getUser(): Promise<User>  {
+  getCurrentUser(): Promise<User>  {
     return this.request.get(\`\${this.baseUrl}/user\`)
   }
 }
 
-export const http =
-  new Http(IS_PRODUCTION ? '/api/v1' : 'http://localhost:4321', axios)
+export const api =
+  new Api(IS_PRODUCTION ? '/api/v1' : 'http://localhost:4321', axios)
   `,
         },
       ]
@@ -34,7 +34,7 @@ export const http =
           code: `
 import axios from 'axios'
 
-class Http {
+export class Api {
   constructor (baseUrl, request) {
     this.baseUrl = baseUrl
     this.request = request
@@ -45,7 +45,7 @@ class Http {
 }
 
 export const http =
-  new Http(IS_PRODUCTION ? '/api/v1' : 'http://localhost:4321', axios)
+  new Api(IS_PRODUCTION ? '/api/v1' : 'http://localhost:4321', axios)
   `,
         },
       ]

packages/overmind-website/examples/guide/runningsideeffects/getuser.ts

@@ -2,22 +2,24 @@ export default (ts) =>
   ts
     ? [
         {
-          fileName: 'overmind/operations.ts',
+          fileName: 'overmind/actions.ts',
           code: `
-import { Operation } from 'overmind'
+import { Action } from 'overmind'
 import { User } from './state'
 
-export const getUser: Operation.Map<any, Promise<User>> = ({ http }) =>
-  http.get<User>('/user')
+export const getCurrentUser: Action = async ({ http, state }) => {
+  state.currentUser = await http.get<User>('/user')
+}
   `,
         },
       ]
     : [
         {
-          fileName: 'overmind/operations.js',
+          fileName: 'overmind/actions.js',
           code: `
-export const getUser = ({ http }) =>
-  http.get('/user')
+export const getCurrentUser = async ({ http, state }) => {
+  state.currentUser = await http.get('/user')
+}
   `,
         },
       ]

packages/overmind-website/examples/guide/runningsideeffects/object.ts

@@ -7,8 +7,8 @@ export default (ts) =>
 import * as axios from 'axios'
 import { User } from './state'
 
-export const http = {
-  getUser() {
+export const api = {
+  getCurrentUser() {
     return axios.get<User>('/user')
   }
 }
@@ -22,7 +22,7 @@ export const http = {
 import axios from 'axios'
 
 export const http = {
-  getUser() {
+  getCurrentUser() {
     return axios.get('/user')
   }
 }

packages/overmind-website/guides/beginner/04_runningsideeffects.md

@@ -1,32 +1,46 @@
 # Running side effects
 
-Developing applications is not only about managing state, but also managing side effects. A side effect is typically exampled with an http request or talking to local storage. In Overmind we just call this **effects**.
+Developing applications is not only about managing state, but also managing side effects. A side effect is typically exampled with an http request or talking to local storage. In Overmind we just call this **effects**. It is highly encouraged that you think about your effects as an application specific API that **you** design and implement. An example of this would be:
 
-Let us start with a simple example.
+```marksy
+h(Example, { name: "guide/runningsideeffects/changestate" })
+```
+
+As you can see we are very specific about what the effect does. This will improve the readability of your actual application logic and you keep the low level generic code abstracted away. But let us start more generically and you can choose how far you want to take this encouragement. 
+
+## Exposing an existing tool
+
+Let us just expose the [axios](https://github.com/axios/axios) library as an **http** effect.
 
 ```marksy
 h(Example, { name: "guide/runningsideeffects/axios" })
 ```
 
-We are just exporting an existing library from our effects file and include it in the application config. Now Overmind is aware of an **http** effect. It can track it for debugging and all operations will have it injected.
+We are just exporting the existing library from our effects file and include it in the application config. Now Overmind is aware of an **http** effect. It can track it for debugging and all actions and operators will have it injected.
 
-Let us put it to use in an operation that grabs the user of the application.
+Let us put it to use in an action that grabs the current user of the application.
 
 ```marksy
 h(Example, { name: "guide/runningsideeffects/getuser" })
 ```
 
-That was basically it. We can take this a step further though. Maybe you want to create a more explicit API effect.
+That was basically it. As you can see we are exposing some low level details like the http method used and the url. Let us follow the encouraged way of doing things and create our own **api** effect.
+
+## Specific API
 
 ```marksy
 h(Example, { name: "guide/runningsideeffects/object" })
 ```
 
-Or maybe you need it to be configurable. Improving testability and environment variables.
+We could also make this effect configurable by defining it as a class instead. 
+## Configurable effect
+
+By defining a class we improve testability, allow using environment variables and even change out the actual request implementation.
+
 
 ```marksy
 h(Example, { name: "guide/runningsideeffects/class" })
 ```
 
 ## Summary
-Adding side effects is easy, but it is worth taking notice that you also get a chance to map an existing tool to something more domain specific. As we did here converting the general **get** method to a **getUser** method. If you think about it from an application standpoint it is kinda weird that it makes arbitrary requests to a string url. It is better to create an abstraction around it to keep things more maintainable and predictable.
+Adding side effects is easy, but it is worth taking notice that you also get a chance to map an existing tool to something more domain specific. As we did here converting the general **get** method to a **getCurrentUser** method. If you think about it from an application standpoint it is kinda weird that it makes arbitrary requests to a string url. It is better to create an abstraction around it to keep things more maintainable and predictable.