GitBook: [master] 10 pages modified

Author: christianalfoni

SUMMARY.md

@@ -16,7 +16,7 @@
 * [Effects](core/running-side-effects.md)
 * [Operators](core/going-functional.md)
 * [Statecharts](core/statecharts.md)
-* [Server Side Rendering](guides-1/server-side-rendering.md)
+* [Server Side Rendering](core/server-side-rendering.md)
 * [Typescript](core/typescript.md)
 
 ## views
@@ -36,7 +36,7 @@
 * [Managing lists](guides-1/managing-lists.md)
 * [State first routing](guides-1/state-first-routing.md)
 * [Move to Typescript](guides-1/move-to-typescript.md)
-* [Testing](features/testing.md)
+* [Testing](guides-1/testing.md)
 
 ## API <a id="api-1"></a>
 

core/running-side-effects.md

@@ -91,6 +91,7 @@ It can be a good idea to not allow your side effects to initialize when they are
 ```typescript
 import * as firebase from 'firebase'
 
+// We use IIFE to hide the private "app" variable
 export const api = (() => {
   let app
 
@@ -132,6 +133,35 @@ export const onInitialize = async ({ effects }) => {
 Typically you explicitly communicate with effects from actions, by calling methods. But sometimes you need effects to know about the state of the application, or maybe some internal state in the effect should be exposed on your application state. Again we can take advantage of an **initialize** method on the effect:
 
 {% tabs %}
+{% tab title="overmind/effects.js" %}
+```javascript
+// We use an IIFE to isolate some variables
+export const socket = (() => {
+  _options
+  _ws
+  return {
+    initialize(options) {
+      _options = options
+      _ws = new WebSocket('ws://...')
+      _ws.onclose = () => options.onStatusChange('close')
+      _ws.onopen = () => options.onStatusChange('open')
+      _ws.addEventListener(
+        'message',
+        (event) => options.onMessage(event.data)
+      )
+    },
+    send(type, data) {
+      _ws.postMessage({
+        type,
+        data,
+        token: _options.getToken()
+      })
+    }
+  }
+})()
+```
+{% endtab %}
+
 {% tab title="overmind/onInitialize.js" %}
 ```typescript
 export const onInitialize = async ({ state, effects, actions }) => {

guides-1/server-side-rendering.md core/server-side-rendering.mdguides-1/server-side-rendering.md renamed to core/server-side-rendering.md

@@ -36,7 +36,7 @@ Here we only export the configuration from the main Overmind file. The instantia
 
 ## Preparing effects
 
-The effects will also be shared with the server. Typically this is not an issue, but you should be careful about creating effects that run logic when they are defined. You might also consider lazy-loading effects so that you avoid loading them on the server at all. You can read more about them in [EFFECTS](../core/running-side-effects.md).
+The effects will also be shared with the server. Typically this is not an issue, but you should be careful about creating effects that run logic when they are defined. You might also consider lazy-loading effects so that you avoid loading them on the server at all. You can read more about them in [EFFECTS](running-side-effects.md).
 
 ## Rendering on the server
 
@@ -103,3 +103,55 @@ export const onInitialize: OnInitialize = ({ state }) => {
 If you are using state first routing, make sure you prevent the router from firing off the initial route, as this is not needed.
 {% endhint %}
 
+## OnInitialize
+
+The `onInitialized` action does not run on the server. The reason is that it is considered a side effect you might not want to run, so we do not force it. If you do want to run an action as Overmind fires up both on the client and the server you can rather create a custom action for it.
+
+{% tabs %}
+{% tab title="overmind/actions.js" %}
+```javascript
+export const initialize = () => {
+  // Whatever...
+}
+```
+{% endtab %}
+
+{% tab title="client/index.js" %}
+```typescript
+import { createOvermind } from 'overmind'
+import { config } from './overmind'
+
+const overmind = createOvermind(config)
+overmind.actions.initialize()
+```
+{% endtab %}
+
+{% tab title="server/index.js" %}
+```javascript
+import { createOvermindSSR } from 'overmind'
+import { config } from '../client/overmind'
+
+export default async (req, res) => {
+  const overmind = createOvermindSSR(config)
+  await overmind.actions.initialize()
+
+  const html = renderToString(
+    // Whatever implementation your view layer provides
+  )
+
+  res.send(`
+<html>
+  <body>
+    <div id="app">${html}</div>
+    <script>
+      window.__OVERMIND_MUTATIONS = ${JSON.stringify(overmind.hydrate())}
+    </script>
+    <script src="/scripts/app.js"></script>
+  </body>
+</html>
+`)
+}
+```
+{% endtab %}
+{% endtabs %}
+

core/typescript.md

@@ -387,7 +387,41 @@ export const filterAwesome: <T extends { isAwesome: boolean }>() => Operator<T>
 
 That means this operator can handle any type that matches an **isAwesome** property, though will pass the original type through.
 
-## Statecharts
+## Statemachine
+
+Statemachines exposes a type called **Statemachine** which you will give a single type argument of what states it should manage:
+
+{% tabs %}
+{% tab title="overmind/state.ts" %}
+```typescript
+import { Statemachine, statemachine } from 'overmind'
+
+type Mode =
+  | 'unauthenticated'
+  | 'authenticating'
+  | 'authenticated'
+  | 'unauthenticating'
+
+type State = {
+  mode: Statemachine<Mode>
+}
+
+export const state: State = {
+  mode: statemachine<Mode>({
+    initial: 'unauthenticated',
+    states: {
+      unauthenticated: ['authenticating'],
+      authenticating: ['unauthenticated', 'authenticated'],
+      authenticated: ['unauthenticating'],
+      unauthenticating: ['unauthenticated', 'authenticated']
+    }
+  })
+}
+```
+{% endtab %}
+{% endtabs %}
+
+## Statechart
 
 To type a statechart you use the **Statechart** type:
 

faq.md

@@ -8,5 +8,9 @@ First… try to refresh your app to reconnect. If this does not work make sure t
 
 Restart VS Code
 
+## My operator actions are not running?
+
+Operators are identified with a Symbol. If you happen to use Overmind across packages you might be running two versions of Overmind. The same goes for core package and view package installed out of version sync. Make sure you are only running on package of Overmind by looking into your **node\_modules** folder.
+
 
 

features/testing.md guides-1/testing.mdfeatures/testing.md renamed to guides-1/testing.md

@@ -11,22 +11,18 @@ You can also do **unit testing** of actions and effects. This will cover expecte
 When you write tests you will create many instances of a mocked version of Overmind with the configuration you have created. To ensure that this configuration can be used many times we have to separate our configuration from the instantiation of the actual app.
 
 {% tabs %}
-{% tab title="overmind/index.ts" %}
+{% tab title="overmind/index.js" %}
 ```typescript
 import { IConfig } from 'overmind'
 import { state } from './state'
 
 export const config = {
   state
 }
-
-declare module 'overmind' {
-  interface Config extends IConfig<typeof config> {}
-}
 ```
 {% endtab %}
 
-{% tab title="index.ts" %}
+{% tab title="index.js" %}
 ```typescript
 import { createOvermind } from 'overmind'
 import { config } from './overmind'
@@ -43,11 +39,9 @@ Now we are free to import our configuration without touching the application ins
 When testing an action you’ll want to verify that changes to state are performed as expected. To give you the best possible testing experience Overmind comes with a mocking tool called **createOvermindMock**. It takes your application configuration and allows you to run actions as if they were run from components.
 
 {% tabs %}
-{% tab title="overmind/actions.ts" %}
+{% tab title="overmind/actions.js" %}
 ```typescript
-import { AsyncAction } from 'overmind'
-
-export const getPost: AsyncAction<string> = async ({ state, api }, id) {
+export const getPost = async ({ state, api }, id) {
   state.isLoadingPost = true
   try {
     state.currentPost = await api.getPost(id)
@@ -63,7 +57,7 @@ export const getPost: AsyncAction<string> = async ({ state, api }, id) {
 You might want to test if a thrown error is handled correctly here. This is an example of how you could do that:
 
 {% tabs %}
-{% tab title="overmind/actions.test.ts" %}
+{% tab title="overmind/actions.test.js" %}
 ```typescript
 import { createOvermindMock } from 'overmind'
 import { config } from './'
@@ -114,7 +108,7 @@ If your actions can result in multiple scenarios a unit test is beneficial. But
 You do not have to explicitly write the expected state. You can also use for example [JEST](https://www.overmindjs.org/guides/intermediate/05_writingtests?view=react&typescript=true) for snapshot testing. The mock instance has a list of mutations performed. This is perfect for snapshot testing.
 
 {% tabs %}
-{% tab title="overmind/actions.test.ts" %}
+{% tab title="overmind/actions.test.js" %}
 ```typescript
 import { createOvermindMock } from 'overmind'
 import { config } from './'
@@ -162,7 +156,7 @@ In this scenario we would also ensure that the **isLoadingPost** state indeed fl
 The **onInitialize** hook will not trigger during testing. To test this action you have to trigger it yourself.
 
 {% tabs %}
-{% tab title="overmind/onInitialize.test.ts" %}
+{% tab title="overmind/onInitialize.test.js" %}
 ```typescript
 import { createOvermindMock } from 'overmind'
 import { config } from './'
@@ -197,29 +191,17 @@ A simple example of this is doing requests. Maybe you want to use e.g. [AXIOS](h
 This is just an example showing you how you can structure your code for optimal testability. You might prefer a different approach or maybe rely on integration tests for this. No worries, you do what makes most sense for your application:
 
 {% tabs %}
-{% tab title="overmind/effects.ts" %}
+{% tab title="overmind/effects.js" %}
 ```typescript
 import * as axios from 'axios'
-import { Post } from './state'
-
-interface IRequest {
-  get<T>(url: string): Promise<T>
-}
-
-interface IOptions {
-  authToken: string
-  baseUrl: string
-}
 
 // This is the class we can create new instances of when testing
 export class Api {
-  request: IRequest
-  options: IOptions
-  constructor(request: IRequest, options: IOptions) {
+  constructor(request, options) {
     this.request = request
     this.options = options
   }
-  async getPost(id: string): Promise<Post> {
+  async getPost(id: string) {
     try {
       const response = await this.request.get(this.options.baseUrl + '/posts/' + id, {
         headers: {
@@ -247,7 +229,7 @@ export const api = new Api(axios, {
 Let’s see how you could write a test for it:
 
 {% tabs %}
-{% tab title="overmind/effects.test.ts" %}
+{% tab title="overmind/effects.test.js" %}
 ```typescript
 import { Api } from './effects'
 

quickstart.md

@@ -35,7 +35,7 @@ export const state = {
 ```
 {% endtab %}
 
-{% tab title="overmind/index.ts" %}
+{% tab title="overmind/index.js" %}
 ```typescript
 import { state } from './state'
 
@@ -44,41 +44,20 @@ export const config = {
 }
 ```
 {% endtab %}
-{% endtabs %}
-
-And fire up your application in the browser or whatever environment your user interface is to be consumed in by the users.
-
-### VS Code
-
-For the best experience you should install the [OVERMIND DEVTOOLS](https://marketplace.visualstudio.com/items?itemName=christianalfoni.overmind-devtools-vscode) extension. This will allow you to work on your application without leaving the IDE at all.
-
-![](.gitbook/assets/amazing_devtools.png)
-
-{% hint style="info" %}
-If you are using the **Insiders** version of VSCode the extension will not work. It seems to be some extra security setting.
-{% endhint %}
-
-### Devtool app
 
-Alternatively you can install the standalone application of the devtools. It is highly recommended to install the package [CONCURRENTLY](https://www.npmjs.com/package/concurrently). It allows you to start the devtools as you start your build process:
+{% tab title="index.js" %}
+```typescript
+import { createOvermind } from 'overmind'
+import { config } from './overmind'
 
-```text
-npm install overmind-devtools concurrently
+const overmind = createOvermind(config)
 ```
+{% endtab %}
+{% endtabs %}
 
-{% code title="package.json" %}
-```javascript
-{
-  ...
-  "scripts": {
-    "start": "concurrently \"overmind-devtools\" \"someBuildTool\""
-  },
-  ...
-}
-```
-{% endcode %}
+And fire up your application in the browser or whatever environment your user interface is to be consumed in by the users.
 
-### Hot Module Replacement <a id="quickstart-hot-module-replacement"></a>
+Move on with the specific view layer of choice to connect your app:
 
-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.
+\*\*\*\*[**REACT** ](views/react.md)**-** [**ANGULAR**](views/angular.md) **-** [**VUE**](views/vue.md)\*\*\*\*
 

views/angular.md

@@ -39,7 +39,7 @@ import { AppComponent } from './app.component';
   declarations: [ AppComponent ],
   bootstrap: [ AppComponent ],
   providers: [
-    { provide: OVERMIND_INSTANCE, useValue: createOvermind(config) },
+    { provide: OVERMIND_INSTANCE, useFactory: () => createOvermind(config) },
     { provide: Store, useExisting: OvermindService }
 ]
 })
@@ -85,7 +85,9 @@ if (environment.production) {
 platformBrowserDynamic()
   .bootstrapModule(AppModule, {
     // We do not need zones, we rather use the tracking
-    // directive, which gives us a huge optimization
+    // directive, which gives us a pretty signifcant performance
+    // boost. Note that 3rd party libraries might need ngZone,
+    // in which case you can not set it to "noop"
     ngZone: "noop"
   })
   .catch(err => console.log(err));
@@ -124,7 +126,7 @@ You can now access the **admin** state and actions directly with **state** and *
 
 ## NgZone
 
-Since Overmind knows when your components should update you can safely turn **ngZone** to `"noop"`. Note that other 3rd party libraries may not support this.
+The Overmind **\*track** directive knows when your components should update, and so is much more efficient at change detection than Angular's default NgZone. In order to take advantage of the efficiency provided by the \***track** directive, you _must_ set **ngZone** to "noop". Note that other 3rd party libraries may not support this. If for any reason you can't set **ngZone** to "noop", then the \***track** directive is redundant, and you can safely exclude it from your templates.
 
 ## Rendering