WIP: Mobx4

.gitignore

@@ -8,7 +8,6 @@ lib
 test/babel-tests.js
 test/typescript/typescript-tests.js
 test/perf/perf.txt
-.vscode
 dist/
 .build*/
 .idea

.prettierrc

@@ -0,0 +1,7 @@
+{
+    "printWidth": 100,
+    "semi": false,
+    "tabWidth": 4,
+    "singleQuote": false,
+    "useTabs": false
+}

.vscode/launch.json

@@ -0,0 +1,17 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+
+        {
+            "type": "node",
+            "request": "launch",
+            "name": "debug unit test",
+            "program": "${workspaceRoot}/node_modules/jest/bin/jest.js",
+            "args": ["-i", "${file}"],
+            // "preLaunchTask": "tsc: build - tsconfig.json"
+        }
+    ]
+}

.vscode/settings.json

@@ -0,0 +1,18 @@
+{
+	"[typescript]": {
+	    "editor.formatOnSave": true,
+	    "editor.formatOnPaste": false
+	},
+	"[javascript]": {
+	    "editor.formatOnSave": true,
+	    "editor.formatOnPaste": false
+	},
+	// Note, these settings should match lint-staged settings!
+	"prettier.semi": false,
+	"prettier.tabWidth": 4,
+	"prettier.useTabs": false,
+	"prettier.printWidth": 100,
+	"prettier.singleQuote": false,
+    "typescript.tsdk": "node_modules/typescript/lib"
+    // "javascript.validate.enable": false // enable for flow
+}

CHANGELOG.md

