Merge pull request cerebral#74 from cerebral/master

Cleaning up

Author: christianalfoni

.gitbook/assets/angular.png

@@ -1,229 +1,3 @@
 # Overmind
 
-Overmind is a state and side effects management tool for popular JavaScript frameworks. If you are familiar with projects like Redux, Vuex, Mobx or similar solutions, Overmind is taking it to the next step.
-
-The default instance of Overmind exposes tools to track access to state. This allows you to integrate Overmind with any view layer you want. Overmind has several preset view implementations like **React**, **VueJS, Preact** etc.
-
-```typescript
-import App from 'overmind'
-
-const {
-  state,
-  actions,
-  trackState,
-  clearTrackState,
-  addMutationListener
-} = new App({
-  state: {
-    title: 'Hello from Overmind'
-  },
-  actions: (action) => ({
-    changeTitle: action()
-      .map(event => event.target.value)
-      .mutate((state, value) => state.title = value)
-  })
-})
-```
-
-#### state
-
-This is the state of your application.
-
-#### actions
-
-The actions defined. These are just plain functions you call with a value:
-
-```typescript
-document.querySelector('#input').addEventListener('input', actions.changeTitle)
-```
-
-#### trackState / clearTrackState
-
-This function allows you to track when state is accessed. Typically you would use this in combination with lifecycle hooks of components to track what the component accesses on render:
-
-```typescript
-const trackId = trackState('ComponentName')
-// Logic that renders a component
-const paths = clearTrackState(trackId)
-
-paths // Set { 'path.to.some.state', 'path.to.some.other.state' }
-```
-
-This information is automatically passed to the Overmind devtools. 
-
-**addMutationListener**
-
-This function is used with the tracked paths. You typically create the listener on the first render and update it on subsequent renders:
-
-```typescript
-const listener = addMutationListener(paths, () => {
-  // This callback is called when the paths are mutated
-  // Typically here you trigger a new render of the component
-  // and update the paths of the listener with the new tracked paths
-})
-
-listener.update(newPaths) // Update the listener with new paths
-listener.dispose() // Dispose the listener, typically when component unmounts
-```
-
-Look at the Overmind implementations of the different views to see how this is used in practice.
-
-### An example application using React and TypeScript
-
-This example shows a structured application using two modules. The **compose** function allows you to namespace your modules. In this example we are not taking any shortcuts. We explicitly split up and type all functions, components etc. By default this typing would be inferred when inlining the functions and components, but we are taking full advantage of the functional approach which makes the application highly testable, predictable and composable. The usage of two modules here is artificial, but important to show you how modules has access to each other.
-
-{% code-tabs %}
-{% code-tabs-item title="index.tsx" %}
-```typescript
-import React from 'react'
-import { render } from 'react-dom'
-import App from './components/App'
-
-render(<App />, document.querySelector('#app'))
-```
-{% endcode-tabs-item %}
-
-{% code-tabs-item title="overmind.ts" %}
-```typescript
-import Overmind, { IContext, IAction, IConnect, compose } from 'overmind/react'
-import * as main from './modules/main'
-import * as items from './modules/items'
-
-export type AppState = {
-  main: main.State,
-  items: items.State
-}
-
-export type Context = IContext<AppState>
-
-export type Action = IAction<Context>
-
-const app = new Overmind(compose({
-  main,
-  items
-}))
-
-export type Connect = IConnect<typeof app.state, typeof app.actions>
-
-export const connect = app.connect
-
-```
-{% endcode-tabs-item %}
-
-{% code-tabs-item title="modules/main/index.ts" %}
-```typescript
-import { AppState, Action } from '../../overmind'
-
-/*
-  STATE
-*/
-export type State = {
-  newItemValue: string
-}
-
-export const state: State = {
-  newItemValue: ''
-}
-
-/*
-  MUTATIONS
-*/
-export const setNewItemValue = (state: AppState, value: string) => state.main.newItemValue = value
-
-/*
-  HELPERS
-*/
-export const getEventValue = (event: React.ChangeEvent) => event.target.value
-
-/*
-  ACTIONS
-*/
-export const actions = (action: Action) => ({
-  changeNewItemValue: action<React.ChangeEvent>()
-    .map(getEventValue)
-    .mutation(setNewItemValue)
-})
-```
-{% endcode-tabs-item %}
-
-{% code-tabs-item title="modules/items/index.ts" %}
-```typescript
-import { AppState, Context, Action } from '../../overmind'
-
-/*
-  STATE
-*/
-export type Item = {
-  title: string
-}
-
-export type State = {
-  items: Item[]
-}
-
-export const state: State = {
-  items: []
-}
-
-/*
-  MUTATIONS
-*/
-export const addNewItem = (state: AppState, item: Item) => state.items.list.push(item)
-
-export const resetNewItemValue = (state: AppState) => state.main.newItemValue = ''
-
-/*
-  HELPERS
-*/
-export const createItem = (_, { state }: Context) => ({
-  title: state.main.newItemValue
-})
-
-/*
-  ACTIONS
-*/
-export const actions = (action: Action) => ({
-  addNewItem: action()
-    .map(createItem)
-    .mutation(addNewItem)
-    .mutation(resetNewItemValue)
-})
-```
-{% endcode-tabs-item %}
-
-{% code-tabs-item title="components/App/index.tsx" %}
-```typescript
-import React from 'react'
-import { connect, Connect } from '../../overmind'
-
-const App: React.SFC<Connect> = ({ appState, actions }) => (
-  <div>
-    <form onSubmit={event => {
-      event.preventDefault()
-      actions.items.addNewItem()
-    }}>
-      <input
-        onChange={actions.changeNewItemValue}
-        value={appState.main.newItemValue}
-      />
-    </form>
-    <ul>
-      {appState.items.list.map(item => (
-        <li>{item.title}</li>
-      ))}
-    </ul>
-  </div>
-)
-
-export default connect(App)
-```
-{% endcode-tabs-item %}
-{% endcode-tabs %}
-
-What to take notice of:
-
-* We are not interfering in any way with the initial rendering of the app, meaning you just connect state where you need it
-* By default Overmind takes a single module with state, actions etc., but **compose** allows us to merge multiple modules together, giving them a namespace \("main" and "items" in this example\)
-* We separate mutations and other side effects. This makes it absolutely clear where mutations are performed and only the **mutation** operator is allowed to perform these mutations.
-* The actions are now just plain functions taking any payload. When the action is typed it requires a value, when it is not typed, it does not require a value \(this is actually very difficult to do in TypeScript\)
-
+Visit website for more information: [www.overmindjs.org](https://www.overmindjs.org).

README.md

@@ -1,4 +1 @@
-# Table of contents
-
-* [Overmind](README.md)
-
+# Readme

SUMMARY.md

@@ -0,0 +1,2 @@
+# API
+

api/README.md

@@ -0,0 +1,99 @@
+# action
+
+```javascript
+import App from 'overmind/$VIEW'
+
+const app = new App({
+  actions: action => ({
+    doThis: action()
+      .do((context, value) => {})
+  })
+})
+```
+
+The actions is defined with a callback receiving the applications action factory. The function is expected to return an object with actions.
+
+### map
+
+Returns a new value to the chain.
+
+```javascript
+export default action => ({
+  getEventValue: action()
+    .map((_, event) => event.target.value)
+})
+```
+
+```javascript
+export default action => ({
+  getPosts: action()
+    .map(({ api }) => api.getPosts())
+})
+```
+
+### mutation
+
+Change the state of the application. State changes are only allowed in this operator, which is why it only receives the state as the first argument, not the other providers.
+
+```javascript
+export default action => ({
+  changeInputValue: action()
+    .mutation((state, value) => state.inputValue = value)
+})
+```
+
+### do
+
+Perform some side effect without returning a new value to the chain. Any returned value will be ignored.
+
+```javascript
+export default action => ({
+  onClick: action()
+    .do(({ track }) => track.click('someClick'))
+})
+```
+
+### debounce
+
+If the action has not been called again within the number of milliseconds, continue execution.
+
+```javascript
+export default action => ({
+  search: action()
+    .mutation((state, value) => state.searchInputValue = value)
+    .debounce(200)
+    .map(({ api}, value) => api.search(value)
+})
+```
+
+### when
+
+Fork execution into **true** and **false** actions based on an expression.
+
+```javascript
+export default action => ({
+  openProfile: action()
+    .when(({ state }) => state.user.isLoggedIn, {
+      true: action(),
+      false: action()
+    })
+})
+```
+
+### fork
+
+Fork execution into any number of actions. Note that fork does not return a new value to the chain.
+
+```javascript
+export default action => ({
+  openAdmin: action()
+    .fork(({ state }) => state.user.role, {
+      admin: action(),
+      superuser: action(),
+      user: action()
+    })
+})
+```
+
+
+