Merge pull request cerebral#58 from cerebral/composition

christianalfoni · web-flow · commit 4d1b005e4ec2 · 2018-08-23T23:11:27.000+02:00
fix(overmind): fix namespaced state adding, also update guides
diff --git a/logo.png b/logo.png
diff --git a/logo.psd b/logo.psd
diff --git a/packages/demos/posts/src/app/posts.js b/packages/demos/posts/src/app/posts.js
diff --git a/packages/demos/posts/src/app/posts/actions.js b/packages/demos/posts/src/app/posts/actions.js
@@ -0,0 +1,7 @@
+import * as operations from './operations'
+import * as mutations from './mutations'
+
+export const loadPost = (action) =>
+  action()
+    .map(operations.getNextPost)
+    .mutation(mutations.addPost)
diff --git a/packages/demos/posts/src/app/posts/index.js b/packages/demos/posts/src/app/posts/index.js
@@ -0,0 +1,4 @@
+import * as state from './state'
+import * as actions from './actions'
+
+export { state, actions }
diff --git a/packages/demos/posts/src/app/posts/mutations.js b/packages/demos/posts/src/app/posts/mutations.js
@@ -0,0 +1 @@
+export const addPost = (state, post) => state.posts.list.unshift(post)
diff --git a/packages/demos/posts/src/app/posts/operations.js b/packages/demos/posts/src/app/posts/operations.js
@@ -0,0 +1,2 @@
+export const getNextPost = ({ state, api }) =>
+  api.getPost(state.posts.list.length + 1)
diff --git a/packages/demos/posts/src/app/posts/state.js b/packages/demos/posts/src/app/posts/state.js
@@ -0,0 +1 @@
+export let list = []
diff --git a/packages/demos/posts/src/app/tabs.js b/packages/demos/posts/src/app/tabs.js
diff --git a/packages/demos/posts/src/app/tabs/actions.js b/packages/demos/posts/src/app/tabs/actions.js
@@ -0,0 +1,3 @@
+import * as mutations from './mutations'
+
+export const changeTo = (action) => action().mutation(mutations.changeTab)
diff --git a/packages/demos/posts/src/app/tabs/index.js b/packages/demos/posts/src/app/tabs/index.js
@@ -0,0 +1,4 @@
+import * as state from './state'
+import * as actions from './actions'
+
+export { state, actions }
diff --git a/packages/demos/posts/src/app/tabs/mutations.js b/packages/demos/posts/src/app/tabs/mutations.js
@@ -0,0 +1 @@
+export const changeTab = (state, tab) => (state.tabs.current = tab)
diff --git a/packages/demos/posts/src/app/tabs/state.js b/packages/demos/posts/src/app/tabs/state.js
@@ -0,0 +1 @@
+export let current = 'posts'
diff --git a/packages/demos/posts/src/app/users.js b/packages/demos/posts/src/app/users.js
diff --git a/packages/demos/posts/src/app/users/index.js b/packages/demos/posts/src/app/users/index.js
@@ -0,0 +1,3 @@
+import * as state from './state'
+
+export { state }
diff --git a/packages/demos/posts/src/app/users/state.js b/packages/demos/posts/src/app/users/state.js
@@ -0,0 +1 @@
+export const list = []
diff --git a/packages/node_modules/overmind/src/index.ts b/packages/node_modules/overmind/src/index.ts
@@ -462,13 +462,15 @@ export default class App<
   private getState(configuration) {
     let state = {}
     if (configuration.state) {
-      state = configuration.state
+      state = this.transformStateToPlainObject(configuration.state)
     }
     if (configuration.namespaces) {
       Object.keys(configuration.namespaces).reduce((aggr, key) => {
         if (configuration.namespaces[key].state) {
           return Object.assign(aggr, {
-            [key]: configuration.namespaces[key].state,
+            [key]: this.transformStateToPlainObject(
+              configuration.namespaces[key].state
+            ),
           })
         }
 
@@ -478,6 +480,13 @@ export default class App<
 
     return state
   }
+  private transformStateToPlainObject(state: {}) {
+    return Object.keys(state).reduce((aggr, key) => {
+      aggr[key] = state[key]
+
+      return aggr
+    }, {})
+  }
   private getActions(configuration, action) {
     let actions = {}
     if (configuration.actions) {
diff --git a/packages/node_modules/proxy-state-tree/src/index.ts b/packages/node_modules/proxy-state-tree/src/index.ts
@@ -1,4 +1,5 @@
 import proxify, { IS_PROXY, STATUS } from './proxify'
+const isPlainObject = require('is-plain-object')
 
 export type Options = {
   devmode?: boolean
@@ -24,22 +25,17 @@ class ProxyStateTree {
   proxy: any
   currentFlushId: number
   constructor(state: object, options: Options = {}) {
-    let stateObject = {}
-    try {
-      stateObject = Object.keys(state).reduce((aggr, key) => {
-        aggr[key] = state[key]
-
-        return aggr
-      }, {})
-    } catch (e) {
-      console.warn('You passed a non-object value to Proxy State Tree ')
+    if (!isPlainObject(state)) {
+      throw new Error(
+        'You did not pass a plain object as state to Proxy State Tree'
+      )
     }
 
     if (typeof options.devmode === 'undefined') {
       options.devmode = true
     }
 
-    this.state = stateObject
+    this.state = state
     this.options = options
     this.pathDependencies = {}
     this.globalDependencies = new Set()
@@ -48,7 +44,7 @@ class ProxyStateTree {
     this.paths = []
     this.objectChanges = new Set()
     this.status = STATUS.IDLE
-    this.proxy = proxify(this, stateObject)
+    this.proxy = proxify(this, state)
     this.currentFlushId = 0
   }
   get() {
diff --git a/packages/overmind-website/backend/index.js b/packages/overmind-website/backend/index.js
@@ -79,6 +79,7 @@ const apis = getApis()
 const searchData = getSearchData()
 
 app.use(express.static('dist'))
+app.use('/images', express.static('images'))
 app.get('/backend/guides', (_, res) =>
   res.send(IS_PRODUCTION ? guides : getGuides())
 )
diff --git a/packages/overmind-website/examples/guide/definingstate/define.ts b/packages/overmind-website/examples/guide/definingstate/define.ts
@@ -0,0 +1,26 @@
+export const js = [
+  {
+    fileName: 'app/state.js',
+    code: `
+export let isLoading = false
+
+export let user = null
+  `,
+  },
+]
+
+export const ts = [
+  {
+    fileName: 'app/state.ts',
+    code: `
+export type User = {
+  username: string
+  bio: string
+}
+
+export let isLoading: boolean = false
+
+export let user: User = null
+  `,
+  },
+]
diff --git a/packages/overmind-website/examples/guide/definingstate/namespaces.ts b/packages/overmind-website/examples/guide/definingstate/namespaces.ts
@@ -0,0 +1,62 @@
+export const js = [
+  {
+    fileName: 'app/admin/state.js',
+    code: `
+export let isLoadingUsers = false
+
+export const users = {}
+  `,
+  },
+  {
+    fileName: 'app/issues/state.js',
+    code: `
+export let isLoading = false
+
+export const issues = {}
+
+export const sorting = {
+  key: "date",
+  type: "asc"
+}
+  `,
+  },
+]
+
+export const ts = [
+  {
+    fileName: 'app/admin/state.ts',
+    code: `
+export type User = {
+  username: string
+  bio: string
+}
+
+export let isLoadingUsers: boolean = false
+
+export const users: { [username: string]: User } = {}
+  `,
+  },
+  {
+    fileName: 'app/issues/state.ts',
+    code: `
+export enum SortKey = {
+  Date = 'date',
+  Title = 'title'
+}
+
+export enum SortType = {
+  Asc = 'asc',
+  Desc = 'desc'
+}
+
+export let isLoading = false
+
+export const issues = {}
+
+export const sorting: { key: SortKey, type: SortType } = {
+  key: SortKey.Date,
+  type: SortType.Asc
+}
+  `,
+  },
+]
diff --git a/packages/overmind-website/guides/beginner/02_definingstate.md b/packages/overmind-website/guides/beginner/02_definingstate.md
@@ -4,6 +4,10 @@ Even though we think of the user interface as the application, it is really not.
 
 On one end we listen to interaction from the user to change this data structure. On the other end we transform this data structure into a user interface. This is what we mean when we say that "the state drives the user interface".
 
+```marksy
+<Image src="state-ui.png" />
+```
+
 ## The values
 
 In JavaScript we can create all sorts of abstractions to describe values, but in Overmind we lean on the core serializable values. These are **objects**, **arrays**, **strings**, **numbers**, **booleans** and **null**. Serializable values means that we can easily convert the state into a string and back again. This is fundamental for creating great developer experiences, passing state between client and server and other features. You can describe any application state with these core values.
@@ -12,21 +16,19 @@ Let us talk a litte bit about what each value helps you represent in your applic
 
 ### Objects
 
-The root value of your state tree is an object, because objects are great for holding other values represented by a pointer with a name. An object can hold a value which also is an object and continuing this way you get a tree structure of values. Sometimes these pointers to other objects represents the domains of your application. A typical state structure looks like:
+The root value of your state tree is an object, because objects are great for holding other values. An object has keys that points to values. Most of these keys points to values that is used to produce a UI, but these keys can also represent domains of the application. A typical state structure could be:
 
 ```marksy
 <Example name="guide/definingstate/objects" />
 ```
 
-As you can see the objects defines the tree structure and the other values allows us to express other things.
-
 ### Arrays
 
-Arrays are in a way similar to objects in the sense that they hold other values represented by a pointer, but this pointer is a number, not a name. That means it is ideal for iteration. But more often than not objects are actually better at managing lists of values. You could actually do quite fine without arrays in your state, it is rather when you produce the actual user interface you want arrays. You can learn more about this in the [managing lists]() guide.
+Arrays are in a way similar to objects in the sense that they hold other values, but instead of keys pointing to values you have indexes. That means it is ideal for iteration. But more often than not objects are actually better at managing lists of values. You could actually do quite fine without arrays in your state, it is rather when you produce the actual user interface you want arrays. You can learn more about this in the [managing lists]() guide.
 
 ### Strings
 
-Strings are of course used to represent text values. Names, descriptions and what not. But strings are also used for ids, types etc. Basically referencing something. This is an important part in structuring state. Whenever you have the need to reference something you want to use objects and strings, not arrays and numbers. It is more concise and effecient. For example in our **objects** example above we chose to use an array to represent the tabs, but we could also do:
+Strings are of course used to represent text values. Names, descriptions and what not. But strings are also used for ids, types etc. Basically values used to reference other values. This is an important part in structuring state. For example in our **objects** example above we chose to use an array to represent the tabs, using an index to point to the current tab, but we could also do:
 
 ```marksy
 <Example name="guide/definingstate/strings" />
@@ -36,7 +38,7 @@ Now we are referencing the current tab with a string. In this scenario you would
 
 ### Numbers
 
-Numbers of course represents things like counts, age etc. But they can also, just like strings, represent a pointer to something in a list. Like we saw in our **objects** example, to define what the current tab of our application is, we use a number. You could say that referencing things by number works very well when the value behind the number does not change. Our tabs will most likely not change that is why an array and referencing the current tab by number is perfectly fine.
+Numbers of course represents things like counts, age etc. But they can also, just like strings, represent a reference to something in a list. Like we saw in our **objects** example, to define what the current tab of our application is, we use a number. You could say that referencing things by number works very well when the value behind the number does not change. Our tabs will most likely not change that is why an array and referencing the current tab by number is perfectly fine.
 
 ### Booleans
 
@@ -46,6 +48,22 @@ Are things loading or not, is the user logged in or not. Typical usage of boolea
 
 All values, with the exception of booleans, can also be **null**. Non existing. You can have a non existing object, array, string or number. That means if you had not selected a tab both the string version and number version should have the value **null**.
 
+## Defining state
+
+You define the state of the application in **state** files. For example top level state could be defined as:
+
+```marksy
+<Example name="guide/definingstate/define" />
+```
+
+Note that we are just exporting variables from our state module. We use **let** for values that can be replaced and **const** for values that can not be replaced. That would typically be derived or computed values, but you might also have arrays or objects that should not be replaced.
+
+As your application grows you will most likely move state to their own namespaces. An example of that could be:
+
+```marksy
+<Example name="guide/definingstate/namespaces" />
+```
+
 ## Summary
 
-This short guide gave you some insight into how we think about state and what state really is in an application. There is more to learn about these values and how you can use them to describe your application.
+This short guide gave you some insight into how we think about state and what state really is in an application. There is more to learn about these values and how you can use them to describe your application. Please move on to other guides to learn more.
diff --git a/packages/overmind-website/images/state-ui.png b/packages/overmind-website/images/state-ui.png
diff --git a/packages/overmind-website/src/utils.tsx b/packages/overmind-website/src/utils.tsx
@@ -142,5 +142,8 @@ export const compile = marksy({
   },
   components: {
     Example: ({ name, view }) => <Example key={name} name={name} view={view} />,
+    Image: ({ src }) => (
+      <img src={`/images/${src}`} style={{ width: '100%' }} />
+    ),
   },
 })

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+export const addPost = (state, post) => state.posts.list.unshift(post)`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+export const getNextPost = ({ state, api }) =>`
	`2`	`+ api.getPost(state.posts.list.length + 1)`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+import * as mutations from './mutations'`
	`2`	`+`
	`3`	`+export const changeTo = (action) => action().mutation(mutations.changeTab)`