review diff methods, add apply method (#215)

* review diff method and add apply

Co-authored-by: Francesca-Bit <francesca@terminusdb.com>
Co-authored-by: Francesca-Bit <Francesca-Bit@users.noreply.github.com>

Author: Francesca-Bit

.eslintignore

@@ -8,3 +8,4 @@ package-lock.json
 .nyc_output
 test/
 tutorial/
+local_test/

docs/api/woqlclient.md

@@ -1122,8 +1122,8 @@ async funtion callGetUserOrganizations(){
 }
 ```
 
-## getDiff
-##### woqlClient.getDiff(before, after, options) ⇒ <code>Promise</code>
+## getJSONDiff
+##### woqlClient.getJSONDiff(before, after, [options]) ⇒ <code>Promise</code>
 Get the patch of difference between two documents.
 
 **Returns**: <code>Promise</code> - A promise that returns the call response object, or an Error if rejected.  
@@ -1132,58 +1132,103 @@ Get the patch of difference between two documents.
 | --- | --- | --- |
 | before | <code>object</code> | The current state of JSON document |
 | after | <code>object</code> | The updated state of JSON document |
-| options | <code>object</code> | [{}] - Options to send to the diff endpoint |
+| [options] | <code>object</code> | {keep:{}} Options to send to the diff endpoint the diff api outputs the changes between the input (JSON Object), but you can list the properties that you would like to see in the diff result in any case. |
 
 **Example**  
 ```javascript
-const diff = await client.getDiff(
+client.getJSONDiff(
      { "@id": "Person/Jane", "@type": "Person", name: "Jane" },
      { "@id": "Person/Jane", "@type": "Person", name: "Janine" }
- );
+ ).then(diffResult=>{
+ console.log(diffResult)
+})
+//result example
+//{'@id': 'Person/Jane',
+// name: { '@after': 'Janine', '@before': 'Jane', '@op': 'SwapValue' }}
 ```
 
 ## getVersionObjectDiff
-##### woqlClient.getVersionObjectDiff(id, beforeVersion, after, options) ⇒ <code>Promise</code>
+##### woqlClient.getVersionObjectDiff(dataVersion, jsonObject, id, [options]) ⇒ <code>Promise</code>
 Get the patch of difference between two documents.
 
 **Returns**: <code>Promise</code> - A promise that returns the call response object, or an Error if rejected.  
 
 | Param | Type | Description |
 | --- | --- | --- |
+| dataVersion | <code>string</code> | The version from which to compare the object |
+| jsonObject | <code>object</code> | The updated state of JSON document |
 | id | <code>string</code> | The object id to be diffed |
-| beforeVersion | <code>string</code> | The version from which to compare the object |
-| after | <code>object</code> | The updated state of JSON document |
-| options | <code>object</code> | [{}] - Options to send to the diff endpoint |
+| [options] | <code>object</code> | {keep:{}} Options to send to the diff endpoint the diff api outputs the changes between the input (branches or commits), but you can list the properties that you would like to see in the diff result in any case. |
 
 **Example**  
 ```javascript
-const diff = await client.getVersionObjectDiff(
-     "Person/Jane",
-     "branch:a73ssscfx0kke7z76083cgswszdxy6l",
-     { "@id": "Person/Jane", "@type": "Person", name: "Janine" }
- );
+const jsonObj =  { "@id": "Person/Jane", "@type": "Person", name: "Janine" }
+client.getVersionObjectDiff("main",jsonObj
+     "Person/Jane").then(diffResp=>{
+   console.log(diffResp)
+})
 ```
 
 ## getVersionDiff
-##### woqlClient.getVersionDiff(id, beforeVersion, afterVersion, options) ⇒ <code>Promise</code>
-Get the patch of difference between two documents.
+##### woqlClient.getVersionDiff(beforeVersion, afterVersion, [id], [options]) ⇒ <code>Promise</code>
+Get the patch of difference between branches or commits.
 
 **Returns**: <code>Promise</code> - A promise that returns the call response object, or an Error if rejected.  
 
 | Param | Type | Description |
 | --- | --- | --- |
-| id | <code>string</code> | The object id to be diffed |
-| beforeVersion | <code>string</code> | The version from which to compare the object |
-| afterVersion | <code>string</code> | The version to which to compare the object |
-| options | <code>object</code> | [{}] - Options to send to the diff endpoint |
+| beforeVersion | <code>string</code> | Before branch/commit to compare |
+| afterVersion | <code>string</code> | Before branch/commit to compare |
+| [id] | <code>string</code> | The object id to be diffed, if it is omitted all the documents will be compared |
+| [options] | <code>object</code> | {keep:{}} Options to send to the diff endpoint the diff api outputs the changes between the input (branches or commits), but you can list the properties that you would like to see in the diff result in any case. |
 
 **Example**  
 ```javascript
-const diff = await client.getVersionDiff(
-     "Person/Jane",
-     "branch:a73ssscfx0kke7z76083cgswszdxy6l",
-     "branch:73rqpooz65kbsheuno5dsayh71x7wf4"
- );
+//This is to view all the changes between two commits
+const beforeCommit = "a73ssscfx0kke7z76083cgswszdxy6l"
+const afterCommit = "73rqpooz65kbsheuno5dsayh71x7wf4"
+
+client.getVersionDiff( beforeCommit, afterCommit).then(diffResult=>{
+ console.log(diffResult)
+})
+
+//This is to view the changes between two commits but only for the given document
+client.getVersionDiff( beforeCommit, afterCommit, "Person/Tom").then(diffResult=>{
+ console.log(diffResult)
+})
+
+//This is to view the changes between a branch (head) and a commit for the given document
+client.getVersionDiff("main", afterCommit, "Person/Tom" ).then(diffResult=>{
+   console.log(diffResult)
+})
+
+//This is to view the changes between two branches with the keep options
+const options = {"keep":{"@id":true, "name": true}}
+client.getVersionDiff("main","mybranch",options).then(diffResult=>{
+   console.log(diffResult)
+})
+```
+
+## apply
+##### woqlClient.apply(beforeVersion, afterVersion, message, [match_final_state], [options])
+Diff two different commits and apply changes on the current branch/commit
+if you would like to change branch or commit before apply use client.checkout("branchName")
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| beforeVersion | <code>string</code> | Before branch/commit to compare |
+| afterVersion | <code>string</code> | Before branch/commit to compare |
+| message | <code>string</code> | apply commit message |
+| [match_final_state] | <code>boolean</code> | the deafult value is false |
+| [options] | <code>object</code> | {keep:{}} Options to send to the apply endpoint |
+
+**Example**  
+```javascript
+client.checkout("mybranch")
+client.apply("main","mybranch").then(result=>{
+   console.log(result)
+})
 ```
 
 ## patch

lib/connectionConfig.js

@@ -512,6 +512,15 @@ ConnectionConfig.prototype.diffURL = function () {
   return purl;
 };
 
+/**
+ * Generate URL for diff endpoint
+ * @returns {string}
+ */
+ConnectionConfig.prototype.applyURL = function () {
+  const purl = this.branchBase('apply');
+  return purl;
+};
+
 /**
  * Generate URL for fetch endpoint
  * @param {string} remoteName

lib/woqlClient.js

@@ -1468,15 +1468,22 @@ WOQLClient.prototype.userOrganizations = function (orgList) {
  * Get the patch of difference between two documents.
  * @param {object} before - The current state of JSON document
  * @param {object} after - The updated state of JSON document
- * @param {object} options [{}] - Options to send to the diff endpoint
+ * @param {object} [options] - {keep:{}} Options to send to the diff endpoint
+ * the diff api outputs the changes between the input (JSON Object),
+ * but you can list the properties that you would like to see in the diff result in any case.
  * @returns {Promise}  A promise that returns the call response object, or an Error if rejected.
  * @example
- *  const diff = await client.getDiff(
+ * client.getJSONDiff(
  *      { "@id": "Person/Jane", "@type": "Person", name: "Jane" },
  *      { "@id": "Person/Jane", "@type": "Person", name: "Janine" }
- *  );
- */
-WOQLClient.prototype.getDiff = function (before, after, options) {
+ *  ).then(diffResult=>{
+ *  console.log(diffResult)
+ * })
+ * //result example
+ * //{'@id': 'Person/Jane',
+ * // name: { '@after': 'Janine', '@before': 'Jane', '@op': 'SwapValue' }}
+ */
+WOQLClient.prototype.getJSONDiff = function (before, after, options) {
   if (typeof before !== 'object' || typeof after !== 'object') {
     const errmsg = '"before" or "after" parameter error - you must specify a valid before or after json document';
 
@@ -1496,30 +1503,37 @@ WOQLClient.prototype.getDiff = function (before, after, options) {
 
 /**
  * Get the patch of difference between two documents.
+ * @param {string} dataVersion - The version from which to compare the object
+ * @param {object} jsonObject - The updated state of JSON document
  * @param {string} id - The object id to be diffed
- * @param {string} beforeVersion - The version from which to compare the object
- * @param {object} after - The updated state of JSON document
- * @param {object} options [{}] - Options to send to the diff endpoint
+ * @param {object} [options] - {keep:{}} Options to send to the diff endpoint
+ * the diff api outputs the changes between the input (branches or commits),
+ * but you can list the properties that you would like to see in the diff result in any case.
  * @returns {Promise}  A promise that returns the call response object, or an Error if rejected.
  * @example
- *  const diff = await client.getVersionObjectDiff(
- *      "Person/Jane",
- *      "branch:a73ssscfx0kke7z76083cgswszdxy6l",
- *      { "@id": "Person/Jane", "@type": "Person", name: "Janine" }
- *  );
+ * const jsonObj =  { "@id": "Person/Jane", "@type": "Person", name: "Janine" }
+ * client.getVersionObjectDiff("main",jsonObj
+ *      "Person/Jane").then(diffResp=>{
+ *    console.log(diffResp)
+ * })
  */
-WOQLClient.prototype.getVersionObjectDiff = function (id, beforeVersion, after, options) {
-  if (typeof id !== 'string' || typeof beforeVersion !== 'string' || typeof after !== 'object') {
-    const errmsg = '"id", "beforeVersion" or "after" parameter error - you must specify a valid after json document and valid id and version';
+WOQLClient.prototype.getVersionObjectDiff = function (dataVersion, jsonObject, id, options) {
+  if (typeof jsonObject !== 'object' || typeof dataVersion !== 'string') {
+    const errmsg = 'Parameters error - you must specify a valid jsonObject document and valid branch or commit';
 
     return Promise.reject(
       new Error(ErrorMessage.getInvalidParameterMessage(CONST.GET_DIFF, errmsg)),
     );
   }
-  const opt = (typeof options === 'undefined') ? {} : options;
+  const opt = options || {};
   const payload = {
-    document_id: id, before_data_version: beforeVersion, after, ...opt,
+    after: jsonObject,
+    before_data_version: dataVersion,
+    ...opt,
   };
+  if (id) {
+    payload.id = id;
+  }
   return this.dispatch(
     CONST.POST,
     this.connectionConfig.diffURL(),
@@ -1528,41 +1542,100 @@ WOQLClient.prototype.getVersionObjectDiff = function (id, beforeVersion, after,
 };
 
 /**
- * Get the patch of difference between two documents.
- * @param {string} id - The object id to be diffed
- * @param {string} beforeVersion - The version from which to compare the object
- * @param {string} afterVersion - The version to which to compare the object
- * @param {object} options [{}] - Options to send to the diff endpoint
+ * Get the patch of difference between branches or commits.
+ * @param {string} beforeVersion - Before branch/commit to compare
+ * @param {string} afterVersion -  Before branch/commit to compare
+ * @param {string} [id] - The object id to be diffed,
+ * if it is omitted all the documents will be compared
+ * @param {object} [options] - {keep:{}} Options to send to the diff endpoint
+ * the diff api outputs the changes between the input (branches or commits),
+ * but you can list the properties that you would like to see in the diff result in any case.
  * @returns {Promise}  A promise that returns the call response object, or an Error if rejected.
  * @example
- *  const diff = await client.getVersionDiff(
- *      "Person/Jane",
- *      "branch:a73ssscfx0kke7z76083cgswszdxy6l",
- *      "branch:73rqpooz65kbsheuno5dsayh71x7wf4"
- *  );
+ * //This is to view all the changes between two commits
+ * const beforeCommit = "a73ssscfx0kke7z76083cgswszdxy6l"
+ * const afterCommit = "73rqpooz65kbsheuno5dsayh71x7wf4"
+ *
+ * client.getVersionDiff( beforeCommit, afterCommit).then(diffResult=>{
+ *  console.log(diffResult)
+ * })
+ *
+ * //This is to view the changes between two commits but only for the given document
+ * client.getVersionDiff( beforeCommit, afterCommit, "Person/Tom").then(diffResult=>{
+ *  console.log(diffResult)
+ * })
+ *
+ * //This is to view the changes between a branch (head) and a commit for the given document
+ * client.getVersionDiff("main", afterCommit, "Person/Tom" ).then(diffResult=>{
+ *    console.log(diffResult)
+ * })
+ *
+ * //This is to view the changes between two branches with the keep options
+ * const options = {"keep":{"@id":true, "name": true}}
+ * client.getVersionDiff("main","mybranch",options).then(diffResult=>{
+ *    console.log(diffResult)
+ * })
  */
-WOQLClient.prototype.getVersionDiff = function (id, beforeVersion, afterVersion, options) {
-  if (typeof id !== 'string' || typeof beforeVersion !== 'string' || typeof afterVersion !== 'string') {
-    const errmsg = '"id", "beforeVersion" or "after" parameter error - you must specify a valid after json document and valid id and version';
+
+WOQLClient.prototype.getVersionDiff = function (beforeVersion, afterVersion, id, options) {
+  if (typeof beforeVersion !== 'string' || typeof afterVersion !== 'string') {
+    const errmsg = 'Error, you have to provide a beforeVersion and afterVersion input';
 
     return Promise.reject(
       new Error(ErrorMessage.getInvalidParameterMessage(CONST.GET_DIFF, errmsg)),
     );
   }
-  const opt = (typeof options === 'undefined') ? {} : options;
+  const opt = options || {};
   const payload = {
-    document_id: id,
     before_data_version: beforeVersion,
     after_data_version: afterVersion,
     ...opt,
   };
+  if (id) {
+    payload.document_id = id;
+  }
   return this.dispatch(
     CONST.POST,
     this.connectionConfig.diffURL(),
     payload,
   ).then((response) => response);
 };
 
+/**
+ * Diff two different commits and apply changes on the current branch/commit
+ * if you would like to change branch or commit before apply use client.checkout("branchName")
+ * @param {string} beforeVersion - Before branch/commit to compare
+ * @param {string} afterVersion - Before branch/commit to compare
+ * @param {string} message - apply commit message
+ * @param {boolean} [match_final_state] -  the deafult value is false
+ * @param {object} [options] - {keep:{}} Options to send to the apply endpoint
+ * @example
+ * client.checkout("mybranch")
+ * client.apply("main","mybranch").then(result=>{
+ *    console.log(result)
+ * })
+ */
+
+// eslint-disable-next-line max-len
+WOQLClient.prototype.apply = function (beforeVersion, afterVersion, message, matchFinalState, options) {
+  const opt = options || {};
+  const commitMsg = this.generateCommitInfo(message);
+  const payload = {
+    before_commit: beforeVersion,
+    after_commit: afterVersion,
+    ...commitMsg,
+    ...opt,
+  };
+  if (matchFinalState) {
+    payload.match_final_state = matchFinalState;
+  }
+  return this.dispatch(
+    CONST.POST,
+    this.connectionConfig.applyURL(),
+    payload,
+  ).then((response) => response);
+};
+
 /**
  * Patch the difference between two documents.
  * @param {object} before - The current state of JSON document