Merge branch 'next' of https://github.com/cerebral/overmind into next

Author: christianalfoni

packages/node_modules/overmind/src/index.ts

@@ -401,6 +401,9 @@ export class Overmind<ThisConfig extends IConfiguration>
         getMutationTree: () => {
           return this.proxyStateTree.getMutationTree()
         },
+        getTrackStateTree: () => {
+          return this.proxyStateTree.getTrackStateTree()
+        },
         emit: this.eventHub.emit.bind(this.eventHub),
       } as any) as Execution
     }
@@ -439,9 +442,14 @@ export class Overmind<ThisConfig extends IConfiguration>
                 this.addExecutionMutation(mutation)
               })
             }
-
-            return mutationTree
-          },
+        return mutationTree
+      },
+      getTrackStateTree: () => {
+        return this.proxyStateTree.getTrackStateTree()
+      },
+      onFlush: (cb) => {
+        return this.proxyStateTree.onFlush(cb)
+      },
       scopeValue: (value, tree) => {
         return this.scopeValue(value, tree)
       },
@@ -1446,3 +1454,29 @@ export function debounce<Input, ThisConfig extends IConfiguration = Config>(
     }
   )
 }
+
+export function throttle<Input, ThisConfig extends IConfiguration = Config>(
+  ms: number
+): IOperator<ThisConfig, Input, Input> {
+  let timeout
+  let previousFinal
+
+  return createOperator(
+    'throttle',
+    String(ms),
+    (err, context, value, next, final) => {
+      if (err) next(err, value)
+      else {
+        if (timeout) {
+          previousFinal(null, value)
+        } else {
+          timeout = setTimeout(() => {
+            timeout = null
+            next(null, value)
+          }, ms)
+        }
+        previousFinal = final
+      }
+    }
+  )
+}

packages/node_modules/overmind/src/internalTypes.ts

@@ -1,4 +1,9 @@
-import { IMutation, IMutationTree } from 'proxy-state-tree'
+import {
+  IMutation,
+  IMutationTree,
+  ITrackStateTree,
+  IFlushCallback,
+} from 'proxy-state-tree'
 import { IAction, IOperator, IState } from './types'
 
 export type SubType<Base, Condition> = Pick<
@@ -71,6 +76,8 @@ export type Execution = {
     flushId: number
   }
   getMutationTree(): IMutationTree<any>
+  getTrackStateTree(): ITrackStateTree<any>
+  onFlush(cb: IFlushCallback): () => IFlushCallback[]
   value?: any
   error?: string
 }

packages/node_modules/overmind/src/operator.test.ts

@@ -1,5 +1,6 @@
 import { createOperator, createMutationOperator } from './operator'
-import { Overmind, IConfig, IOperator, pipe, map, mutate } from './'
+import { Overmind, IConfig, IOperator, pipe, map, mutate, IAction } from './'
+import { IS_PROXY, PATH } from 'proxy-state-tree'
 
 describe('OPERATOR', () => {
   test('should be able to create an operator', () => {
@@ -181,4 +182,125 @@ describe('OPERATOR', () => {
       expect(overmind.state.foo).toBe('hihihi')
     })
   })
+  test('should be able to create an operator that can track mutations', (done) => {
+    function waitForMutation(
+      operation: (state: Config['state']) => void
+    ): Operator {
+      return createOperator<Config>(
+        'waitForMutation',
+        operation.name,
+        (err, context, value, next) => {
+          if (err) next(err, value)
+          else {
+            const tree = context.execution.getTrackStateTree()
+            tree.trackScope(
+              () => {
+                operation(tree.state)
+              },
+              () => {
+                tree.dispose()
+                next(null, value)
+              }
+            )
+          }
+        }
+      )
+    }
+
+    const waitForFoo: Operator = waitForMutation((state) => {
+      state.foo
+    })
+
+    const test: Operator = pipe(waitForFoo)
+
+    const mutateFoo: Action = ({ state }) => {
+      state.foo = 'hihihi'
+    }
+
+    const state = {
+      foo: 'bar',
+    }
+
+    const config = {
+      state,
+      actions: {
+        test,
+        mutateFoo,
+      },
+    }
+    const overmind = new Overmind(config)
+
+    type Config = IConfig<typeof config>
+
+    interface Operator<Input = void, Output = Input>
+      extends IOperator<Config, Input, Output> {}
+
+    interface Action<Input = void, Output = void | Promise<void>>
+      extends IAction<Config, Input, Output> {}
+
+    overmind.actions.test().then(done)
+
+    // Trigger mutation with an action.
+    overmind.actions.mutateFoo()
+  })
+  test('should be able to create an operator that evaluates mutations', (done) => {
+    function waitUntilTrue(
+      operation: (state: Config['state']) => boolean
+    ): Operator {
+      return createOperator<Config>(
+        'waitUntilTrue',
+        operation.name,
+        (err, context, value, next) => {
+          if (err) next(err, value)
+          else {
+            const tree = context.execution.getTrackStateTree()
+            const test = () => {
+              if (operation(tree.state)) {
+                tree.dispose()
+                next(null, value)
+              }
+            }
+            tree.trackScope(test, test)
+          }
+        }
+      )
+    }
+
+    const waitForFoo: Operator = waitUntilTrue(
+      (state) => state.foo.bar === 'hihihi'
+    )
+
+    const test: Operator = pipe(waitForFoo)
+
+    const mutateBar: Action = ({ state }) => {
+      state.foo.bar = 'hihihi'
+    }
+
+    const state = {
+      foo: {
+        bar: 'baz',
+      },
+    }
+
+    const config = {
+      state,
+      actions: {
+        test,
+        mutateBar,
+      },
+    }
+    const overmind = new Overmind(config)
+
+    type Config = IConfig<typeof config>
+
+    interface Operator<Input = void, Output = Input>
+      extends IOperator<Config, Input, Output> {}
+
+    interface Action<Input = void> extends IAction<Config, Input> {}
+
+    overmind.actions.test().then(done)
+
+    // Trigger mutation with an action.
+    overmind.actions.mutateBar()
+  })
 })

