dataflux 1.6.1 → 1.7.2

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,84 @@ 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
+
+    if (params) {
+      // You can return a URL or directly one or more JSON objects
+      return `https://api.example.net/authors/${params.id}`
+    } else {
+      return Promise.resolve([]); // It's important to handle the base case where params is null
+    }
+  }
+});
+
+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 +583,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/BasicObj.js

@@ -48,7 +48,9 @@ function setValues(values, model, SubObj, parent, context) {
       context[key] = mmnt.isValid() ? mmnt : value;
     } else if (model.options.deep && value != null && _typeof(value) === "object" && !Array.isArray(value)) {
       context[key] = new SubObj(parent, key, value, model);
-    } else if (model.options.deep && value != null && Array.isArray(value)) {
+    } else if (model.options.deep && value != null && Array.isArray(value) && !value.some(function (str) {
+      return ["string", "number"].includes(_typeof(str));
+    })) {
       context[key] = value.map(function (i) {
         return new SubObj(parent, key, i, model);
       });

package/dist/Model.js

@@ -17,8 +17,6 @@ var _SubObj = _interopRequireDefault(require("./SubObj"));
 
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { "default": obj }; }
 
-function _typeof(obj) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (obj) { return typeof obj; } : function (obj) { return obj && "function" == typeof Symbol && obj.constructor === Symbol && obj !== Symbol.prototype ? "symbol" : typeof obj; }, _typeof(obj); }
-
 function _slicedToArray(arr, i) { return _arrayWithHoles(arr) || _iterableToArrayLimit(arr, i) || _unsupportedIterableToArray(arr, i) || _nonIterableRest(); }
 
 function _nonIterableRest() { throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
@@ -31,6 +29,8 @@ function ownKeys(object, enumerableOnly) { var keys = Object.keys(object); if (O
 
 function _objectSpread(target) { for (var i = 1; i < arguments.length; i++) { var source = null != arguments[i] ? arguments[i] : {}; i % 2 ? ownKeys(Object(source), !0).forEach(function (key) { _defineProperty(target, key, source[key]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(target, Object.getOwnPropertyDescriptors(source)) : ownKeys(Object(source)).forEach(function (key) { Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key)); }); } return target; }
 
+function _typeof(obj) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (obj) { return typeof obj; } : function (obj) { return obj && "function" == typeof Symbol && obj.constructor === Symbol && obj !== Symbol.prototype ? "symbol" : typeof obj; }, _typeof(obj); }
+
 function _createForOfIteratorHelper(o, allowArrayLike) { var it = typeof Symbol !== "undefined" && o[Symbol.iterator] || o["@@iterator"]; if (!it) { if (Array.isArray(o) || (it = _unsupportedIterableToArray(o)) || allowArrayLike && o && typeof o.length === "number") { if (it) o = it; var i = 0; var F = function F() {}; return { s: F, n: function n() { if (i >= o.length) return { done: true }; return { done: false, value: o[i++] }; }, e: function e(_e2) { throw _e2; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var normalCompletion = true, didErr = false, err; return { s: function s() { it = it.call(o); }, n: function n() { var step = it.next(); normalCompletion = step.done; return step; }, e: function e(_e3) { didErr = true; err = _e3; }, f: function f() { try { if (!normalCompletion && it["return"] != null) it["return"](); } finally { if (didErr) throw err; } } }; }
 
 function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
@@ -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();
@@ -272,13 +260,11 @@ var Model = /*#__PURE__*/_createClass(function Model(name) {
 
   _defineProperty(this, "retrieveAll", function () {
     return (0, _modelHooksUtils.executeHook)("retrieve", _classPrivateFieldGet(_this, _retrieveHook), null, _classPrivateFieldGet(_this, _axios)).then(function (data) {
-      if (Array.isArray(data)) {
-        return data;
-      } else {
+      if (!Array.isArray(data)) {
         _classPrivateFieldSet(_this, _singleItemQuery, true);
-
-        return [data];
       }
+
+      return _classPrivateFieldGet(_this, _toArray).call(_this, data);
     });
   });
 
@@ -294,6 +280,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) {
@@ -355,9 +349,23 @@ var Model = /*#__PURE__*/_createClass(function Model(name) {
     writable: true,
     value: function value(data) {
       if (Array.isArray(data)) {
-        return data;
+        if (data.every(function (str) {
+          return ["string", "number"].includes(_typeof(str));
+        })) {
+          return [{
+            value: data
+          }];
+        } else {
+          return data;
+        }
       } else {
-        return [data];
+        if (["string", "number"].includes(_typeof(data))) {
+          return [{
+            value: data
+          }];
+        } else {
+          return [data];
+        }
       }
     }
   });
@@ -387,7 +395,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

@@ -29,6 +29,8 @@ function _classPrivateMethodInitSpec(obj, privateSet) { _checkPrivateRedeclarati
 
 function _checkPrivateRedeclaration(obj, privateCollection) { if (privateCollection.has(obj)) { throw new TypeError("Cannot initialize the same private elements twice on an object"); } }
 
+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; }
+
 function _classPrivateFieldGet(receiver, privateMap) { var descriptor = _classExtractFieldDescriptor(receiver, privateMap, "get"); return _classApplyDescriptorGet(receiver, descriptor); }
 
 function _classExtractFieldDescriptor(receiver, privateMap, action) { if (!privateMap.has(receiver)) { throw new TypeError("attempted to " + action + " private field on non-instance"); } return privateMap.get(receiver); }
@@ -67,6 +69,10 @@ var Store = /*#__PURE__*/function () {
 
     _classPrivateMethodInitSpec(this, _error);
 
+    _defineProperty(this, "getModels", function () {
+      return Object.keys(_this.models);
+    });
+
     _classPrivateFieldInitSpec(this, _deleteByObject, {
       writable: true,
       value: function value(object) {
@@ -114,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";
@@ -290,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;
@@ -304,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) {
@@ -332,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");
@@ -340,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;
@@ -367,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", {
@@ -375,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

@@ -65,7 +65,18 @@ var createHookItem = function createHookItem(optionItem, defaultMethod, defaultU
 
     case "function":
       return function (data) {
-        return Promise.resolve(optionItem(data));
+        var res = optionItem(data);
+
+        if (typeof res === "string") {
+          return {
+            method: defaultMethod,
+            url: res,
+            fields: options.fields || [],
+            headers: options.headers || {}
+          };
+        } else {
+          return Promise.resolve(res);
+        }
       };
 
     case "object":
@@ -114,7 +125,13 @@ var executeHook = function executeHook(type, hook, data, axios) {
       return getDataStringHook(hook, data, axios);
 
     case "function":
-      return hook(data);
+      var res = hook(data);
+
+      if (res.method && res.url && res.headers) {
+        return getDataStringHook(res, data, axios);
+      } else {
+        return 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.1",
+  "version": "1.7.2",
   "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