Merge pull request #276 from terminusdb/history

add history endPoint

Author: GavinMendelGleason

docs/api/typedef.md

@@ -200,3 +200,15 @@ the manage capability command type
 ##### RolesActions:  `  Array.<ACTIONS>`
 [ACTIONS.CREATE_DATABASE | ACTIONS.DELETE_DATABASE]
 
+
+## DocHistoryParams
+##### DocHistoryParams:  `  Object`
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| [start] | <code>number</code> | Index to start from, 0 is the default |
+| [count] | <code>number</code> | Amount of commits to show, 10 is the default |
+| [updated] | <code>boolean</code> | Last updated time (excludes history) false is the default |
+| [created] | <code>boolean</code> | Created date of object (excludes history) false is the default |
+

docs/api/woqlclient.md

@@ -1388,6 +1388,29 @@ client.apply("main","mybranch","merge main").then(result=>{
 })
 ```
 
+## docHistory
+##### woqlClient.docHistory(id, [historyParams])
+Get the document's history for a specific database or branch
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| id | <code>string</code> | id of document to report history of |
+| [historyParams] | <code>typedef.DocHistoryParams</code> |  |
+
+**Example**  
+```javascript
+//this will return the last 5 commits for the Person/Anna document
+client.checkout("mybranch")
+client.docHistory("Person/Anna",{start:0,count:5}).then(result=>{
+   console.log(result)
+})
+//this will return the last and the first commit for the Person/Anna document
+client.docHistory("Person/Anna",{updated:true,created:true}).then(result=>{
+   console.log(result)
+})
+```
+
 ## sendCustomRequest
 ##### woqlClient.sendCustomRequest(requestType, customRequestURL, [payload]) ⇒ <code>Promise</code>
 Call a custom Api endpoit

lib/connectionConfig.js

@@ -540,6 +540,20 @@ ConnectionConfig.prototype.applyURL = function () {
   return purl;
 };
 
+/**
+ * Generate url portion consisting of organization/dbid
+ * (unless dbid = system dbname in which case there is no organization)
+ * @property {typedef.DocParamsPost|Object} params
+ */
+
+ConnectionConfig.prototype.docHistoryURL = function (params) {
+  const paramsStr = this.queryParameter(params);
+  if (this.db() === this.system_db) {
+    return this.dbBase('history') + paramsStr;
+  }
+  return this.branchBase('history') + paramsStr;
+};
+
 /**
  * Generate URL for fetch endpoint
  * @param {string} remoteName

lib/typedef.js

@@ -169,4 +169,12 @@ const { ACTIONS } = Utils.ACTIONS;
  * @typedef  {ACTIONS[]} RolesActions - [ACTIONS.CREATE_DATABASE | ACTIONS.DELETE_DATABASE]
  */
 
+/**
+ * @typedef  {Object} DocHistoryParams
+ * @property {number} [start] - Index to start from, 0 is the default
+ * @property {number} [count] - Amount of commits to show, 10 is the default
+ * @property {boolean} [updated] - Last updated time (excludes history) false is the default
+ * @property {boolean} [created] - Created date of object (excludes history) false is the default
+ */
+
 module.exports = {};

lib/woqlClient.js

@@ -1840,6 +1840,32 @@ WOQLClient.prototype.apply = function (beforeVersion, afterVersion, message, mat
   ).then((response) => response);
 };
 
+/**
+ * Get the document's history for a specific database or branch
+ * @param {string} id - id of document to report history of
+ * @param {typedef.DocHistoryParams} [historyParams]
+ * @example
+ * //this will return the last 5 commits for the Person/Anna document
+ * client.checkout("mybranch")
+ * client.docHistory("Person/Anna",{start:0,count:5}).then(result=>{
+ *    console.log(result)
+ * })
+ * //this will return the last and the first commit for the Person/Anna document
+ * client.docHistory("Person/Anna",{updated:true,created:true}).then(result=>{
+ *    console.log(result)
+ * })
+ */
+
+// eslint-disable-next-line max-len
+WOQLClient.prototype.docHistory = function (id, historyParams) {
+  const params = historyParams || {};
+  params.id = id;
+  return this.dispatch(
+    CONST.GET,
+    this.connectionConfig.docHistoryURL(params),
+  ).then((response) => response);
+};
+
 /**
  * Call a custom Api endpoit
  * @param {string} requestType - The current state of JSON document