docs(website): improve effects docs

Author: christianalfoni

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

@@ -6,7 +6,7 @@ export default (ts) =>
           code: `
 import { Action } from 'overmind'
 
-export const getCurrentUser: Action = async ({ effects, state }) => {
+export const loadApp: Action = async ({ effects, state }) => {
   state.currentUser = await effects.api.getCurrentUser()
 }
   `,
@@ -16,7 +16,7 @@ export const getCurrentUser: Action = async ({ effects, state }) => {
         {
           fileName: 'overmind/actions.js',
           code: `
-export const getCurrentUser = async ({ effects, state }) => {
+export const loadApp = async ({ effects, state }) => {
   state.currentUser = await effects.api.getCurrentUser()
 }
   `,

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

@@ -44,7 +44,7 @@ export class Api {
   }
 }
 
-export const http =
+export const api =
   new Api(IS_PRODUCTION ? '/api/v1' : 'http://localhost:4321', axios)
   `,
         },

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

@@ -0,0 +1,50 @@
+export default (ts) =>
+  ts
+    ? [
+        {
+          fileName: 'overmind/effects.ts',
+          code: `
+import * as firebase from 'firebase'
+import { Post } from './state'
+
+export const api = (() => {
+  let app
+
+  return {
+    initialize() {
+      app = firebase.initializeApp(...)      
+    },
+    async getPosts(): Promise<Post[]> {
+      const snapshot = await app.database().ref('/posts').once('value')
+
+      return snapshot.val()
+    }
+  }
+})()
+  `,
+        },
+      ]
+    : [
+        {
+          fileName: 'overmind/effects.js',
+          code: `
+import * as firebase from 'firebase'
+
+
+export const api = (() => {
+  let app
+
+  return {
+    initialize() {
+      app = firebase.initializeApp(...)      
+    },
+    async getPosts() {
+      const snapshot = await app.database().ref('/posts').once('value')
+
+      return snapshot.val()
+    }
+  }
+})()
+  `,
+        },
+      ]

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

@@ -0,0 +1,53 @@
+export default (ts) =>
+  ts
+    ? [
+        {
+          fileName: 'overmind/effects.ts',
+          code: `
+import { Post } from './state'
+
+export const api = (() => {
+  let app
+
+  return {
+    async initialize() {
+      const firebase = await import('firebase')
+
+      app = firebase.initializeApp(...)
+    },
+    async getPosts(): Promise<Post[]> {
+      const snapshot = await app.database().ref('/posts').once('value')
+
+      return snapshot.val()
+    }
+  }
+})()
+  `,
+        },
+      ]
+    : [
+        {
+          fileName: 'overmind/effects.js',
+          code: `
+import * as firebase from 'firebase'
+
+
+export const api = (() => {
+  let app
+
+  return {
+    async initialize() {
+      const firebase = await import('firebase')
+
+      app = firebase.initializeApp(...)
+    },
+    async getPosts() {
+      const snapshot = await app.database().ref('/posts').once('value')
+
+      return snapshot.val()
+    }
+  }
+})()
+  `,
+        },
+      ]

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

@@ -8,8 +8,10 @@ import * as axios from 'axios'
 import { User } from './state'
 
 export const api = {
-  getCurrentUser() {
-    return axios.get<User>('/user')
+  async getCurrentUser() {
+    const response = await axios.get<User>('/user')
+
+    return response.data
   }
 }
   `,
@@ -22,8 +24,10 @@ export const api = {
 import axios from 'axios'
 
 export const http = {
-  getCurrentUser() {
-    return axios.get('/user')
+  async getCurrentUser() {
+    const response = await axios.get('/user')
+
+    return response.data
   }
 }
   `,

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

@@ -0,0 +1,26 @@
+export default (ts) =>
+  ts
+    ? [
+        {
+          fileName: 'overmind/onInitialize.ts',
+          code: `
+import { OnInitialize } from 'overmind'
+
+export const onInitialize: OnInitialize = async ({ effects }) => {
+  effects.api.initialize()
+  state.posts = await effects.api.getPosts()
+}
+  `,
+        },
+      ]
+    : [
+        {
+          fileName: 'overmind/onInitialize.js',
+          code: `
+export const onInitialize = async ({ state, effects }) => {
+  effects.api.initialize()
+  state.posts = await effects.api.getPosts()
+}
+  `,
+        },
+      ]

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

@@ -0,0 +1,26 @@
+export default (ts) =>
+  ts
+    ? [
+        {
+          fileName: 'overmind/onInitialize.ts',
+          code: `
+import { OnInitialize } from 'overmind'
+
+export const onInitialize: OnInitialize = async ({ effects }) => {
+  await effects.api.initialize()
+  state.posts = await effects.api.getPosts()
+}
+  `,
+        },
+      ]
+    : [
+        {
+          fileName: 'overmind/onInitialize.js',
+          code: `
+export const onInitialize = async ({ state, effects }) => {
+  await effects.api.initialize()
+  state.posts = await effects.api.getPosts()
+}
+  `,
+        },
+      ]

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

@@ -1,12 +1,6 @@
 # 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**. 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:
-
-```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. 
+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**.
 
 ## Exposing an existing tool
 
@@ -28,11 +22,54 @@ That was basically it. As you can see we are exposing some low level details lik
 
 ## Specific API
 
+It is highly encouraged that you avoid exposing tools with their generic APIs. Rather build your own APIs that are more closely related to your application logic. So for example maybe you have an endpoint for fetching the current user. Create that as an API for your app.
+
 ```marksy
 h(Example, { name: "guide/runningsideeffects/object" })
 ```
 
+Now you can see how clean your application logic becomes:
+
+```marksy
+h(Example, { name: "guide/runningsideeffects/changestate" })
+```
+
 We could also make this effect configurable by defining it as a class instead. 
+
+## Initializing effects
+
+It can be a good idea to not allow your side effects to initialize when they are defined. This makes sure that they do not leak into tests or server side rendering. For example if you want to use Firebase. Instead of initializing the Firebase application immediately we rather do it behind an **initialize** method:
+
+```marksy
+h(Example, { name: "guide/runningsideeffects/initialize" })
+```
+
+We are doing 2 things here:
+
+1. We have created an **initialize** method which we can call from the Overmind **onInitialize** action, which runs when the Overmind instance is created
+2. We use an [IIFE](https://developer.mozilla.org/en-US/docs/Glossary/IIFE) to create a scoped internal variable to be used for that specific effect
+
+Example of initializing the effect:
+
+```marksy
+h(Example, { name: "guide/runningsideeffects/oninitialize" })
+```
+
+## Lazy effects
+
+You can also lazily load your effects in the **initialize** method. Let us say we wanted to load Firebase and its API on demand, or maybe just split out the code to make our app start faster.
+
+```marksy
+h(Example, { name: "guide/runningsideeffects/lazy" })
+```
+
+In our initialize we would just have to wait for the initialize to finish before using the API:
+
+
+```marksy
+h(Example, { name: "guide/runningsideeffects/oninitialize_lazy" })
+```
+
 ## Configurable effect
 
 By defining a class we improve testability, allow using environment variables and even change out the actual request implementation.
@@ -42,5 +79,7 @@ By defining a class we improve testability, allow using environment variables an
 h(Example, { name: "guide/runningsideeffects/class" })
 ```
 
+We export an instance of our **Api** to the application. This allows us to also create instances in isolation for testing purposes, making sure our Api class works as we expect.
+
 ## 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 **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.