mobx-state-tree 5.0.0 → 5.0.4

package/README.md

@@ -2,14 +2,20 @@
 
 # mobx-state-tree
 
-_Opinionated, transactional, MobX powered state container combining the best features of the immutable and mutable world for an optimal DX_
-
 [![npm version](https://badge.fury.io/js/mobx-state-tree.svg)](https://badge.fury.io/js/mobx-state-tree)
 [![CircleCI](https://circleci.com/gh/mobxjs/mobx-state-tree.svg?style=svg)](https://circleci.com/gh/mobxjs/mobx-state-tree)
 [![Coverage Status](https://coveralls.io/repos/github/mobxjs/mobx-state-tree/badge.svg?branch=master)](https://coveralls.io/github/mobxjs/mobx-state-tree?branch=master)
-[![Join the community on Spectrum](https://withspectrum.github.io/badge/badge.svg)](https://spectrum.chat/mobx-state-tree)
+[![Have a question? Ask on GitHub Discussions!](https://img.shields.io/badge/Have%20a%20question%3F-Ask%20on%20GitHub%20Discussions!-blue)](https://github.com/mobxjs/mobx-state-tree/discussions)
+
+## What is mobx-state-tree?
+
+Technically speaking, mobx-state-tree (also known as MST) is a state container system built on [MobX](https://github.com/mobxjs/mobx), a functional reactive state library.
+
+This may not mean much to you, and that’s okay. I’ll explain it like this: **MobX is a state management "engine", and MobX-State-Tree gives it structure and common tools you need for your app.** MST is valuable in a large team but also useful in smaller applications when you expect your code to scale rapidly. And if we compare it to Redux, MST offers better performance and much less boilerplate code than Redux!
 
-> Mobx and MST are amazing pieces of software, for me it is the missing brick when you build React based apps. Thanks for the great work!
+MobX is [one of the most popular Redux alternatives](https://2019.stateofjs.com/data-layer/mobx/) and is used (along with MobX-State-Tree) by companies worldwide. MST plays very well with TypeScript, React, and React Native, especially when paired with [mobx-react-lite](https://github.com/mobxjs/mobx/tree/main/packages/mobx-react-lite). It supports multiple stores, async actions and side effects, enables extremely targeted re-renders for React apps, and much more -- all in a package with _zero dependencies_ other than MobX itself.
+
+_Note: you don't need to know how to use MobX in order to use MST._
 
 # Getting started
 
@@ -17,8 +23,67 @@ See the [Getting started](https://mobx-state-tree.js.org/intro/getting-started)
 
 👉 Official docs can be found at [http://mobx-state-tree.js.org/](http://mobx-state-tree.js.org/)
 
+## Quick Code Example
+
+There's nothing quite like looking at some code to get a feel for a library. Check out this small example of an author and list of tweets by that author.
+
+```js
+import { types } from "mobx-state-tree"
+
+// Define a couple models
+const Author = types.model({
+    id: types.identifier,
+    firstName: types.string,
+    lastName: types.string
+})
+const Tweet = types.model({
+    id: types.identifier,
+    author: types.reference(Author), // stores just the `id` reference!
+    body: types.string,
+    timestamp: types.number
+})
+
+// Define a store just like a model
+const RootStore = types.model({
+    authors: types.array(Author),
+    tweets: types.array(Tweet)
+})
+
+// Instantiate a couple model instances
+const jamon = Author.create({
+    id: "jamon",
+    firstName: "Jamon",
+    lastName: "Holmgren"
+})
+
+const tweet = Tweet.create({
+    id: "1",
+    author: jamon.id, // just the ID needed here
+    body: "Hello world!",
+    timestamp: Date.now()
+})
+
+// Now instantiate the store!
+const rootStore = RootStore.create({
+    authors: [jamon],
+    tweets: [tweet]
+})
+
+// Ready to use in a React component, if that's your target.
+import { observer } from "mobx-react-lite"
+const MyComponent = observer((props) => {
+    return <div>Hello, {rootStore.authors[0].firstName}!</div>
+})
+
+// Note: since this component is "observed", any changes to rootStore.authors[0].firstName
+// will result in a re-render! If you're not using React, you can also "listen" to changes
+// using `onSnapshot`: https://mobx-state-tree.js.org/concepts/snapshots
+```
+
 ## Thanks!
 
+-   [Michel Weststrate](https://twitter.com/mweststrate) for creating MobX, MobX-State-Tree, and MobX-React.
+-   [Infinite Red](https://infinite.red) for supporting ongoing maintenance on MST.
 -   [Mendix](https://mendix.com) for sponsoring and providing the opportunity to work on exploratory projects like MST.
 -   [Dan Abramov](https://twitter.com/dan_abramov)'s work on [Redux](http://redux.js.org) has strongly influenced the idea of snapshots and transactional actions in MST.
 -   [Giulio Canti](https://twitter.com/GiulioCanti)'s work on [tcomb](http://github.com/gcanti/tcomb) and type systems in general has strongly influenced the type system of MST.

package/dist/mobx-state-tree.js

@@ -68,11 +68,13 @@ PERFORMANCE OF THIS SOFTWARE.
 var extendStatics = function(d, b) {
     extendStatics = Object.setPrototypeOf ||
         ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
-        function (d, b) { for (var p in b) if (b.hasOwnProperty(p)) d[p] = b[p]; };
+        function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
     return extendStatics(d, b);
 };
 
 function __extends(d, b) {
+    if (typeof b !== "function" && b !== null)
+        throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
     extendStatics(d, b);
     function __() { this.constructor = d; }
     d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
@@ -101,13 +103,6 @@ function __rest(s, e) {
     return t;
 }
 
-function __decorate(decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-}
-
 function __generator(thisArg, body) {
     var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
     return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
@@ -165,6 +160,7 @@ function __read(o, n) {
     return ar;
 }
 
+/** @deprecated */
 function __spread() {
     for (var ar = [], i = 0; i < arguments.length; i++)
         ar = ar.concat(__read(arguments[i]));
@@ -1134,6 +1130,14 @@ var BaseNode = /** @class */ (function () {
         enumerable: false,
         configurable: true
     });
+    Object.defineProperty(BaseNode.prototype, "getReconciliationType", {
+        enumerable: false,
+        configurable: true,
+        writable: true,
+        value: function () {
+            return this.type;
+        }
+    });
     Object.defineProperty(BaseNode.prototype, "baseSetParent", {
         enumerable: false,
         configurable: true,
@@ -1269,7 +1273,6 @@ var ScalarNode = /** @class */ (function (_super) {
     __extends(ScalarNode, _super);
     function ScalarNode(simpleType, parent, subpath, environment, initialSnapshot) {
         var _this = _super.call(this, simpleType, parent, subpath, environment) || this;
-        mobx.makeObservable(_this);
         try {
             _this.storedValue = simpleType.createNewInstance(initialSnapshot);
         }
@@ -1390,11 +1393,9 @@ var ScalarNode = /** @class */ (function (_super) {
             this.fireInternalHook(name);
         }
     });
-    __decorate([
-        mobx.action
-    ], ScalarNode.prototype, "die", null);
     return ScalarNode;
 }(BaseNode));
+ScalarNode.prototype.die = mobx.action(ScalarNode.prototype.die);
 
 var nextNodeId = 1;
 var snapshotReactionOptions = {
@@ -1512,6 +1513,12 @@ var ObjectNode = /** @class */ (function (_super) {
             writable: true,
             value: false
         });
+        Object.defineProperty(_this, "_snapshotComputed", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         Object.defineProperty(_this, "_snapshotUponDeath", {
             enumerable: true,
             configurable: true,
@@ -1525,7 +1532,7 @@ var ObjectNode = /** @class */ (function (_super) {
             writable: true,
             value: void 0
         });
-        mobx.makeObservable(_this);
+        _this._snapshotComputed = mobx.computed(function () { return freeze(_this.getSnapshot()); });
         _this.unbox = _this.unbox.bind(_this);
         _this._initialSnapshot = freeze(initialValue);
         _this.identifierAttribute = complexType.identifierAttribute;
@@ -1645,9 +1652,7 @@ var ObjectNode = /** @class */ (function (_super) {
                 this._isRunningAction = false;
             }
             this._observableInstanceState = 2 /* CREATED */;
-            // NOTE: we need to touch snapshot, because non-observable
-            // "_observableInstanceState" field was touched
-            invalidateComputed(this, "snapshot");
+            this._snapshotComputed.trackAndCompute();
             if (this.isRoot)
                 this._addSnapshotReaction();
             this._childNodes = EMPTY_OBJECT;
@@ -1759,7 +1764,7 @@ var ObjectNode = /** @class */ (function (_super) {
     Object.defineProperty(ObjectNode.prototype, "snapshot", {
         // advantage of using computed for a snapshot is that nicely respects transactions etc.
         get: function () {
-            return freeze(this.getSnapshot());
+            return this._snapshotComputed.get();
         },
         enumerable: false,
         configurable: true
@@ -2255,21 +2260,13 @@ var ObjectNode = /** @class */ (function (_super) {
             }
         }
     });
-    __decorate([
-        mobx.action
-    ], ObjectNode.prototype, "createObservableInstance", null);
-    __decorate([
-        mobx.computed
-    ], ObjectNode.prototype, "snapshot", null);
-    __decorate([
-        mobx.action
-    ], ObjectNode.prototype, "detach", null);
-    __decorate([
-        mobx.action
-    ], ObjectNode.prototype, "die", null);
     return ObjectNode;
 }(BaseNode));
+ObjectNode.prototype.createObservableInstance = mobx.action(ObjectNode.prototype.createObservableInstance);
+ObjectNode.prototype.detach = mobx.action(ObjectNode.prototype.detach);
+ObjectNode.prototype.die = mobx.action(ObjectNode.prototype.die);
 
+var _a;
 /**
  * @internal
  * @hidden
@@ -2355,7 +2352,6 @@ var BaseType = /** @class */ (function () {
             writable: true,
             value: void 0
         });
-        mobx.makeObservable(this);
         this.name = name;
     }
     Object.defineProperty(BaseType.prototype, "create", {
@@ -2440,13 +2436,10 @@ var BaseType = /** @class */ (function () {
         enumerable: false,
         configurable: true
     });
-    var _a;
-    _a = $type;
-    __decorate([
-        mobx.action
-    ], BaseType.prototype, "create", null);
     return BaseType;
 }());
+_a = $type;
+BaseType.prototype.create = mobx.action(BaseType.prototype.create);
 /**
  * A complex type produces a MST node (Node in the state tree)
  *
@@ -2483,6 +2476,16 @@ var ComplexType = /** @class */ (function (_super) {
             return node.storedValue;
         }
     });
+    Object.defineProperty(ComplexType.prototype, "isMatchingSnapshotId", {
+        enumerable: false,
+        configurable: true,
+        writable: true,
+        value: function (current, snapshot) {
+            return (!current.identifierAttribute ||
+                current.identifier ===
+                    normalizeIdentifier(snapshot[current.identifierAttribute]));
+        }
+    });
     Object.defineProperty(ComplexType.prototype, "tryToReconcileNode", {
         enumerable: false,
         configurable: true,
@@ -2501,9 +2504,7 @@ var ComplexType = /** @class */ (function (_super) {
             if (current.type === this &&
                 isMutable(newValue) &&
                 !isStateTreeNode(newValue) &&
-                (!current.identifierAttribute ||
-                    current.identifier ===
-                        normalizeIdentifier(newValue[current.identifierAttribute]))) {
+                this.isMatchingSnapshotId(current, newValue)) {
                 // the newValue has no node, so can be treated like a snapshot
                 // we can reconcile
                 current.applySnapshot(newValue);
@@ -2543,11 +2544,9 @@ var ComplexType = /** @class */ (function (_super) {
             return null;
         }
     });
-    __decorate([
-        mobx.action
-    ], ComplexType.prototype, "create", null);
     return ComplexType;
 }(BaseType));
+ComplexType.prototype.create = mobx.action(ComplexType.prototype.create);
 /**
  * @internal
  * @hidden
@@ -3976,12 +3975,21 @@ function deepFreeze(value) {
 function isSerializable(value) {
     return typeof value !== "function";
 }
+/**
+ * @internal
+ * @hidden
+ */
+function defineProperty(object, key, descriptor) {
+    mobx.isObservableObject(object)
+        ? mobx.defineProperty(object, key, descriptor)
+        : Object.defineProperty(object, key, descriptor);
+}
 /**
  * @internal
  * @hidden
  */
 function addHiddenFinalProp(object, propName, value) {
-    Object.defineProperty(object, propName, {
+    defineProperty(object, propName, {
         enumerable: false,
         writable: false,
         configurable: true,
@@ -3993,7 +4001,7 @@ function addHiddenFinalProp(object, propName, value) {
  * @hidden
  */
 function addHiddenWritableProp(object, propName, value) {
-    Object.defineProperty(object, propName, {
+    defineProperty(object, propName, {
         enumerable: false,
         writable: true,
         configurable: true,
@@ -4185,14 +4193,6 @@ function argsToArray(args) {
         res[i] = args[i];
     return res;
 }
-/**
- * @internal
- * @hidden
- */
-function invalidateComputed(target, propName) {
-    var atom = mobx.getAtom(target, propName);
-    atom.trackAndCompute();
-}
 /**
  * @internal
  * @hidden
@@ -4594,6 +4594,8 @@ function splitJsonPath(path) {
     return parts;
 }
 
+/** @hidden */
+var $preProcessorFailed = Symbol("$preProcessorFailed");
 var SnapshotProcessor = /** @class */ (function (_super) {
     __extends(SnapshotProcessor, _super);
     function SnapshotProcessor(_subtype, _processors, name) {
@@ -4638,6 +4640,19 @@ var SnapshotProcessor = /** @class */ (function (_super) {
             return sn;
         }
     });
+    Object.defineProperty(SnapshotProcessor.prototype, "preProcessSnapshotSafe", {
+        enumerable: false,
+        configurable: true,
+        writable: true,
+        value: function (sn) {
+            try {
+                return this.preProcessSnapshot(sn);
+            }
+            catch (e) {
+                return $preProcessorFailed;
+            }
+        }
+    });
     Object.defineProperty(SnapshotProcessor.prototype, "postProcessSnapshot", {
         enumerable: false,
         configurable: true,
@@ -4656,11 +4671,14 @@ var SnapshotProcessor = /** @class */ (function (_super) {
         value: function (node) {
             var _this = this;
             // the node has to use these methods rather than the original type ones
-            proxyNodeTypeMethods(node.type, this, "create");
+            proxyNodeTypeMethods(node.type, this, "create", "is", "isMatchingSnapshotId");
             var oldGetSnapshot = node.getSnapshot;
             node.getSnapshot = function () {
                 return _this.postProcessSnapshot(oldGetSnapshot.call(node));
             };
+            node.getReconciliationType = function () {
+                return _this;
+            };
         }
     });
     Object.defineProperty(SnapshotProcessor.prototype, "instantiate", {
@@ -4703,7 +4721,10 @@ var SnapshotProcessor = /** @class */ (function (_super) {
         configurable: true,
         writable: true,
         value: function (value, context) {
-            var processedSn = this.preProcessSnapshot(value);
+            var processedSn = this.preProcessSnapshotSafe(value);
+            if (processedSn === $preProcessorFailed) {
+                return typeCheckFailure(context, value, "Failed to preprocess value");
+            }
             return this._subtype.validate(processedSn, context);
         }
     });
@@ -4724,7 +4745,10 @@ var SnapshotProcessor = /** @class */ (function (_super) {
                 ? this._subtype
                 : isStateTreeNode(thing)
                     ? getSnapshot(thing, false)
-                    : this.preProcessSnapshot(thing);
+                    : this.preProcessSnapshotSafe(thing);
+            if (value === $preProcessorFailed) {
+                return false;
+            }
             return this._subtype.validate(value, [{ path: "", type: this._subtype }]).length === 0;
         }
     });
@@ -4736,6 +4760,18 @@ var SnapshotProcessor = /** @class */ (function (_super) {
             return this._subtype.isAssignableFrom(type);
         }
     });
+    Object.defineProperty(SnapshotProcessor.prototype, "isMatchingSnapshotId", {
+        enumerable: false,
+        configurable: true,
+        writable: true,
+        value: function (current, snapshot) {
+            if (!(this._subtype instanceof ComplexType)) {
+                return false;
+            }
+            var processedSn = this.preProcessSnapshot(snapshot);
+            return ComplexType.prototype.isMatchingSnapshotId.call(this._subtype, current, processedSn);
+        }
+    });
     return SnapshotProcessor;
 }(BaseType));
 function proxyNodeTypeMethods(nodeType, snapshotProcessorType) {
@@ -4967,7 +5003,6 @@ var MapType = /** @class */ (function (_super) {
         });
         _this._determineIdentifierMode();
         _this.hookInitializers = hookInitializers;
-        mobx.makeObservable(_this);
         return _this;
     }
     Object.defineProperty(MapType.prototype, "hooks", {
@@ -5268,16 +5303,14 @@ var MapType = /** @class */ (function (_super) {
             node.storedValue.delete(subpath);
         }
     });
-    __decorate([
-        mobx.action
-    ], MapType.prototype, "applySnapshot", null);
     return MapType;
 }(ComplexType));
+MapType.prototype.applySnapshot = mobx.action(MapType.prototype.applySnapshot);
 /**
  * `types.map` - Creates a key based collection type who's children are all of a uniform declared type.
  * If the type stored in a map has an identifier, it is mandatory to store the child under that identifier in the map.
  *
- * This type will always produce [observable maps](https://mobx.js.org/refguide/map.html)
+ * This type will always produce [observable maps](https://mobx.js.org/api.html#observablemap)
  *
  * Example:
  * ```ts
@@ -5340,7 +5373,6 @@ var ArrayType = /** @class */ (function (_super) {
             writable: true,
             value: []
         });
-        mobx.makeObservable(_this);
         _this.hookInitializers = hookInitializers;
         return _this;
     }
@@ -5589,15 +5621,13 @@ var ArrayType = /** @class */ (function (_super) {
             node.storedValue.splice(Number(subpath), 1);
         }
     });
-    __decorate([
-        mobx.action
-    ], ArrayType.prototype, "applySnapshot", null);
     return ArrayType;
 }(ComplexType));
+ArrayType.prototype.applySnapshot = mobx.action(ArrayType.prototype.applySnapshot);
 /**
  * `types.array` - Creates an index based collection type who's children are all of a uniform declared type.
  *
- * This type will always produce [observable arrays](https://mobx.js.org/refguide/array.html)
+ * This type will always produce [observable arrays](https://mobx.js.org/api.html#observablearray)
  *
  * Example:
  * ```ts
@@ -5738,8 +5768,8 @@ function areSame(oldNode, newValue) {
         oldNode.identifier !== null &&
         oldNode.identifierAttribute &&
         isPlainObject(newValue) &&
-        oldNode.identifier === normalizeIdentifier(newValue[oldNode.identifierAttribute]) &&
-        oldNode.type.is(newValue));
+        oldNode.type.is(newValue) &&
+        oldNode.type.isMatchingSnapshotId(oldNode, newValue));
 }
 /**
  * Returns if a given value represents an array type.
@@ -5902,7 +5932,6 @@ var ModelType = /** @class */ (function (_super) {
                     });
             }
         });
-        mobx.makeObservable(_this);
         Object.assign(_this, defaultObjectOptions, opts);
         // ensures that any default value gets converted to its related type
         _this.properties = toPropertiesObject(_this.properties);
@@ -6065,19 +6094,8 @@ var ModelType = /** @class */ (function (_super) {
                 // is this a computed property?
                 var descriptor = Object.getOwnPropertyDescriptor(views, key);
                 if ("get" in descriptor) {
-                    if (mobx.isComputedProp(self, key)) {
-                        var computedValue = mobx._getAdministration(self, key);
-                        // TODO: mobx currently does not allow redefining computes yet, pending #1121
-                        // FIXME: this binds to the internals of mobx!
-                        computedValue.derivation = descriptor.get;
-                        computedValue.scope = self;
-                        if (descriptor.set)
-                            computedValue.setter = mobx.action(computedValue.name + "-setter", descriptor.set);
-                    }
-                    else {
-                        Object.defineProperty(self, key, descriptor);
-                        mobx.makeObservable(self, (_a = {}, _a[key] = mobx.computed, _a));
-                    }
+                    mobx.defineProperty(self, key, descriptor);
+                    mobx.makeObservable(self, (_a = {}, _a[key] = mobx.computed, _a));
                 }
                 else if (typeof descriptor.value === "function") {
                     (!devMode() ? addHiddenFinalProp : addHiddenWritableProp)(self, key, descriptor.value);
@@ -6341,11 +6359,9 @@ var ModelType = /** @class */ (function (_super) {
             node.storedValue[subpath] = undefined;
         }
     });
-    __decorate([
-        mobx.action
-    ], ModelType.prototype, "applySnapshot", null);
     return ModelType;
 }(ComplexType));
+ModelType.prototype.applySnapshot = mobx.action(ModelType.prototype.applySnapshot);
 /**
  * `types.model` - Creates a new model type by providing a name, properties, volatile state and actions.
  *
@@ -6907,7 +6923,7 @@ var Union = /** @class */ (function (_super) {
         configurable: true,
         writable: true,
         value: function (current, newValue, parent, subpath) {
-            var type = this.determineType(newValue, current.type);
+            var type = this.determineType(newValue, current.getReconciliationType());
             if (!type)
                 throw fail$1("No matching type for union " + this.describe()); // can happen in prod builds
             return type.reconcile(current, newValue, parent, subpath);