docs(website): docs updates

Author: christianalfoni

packages/overmind-website/examples/guide/definingstate/derived_passvalue.ts

@@ -0,0 +1,7 @@
+export default () => [
+  {
+    code: `
+const posts = state.userPosts(userId)
+  `,
+  },
+]

packages/overmind-website/examples/guide/goingfunctional/map.ts

@@ -0,0 +1,54 @@
+export default (ts) =>
+  ts
+    ? [
+        {
+          fileName: 'overmind/operators.ts',
+          code: `
+import { Operator, map } from 'overmind'
+
+export const getTargetValue: Operator<Event, string> = map(({ value : event }) => 
+  event.currentTarget.value
+)
+  `,
+        },
+        {
+          fileName: 'overmind/actions.ts',
+          code: `
+import { Operator, pipe, action } from 'overmind'
+import { getTargetValue } from './operators'
+
+export const setValue: Operator<Event, string> = pipe(
+  getTargetValue,
+  action(({ state, value }) => {
+    state.value = value
+  })
+)
+  `,
+        },
+      ]
+    : [
+        {
+          fileName: 'overmind/operators.js',
+          code: `
+import { map } from 'overmind'
+
+export const getTargetValue = map(({ value : event }) => 
+  event.currentTarget.value
+)
+`,
+        },
+        {
+          fileName: 'overmind/actions.js',
+          code: `
+import { pipe, action } from 'overmind'
+import { getTargetValue } from './operators'
+
+export const setValue = pipe(
+  getTargetValue,
+  action(({ state, value }) => {
+    state.value = value
+  })
+)
+`,
+        },
+      ]

packages/overmind-website/guides/beginner/02_definingstate.md

@@ -67,6 +67,22 @@ That means the function only runs when accessed and the depending state has chan
 h(Notice, null, "Even though derived state is defined as functions you consume them as plain values. You do not have to call the derived function to get the value")
 ```
 
+You might intuitively want to pass in an argument to this derived function, but that is actually a very problematic concept that can be solved more elegantly. An example of this would be that you open a page showing the current user and with the **id** of that user you want find the related posts. So you might want to:
+
+
+```marksy
+h(Example, { name: "guide/definingstate/derived_passvalue" })
+```
+
+But this is actually a really bad idea and there are a couple of reasons for that:
+
+1. We need a mechanism to use the argument passed in as a caching key. With an **id** that is not so difficult, but what if you passed in an object with some options? Or maybe you use the same object multiple times, but the values on the object changed? Should we stringify the object? What about multiple arguments? As you can understand it becomes quite complex
+2. When should we remove a cached value? We have no idea when you have stopped using the derived value, so we do not know when to remove it. We could have created a limited cache, though how big should it be? 10 entries? What if you have a list of 100 users? Should it be configurable?
+
+So to solve this specific scenario you would rather create a new state called **currentUserId** and use that state to derive the posts. So whenever you have an itch to pass in a value to a derived, try imagine it from the perspective of only using state instead. This also improves the debugging experience.
+
+Also remember that **derived** is a concept for computation heavy derived state, you most commonly want to use a **getter**.
+
 ## Getter
 
 A concept in Javascript called a [getter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get) allows you to intercept accessing a property in an object. This is similar to deriving state, though they are dynamic. That means derived state can only be defined once and needs to stay in the state tree. A getter is just like a plain value, it can be added an removed at any point. Getters does **not** cache the result for that very reason, but whatever state they access is tracked.
@@ -84,6 +100,10 @@ We define the state of the application in **state** files. For example, the top
 h(Example, { name: "guide/definingstate/define" })
 ```
 
+```marksy
+h(TypescriptNotice, null, "Is is important that you define your state with a **type**, do **NOT** use an **interface**")
+```
+
 As your application grows you will most likely move parts of the state to their own namespaces. An example of that could be:
 
 ```marksy

packages/overmind-website/guides/beginner/03_connectingcomponents.md

@@ -65,6 +65,10 @@ All the actions defined in the Overmind application is available to connected co
 h(Example, { name: "guide/connectingcomponents/actions" })
 ```
 
+```marksy
+h(Notice, null, "If you need to pass multiple values to an action, you rather use an **object** instead")
+```
+
 ## Reactions
 
 Sometimes you want to make something happen inside a component related to a state change. This is typically doing some manual work on the DOM. When you connect a component to overmind it also gets access to **addMutationListener**. This function allows you to subscribe to changes in state, mutations as we call them. Each mutation holds information about what kind of mutation it was, at what path it happened and even any arguments used in the mutation. You can use all this information to create an effect.

packages/overmind-website/guides/intermediate/03_typescript.md

@@ -1,8 +1,10 @@
 # Typescript
 
-Overmind is written in Typescript and it is written with a focus on your keeping as little time as possible helping Typescript understand what your app is all about. Typescript will spend a lot more time helping you. There are actually two approaches to typing in Overmind.
+Overmind is written in Typescript and it is written with a focus on your keeping as little time as possible helping Typescript understand what your app is all about. Typescript will spend a lot more time helping you.
 
-## Declare module
+## Two typing approaches
+
+### 1. Declare module
 
 The most straight forward way to type your application is to use the **declare module** approach. This will work for most applications, but might make you feel uncomfortable as a harcore Typescripter. The reason is that we are overriding an internal type, meaning that you can only have one instance of Overmind running inside your application.
 
@@ -16,7 +18,7 @@ Now you can import any type directly from Overmind and it will understand the co
 h(Example, { name: "guide/typescript/declare_imports.ts" })
 ```
 
-## Explicit typing
+### 2. Explicit typing
 You can also explicitly type your application. This gives more flexibility.
 
 ```marksy
@@ -35,6 +37,9 @@ h(Example, { name: "guide/typescript/explicit_import.ts" })
 h(Notice, null, "The Overmind documentation is written for implicit typing. That means whenever you see a type import directly from the Overmind package, you should rather import from your own defined types")
 ```
 
+## Linting
+
+When you are using TSLint it is important that you use the official [Microsoft Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-typescript-tslint-plugin) for VS Code. 
 
 ## Actions
 

packages/overmind-website/guides/intermediate/04_goingfunctional.md

@@ -44,7 +44,6 @@ Here we see the **parallel** operator being used as a callable action to run two
 
 ## Piping
 
-
 To compose the different operators together you typically use **pipe**. You can also compose pipes into pipes, it is just an operator like the rest.
 
 ```marksy
@@ -53,6 +52,18 @@ h(Example, { name: "guide/goingfunctional/pipe" })
 
 There are several operators available and you can quite easily create new operators from scratch. They are built with the [op-op spec](https://github.com/christianalfoni/op-op-spec). A specification designed specifically to move state management solutions into a functional world.
 
+## Inputs and Outputs
+
+To produce new values throughout your pipe you can use the **map** operator. It will put whatever value you return from it on the pipe for the next operator to consume.
+
+```marksy
+h(Example, { name: "guide/goingfunctional/map" })
+```
+
+```marksy
+h(TypescriptNotice, null, "Notice here that we are typing both the input and the output. Both for the **map** operator and the **pipe** operator. This is important to manage the composition of operators. Typically operators pass on the same value they receive, meaning that you do not need the second typing parameter for the **Operator** type.")
+```
+
 ## Factories
 
 A familiar concept in functional programming is the use of factories. A factory is a function that creates an operator. This can be used to send *options* to an operator. A typical example of this is the **lengthGreaterThan** operator we built previously.