dataflux 1.1.2 → 1.2.0

package/README.md

@@ -48,7 +48,7 @@ export default store;
 
 The store can be initialized with [various options](#configuration). You need only one store for the entire application, that's why you should declare it in its own file and import it in multiple places.
 
-The creation of a model requires at least a name and an url. GET, POST, PUT, and DELETE operations are going to be performed against the same url. [Models can be created with considerably more advanced options.](#models-creation)
+The creation of a model requires at least a name and a url. GET, POST, PUT, and DELETE operations are going to be performed against the same url. [Models can be created with considerably more advanced options.](#models-creation)
 
 A JS object is automatically created for each item returned by the API, for each model. The object has the same properties of the JSON item plus some high-level method (see [objects methods](#objects-methods)).
 **All the objects are indexed in the store.**
@@ -219,39 +219,78 @@ A model can be simply created with:
 const book = new Model("book", `https://rest.example.net/api/v1/books`);
 ```
 
-However, in many cases more complex APIs require different settings for the various operations.
+However, sometimes you may want to define a more complex interaction with the API. In such cases you can pass options to perform more elaborated model's initializations.
+
+```js
+const book = new Model("book", options);
+```
+
+All the possible options for a model creation are (they are all optional):
+
+| Name     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Default              |
+|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------|
+| retrieve | Describes the operation to retrieve the collection of objects from the REST API. It can be an operation object or a function. See [operations](#operations).                                                                                                                                                                                                                                                                                                                                                                                                                  | `{method: "get"}`    |
+| insert   | Describes the operation to insert a new object in the collection. It can be an operation object or a function. See [operations](#operations).                                                                                                                                                                                                                                                                                                                                                                                                                                 | `{method: "post"}`   |
+| update   | Describes the operation to update objects of the collection. It can be an operation object or a function. See [operations](#operations).                                                                                                                                                                                                                                                                                                                                                                                                                                      | `{method: "put"}`    |
+| delete   | Describes the operation to remove objects from the collection. It can be an operation object or a function. See [operations](#operations).                                                                                                                                                                                                                                                                                                                                                                                                                                    | `{method: "delete"}` |
+| fields   | An array of strings defining which attributes the retrieved objects should have. Essentially, it allows you to contemporarily specify the [X-Fields header](https://flask-restplus.readthedocs.io/en/stable/mask.html) and the [fields GET parameter](https://developers.google.com/slides/api/guides/performance#partial). This reduces transfer size and memory usage. E.g., if you have a collection of books, of which you are interested only in the name, you can define `fields: ["name"]`. In combination with `load` it allows for partial lazy load of the objects. | All the fields       |
+| headers  | A dictionary of headers for the HTTP request. E.g., `{"Authorization": "bearer XXXX"}`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | No headers           |
+| load     | A function that allows to enrich the objects on demand. E.g., you can use `fields` to download only the titles of a collection of books, and `load` to load completely the object. See [object enrichment](#object-enrichment).                                                                                                                                                                                                                                                                                                                                               |
+| axios    | It allows to specify an axios instance to be used for the queries. If not specified, a new one will be used.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | A new axios instance |
 
-Instead of an url, you can pass options to perform more elaborated Model's initializations.
+
+### 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.
+
+#### Operation object
+
+An operation object is an object like follows:
+
+```json
+{
+  "method": "get",
+  "url": "https://api.example.com",
+  "headers": {"Authorization": "bearer XXXX"}
+}
+```
+
+Usage example:
 
 ```js
 const options = {
+
   retrieve: {
     method: "get",
-    url: "https://rest.example.net/api/v1/books"
+    url: "https://rest.example.net/api/v1/books",
+    headers: {} // Headers can be define per operation or globally
   },
+
   insert: {
     method: "post",
     url: "https://rest.example.net/api/v1/books"
   },
+
   update: {
     method: "put",
     url: "https://rest.example.net/api/v1/books"
   },
+
   delete: {
     method: "delete",
     url: "https://rest.example.net/api/v1/books"
-  }
+  },
+
+  headers: {"Authorization": "bearer XXXX"} // Globally defined headers
 };
 
 const book = new Model("book", options);
 ```
-You don't necessarily need to specify a url for each operation. If a url is not specified for an operation, the url defined for the `GET` operation is used.
+You don't need to specify all the attributes for each operation, only the ones you want to variate from the defaults (see table above). If a url is not specified for an operation, the url defined for the `GET` operation is used.
 
-For example, if you want to perform both inserts and updates with `PUT`, you can do:
+For example, if you are ok with the default behaviour except you want to perform both inserts and updates with `PUT` (instead of post/put), you can do:
 ```js
 const options = {
   retrieve: {
-    method: "get",
     url: "https://rest.example.net/api/v1/books"
   },
   insert: {
@@ -262,7 +301,9 @@ const options = {
 const book = new Model("book", options);
 ```
 
-Or, even more flexible, you can pass functions and handle yourself the operations. The functions MUST return promises.
+#### 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.
 
 
 ```js
@@ -276,7 +317,7 @@ const options = {
   insert: (data) => {
     // 1) recieve the data from the store
     // 2) transform the data however you like 
-    // 3) send data to server
+    // 3) send data to server and resolve empty
     return Promise.resolve();
   }
 };
@@ -284,16 +325,49 @@ const options = {
 const book = new Model("book", options);
 ```
 
-All the possible options for a model creation are:
+#### Object enrichment
+
+DataFlux objects can have a `load()` method which enables you to load extra attributes of an object.
+
+Example of usage of `load()`:
+
+```js
+console.log(book);
+// {title: "The little prince"}
+
+book.load();
+// The book object will be updated and it will contain
+// {id: 23, title: "The little prince", price: 9.99, year: 1943}
+//
+// If you are using React, book.load() will automatically update your state
+```
+
 
-| Name     | Description                                                                                                                                                       |
-|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| retrieve | Describes the operation to retrieve a collection of objects from a REST API. It can be an object containing `method` and `url` or a function. See examples above. |
-| insert   | Describes the operation to insert a new object in the collection. It can be an object containing `method` and `url` or a function. See examples above.            |
-| update   | Describes the operation to update objects of the collection. It can be an object containing `method` and `url` or a function. See examples above.                 |
-| delete   | Describes the operation to remove objects from the collection. It can be an object containing `method` and `url` or a function. See examples above.               |
-| axios    | It allows to specify an axios instance to be used for the queries. If not specified, a new one will be used.                                                      |
 
+To enable such a method, you have to define the `load` option during model creation. The load option accepts a function that returns the complete object of a url. The function receives in input the current JSON object.
+
+Example of creation of a model with `load` support:
+```js
+const book = new Model("book", {
+  retrieve: {
+    url: "https://rest.example.net/api/v1/books/"
+  },
+  fields: ["title"], // By default the books will contain only the title
+  load: (object) => { // "object" contains the current object to be enriched
+
+    // Return the url where to retrieve the object
+    return "https://rest.example.net/api/v1/books/" + object.id;
+  }
+});
+```
+Alternatively, the `load` function can return directly the enriched object.
+```js
+const book = new Model("book", {
+  load: (object) => {
+    return axios({...}).then(raw => raw.data);
+  }
+});
+```
 
 ### Model relations
 

package/dist/Model.js

@@ -69,6 +69,8 @@ var _batchSize = /*#__PURE__*/new WeakMap();
 
 var _axios = /*#__PURE__*/new WeakMap();
 
+var _loadFunction = /*#__PURE__*/new WeakMap();
+
 var _addRelationByField = /*#__PURE__*/new WeakMap();
 
 var _addRelationByFilter = /*#__PURE__*/new WeakMap();
@@ -140,6 +142,11 @@ var Model = /*#__PURE__*/_createClass(function Model(name) {
     value: void 0
   });
 
+  _classPrivateFieldInitSpec(this, _loadFunction, {
+    writable: true,
+    value: void 0
+  });
+
   _defineProperty(this, "getStore", function () {
     return _classPrivateFieldGet(_this, _store);
   });
@@ -152,6 +159,38 @@ var Model = /*#__PURE__*/_createClass(function Model(name) {
     }
   });
 
+  _defineProperty(this, "load", function (obj) {
+    return new Promise(function (resolve, reject) {
+      var applyData = function applyData(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.");
+          }
+        }
+      };
+
+      if (_classPrivateFieldGet(_this, _loadFunction)) {
+        var res = _classPrivateFieldGet(_this, _loadFunction).call(_this, obj.toJson());
+
+        if (typeof res === "string") {
+          _classPrivateFieldGet(_this, _axios).call(_this, {
+            method: "get",
+            url: res,
+            responseType: "json"
+          }).then(function (data) {
+            return applyData(data.data);
+          }).then(resolve);
+        } else {
+          res.then(applyData).then(resolve);
+        }
+      } else {
+        reject("You must define a loading function in the model to enable load().");
+      }
+    });
+  });
+
   _defineProperty(this, "addRelation", function (model, param2, param3) {
     if (model) {
       _this.getStore().validateModel(model);
@@ -285,10 +324,16 @@ var Model = /*#__PURE__*/_createClass(function Model(name) {
 
   _classPrivateFieldSet(this, _axios, options.axios || _axios2["default"]);
 
+  _classPrivateFieldSet(this, _loadFunction, options.load || null);
+
   if (!name || !options) {
     throw new Error("A Model requires at least a name and a hook");
   }
 
+  if (_classPrivateFieldGet(this, _loadFunction) && typeof _classPrivateFieldGet(this, _loadFunction) !== "function") {
+    throw new Error("The load option must be a function");
+  }
+
   var _ref = _typeof(options) === "object" ? (0, _modelHooksUtils.getHooksFromOptions)(options) : (0, _modelHooksUtils.getHooksFromUrl)(options),
       _ref2 = _slicedToArray(_ref, 4),
       retrieveHook = _ref2[0],

package/dist/StoreObject.js

@@ -19,11 +19,44 @@ 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; }
 
+function _classPrivateFieldInitSpec(obj, privateMap, value) { _checkPrivateRedeclaration(obj, privateMap); privateMap.set(obj, value); }
+
+function _checkPrivateRedeclaration(obj, privateCollection) { if (privateCollection.has(obj)) { throw new TypeError("Cannot initialize the same private elements twice on an object"); } }
+
+function _classPrivateFieldSet(receiver, privateMap, value) { var descriptor = _classExtractFieldDescriptor(receiver, privateMap, "set"); _classApplyDescriptorSet(receiver, descriptor, value); return value; }
+
+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; } }
+
+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); }
+
+function _classApplyDescriptorGet(receiver, descriptor) { if (descriptor.get) { return descriptor.get.call(receiver); } return descriptor.value; }
+
+var _loaded = /*#__PURE__*/new WeakMap();
+
 var Obj = /*#__PURE__*/_createClass(function Obj(values, model) {
   var _this = this;
 
   _classCallCheck(this, Obj);
 
+  _classPrivateFieldInitSpec(this, _loaded, {
+    writable: true,
+    value: false
+  });
+
+  _defineProperty(this, "load", function () {
+    if (_classPrivateFieldGet(_this, _loaded)) {
+      return Promise.resolve(_this);
+    } else {
+      return _this.getModel().load(_this).then(function () {
+        _classPrivateFieldSet(_this, _loaded, true);
+
+        return _this;
+      });
+    }
+  });
+
   _defineProperty(this, "getFingerprint", function () {
     return (0, _fingerprint["default"])(_this.toJson());
   });

package/dist/modelHooksUtils.js

@@ -5,23 +5,46 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.getHooksFromUrl = exports.getHooksFromOptions = exports.executeHook = void 0;
 
+var _brembo = _interopRequireDefault(require("brembo"));
+
+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); }
 
-var getDataStringHook = function getDataStringHook(url) {
-  var method = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : "get";
-  var data = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : null;
-  var axios = arguments.length > 3 ? arguments[3] : undefined;
-  return axios({
-    url: url,
-    method: method,
+var getDataStringHook = function getDataStringHook(hook) {
+  var data = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : null;
+  var axios = arguments.length > 2 ? arguments[2] : undefined;
+  var options = {
+    url: hook.url,
+    method: hook.method || "get",
     data: data,
     reponseType: 'json'
-  }).then(function (data) {
+  };
+
+  if (hook.headers) {
+    options.headers = hook.headers;
+  }
+
+  if (hook.fields) {
+    setFields(options, hook);
+  }
+
+  return axios(options).then(function (data) {
     return data.data;
   });
 };
 
-var createHookItem = function createHookItem(optionItem, defaultMethod, defaultUrl) {
+var setFields = function setFields(options, hook) {
+  options.headers = options.headers || {};
+  options.headers['X-Fields'] = hook.fields;
+  options.url = _brembo["default"].build(options.url, {
+    params: {
+      fields: hook.fields.join(",")
+    }
+  });
+};
+
+var createHookItem = function createHookItem(optionItem, defaultMethod, defaultUrl, options) {
   switch (_typeof(optionItem)) {
     case "undefined":
       if (!defaultUrl) {
@@ -44,7 +67,9 @@ var createHookItem = function createHookItem(optionItem, defaultMethod, defaultU
     case "object":
       return {
         method: optionItem.method || defaultMethod,
-        url: optionItem.url || defaultUrl
+        url: optionItem.url || defaultUrl,
+        fields: options.fields || [],
+        headers: optionItem.headers || options.headers || {}
       };
 
     default:
@@ -54,7 +79,7 @@ var createHookItem = function createHookItem(optionItem, defaultMethod, defaultU
 
 var getHooksFromOptions = function getHooksFromOptions(options) {
   var defaultUrl = typeof options.retrieve === "function" ? null : options.retrieve.url;
-  return [createHookItem(options.retrieve, "get", defaultUrl), createHookItem(options.insert, "post", defaultUrl), createHookItem(options.update, "put", defaultUrl), createHookItem(options["delete"], "delete", defaultUrl)];
+  return [createHookItem(options.retrieve, "get", defaultUrl, options), createHookItem(options.insert, "post", defaultUrl, options), createHookItem(options.update, "put", defaultUrl, options), createHookItem(options["delete"], "delete", defaultUrl, options)];
 };
 
 exports.getHooksFromOptions = getHooksFromOptions;
@@ -82,7 +107,7 @@ var executeHook = function executeHook(type, hook, data, axios) {
 
   switch (hookType) {
     case "object":
-      return getDataStringHook(hook.url, hook.method, data, axios);
+      return getDataStringHook(hook, data, axios);
 
     case "function":
       return hook(data);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dataflux",
-  "version": "1.1.2",
+  "version": "1.2.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",
@@ -78,13 +78,13 @@
   },
   "devDependencies": {
     "@babel/cli": "^7.16.8",
-    "@babel/core": "^7.16.10",
+    "@babel/core": "^7.16.12",
     "@babel/node": "^7.16.8",
     "@babel/plugin-proposal-class-properties": "^7.16.7",
     "@babel/plugin-proposal-object-rest-spread": "^7.16.7",
     "@babel/plugin-transform-async-to-generator": "^7.16.8",
     "@babel/plugin-transform-runtime": "^7.16.10",
-    "@babel/preset-env": "^7.16.10",
+    "@babel/preset-env": "^7.16.11",
     "@babel/preset-react": "^7.16.7",
     "dotenv-cli": "^4.1.1",
     "release-it": "^14.12.3"
@@ -92,6 +92,7 @@
   "dependencies": {
     "axios": "^0.25.0",
     "batch-promises": "^0.0.3",
+    "brembo": "^2.0.6",
     "crc-32": "^1.2.0",
     "uuid": "^8.3.2"
   },