dataflux 1.6.2 → 1.7.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022-present Massimo Candela
+Copyright (c) 2022-present Massimo Candela <https://massimocandela.com>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -276,6 +276,7 @@ All the possible options for a model creation are (they are all optional):
 | parseMoment  | Automatically creates Moment.js objects out of ISO8601 strings. E.g., if an object has a property `createdAt: "2022-01-07T21:38:50.295Z"`, this will be transformed to a moment object.                                                                                                                                                                                                                                                                                                                                                                                       |                      | 
 | hiddenFields | An array of attribute names that will never be sent back to the API. E.g., if you set `hiddenFields: ["pages"]`, a book object can contain an attribute `pages` locally, but this will be stripped out in PUT/POST requests.                                                                                                                                                                                                                                                                                                                                                  |
 | deep         | A boolean defining if nested objects should be enriched with the object methods.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | true                 |
+| lazyLoad     | A boolean defining if the model should be lazy loaded on the first use. This takes precedence over the lazyLoad declared during store initialization.                                                                                                                                                                                                                                                                                                                                                                                                                         | false                |
 
 ### Operations
 As described in the table above, there are four possible operations: **retrieve, insert, update,** and **delete**. An operation can be defined as an operation object or a function.
@@ -341,28 +342,80 @@ const book = new Model("book", options);
 
 #### Operation function
 
-To be even more flexible, you can pass functions and handle yourself the operations. An operation function must return a promise, the promise must return an array of JSON objects when these are ready.
+To be even more flexible, you can pass functions to generate the API urls or retrieve the data. An operation function can return a url or a promise. If the function returns a promise, the promise must resolve in an array of JSON objects when these are ready.
 
 
+Example of operation function returning from the API and submitting to the API an array of JSON objects.
+
 ```js
 const options = {
   retrieve: () => {
     // 1) get the data from the API 
     // 2) tranforms the data
     // 3) return the data to the store
-    return Promise.resolve(data);
+    return axios({ // Example with axios, but you can use whatever you prefer
+      url: "https://api.example.net/example",
+      method: "get"
+    });
   },
   insert: (data) => {
     // 1) recieve the data from the store
     // 2) transform the data however you like 
-    // 3) send data to server and resolve empty
-    return Promise.resolve();
+    // 3) send data to server
+    return axios({
+      url: "https://api.example.net/example",
+      data,
+      method: "post"
+    });
   }
 };
 
 const book = new Model("book", options);
 ```
 
+#### Object factory
+
+In the examples we saw above, objects are retrieved from an API returning one or more objects. However, sometimes object creation requires a more complex logic. This can be summarized as: the object must be created based on some input parameter
+
+Typical examples are:
+* There is no API returning all the objects of a given type, you can only access specific objects based on a parameter (e.g., based on the ID).
+* It doesn't make sense to retrieve all the objects of a given type, since the client needs to access only to a subset of them.
+* The APIs to get/post/put/delete objects are parametric (e.g., you need to specify the ID in the url).
+* The model is polymorphic, and the final object's format is based on some parameter;
+* The model is polymorphic, a different API is used to retrieve the objects based on some input parameter (e.g., they are all books, but there are different APIs by genre).
+
+This is a well-know problem, described by the [factory design pattern](https://refactoring.guru/design-patterns/factory-method).
+In DataFlux, the store provides for this use case the `.factory()` method that allows you to implement Factory.
+
+To create a factory, you must declare a model as follows:
+
+```js
+const author = new Model("author", {
+  lazyLoad: true, // It MUST be lazyLoaded
+  retrieve: ({params}) => { // The retrieve function now takes some parameters
+
+    // You can return a URL or directly one or more JSON objects
+    return `https://api.example.net/authors/${params.id}`;
+  }
+});
+
+store.addModel(author);
+```
+
+It is important to notice in the example above, how `lazyLoad` must be set to `true` and how the retrieve function returns a URL based on an input parameter. As always, the operation function can return a URL (DataFlux will download the objects) or directly a collection of objects.
+
+> If you don't specify the insert/update/delete operation functions, the same URL of the retrieve function will be used.
+
+Once the parametric retrieve function is declared, you can instantiate the objects with the `store.factory()` method:
+
+```js
+store.factory("author", {id: 4});
+```
+Invoking `store.factory()` will create a new object in the "author" collection.
+
+> store.factory() will not return the object. It just inserts the object in the collection. You will need to use any of the usual .find/.findOne/.findAll/.subscribe to retrieve it.
+
+
 #### Object enrichment
 
 DataFlux objects can have a `load()` method which enables you to load extra attributes of an object.
@@ -526,13 +579,13 @@ You can operate on the reviews similarly to how you operate on the main model's
 
 ```js
 store.find("book")
