dataflux 1.0.4 → 1.2.0

package/README.md

@@ -13,13 +13,22 @@ DataFlux is a JavaScript library that automatically interfaces with your REST AP
 
 ## Installation
 
+Using npm:
 ```sh
 npm install dataflux
 ```
 
+Using jsDelivr CDN:
+```html
+<script src="https://cdn.jsdelivr.net/npm/dataflux/dist/index.js"></script>
+```
+
 ## Examples
 
-Consider the following store/model declaration common to all the examples below:
+Create your global store by creating a file (e.g., named `store.js`) containing the model declaration.
+
+Consider the following hypothetical store/model declaration common to all the examples below:
+
 ```js
 import {Store, Model} from "dataflux";
 
@@ -30,16 +39,27 @@ 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
+// An object relation between author.id and book.authorId as follows
+author.addRelation(book, "id", "authorId");
+
+export default store;
 ```
-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)
+
+
+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 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.**
 
 ### Example 1
 
 Retrieve and edit an author not knowing the ID:
 
 ```js
+import store from "./store";
+
 // Find the author Dante Alighieri
 store.find("author", ({name, surname}) => name == "Dante" && surname == "Alighieri")
         .then(([author]) => {
@@ -148,9 +168,9 @@ class MyComponent extends React.Component {
   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).
+    // 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})};
@@ -160,19 +180,23 @@ class MyComponent extends React.Component {
   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
-      />
-    });
+    return books.map(book =>
+            <Book
+                    onTitleChange={(title) => book.set("title", title)}
+                    // onTitleChange will alter the book and so the current 
+                    // state of "books" (a setState will be performed).
+                    //
+                    // 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.
+The method `findAll` returns always an array. The method `findOne` returns a single object (if multiple objects satisfy the search, the first is returned).
+
+When the component will unmount, the `findAll` subscription will be automatically terminated without the need to unsubscribe. Be aware, `store.findAll` injects the unsubscribe call inside `componentWillUnmount`. If your component already implements `componentWillUnmount()`, then you will have to use `store.subscribe` and `store.unsubscribe` instead of `store.findAll`, to avoid side effects when the component is unmounted.
 
 ## Configuration
 
@@ -187,147 +211,86 @@ The store can be configured with the following options:
 
 
 
-## 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)`.**
+## Models creation
 
-  > 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.
+A model can be simply created with:
 
-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 book = new Model("book", `https://rest.example.net/api/v1/books`);
+```
 
-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).
+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);
 ```
 
-### REST API format
+All the possible options for a model creation are (they are all optional):
 
-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.
+| 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 |
 
-The following format is automatically accepted, and it will create two objects.
 
-```json
-[
-  {
-    "name": "Dante",
-    "surname": "Alighieri",
-    "reviews": [...]
-  },
-  {
-    "name": "Giovanni",
-    "surname": "Boccaccio",
-    "reviews": [...]
-  }
-]
-```
+### 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.
 
-The following format is automatically accepted, and it will create one object.
+#### Operation 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.
+An operation object is an object like follows:
 
 ```json
 {
-  "books": [],
-  "authors": []
+  "method": "get",
+  "url": "https://api.example.com",
+  "headers": {"Authorization": "bearer XXXX"}
 }
 ```
 
-## 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.
+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 inserts and updates with just `PUT`, you can simply 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: {
@@ -338,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
@@ -352,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();
   }
 };
@@ -360,7 +325,51 @@ const options = {
 const book = new Model("book", options);
 ```
 
-## Relations among models
+#### 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
+```
+
+
+
+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
 
 Optionally, you can create relations among models.
 
@@ -374,15 +383,30 @@ 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.
+
+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; e.g., a `filterFunction` equal to `(author, book) => author.name == book.authorName && author.surname == book.authorSurname` creates a relation based on two attributes.
+
+
+#### Accessing model relations
+
+Once the relation between the author and the book models is declared, all the author objects will expose a 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
-  });
+        .then(dantesBooks => {
+          // Do something with Dante's books
+        });
 
 // Or..
 author1.getRelation("book", (book) => book.price < 20)
@@ -390,14 +414,133 @@ author1.getRelation("book", (book) => book.price < 20)
           // Do something with Dante's books cheaper than 20
         });
 ```
+## Store methods
+
+The store has the following method.
+
+| Method                       | Description                                                                                                                                                |
+|------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| addModel(model)              | Introduce a new model to the store. If lazyLoad = false (default), the model is populated with the objects coming from the API.                            |
+| get(type, id)                | It allows to retrieve an object based on its type and store's ID (see `getId()` in [objects methods](#objects-methods). The type is the name of the model. |
+| find(type,filterFunction)    | The promise-oriented method to access objects given a type and a filter function. See [example 1](#example-1).                                             |
+| delete(objects)              | It deletes an array of objects. See [example 1](#example-3).                                                                                               |
+| delete(type, filterFunction) | It deleted objects given an array and a filter function. See [example 1](#example-3).                                                                      |
+| insert(type, object)         | It creates a new object of a given type and inserts it in the store.                                                                                       |
+
+## Objects methods
+Each object created is enriched with the following methods.
+
+
+| Method                             | Description                                                                                                                                                                                                                                      |
+|------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| getId()                            | It returns a unique ID used by the store to identify the object. The ID is unique inside a single model. Be aware, `object.id` and `objet.getId()` may return different values, since store's IDs can be different from the one of the REST API. |
+| set(attribute, value)              | A method to set an attribute to the object. It provides some advantages compared to doing `object.attribute = value`, these are discussed in [below](#editing-objects).                                                                          |
+| save()                             | Method to save the object. You can do `store.save()` instead.                                                                                                                                                                                    |
+| destroy()                          | Method to delete the object. You can do `store.delete()` instead.                                                                                                                                                                                |
+| get(attribute)                     | If you like symmetry and since you do `.set()` you would like to do also `.get()` of the attributes. It does not provide any advantage compared to accessing directly the attribute (e.g., `author.name`).                                       |
+| getRelation(model, filterFunction) | To get all the objects respecting a specific relation with this object (see [model relations](#model-relations)).                                                                                                                                |
+| toJSON()                           | It returns a pure JSON representation of the object.                                                                                                                                                                                             |
+| toString()                         | It returns a string representation of the object.                                                                                                                                                                                                |
+| getFingerprint()                   | It returns a hash of the object. The hash changes at every change of the object or of any nested object. Useful to detect object changes.                                                                                                        |
+| getModel()                         | It returns the model of this object. Mostly useful to do `object.getModel().getType()` and obtain a string defining the type of the object.                                                                                                      |
 
-Other ways to declare relations:
+## Editing objects
+The option `autoSave` can be `true`, `false`, or a number (milliseconds).
 
-* `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`.
+* 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.
 
-* `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; e.g., a `filterFunction` equal to `(author, book) => author.name == book.authorName && author.surname == book.authorSurname` creates a relation based on two attributes.
+* **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 an attribute of 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 an attribute 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 with 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");
+store.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 [models creation](#models-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 [models creation](#models-creation) to unwrap the data.
+
+```json
+{
+  "books": [],
+  "authors": []
+}
+```