@@ -1,3 +1,133 @@
+# 4.0.0
+
+* For the highlights of this release, read the [blog](https://medium.com/p/c1fbc08008da/):
+* For migration notes: see the [wiki page](https://github.com/mobxjs/mobx/wiki/Migrating-from-mobx-3-to-mobx-4)
+* Note; many things that were removed were removed to make the api surface smaller. If you thing some feature shouldn't have been removed, feel free to open an issue!
+
+This is the extensive list of all changes.
+
+### New features
+
+The changes mentioned here are discussed in detail in the [release highlights](https://medium.com/p/c1fbc08008da/), or were simply updated in the docs.
+
+* MobX 4 introduces separation between the production and non production build. The production build strips most typechecks, resulting in a faster and smaller build. Make sure to substitute process.env.NODE_ENV = "production" in your build process! If you are using MobX in a react project, you most probably already have set this up. Otherwise, they idea is explained [here](https://reactjs.org/docs/add-react-to-an-existing-app.html).
+* Introduced `flow` to create a chain of async actions. This is the same function as [`asyncActions`](https://github.com/mobxjs/mobx-utils#asyncaction) of the mobx-utils package
+* These `flow`'s are now cancellable, by calling `.cancel()` on the returned promise, which will throw a cancellation exception into the generator function.
+* `flow` also has experimental support for async iterators (`async * function`)
+* Introduced `decorate(thing, decorators)` to decorate classes or object without needing decorator syntax.
+* Introduced `onBecomeObserved` and `onBecomeUnobserved`. These API's enable hooking into the observability system and get notified about when an observable starts / stops becoming used. This is great to automaticaly fetch data from external resources, or stop doing so.
+* `computed` / `@computed` now accepts a `requiresReaction` option. If it set, the computed value will throw an exception if it is being read while not being tracked by some reaction.
+* To make `requiresReaction` the default, use `mobx.configure({ computedRequiresReaction: true })`
+* Introduced `mobx.configure({ disableErrorBoundaries })`, for easier debugging of exceptoins. By [NaridaL](https://github.com/NaridaL) through [#1262](https://github.com/mobxjs/mobx/pull/1262)
+* `toJS` now accepts the options: `{ detectCycles?: boolean, exportMapsAsObjects?: boolean }`, both `true` by default
+* Observable maps are now backed by real ES6 Maps. This means that any value can be used as key now, not just strings and numbers.
+* The flow typings have been updated. Since this is a manual effort, there can be mistakes, so feel free to PR!
+
+* `computed(fn, options?)` / `@computed(options) get fn()` now accept the following options:
+  * `set: (value) => void` to set a custom setter on the computed property
+  * `name: "debug name"`
+  * `equals: fn` the equality value to use for the computed to determine whether it's output has changed. The default is `comparer.default`. Alternatives are `comparer.structural`, `comparer.identity` or just your own comparison function.
+  * `requiresReaction: boolean` see above.
+
+* `autorun(fn, options?)` now accepts the following options:
+  * `delay: number` debounce the autorun with the given amount of milliseconds. This replaces the MobX 3 api `autorunAsync`
+  * `name: "debug name"
+  * `scheduler: function` a custom scheduler to run the autorun. For example to connect running the autorun to `requestAnimationFrame`. See the docs for more details
+  * `onError`. A custom error handler to be notified when an autorun throws an exception.
+
+* `reaction(expr, effect, options?)` now accepts the following options:
+  * `delay: number` debounce the autorun with the given amount of milliseconds. This replaces the MobX 3 api `autorunAsync`
+  * `fireImmediately`. Immediately fire the effect function after the first evaluation of `expr`
+  * `equals`. Custom equality function to determine whether the `expr` function differed from it's previous result, and hence should fire `effect`. Accepts the same options as the `equals` option of computed.
+  * All the options `autorun` accepts
+
+* `when(predicate, effect?, options?)` now accepts the following options:
+  * `name: "debug name"`
+  * `onError`. A custom error handler to be notified when an autorun throws an exception.
+  * `timeout: number` a timeout in milliseconds, after which the `onError` handler will be triggered to signal the condition not being met within a certain time
+* The `effect` parameter of `when` has become optional. If it is omitted, `when` will return a promise. This makes it easy to `await` a condition, for example: `await when(() => user.profile.loaded)`. The returned promise can be cancelled using `promise.cancel()`
+
+* There is now an utility API that enables manipulating observable maps, objects and arrays with the same api. These api's are fully reactive, which means that even new property declarations can be detected by mobx if `set` is used to add them, and `values` or `keys` to iterate them.
+  * `values(thing)` returns all values in the collection as array
+  * `keys(thing)` returns all keys in the collection as array
+  * `set(thing, key, value)` or `set(thing, { key: value })` Updates the given collection with the provided key / value pair(s).
+  * `remove(thing, key)` removes the specified child from the collection. For arrays splicing is used.
+  * `has(thing, key)` returns true if the collection has the specified _observable_ property.
+  * `get(thing, key)` returns the chlid under the specified key.
+
+* `observable`, `observable.array`, `observable.object`, `observable.map` and `extendObservable` now accept an additional options object, which can specify the following attributes:
+  * `name: "debug name"`
+  * `deep: boolean`. `true` by default, indicates whether the children of this collection are automatically converted into observables as well.
+  * `defaultDecorator: <decorator>` specifies the default decorator used for new children / properties, by default: `observable.deep`, but could be changed to `observable.ref`, `observable.struct` etc. (The `deep` property is just a short-hand for switching between `observable.deep` or `observable.ref` as default decorator for new properties)
+
+
+### Breaking changes
+
+The changes mentioned here are discussed in detail in the [migration notes](https://github.com/mobxjs/mobx/wiki/Migrating-from-mobx-3-to-mobx-4)
+
+* MobX 4 requires `Map` to be globally available. Polyfill it if targeting IE < 11 or other older browsers.
+* For typescript users, MobX now requires `Map` and several `Symbol`s to exist for it's typings. So make sure that the `lib` configuration of your project is set to `"es6"`. (The compilation target can still be `"es5"`)
+* `observable.shallowArray(values)` has been removed, instead use `observable.array(values, { deep: false })`
+* `observable.shallowMap(values)` has been removed, instead use `observable.map(values, { deep: false })`
+* `observable.shallowObject(values)` has been removed, instead use `observable.object(values, {}, { deep: false })`
+* `extendShallowObservable(target, props)`, instead use `extendObservable(target, props, {}, { deep: false })`
+* The decorators `observable.ref`, `observable.shallow`, `observable.deep`, `observable.struct` can no longer be used as functions. Instead, they should be passed as part of the `decorators` param to resp. `observable.object` and `extendObservable`
+* The new signature of `extendObservable` is `extendObservable(target, props, decorators?, options?)`. This also means it is no longer possible to pass multiple bags of properties to `extendObservable`. `extendObservable` can no longer be used to re-declare properties. Use `set` instead to update existing properties (or introduce new ones).
+* Iterating maps now follows the spec, that is, `map.values()`, `map.entries()`, `map.keys()`, `map[@@iterator]()` and `array[@@iterator]()` no longer return an array, but an iterator. Use `mobx.values(map)` or `Array.from(map)` to convert the iterators to arrays.
+* dropped `@computed.equals`, instead, you can now use `@computed({ equals: ... })`
+* `useStrict(boolean)` was dropped, use `configure({ enforceActions: boolean })` instead
+* `isolateGlobalState` was dropped, use `configure({ isolateGlobalState: true})` instead
+* If there are multiple mobx instances active in a single project, an exception will be thrown. Previously only a warning was printed. Fixes #1098. For details, see [#1082](https://github.com/mobxjs/mobx/issues/1082).
+* Dropped the `shareGlobalState` feature. Instead, projects should be setup properly and it is up to the hosting package to make sure that there is only one MobX instance
+* `expr` has been moved to mobx-utils. Remember, `expr(fn)` is just `computed(fn).get()`
+* `createTransformer` has been moved to mobx-utils
+* Passing `context` explicitly to `autorun`, `reaction` etc is no longer supported. Use arrow functions or function.bind instead.
+* Removed `autorunAsync`. Use the `delay` option of `autorun` instead.
+* `autorun`, `when`, `reaction` don't support name as first argument anymore, instead pass the `name` option.
+* The `extras.` namespace has been dropped to enable tree-shaking non-used MobX features. All methods that where there originally are now exported at top level. If they are part of the official public API (you are encouraged to use them) they are exported as is. If they are experimental or somehow internal (you are discouraged to use them), they are prefixed with `_`.
+* Dropped bower support. Fixes #1263
+* The `spyReportStart`, `spyReportEnd`, `spyReport` and `isSpyEnabled` are no longer public. It is no longer possible to emit custom spy events as to avoid confusing in listeners what the possible set of events is.
+* Dropped `isStrictModeEnabled`
+* `observable(value)` will only succeed if it can turn the value into an observable data structure (a Map, Array or observable object). But it will no longer create an observable box for other values to avoid confusion. Call `observable.box(value)`  explictly in such cases.
+* `isComputed` and `isObservable` no longer accept a property as second argument. Instead use `isComputedProp` and `isObservableProp`.
+* Removed `whyRun`, use `trace` instead
+* The spy event signature has slightly changed
+* The `Atom` class is no longer exposed. Use `createAtom` instead (same signature).
+* Calling reportObserved() on a self made atom will no longer trigger the hooks if reportObserved is triggered outside a reactive context.
+* The options `struct` and `compareStructural` for computed values are deprecated, use `@computed.struct` or `computed({ equals: comparer.structural})` instead.
+* `isModifierDescriptor` is no longer exposed.
+* `deepEqual` is no longer exposed, use `comparer.structural` instead.
+* `setReactionScheduler` -> `configure({ reactionScheduler: fn })`
+* `reserveArrayBuffer` -> `configure({ reactionErrorHandler: fn })`
+* `ObservableMap` is no longer exposed as constructor, use `observable.map` or `isObservableMap` instead
+* `map` -> `observable.map`
+* `runInAction` no longer accepts a custom scope
+* Dropped the already deprecated and broken `default` export that made it harder to tree-shake mobx. Make sure to always use `import { x } from "mobx"` and not `import mobx from "mobx"`.
+* Killed the already deprecated modifiers `asFlat` etc. If you war still using this, see the MobX 2 -> 3 migration notes.
+* Observable maps now fully implement the map interface. See [#1361](https://github.com/mobxjs/mobx/pull/1361) by [Marc Fallows](https://github.com/marcfallows)
+* Observable arrays will no longer expose the `.move` method
+* Dropped the `observable.deep.struct` modifier
+* Dropped the `observable.ref.struct` modifier
+* `observable.struct` now behaves like `observable.ref.struct` (this used to be `observable.deep.struct`). That is; values in an `observable.struct` field will be stored as is, but structural comparison will be used when assigning a new value
+* IReactionDisposer.onError has been removed, use the `onError` option of reactions instead
+
+### Issues fixed in this release:
+
+The issues are incoprorated in the above notes.
+
+* [#1316](https://github.com/mobxjs/mobx/issues/1316) - Improve `observable` api
+* [#992](https://github.com/mobxjs/mobx/issues/992) - `onBecomeObserved` & `onBecomeUnobserved`
+* [#1301](https://github.com/mobxjs/mobx/issues/1301) - Set `onError` handler when creating reactions
+* [#817](https://github.com/mobxjs/mobx/issues/817) - Improve typings of `observe`
+* [#800](https://github.com/mobxjs/mobx/issues/800) - Use `Map` as backend implementation of observable maps
+* [#1361](https://github.com/mobxjs/mobx/issues/1361) - Make observableMaps structurally correct maps
+* [#813](https://github.com/mobxjs/mobx/issues/813) - Create separate dev and production builds
+* [#961](https://github.com/mobxjs/mobx/issues/961), [#1197](https://github.com/mobxjs/mobx/issues/1197) - Make it possible to forbid reading an untracked computed value
+* [#1098](https://github.com/mobxjs/mobx/issues/1098) - Throw instead of warn if multiple MobX instances are active
+* [#1122](https://github.com/mobxjs/mobx/issues/1122) - Atom hooks fired to often for observable maps
+* [#1148](https://github.com/mobxjs/mobx/issues/1148) - Disposer of reactions should also cancel all scheduled effects
+* [#1241](https://github.com/mobxjs/mobx/issues/1241) - Make it possible to disable error boundaries, to make it easier to find exceptions
+* [#1263](https://github.com/mobxjs/mobx/issues/1263) - Remove bower.json
 
 # 3.6.2
 

README.md

@@ -31,7 +31,7 @@ MobX is proudly sponsored by Mendix, Coinbase, Facebook Open Source and many [in
 
 * <i><a style="color: white; background:green;padding:5px;margin:5px;border-radius:2px" href="https://egghead.io/courses/manage-complex-state-in-react-apps-with-mobx">Egghead.io course</a></i>
 * [Ten minute, interactive MobX + React tutorial](https://mobxjs.github.io/mobx/getting-started.html)
-* [Official MobX 3 documentation and API overview](https://mobxjs.github.io/mobx/refguide/api.html) ([MobX 2](https://github.com/mobxjs/mobx/blob/7c9e7c86e0c6ead141bb0539d33143d0e1f576dd/docs/refguide/api.md))
+* [Official MobX 4 documentation and API overview](https://mobxjs.github.io/mobx/refguide/api.html) ([MobX 3](https://github.com/mobxjs/mobx/blob/54557dc319b04e92e31cb87427bef194ec1c549c/docs/refguide/api.md), [MobX 2](https://github.com/mobxjs/mobx/blob/7c9e7c86e0c6ead141bb0539d33143d0e1f576dd/docs/refguide/api.md))
 * Videos:
   * [ReactNext 2016: Real World MobX](https://www.youtube.com/watch?v=Aws40KOx90U) - 40m [slides](https://docs.google.com/presentation/d/1DrI6Hc2xIPTLBkfNH8YczOcPXQTOaCIcDESdyVfG_bE/edit?usp=sharing)
   * [Practical React with MobX](https://www.youtube.com/watch?v=XGwuM_u7UeQ). In depth introduction and explanation to MobX and React by Matt Ruby on OpenSourceNorth (ES5 only) - 42m.
@@ -69,6 +69,8 @@ MobX adds observable capabilities to existing data structures like objects, arra
 This can simply be done by annotating your class properties with the [@observable](http://mobxjs.github.io/mobx/refguide/observable-decorator.html) decorator (ES.Next).
 
 ```javascript
+import { observable } from "mobx"
+
 class Todo {
     id = Math.random();
     @observable title = "";
@@ -78,33 +80,32 @@ class Todo {
 
 Using `observable` is like turning a property of an object into a spreadsheet cell.
 But unlike spreadsheets, these values can be not only primitive values, but also references, objects and arrays.
-You can even [define your own](http://mobxjs.github.io/mobx/refguide/extending.html) observable data sources.
-
-### Intermezzo: Using MobX in ES5, ES6 and ES.next environments
-
-If these `@` thingies look alien to you, these are ES.next decorators.
-Using them is entirely optional in MobX. See the [documentation](http://mobxjs.github.io/mobx/best/decorators.html) for details how to either use or avoid them.
-MobX runs on any ES5 environment, but leveraging ES.next features like decorators are the cherry on the pie when using MobX.
-The remainder of this readme uses decorators, but remember, _they are optional_.
 
-For example, in good ol' ES5 the above snippet would look like:
+If your environment doesn't support decorator syntax, don't worry.
+You can read [here](http://mobxjs.github.io/mobx/best/decorators.html) about how to set them up.
+Or you can skip them altoghether, as MobX can be used fine without decorator _syntax_, by leveraging the _decorate_ utility.
+Many MobX users do prefer the decorator syntax though, as it is slightly more concise.
 
 ```javascript
-function Todo() {
-    this.id = Math.random()
-    extendObservable(this, {
-        title: "",
-        finished: false
-    })
+import { decorate, observable } from "mobx"
+
+class Todo {
+    id = Math.random();
+    title = "";
+    finished = false;
 }
+decorate(Todo, {
+    title: observable,
+    finished: observable
+})
 ```
 
 ### Computed values
 
 <i><a style="color: white; background:green;padding:5px;margin:5px;border-radius:2px" href="https://egghead.io/lessons/javascript-derive-computed-values-and-manage-side-effects-with-mobx-reactions">Egghead.io lesson 3: computed values</a></i>
 
 With MobX you can define values that will be derived automatically when relevant data is modified.
-By using the [`@computed`](http://mobxjs.github.io/mobx/refguide/computed-decorator.html) decorator or by using getter / setter functions when using `(extend)Observable`.
+By using the [`@computed`](http://mobxjs.github.io/mobx/refguide/computed-decorator.html) decorator or by using getter / setter functions when using `(extend)Observable` (Of course, you can use `decorate` here again as alternative to the `@` syntax).
 
 ```javascript
 class TodoList {
@@ -214,6 +215,7 @@ store.todos[0].finished = true;
 ```
 
 Nonetheless, MobX has an optional built-in concept of [`actions`](https://mobxjs.github.io/mobx/refguide/action.html).
+Read this section as well if you want to now more about writing asynchronous actions. It's easy!
 Use them to your advantage; they will help you to structure your code better and make wise decisions about when and where state should be modified.
 
 ## MobX: Simple and scalable
@@ -304,13 +306,6 @@ To use the [flow typings](flow-typed/mobx.js) shipped with MobX:
 * In `.flowconfig`, you **cannot** import it explicitly in the `[libs]` section.
 * You **do not** need to install library definition using [flow-typed](https://github.com/flowtype/flow-typed).
 
-## Bower support
-
-Bower support is available through the infamous unpkg.com:
-`bower install https://unpkg.com/mobx/bower.zip`
-
-Then use `lib/mobx.umd.js` or `lib/mobx.umd.min.js`
-
 ## Donating
 
 Was MobX key in making your project a success?