dataflux 1.0.2

package/.babelrc

@@ -0,0 +1,20 @@
+{
+  "presets": [
+    "@babel/preset-env"
+  ],
+  "plugins": [
+    "@babel/plugin-proposal-class-properties",
+    "@babel/plugin-transform-async-to-generator",
+    "@babel/plugin-proposal-object-rest-spread"
+  ],
+
+  "ignore": [
+    "./node_modules",
+    "./assets",
+    "./view",
+    "./tests",
+    "./logs",
+    "./dist",
+    "./build"
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Massimo Candela
+
+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.

package/README.md

@@ -0,0 +1,403 @@
+## DataFlux
+
+DataFlux is a JavaScript library that automatically interfaces with your REST APIs to create a 2-way-synced local data store. If used with React, it transparently manages data propagation in the state.
+
+* **Automated:** Given a collection of urls pointing to REST APIs, it creates a data layer (called `store`) able to retrieve, insert, update, delete the objects returned by the API. When objects are edited by the client, the store detects the edited objects and dispatches targeted updates to the APIs. You will **work on local JS objects** (e.g., you can do `myObject.name = "test"`, or `myObject.destroy()`) and **ignore the synchronization with the server** that will happen automagically.
+
+
+* **Observable:** Queries to the store are observable. If you ask the store one or more objects (e.g., a list of books you want to display on your website), the store will track what subset of data you are using and push updates every time any of the object in the subset is subject to a change (e.g., a title of a book displayed on your page is edited or a new book matching the search criteria is added). **This is extremely useful with React!**
+
+
+* **Full control:** If you don't like the store to manage the ORM operations automatically, you can set `autoSave: false` and explicitly tell the store when to save (i.e., `store.save()`). Additionally, you can control the single objects individually (e.g., `myObject.save()`). You can also set `lazyLoad: true` and only retrieve the data from the API when requested (e.g., if you never search for books, these will never be retrieved)
+
+
+## Installation
+
+```sh
+npm install dataflux
+```
+
+## Examples
+
+Consider the following store/model declaration common to all the examples below:
+```js
+import {Store, Model} from "dataflux";
+
+const store = new Store();
+const author = new Model("author", `https://rest.example.net/api/v1/authors`);
+const book = new Model("book", `https://rest.example.net/api/v1/books`);
+
+store.addModel(author);
+store.addModel(book);
+
+author.addRelation(book, "id", "authorId"); // Add an object relation between author.id and book.authorId
+```
+The store can be initialized with [various options](#configuration).
+The creation of a model requires at least a name and an url. GET, POST, PUT, DELETE operations are going to be performed against the same url. [Models can be created with considerably more advanced options.](#model-creation)
+
+### Example 1
+
+Retrieve and edit an author not knowing the ID:
+
+```js
+// Find the author Dante Alighieri
+store.find("author", ({name, surname}) => name == "Dante" && surname == "Alighieri")
+        .then(([author]) => {
+          author.set("country", "Italy");
+          author.set("type", "poet");
+          // Nothing else to do, the store does a single PUT request to the model's API about the edited object
+        });
+```
+
+> You don't necessarily need to use `object.set` to edit an object attribute. You could do `author.country = "Italy"`. However, this approach relies on a periodic detection of changes (while `.set` triggers an update immediately). Check the `autoSave` option for more information
+
+### Example 2
+
+Operations without autoSave:
+
+```js
+// To disable autoSave you must declare the store as follows
+const store = new Store({autoSave: false});
+```
+
+The same example above now becomes:
+
+```js
+// Find the author Dante Alighieri
+store.find("author", ({name, surname}) => name == "Dante" && surname == "Alighieri")
+        .then(([author]) => {
+          // When autoSave = false, you can still use author.set, but there is no actual benefit
+          author.country = "Italy"
+          author.type = "poet"
+
+          store.save(); // Even if we changed only one author, prefer always store.save() to author.save()
+        });
+```
+
+### Example 3
+
+Insert and delete objects:
+```js
+// Remove all authors with a name starting with "A"
+store.delete("author", ({name}) => name.startsWith("A"));
+// Add a new author
+store.insert("author", {name: "Jane", surname: "Austen"});
+// If autoSave = false, remember to do store.save();
+```
+
+You can also destroy a single object
+```js
+author.destroy();
+```
+
+Or destroy a collection of authors you already selected
+```js
+store.find("author", ({name}) => name.startsWith("A"))
+        .then(authors => {
+          store.delete(authors);
+        });
+```
+### Example 4
+
+Get all books of an author:
+
+```js
+author.getRelation("book");
+```
+
+### Example 5 - Observability
+
+If you use `subscribe` instead of `find`, you can provide a callback to be invoked when data is ready or there is a change in the data.
+
+
+```js
+const drawBooksCallback = (books) => {
+  // Do something with the books
+};
+
+// Get all books with a price < 20
+store.subscribe("book", drawBooks, ({price}) => price < 20);
+```
+
+If now somewhere a book is inserted/deleted/edited:
+* if the book has `price < 20`,  `drawBooksCallback` will be called again with the new dataset;
+* if the book has `price > 20`,  `drawBooksCallback` will NOT be called again (because the new book doesn't impact our selection).
+
+You can terminate the subscription with `store.unsubscribe()`:
+
+```js
+const subKey = store.subscribe("book", drawBooks, ({price}) => price < 20); // Subscribe
+
+store.unsubscribe(subKey); // Unsubscribe
+```
+
+### Example 6 - Observability + React
+
+The integration with React is offered transparently when using the store inside a `React.Component`.
+You can use two methods: `findOne`, and `findAll`.
+
+> Since the store is able to detect changes deep in a nested structure, you will not have to worry about the component not re-rendering. Also, the setState will only be triggered when the next change of the dataset is really impacting your selection.
+
+React Component example
+```jsx
+class MyComponent extends React.Component {
+  constructor(props) {
+    super(props);
+  }
+
+  componentDidMount() {
+    // Get all books with a price < 20
+    store.findAll("book", "books", this, ({price}) => price < 20);
+    // Every time the dataset changes, a setState will be automatically performed.
+    // An attribute "books" will be added/updated in the state (the rest of the 
+    // state remains unchanged).
+
+    // findAll is a syntactic sugar for:
+    // const callback = (books) => {this.setState({...this.state, books})};
+    // store.subscribe("book", callback, ({price}) => price < 20);
+  }
+
+  render(){
+    const {books} = this.state;
+
+    return books.map(book => {
+      return <Book
+              // onTitleChange will alter the book and so the current state of "books"
+              onTitleChange={(title) => book.set("title", title)}
+              // alternatively, onTitleChange={store.handleChange(book, "title")} 
+              // is a syntactic sugar of the function above
+      />
+    });
+  }
+}
+```
+
+When the component will unmount, the `findAll` subscription will be terminated.
+
+## Configuration
+
+The store can be configured with the following options:
+
+
+| Option    | Description                                                                                                                                                                                                                                                                                                                                                                              | Default |
+|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|
+| autoSave  | It can be `true`, `false`, or an amount of milliseconds (integer). If `false`, you will have to perform `store.save()` manually. If `true`, the store will automatically perform `save()` when objects change. If an amount of milliseconds is provided, the objects are saved periodically AND when a change is detected. See [Editing objects](#editing-objects) for more information. | 3000    |
+| saveDelay | An amount of milliseconds used to defer synching operations with the server. It triggers `store.save()` milliseconds after the last change on the store's objects is detedect. This allows to bundle together multiple changes operated by an interacting user. See [Editing objects](#editing-objects) for more information.                                                            | 1000    |
+| lazyLoad  | A boolean. If set to `false`, the store is pre-populated with all the models' objects. If set to `true`, models' objects are loaded only on first usage (e.g., 'find', 'subscribe', 'getRelation'). LazyLoad operates per model, only the objects of the used models are loaded.                                                                                                         | false   |
+
+
+
+## Editing objects
+The option `autoSave` can be `true`, `false`, a number (milliseconds).
+
+* When `autoSave` is set to `false`, the following operations are equivalent:
+    ```js
+    object.set("name", "Dante");
+    
+    object.name = "Dante";
+    ```
+  No matter which of the two approaches you use, the command `store.save()` must be invoked to sync the changes with the server.
+
+  > The command `store.save()` is always able to recognize changed objects that need to be persisted.
+
+
+* **When `autoSave` is set to `true`, the above operations are NOT equivalent.**
+
+  Using `.set(attribute, value)` informs the store that an object changed, while changing directly a property the object (`object.name = "Dante"`) does not. Since the store is not aware of the changes, they will not be synced with the server. **To avoid this, always use `.set(attribute, value)`.**
+
+  > The commands `store.insert()`, `store.delete()`, and `object.destroy()` are always visible to the store, and so syncing is always performed when `autoSave` is `true`.
+
+* **When `autoSave` is set to an amount of milliseconds, the above operations are still NOT equivalent, but...**
+
+  The store will perform as if the `autoSave` was set to `true`; hence, changes performed with `.set(attribute, value)` are synced. However, it will periodically attempt also a `store.save()`. Since `store.save()` is always able to recognize edited objects, also changes directly operated on a property of the object (`object.name = "Dante"`) are synced.
+
+
+## API interaction
+DataFlux is able to identify three sets of objects: inserted, updated, deleted.
+Each of these set is synced to the server with POST, PUT, and DELETE REST operations, respectively.
+
+The interaction with the API is handled automatically, multiple requests are prevented and operations are bundled as much as possible.
+
+For example (with autoSave):
+```js
+store.find('book', (book) => book.price < 20);
+store.find('book', (book) => book.price > 60);
+// The commands above will correspond to 1 single query to the REST API.
+
+author1.set("name", "Dante");
+author2.set("name", "Italo");
+author3.set("name", "Umberto");
+author4.name = "Primo";
+// The commands above will correspond to 1 single query to the REST API, 
+// no matter how many editing operations.
+
+
+author1.set("name", "Dante");
+setTimeout(() => author2.set("name", "Italo"), 10000); // To "emulate" a user interaction.
+// The commands above will correspond to 2 queries to the REST API
+
+const author1 = {surname: "Alighieri"};
+store.insert(author1);
+author1.set("name", "Dante");
+author1.delete(author1);
+// The commands above will not produce any query to the REST API since 
+// the initial and final states of the store are the same (object created and removed).
+
+```
+
+### REST API format
+
+The APIs must return/accept an array of JSON objects or a single object. If your API uses a different format, use a function in the [model creation](#model-creation) to transform the data.
+
+The following format is automatically accepted, and it will create two objects.
+
+```json
+[
+  {
+    "name": "Dante",
+    "surname": "Alighieri",
+    "reviews": [...]
+  },
+  {
+    "name": "Giovanni",
+    "surname": "Boccaccio",
+    "reviews": [...]
+  }
+]
+```
+
+The following format is automatically accepted, and it will create one object.
+
+```json
+{
+  "username": "Massimo",
+  "website": "https://massimocandela.com",
+  "otherParameters": {
+    ...
+  }
+}
+```
+
+The following format will create a single object, which probably you don't want. Use a function in [model creation](#model-creation) to unwrap the data.
+
+```json
+{
+  "books": [],
+  "authors": []
+}
+```
+
+## Model creation
+
+A model can be simply created with:
+
+```js
+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.
+
+Instead of an url, you can pass options to perform more elaborated Model's initialization.
+
+```js
+const options = {
+  retrieve: {
+    method: "get",
+    url: "https://rest.example.net/api/v1/books"
+  },
+  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"
+  }
+};
+
+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.
+
+For example, if you want to perform inserts and updates with just `PUT`, you can simply do:
+```js
+const options = {
+  retrieve: {
+    method: "get",
+    url: "https://rest.example.net/api/v1/books"
+  },
+  insert: {
+    method: "put" // It will use the same GET url
+  }
+};
+
+const book = new Model("book", options);
+```
+
+Or, even more flexible, you can pass functions and handle yourself the operations. The functions MUST return promises.
+
+
+```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);
+  },
+  insert: (data) => {
+    // 1) recieve the data from the store
+    // 2) transform the data however you like 
+    // 3) send data to server
+    return Promise.resolve();
+  }
+};
+
+const book = new Model("book", options);
+```
+
+## Relations among models
+
+Optionally, you can create relations among models.
+
+For example, you can declare that an author has one or more objects of type book in the following way:
+
+```js
+const author = new Model("author", `https://rest.example.net/api/v1/authors`);
+const book = new Model("book", `https://rest.example.net/api/v1/books`);
+
+author.addRelation(book, "id", "authorId");
+```
+In this example, we added an explicit relation between `author.id` and `book.authorId`. This means that the store will return as books belonging to the author, all the books having `authorId` equals to the id of the author.
+
+Now all the author objects will have the method `getRelation(type, filterFunction)` that can be used to retrieve a relation associated with the author. The `type` defines the model type (in our case, 'book'), the `filterFunction` is an optional parameter that can be passed in case the output needs an additional filtering.
+
+For example, imagine you have the `author1` object defined in the examples above (Dante Alighieri):
+
+```js
+author1.getRelation("book")
+  .then(dantesBooks => {
+    // Do something with Dante's books
+  });
+
+// Or..
+author1.getRelation("book", (book) => book.price < 20)
+        .then(cheapDantesBooks => {
+          // Do something with Dante's books cheaper than 20
+        });
+```
+
+Other ways to declare relations:
+
+* `account.addRelation("user", "userId")`
+  
+  When the third parameter is missing, it defaults to "id" (i.e., it is the shorter version of `account.addRelation("user", "userId", "id")`). This means that the store will return as user of the account, the user having `id` equals to `account.userId`.
+
+
+* `author.addRelation("book", filterFunction)`
+
+  When the second parameter is a function, the function will be used by the store to filter the objects of the connected model. The `filterFunction` receives two parameters `(parentObject, possibleChildObject)` and returns a boolean. In this way you can create complex relations based on multiple fields/factors; e.g., a `filterFunction` equals to `(author, book) => author.name == book.authorName && author.surname == book.authorSurname`.

package/dist/Model.js

@@ -0,0 +1,175 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports["default"] = void 0;
+
+var _modelHooksUtils = require("./modelHooksUtils");
+
+var _batchPromises = _interopRequireDefault(require("batch-promises"));
+
+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."); }
+
+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); }
+
+function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) { arr2[i] = arr[i]; } return arr2; }
+
+function _iterableToArrayLimit(arr, i) { var _i = arr == null ? null : typeof Symbol !== "undefined" && arr[Symbol.iterator] || arr["@@iterator"]; if (_i == null) return; var _arr = []; var _n = true; var _d = false; var _s, _e; try { for (_i = _i.call(arr); !(_n = (_s = _i.next()).done); _n = true) { _arr.push(_s.value); if (i && _arr.length === i) break; } } catch (err) { _d = true; _e = err; } finally { try { if (!_n && _i["return"] != null) _i["return"](); } finally { if (_d) throw _e; } } return _arr; }
+
+function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
+
+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); } }
+
+function _createClass(Constructor, protoProps, staticProps) { if (protoProps) _defineProperties(Constructor.prototype, protoProps); if (staticProps) _defineProperties(Constructor, staticProps); Object.defineProperty(Constructor, "prototype", { writable: false }); return Constructor; }
+
+function _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError("Cannot call a class as a function"); } }
+
+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; }
+
+var Model = /*#__PURE__*/_createClass(function Model(name, options) {
+  var _this = this;
+
+  _classCallCheck(this, Model);
+
+  _defineProperty(this, "_bulkOperation", function (objects, action) {
+    if (_this.__singleItemQuery) {
+      return (0, _batchPromises["default"])(_this.__batchSize, objects, action);
+    } else {
+      return action(objects);
+    }
+  });
+
+  _defineProperty(this, "getType", function () {
+    return _this.__type;
+  });
+
+  _defineProperty(this, "_toArray", function (data) {
+    if (Array.isArray(data)) {
+      return data;
+    } else {
+      _this.__singleItemQuery = true;
+      return [data];
+    }
+  });
+
+  _defineProperty(this, "retrieveAll", function () {
+    return (0, _modelHooksUtils.executeHook)("retrieve", _this.__retrieveHook, null).then(_this._toArray);
+  });
+
+  _defineProperty(this, "insertObjects", function (objects) {
+    return _this._bulkOperation(objects, _this._insertObjects);
+  });
+
+  _defineProperty(this, "updateObjects", function (objects) {
+    return _this._bulkOperation(objects, _this._updateObjects);
+  });
+
+  _defineProperty(this, "deleteObjects", function (objects) {
+    return _this._bulkOperation(objects, _this._deleteObjects);
+  });
+
+  _defineProperty(this, "_insertObjects", function (data) {
+    return Promise.resolve(true);
+    return (0, _modelHooksUtils.executeHook)("insert", _this.__insertHook, data).then(_this._toArray);
+  });
+
+  _defineProperty(this, "_updateObjects", function (data) {
+    return Promise.resolve(true);
+    return (0, _modelHooksUtils.executeHook)("update", _this.__updateHook, data).then(_this._toArray);
+  });
+
+  _defineProperty(this, "_deleteObjects", function (data) {
+    return Promise.resolve(true);
+    return (0, _modelHooksUtils.executeHook)("update", _this.__deleteHook, data).then(_this._toArray);
+  });
+
+  _defineProperty(this, "getStore", function () {
+    return _this.store;
+  });
+
+  _defineProperty(this, "addRelationByField", function (model, localField) {
+    var remoteField = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : "id";
+
+    var filterFunction = function filterFunction(parentObject, child) {
+      return parentObject[localField] === child[remoteField];
+    };
+
+    return _this.addRelationByFilter(model, filterFunction);
+  });
+
+  _defineProperty(this, "addRelationByFilter", function (model, filterFunction) {
+    var includedType = model.getType();
+    _this.__includes[includedType] = filterFunction;
+  });
+
+  _defineProperty(this, "addRelation", function (model, param2, param3) {
+    if (model) {
+      _this.getStore().validateModel(model);
+
+      if (typeof param2 === "string" && (!param3 || typeof param3 === "string")) {
+        // explicit model, from, to
+        return _this.addRelationByField(model, param2, param3);
+      } else if (!param3 && typeof param2 === "function") {
+        // explicit model, filterFunction
+        return _this.addRelationByFilter(model, param2);
+      } else if (!param2 && !param3) {
+        // implicit model, from, to (it uses the type as local key and the id as remote key)
+        return _this.addRelationByField(model, model.getType(), "id");
+      } else {
+        throw new Error("Invalid relation declaration");
+      }
+    } else {
+      throw new Error("A relation needs a model");
+    }
+  });
+
+  _defineProperty(this, "getRelation", function (parentObject, includedType, filterFunction) {
+    var filterRelation = _this.__includes[includedType];
+
+    if (filterRelation) {
+      return _this.getStore().find(includedType, function (item) {
+        return filterRelation(parentObject, item);
+      }).then(function (data) {
+        if (filterFunction) {
+          return data.filter(filterFunction);
+        }
+
+        return data;
+      });
+    } else {
+      return Promise.reject("The relation doesn't exist");
+    }
+  });
+
+  this.__type = name;
+
+  if (!name || !options) {
+    throw new Error("A Model requires at least a name and a hook");
+  }
+
+  var _ref = _typeof(options) === "object" ? (0, _modelHooksUtils.getHooksFromOptions)(options) : (0, _modelHooksUtils.getHooksFromUrl)(options),
+      _ref2 = _slicedToArray(_ref, 4),
+      retrieveHook = _ref2[0],
+      insertHook = _ref2[1],
+      updateHook = _ref2[2],
+      deleteHook = _ref2[3];
+
+  this.__retrieveHook = retrieveHook;
+  this.__updateHook = updateHook;
+  this.__insertHook = insertHook;
+  this.__deleteHook = deleteHook;
+  this.__singleItemQuery = false; // By default use arrays
+
+  this.__batchSize = 4; // For HTTP requests in parallel if your API doesn't support multiple resources
+
+  this.__includes = {};
+});
+
+exports["default"] = Model;