-      .then(([book]) => {
-        const firstReview = book.reviews[0];
+        .then(([book]) => {
+          const firstReview = book.reviews[0];
 
-        // Examples of what you can do:
-        firstReview.detroy(); // The first review is removed from the array book.reviews
-        firstReview.set("stars", 5); // Set the stars of the first review to 5
-      });
+          // Examples of what you can do:
+          firstReview.detroy(); // The first review is removed from the array book.reviews
+          firstReview.set("stars", 5); // Set the stars of the first review to 5
+        });
 ```
 
 

package/dist/Model.js

@@ -63,18 +63,6 @@ function _classExtractFieldDescriptor(receiver, privateMap, action) { if (!priva
 
 function _classApplyDescriptorSet(receiver, descriptor, value) { if (descriptor.set) { descriptor.set.call(receiver, value); } else { if (!descriptor.writable) { throw new TypeError("attempted to set read only private field"); } descriptor.value = value; } }
 
-var applyData = function applyData(obj, data) {
-  for (var att in data) {
-    if (att !== "id" || obj.id === undefined || att === "id" && obj.id === data.id) {
-      obj[att] = data[att];
-    } else {
-      return Promise.reject("The loading function cannot change the id of the object.");
-    }
-  }
-
-  return Promise.resolve(obj);
-};
-
 var _type = /*#__PURE__*/new WeakMap();
 
 var _store = /*#__PURE__*/new WeakMap();
@@ -294,6 +282,14 @@ var Model = /*#__PURE__*/_createClass(function Model(name) {
     return objects.length ? _classPrivateFieldGet(_this, _bulkOperation).call(_this, objects, _classPrivateFieldGet(_this, _deleteObjects)) : Promise.resolve();
   });
 
+  _defineProperty(this, "factory", function (params) {
+    if (!_this.options.lazyLoad) {
+      return Promise.reject("Factory can be used only on a model declared with lazyLoad: true");
+    } else {
+      return (0, _modelHooksUtils.executeHook)("retrieve", _classPrivateFieldGet(_this, _retrieveHook), params, _classPrivateFieldGet(_this, _axios));
+    }
+  });
+
   _classPrivateFieldInitSpec(this, _addRelationByField, {
     writable: true,
     value: function value(model, localField) {
@@ -387,7 +383,8 @@ var Model = /*#__PURE__*/_createClass(function Model(name) {
 
   this.options = _objectSpread(_objectSpread({}, options), {}, {
     deep: (_options$deep = options.deep) !== null && _options$deep !== void 0 ? _options$deep : true,
-    parseMoment: (_options$parseMoment = options.parseMoment) !== null && _options$parseMoment !== void 0 ? _options$parseMoment : false
+    parseMoment: (_options$parseMoment = options.parseMoment) !== null && _options$parseMoment !== void 0 ? _options$parseMoment : false,
+    lazyLoad: options.lazyLoad
   });
 
   _classPrivateFieldSet(this, _store, null);

package/dist/PubSub.js

@@ -19,6 +19,29 @@ function _classCallCheck(instance, Constructor) { if (!(instance instanceof Cons
 
 function _defineProperty(obj, key, value) { if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
 
+/*
+ * MIT License
+ *
+ * Copyright (c) 2022 Massimo Candela <https://massimocandela.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
 var PubSub = /*#__PURE__*/_createClass(function PubSub() {
   var _this = this;
 

package/dist/Store.js

@@ -120,16 +120,19 @@ var Store = /*#__PURE__*/function () {
         var type = model.getType();
 
         if (!_this2.models[type]) {
+          var _model$options$lazyLo;
+
           _this2.models[type] = {
             model: model,
             storedObjects: {}
           };
           model.setStore(_this2);
+          var lazyLoad = (_model$options$lazyLo = model.options.lazyLoad) !== null && _model$options$lazyLo !== void 0 ? _model$options$lazyLo : _this2.options.lazyLoad;
 
-          if (!_this2.options.lazyLoad) {
-            resolve(_classPrivateMethodGet(_this2, _loadObjects, _loadObjects2).call(_this2, type));
-          } else {
+          if (lazyLoad) {
             resolve();
+          } else {
+            resolve(_classPrivateMethodGet(_this2, _loadObjects, _loadObjects2).call(_this2, type));
           }
         } else {
           var error = "The model already exists";
@@ -296,6 +299,38 @@ var Store = /*#__PURE__*/function () {
         };
       });
     }
+  }, {
+    key: "factory",
+    value: function factory(type, params) {
+      var _this8 = this;
+
+      var item = this.models[type];
+      this.pubSub.publish("loading", {
+        status: "start",
+        model: type
+      });
+      return item.promise = item.model.factory(params).then(function (items) {
+        var _iterator3 = _createForOfIteratorHelper(items),
+            _step3;
+
+        try {
+          for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
+            var _item = _step3.value;
+
+            _classPrivateMethodGet(_this8, _insertObject, _insertObject2).call(_this8, type, _item, false);
+          }
+        } catch (err) {
+          _iterator3.e(err);
+        } finally {
+          _iterator3.f();
+        }
+
+        _this8.pubSub.publish("loading", {
+          status: "end",
+          model: type
+        });
+      });
+    }
   }]);
 
   return Store;
@@ -310,25 +345,25 @@ function _error2(error) {
 }
 
 function _deleteByFilter2(type, filterFunction) {
-  var _this8 = this;
+  var _this9 = this;
 
   return _classPrivateMethodGet(this, _getPromise, _getPromise2).call(this, type).then(function () {
-    var deleted = Object.values(_this8.models[type].storedObjects).filter(function (i) {
+    var deleted = Object.values(_this9.models[type].storedObjects).filter(function (i) {
       return filterFunction(i.object);
     });
 
-    var _iterator3 = _createForOfIteratorHelper(deleted),
-        _step3;
+    var _iterator4 = _createForOfIteratorHelper(deleted),
+        _step4;
 
     try {
-      for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
-        var object = _step3.value;
+      for (_iterator4.s(); !(_step4 = _iterator4.n()).done;) {
+        var object = _step4.value;
         object.status = "deleted";
       }
     } catch (err) {
-      _iterator3.e(err);
+      _iterator4.e(err);
     } finally {
-      _iterator3.f();
+      _iterator4.f();
     }
 
     return deleted.map(function (i) {
@@ -338,7 +373,7 @@ function _deleteByFilter2(type, filterFunction) {
 }
 
 function _getPromise2(type) {
-  var _this9 = this;
+  var _this10 = this;
 
   if (!this.models[type]) {
     return Promise.reject("The model doesn't exist");
@@ -346,7 +381,7 @@ function _getPromise2(type) {
     return Promise.reject("The model is not loaded");
   } else if (!this.models[type].promise && this.options.lazyLoad) {
     return _classPrivateMethodGet(this, _loadObjects, _loadObjects2).call(this, type).then(function () {
-      return _this9.models[type].promise;
+      return _this10.models[type].promise;
     });
   } else {
     return this.models[type].promise;
@@ -373,7 +408,7 @@ function _insertObject2(type, item) {
 }
 
 function _loadObjects2(type) {
-  var _this10 = this;
+  var _this11 = this;
 
   var item = this.models[type];
   this.pubSub.publish("loading", {
@@ -381,22 +416,22 @@ function _loadObjects2(type) {
     model: type
   });
   return item.promise = item.model.retrieveAll().then(function (items) {
-    var _iterator4 = _createForOfIteratorHelper(items),
-        _step4;
+    var _iterator5 = _createForOfIteratorHelper(items),
+        _step5;
 
     try {
-      for (_iterator4.s(); !(_step4 = _iterator4.n()).done;) {
-        var _item = _step4.value;
+      for (_iterator5.s(); !(_step5 = _iterator5.n()).done;) {
+        var _item2 = _step5.value;
 
-        _classPrivateMethodGet(_this10, _insertObject, _insertObject2).call(_this10, type, _item, false);
+        _classPrivateMethodGet(_this11, _insertObject, _insertObject2).call(_this11, type, _item2, false);
       }
     } catch (err) {
-      _iterator4.e(err);
+      _iterator5.e(err);
     } finally {
-      _iterator4.f();
+      _iterator5.f();
     }
 
-    _this10.pubSub.publish("loading", {
+    _this11.pubSub.publish("loading", {
       status: "end",
       model: type
     });

package/dist/modelHooksUtils.js

@@ -114,7 +114,8 @@ var executeHook = function executeHook(type, hook, data, axios) {
       return getDataStringHook(hook, data, axios);
 
     case "function":
-      return hook(data);
+      var res = hook(data);
+      return typeof res === "string" ? getDataStringHook(res, data, axios) : res;
 
     default:
       return Promise.reject("The ".concat(type, " hook must be a URL or a function returning a promise"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dataflux",
-  "version": "1.6.2",
+  "version": "1.7.0",
   "description": "DataFlux, automatically interfaces with your REST APIs to create a 2-way-synced local data store. Transparently manages data propagation in the React state.",
   "main": "dist/index.js",
   "bin": "dist/index.js",

package/CNAME

@@ -1 +0,0 @@
-dataflux.js.org

package/_config.yml

@@ -1 +0,0 @@
-theme: jekyll-theme-cayman