packages/node_modules/overmind/src/operator.ts

@@ -4,7 +4,7 @@ import {
   createActionsProxy,
   ORIGINAL_ACTIONS,
 } from './utils'
-import { EventType } from './internalTypes'
+import { EventType, Execution } from './internalTypes'
 import { safeValue } from './Devtools'
 import { IContext, IConfiguration, IOperator } from './types'
 
@@ -127,7 +127,7 @@ export function createOperator<ThisConfig extends IConfiguration>(
   name: string,
   cb: (
     err: Error | null,
-    context: IContext<ThisConfig>,
+    context: IContext<ThisConfig> & { execution: Execution },
     value: any,
     next: (
       err: Error | null,
@@ -150,6 +150,7 @@ export function createOperator<ThisConfig extends IConfiguration>(
           state: context.state,
           effects: context.effects,
           actions: context.actions,
+          execution: context.execution,
         },
         context.value,
         (err, value, options = {}) => {

packages/node_modules/overmind/src/operators.test.ts

@@ -15,6 +15,7 @@ import {
   IAction,
   catchError,
   tryCatch,
+  throttle,
 } from './'
 
 describe('OPERATORS', () => {
@@ -316,6 +317,35 @@ describe('OPERATORS', () => {
       }
     )
   })
+  test('throttle', () => {
+    expect.assertions(1)
+    const test: Operator = pipe(
+      throttle(100),
+      mutate(({ state }) => state.runCount++)
+    )
+    const state = {
+      runCount: 0,
+    }
+    const config = {
+      state,
+      actions: {
+        test,
+      },
+    }
+    const overmind = new Overmind(config)
+
+    type Config = IConfig<typeof config>
+
+    interface Operator<Input = void, Output = Input>
+      extends IOperator<Config, Input, Output> {}
+
+    return Promise.all([overmind.actions.test(), overmind.actions.test()]).then(
+      () => {
+        expect(overmind.state.runCount).toBe(1)
+      }
+    )
+  })
+
   test('catchError', () => {
     expect.assertions(3)
     const test: Operator<string> = pipe(

packages/overmind-website/guides/beginner/01_quickstart.md

@@ -14,7 +14,7 @@ Now set up a simple application like this:
 h(Example, { name: "guide/quickstart/simple_app" })
 ```
 
-And fire up your application in the browser or whatever environment your user interface is to be consumed by the users.
+And fire up your application in the browser or whatever environment your user interface is to be consumed in by the users.
 
 
 ## VS Code
@@ -38,4 +38,4 @@ First... try to refresh your app to reconnect. If this does not work make sure t
 
 **The devtool does not open in VS Code?**
 
-Restart VS Code.
+Restart VS Code.

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

@@ -5,11 +5,11 @@ If you are moving from an existing state management solution, please read the re
 To get started with Overmind you have to set up a project. You can do this with whatever tool your framework of choice provides or you can use [webpack](https://webpack.js.org/) or [parceljs](https://parceljs.org/). You can also use [codesandbox.io](https://codesandbox.io/) to play around with Overmind directly in the browser.
 
 ```marksy
-h(Notice, null, "Due to using the Proxy feature of JavaScript, Overmind does not support **Internet Explorer 11**. Though did you know IE 11 mode is coming to [Microsofts next browser](https://www.pcworld.com/article/3393198/microsoft-edge-ie-mode.html)?")
+h(Notice, null, "Due to using the Proxy feature of JavaScript, Overmind does not support **Internet Explorer 11**. Though did you know IE 11 mode is coming to [Microsoft's next browser](https://www.pcworld.com/article/3393198/microsoft-edge-ie-mode.html)?")
 ```
 
 
-When you have your project up and running install the Overmind dependency by using [npm](https://www.npmjs.com/) or [yarn](https://yarnpkg.com/en/):
+When you have your project up and running, install the Overmind dependency by using [npm](https://www.npmjs.com/) or [yarn](https://yarnpkg.com/en/):
 
 ```marksy
 h(Example, { name: "guide/getstarted/install" })
@@ -41,7 +41,7 @@ The devtools should respond when you open up your application:
 
 ![open_devtool](/images/devtool_state.png)
 
-Now that we have our state in place, lets change it.
+Now that we have our state in place, let's change it.
 
 ## Changing state
 
@@ -58,13 +58,13 @@ To trigger this action, go to the **actions** tab in the development tool and ru
 
 ## Creating effects
 
- State management tools has a tendency to end their introduction here, but Overmind helps you manage one more important ingredient, **effects**. An effect, or side effect, is everything from doing http requests to storing data in local storage. What Overmind helps you with is separating the generic low level APIs of using effects from your actual application logic inside actions. Let us look at an example. We are simply going to grab a random number from "somewhere out there":
+State management tools have a tendency to end their introduction here, but Overmind helps you manage one more important ingredient, **effects**. An effect, or side effect, is everything from doing HTTP requests to storing data in local storage. What Overmind helps you with is separating the generic low level APIs of using effects from your actual application logic inside actions. Let us look at an example. We are simply going to grab a random number from "somewhere out there":
 
 ```marksy
 h(Example, { name: "guide/getstarted/effect" })
 ```
 
-As you can see we separated the low level generic code of creating a random number from our actual application logic in the action. Think of effects as the API you custom tailor to your application. There are several benefits to effects, which you can read about later, but the really important thing is that you separate the tools you are using from your actual application. That means you can at any time replace this custom random number generator with some existing tool or maybe you will grab it from the server? This is also true for everything else. If your application needs posts you will create a **getPosts** effect. It does not matter to the application if this comes from a restful API, graphql or whatever other source. It is an implementation detail.
+As you can see we separated the low level generic code of creating a random number from our actual application logic in the action. Think of effects as the API you custom tailor to your application. There are several benefits to effects, which you can read about later, but the really important thing is that you separate the tools you are using from your actual application. That means you can at any time replace this custom random number generator with some existing tool or maybe you will grab it from the server? This is also true for everything else. If your application needs posts you will create a **getPosts** effect. It does not matter to the application if this comes from a restful API, GraphQL or whatever other source. It is an implementation detail.
 
 With our effect in place, let us run the actions again:
 
@@ -78,12 +78,12 @@ Now that we know our application works as expected we can actually produce the U
 h(Example, { name: "guide/getstarted/connectapp" })
 ```
 
-Now you can run the actions by clicking the buttons in the UI and the devtools continues to track their execution giving you valuable insight into what happens inside your app.
+Now you can run the actions by clicking the buttons in the UI and the devtool continues to track their execution giving you valuable insight into what happens inside your app.
 
 ## Hot Module Replacement
 
 A popular concept introduced by Webpack is [HMR](https://webpack.js.org/concepts/hot-module-replacement/). It allows you to make changes to your code without having to refresh. Overmind automatically supports HMR. That means when **HMR** is activated Overmind will make sure it updates and manages its state, actions and effects. Even the devtools will be updated as you make changes.
 
 ## Summary
 
-You have now stepped your toes into Overmind. We introduced Overmind with the concept of thinking the UI as an implementation detail, but it is totally up to you have you want to separate the responsibilities of states and logic in your application. Please continue reading guides to learn more about how Overmind scales.
+You have now stepped your toes into Overmind. We introduced Overmind with the concept of thinking of the UI as an implementation detail, but it is totally up to you how you want to separate the responsibilities of states and logic in your application. Please continue reading guides to learn more about how Overmind scales.