docs (easyComp): comment the render function logic

Author: solkimicreb

dist/clock.js

@@ -14523,8 +14523,10 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.default = autoBind;
+// do not bind these, they should not be directly invoked or passed as callbacks by the user
 var reactInternals = new Set(['constructor', 'render', 'componentWillMount', 'componentDidMount', 'componentWillReceiveProps', 'shouldComponentUpdate', 'componentWillUpdate', 'componentDidUpdate', 'componentWillUnmount']);
 
+// bind the methods from proto to the passed context object and assign them to the context
 function autoBind(context, proto, isReact) {
   var _iteratorNormalCompletion = true;
   var _didIteratorError = false;
@@ -27058,7 +27060,7 @@ var _get = function get(object, property, receiver) { if (object === null) objec
 
 var _createClass = function () { function defineProperties(target, props) { for (var i = 0; i < props.length; i++) { var descriptor = props[i]; descriptor.enumerable = descriptor.enumerable || false; descriptor.configurable = true; if ("value" in descriptor) descriptor.writable = true; Object.defineProperty(target, descriptor.key, descriptor); } } return function (Constructor, protoProps, staticProps) { if (protoProps) defineProperties(Constructor.prototype, protoProps); if (staticProps) defineProperties(Constructor, staticProps); return Constructor; }; }();
 
-exports.default = easyCompHOC;
+exports.default = easyComp;
 
 var _react = __webpack_require__(25);
 
@@ -27076,91 +27078,129 @@ function _possibleConstructorReturn(self, call) { if (!self) { throw new Referen
 
 function _inherits(subClass, superClass) { if (typeof superClass !== "function" && superClass !== null) { throw new TypeError("Super expression must either be null or a function, not " + typeof superClass); } subClass.prototype = Object.create(superClass && superClass.prototype, { constructor: { value: subClass, enumerable: false, writable: true, configurable: true } }); if (superClass) Object.setPrototypeOf ? Object.setPrototypeOf(subClass, superClass) : subClass.__proto__ = superClass; }
 
-var OBSERVED_RENDER = Symbol('observed render');
-var IS_DIRECT_RENDER = Symbol('is direct render');
-var RENDER_RESULT = Symbol('render result');
+var REACTIVE_RENDER = Symbol('reactive render');
 
-function easyCompHOC(WrappedComp) {
-  if (typeof WrappedComp !== 'function') {
-    throw new TypeError('easyComp expects a component class or function as argument.');
+function easyComp(Comp) {
+  if (typeof Comp !== 'function') {
+    throw new TypeError('easyComp expects a component as argument.');
   }
 
-  if ((!WrappedComp.prototype || !WrappedComp.prototype.render) && !WrappedComp.isReactClass && !_react.Component.isPrototypeOf(WrappedComp)) {
-    var renderer = WrappedComp;
-    WrappedComp = function (_Component) {
-      _inherits(WrappedComp, _Component);
+  // wrap stateless components in a class
+  if (isStatelessComp(Comp)) {
+    Comp = statelessToStatefulComp(Comp);
+  } else if (hasComponentShouldUpdate(Comp)) {
+    // shouldComponentUpdate is optimized by easyState, overwriting it would add zero or less value
+    throw new Error('easyState optimizes shouldComponentUpdate, do not implement it.');
+  }
+
+  return toReactiveComp(Comp);
+}
+
+function isStatelessComp(Comp) {
+  return !(Comp.prototype && Comp.prototype.render) && !_react.Component.isPrototypeOf(Comp);
+}
+
+function statelessToStatefulComp(StatelessComp) {
+  var _class, _temp;
+
+  return _temp = _class = function (_Component) {
+    _inherits(StatefulComp, _Component);
+
+    function StatefulComp() {
+      _classCallCheck(this, StatefulComp);
+
+      return _possibleConstructorReturn(this, (StatefulComp.__proto__ || Object.getPrototypeOf(StatefulComp)).apply(this, arguments));
+    }
+
+    _createClass(StatefulComp, [{
+      key: 'render',
+
 
-      function WrappedComp() {
-        _classCallCheck(this, WrappedComp);
+      // call the original function component inside the render method
 
-        return _possibleConstructorReturn(this, (WrappedComp.__proto__ || Object.getPrototypeOf(WrappedComp)).apply(this, arguments));
+      // proxy react specific static variables to the stateful component
+      // from the stateless component
+      value: function render() {
+        return StatelessComp.call(this, this.props, this.context);
       }
+    }]);
 
-      _createClass(WrappedComp, [{
-        key: 'render',
-        value: function render() {
-          return renderer.call(this, this.props, this.context);
-        }
-      }]);
+    return StatefulComp;
+  }(_react.Component), _class.displayName = StatelessComp.displayName || StatelessComp.name, _class.contextTypes = StatelessComp.contextTypes, _class.propTypes = StatelessComp.propTypes, _class.defaultProps = StatelessComp.defaultProps, _temp;
+}
 
-      return WrappedComp;
-    }(_react.Component);
-    WrappedComp.displayName = renderer.displayName || renderer.name;
-    WrappedComp.contextTypes = renderer.contextTypes;
-    WrappedComp.propTypes = renderer.propTypes;
-    WrappedComp.defaultProps = renderer.defaultProps;
-  }
+function hasComponentShouldUpdate(Comp) {
+  return typeof Comp.prototype.shouldComponentUpdate === 'function';
+}
 
-  if (typeof WrappedComp.prototype.shouldComponentUpdate === 'function') {
-    throw new Error('Do not implement shouldComponentUpdate, easyState already optimizes it for you!');
-  }
+function toReactiveComp(Comp) {
+  var _class2, _temp2;
 
-  return function (_WrappedComp) {
-    _inherits(EasyCompWrapper, _WrappedComp);
+  // return a HOC which overwrites render, shouldComponentUpdate and componentWillUnmount
+  // it decides when to run the new reactive methods and when to proxy to the original methods
+  return _temp2 = _class2 = function (_Comp) {
+    _inherits(EasyHOC, _Comp);
 
-    function EasyCompWrapper(props) {
-      _classCallCheck(this, EasyCompWrapper);
+    // proxy react specific static variables to the HOC from the component
+    function EasyHOC(props) {
+      _classCallCheck(this, EasyHOC);
 
-      var _this2 = _possibleConstructorReturn(this, (EasyCompWrapper.__proto__ || Object.getPrototypeOf(EasyCompWrapper)).call(this, props));
+      // auto bind non react specific original methods to the component instance
+      var _this2 = _possibleConstructorReturn(this, (EasyHOC.__proto__ || Object.getPrototypeOf(EasyHOC)).call(this, props));
 
-      (0, _autoBind2.default)(_this2, WrappedComp.prototype, true);
+      (0, _autoBind2.default)(_this2, Comp.prototype, true);
+
+      // turn the state into an observable object, which triggers rendering on mutations
       _this2.state = (0, _observerUtil.observable)(_this2.state);
       return _this2;
     }
 
-    _createClass(EasyCompWrapper, [{
+    _createClass(EasyHOC, [{
       key: 'render',
       value: function render() {
         var _this3 = this;
 
-        if (!this[OBSERVED_RENDER]) {
-          this[OBSERVED_RENDER] = function () {
-            if (_this3[IS_DIRECT_RENDER]) {
-              _this3[RENDER_RESULT] = _get(EasyCompWrapper.prototype.__proto__ || Object.getPrototypeOf(EasyCompWrapper.prototype), 'render', _this3).call(_this3);
+        // if it is the first direct render from react call there is no reactive render yet
+        if (!this[REACTIVE_RENDER]) {
+          var result = void 0;
+          // create a reactive render, which is automatically called by easyState on relevant state and store mutations
+          // the passed function is executed right away synchronously once by easyState
+          this[REACTIVE_RENDER] = (0, _observerUtil.observe)(function () {
+            // if it is the first (synchronous) execution, call the original component's render
+            // this is necessary because forceUpdate can not be called synchronously inside render functions
+            if (!_this3[REACTIVE_RENDER]) {
+              result = _get(EasyHOC.prototype.__proto__ || Object.getPrototypeOf(EasyHOC.prototype), 'render', _this3).call(_this3);
             } else {
-              _get(EasyCompWrapper.prototype.__proto__ || Object.getPrototypeOf(EasyCompWrapper.prototype), 'forceUpdate', _this3).call(_this3);
+              // if it is a later reactive, asynchronous execution - triggered by easyState - forceUpdate the original component
+              // this is necessary, because calling render would require the result to be returned
+              // which is not possible from this asynchronous context
+              _get(EasyHOC.prototype.__proto__ || Object.getPrototypeOf(EasyHOC.prototype), 'forceUpdate', _this3).call(_this3);
             }
-          };
+          });
+          // return the result from super.render() inside the reactive render on the first render execution
+          return result;
+        } else {
+          // return the original component's render result on direct calls from react
+          return _get(EasyHOC.prototype.__proto__ || Object.getPrototypeOf(EasyHOC.prototype), 'render', this).call(this);
         }
+      }
 
-        this[IS_DIRECT_RENDER] = true;
-        this[OBSERVED_RENDER] = (0, _observerUtil.observe)(this[OBSERVED_RENDER]);
-        this[IS_DIRECT_RENDER] = false;
+      // react should trigger updates on prop changes, while easyState handles state changes
 
-        return this[RENDER_RESULT];
-      }
     }, {
       key: 'shouldComponentUpdate',
-      value: function shouldComponentUpdate(nextProps, nextState) {
+      value: function shouldComponentUpdate(nextProps) {
         var props = this.props;
 
         var keys = Object.keys(props);
         var nextKeys = Object.keys(nextProps);
 
+        // component should update if the number of its props changed
         if (keys.length !== nextKeys.length) {
           return true;
         }
 
+        // component should update if any of its props changed value
         var _iteratorNormalCompletion = true;
         var _didIteratorError = false;
         var _iteratorError = undefined;
@@ -27173,6 +27213,8 @@ function easyCompHOC(WrappedComp) {
               return true;
             }
           }
+
+          // do not let react update the comp otherwise, leave state triggered updates to easyState
         } catch (err) {
           _didIteratorError = true;
           _iteratorError = err;
@@ -27193,15 +27235,19 @@ function easyCompHOC(WrappedComp) {
     }, {
       key: 'componentWillUnmount',
       value: function componentWillUnmount() {
-        if (_get(EasyCompWrapper.prototype.__proto__ || Object.getPrototypeOf(EasyCompWrapper.prototype), 'componentWillUnmount', this)) {
-          return _get(EasyCompWrapper.prototype.__proto__ || Object.getPrototypeOf(EasyCompWrapper.prototype), 'componentWillUnmount', this).call(this);
+        // clean up memory used by easyState
+        (0, _observerUtil.unobserve)(this[REACTIVE_RENDER]);
+
+        // also call user defined componentWillUnmount to allow the user
+        // to clean up additional memory
+        if (_get(EasyHOC.prototype.__proto__ || Object.getPrototypeOf(EasyHOC.prototype), 'componentWillUnmount', this)) {
+          _get(EasyHOC.prototype.__proto__ || Object.getPrototypeOf(EasyHOC.prototype), 'componentWillUnmount', this).call(this);
         }
-        (0, _observerUtil.unobserve)(this[OBSERVED_RENDER]);
       }
     }]);
 
-    return EasyCompWrapper;
-  }(WrappedComp);
+    return EasyHOC;
+  }(Comp), _class2.displayName = Comp.displayName || Comp.name, _class2.contextTypes = Comp.contextTypes, _class2.propTypes = Comp.propTypes, _class2.defaultProps = Comp.defaultProps, _temp2;
 }
 
 /***/ }),
@@ -27407,9 +27453,11 @@ function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { de
 
 function easyStore(store) {
   if ((typeof store === 'undefined' ? 'undefined' : _typeof(store)) !== 'object' || store === null) {
-    throw new TypeError('easyStore expects an object as argument.');
+    throw new TypeError('easyStore expects an object as argument');
   }
 
+  // create an observable object from the passed store
+  // and bind all of its methods to the created observable
   var observableStore = (0, _observerUtil.observable)(store);
   (0, _autoBind2.default)(observableStore, store, false);
   return observableStore;